@caddis/cli 0.3.0 → 0.4.0

package/bundles/codex/.codex/skills/docs/code-documentation/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: code-documentation
+description: Writing effective code documentation - API docs, README files, inline comments, and technical guides. Use for documenting codebases, APIs, or writing developer guides.
+source: wshobson/agents
+license: MIT
+---
+
+# Code Documentation
+
+## Document Metadata
+
+For standalone Markdown docs such as README files, guides, ADRs, and API reference pages, apply `.github/instructions/document-frontmatter.instructions.md` before the first heading.
+
+- **New docs**: add `Original Author`, `Creation Date`, and `Creating Model`.
+- **Updated docs**: preserve the original fields and add or update `Last Author`, `Last Updated`, and `Last Model Used`.
+- Use full ISO 8601 UTC timestamps for `Creation Date` and `Last Updated` values.
+
+## README Structure
+
+### Standard README Template
+```markdown
+# Project Name
+
+Brief description of what this project does.
+
+## Quick Start
+
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+
+## Installation
+
+Detailed installation instructions...
+
+## Usage
+
+\`\`\`typescript
+import { something } from 'project';
+
+// Example usage
+const result = something.doThing();
+\`\`\`
+
+## API Reference
+
+### `functionName(param: Type): ReturnType`
+
+Description of what the function does.
+
+**Parameters:**
+- `param` - Description of parameter
+
+**Returns:** Description of return value
+
+**Example:**
+\`\`\`typescript
+const result = functionName('value');
+\`\`\`
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `option1` | `string` | `'default'` | What it does |
+
+## Contributing
+
+How to contribute...
+
+## License
+
+MIT
+```
+
+## API Documentation
+
+### JSDoc/TSDoc Style
+```typescript
+/**
+ * Creates a new user account.
+ *
+ * @param userData - The user data for account creation
+ * @param options - Optional configuration
+ * @returns The created user object
+ * @throws {ValidationError} If email is invalid
+ * @example
+ * ```ts
+ * const user = await createUser({
+ *   email: 'user@example.com',
+ *   name: 'John'
+ * });
+ * ```
+ */
+async function createUser(
+  userData: UserInput,
+  options?: CreateOptions
+): Promise<User> {
+  // Implementation
+}
+
+/**
+ * Configuration options for the API client.
+ */
+interface ClientConfig {
+  /** The API base URL */
+  baseUrl: string;
+  /** Request timeout in milliseconds @default 5000 */
+  timeout?: number;
+  /** Custom headers to include in requests */
+  headers?: Record<string, string>;
+}
+```
+
+### OpenAPI/Swagger
+```yaml
+openapi: 3.0.0
+info:
+  title: My API
+  version: 1.0.0
+
+paths:
+  /users:
+    post:
+      summary: Create a user
+      description: Creates a new user account
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UserInput'
+      responses:
+        '201':
+          description: User created successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+        '400':
+          description: Invalid input
+
+components:
+  schemas:
+    UserInput:
+      type: object
+      required:
+        - email
+        - name
+      properties:
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+        email:
+          type: string
+        name:
+          type: string
+        createdAt:
+          type: string
+          format: date-time
+```
+
+## Inline Comments
+
+### When to Comment
+```typescript
+// GOOD: Explain WHY, not WHAT
+
+// Use binary search because the list is always sorted and
+// can contain millions of items - O(log n) vs O(n)
+const index = binarySearch(items, target);
+
+// GOOD: Explain complex business logic
+// Users get 20% discount if they've been members for 2+ years
+// AND have made 10+ purchases (per marketing team decision Q4 2024)
+if (user.memberYears >= 2 && user.purchaseCount >= 10) {
+  applyDiscount(0.2);
+}
+
+// GOOD: Document workarounds
+// HACK: Safari doesn't support this API, fallback to polling
+// TODO: Remove when Safari adds support (tracking: webkit.org/b/12345)
+if (!window.IntersectionObserver) {
+  startPolling();
+}
+```
+
+### When NOT to Comment
+```typescript
+// BAD: Stating the obvious
+// Increment counter by 1
+counter++;
+
+// BAD: Explaining clear code
+// Check if user is admin
+if (user.role === 'admin') { ... }
+
+// BAD: Outdated comments (worse than no comment)
+// Returns the user's full name  <-- Actually returns email now!
+function getUserIdentifier(user) {
+  return user.email;
+}
+```
+
+## Architecture Documentation
+
+### ADR (Architecture Decision Record)
+```markdown
+# ADR-001: Use PostgreSQL for Primary Database
+
+## Status
+Accepted
+
+## Context
+We need a database for storing user data and transactions.
+Options considered: PostgreSQL, MySQL, MongoDB, DynamoDB.
+
+## Decision
+Use PostgreSQL with Supabase hosting.
+
+## Rationale
+- Strong ACID compliance needed for financial data
+- Team has PostgreSQL experience
+- Supabase provides auth and realtime features
+- pgvector extension for future AI features
+
+## Consequences
+- Need to manage schema migrations
+- May need read replicas for scale
+- Team needs to learn Supabase-specific features
+```
+
+### Component Documentation
+```markdown
+## Authentication Module
+
+### Overview
+Handles user authentication using JWT tokens with refresh rotation.
+
+### Flow
+1. User submits credentials to `/auth/login`
+2. Server validates and returns access + refresh tokens
+3. Access token used for API requests (15min expiry)
+4. Refresh token used to get new access token (7d expiry)
+
+### Dependencies
+- `jsonwebtoken` - Token generation/validation
+- `bcrypt` - Password hashing
+- `redis` - Refresh token storage
+
+### Configuration
+- `JWT_SECRET` - Secret for signing tokens
+- `ACCESS_TOKEN_EXPIRY` - Access token lifetime
+- `REFRESH_TOKEN_EXPIRY` - Refresh token lifetime
+```
+
+## Documentation Principles
+
+1. **Write for your audience** - New devs vs API consumers
+2. **Keep it close to code** - Docs in same repo, near relevant code
+3. **Update with code** - Stale docs are worse than none
+4. **Examples over explanations** - Show, don't just tell
+5. **Progressive disclosure** - Quick start first, details later

package/bundles/codex/.codex/skills/docs/explainer-doc/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: explainer-doc
+context: fork
+description: Write a document that hands off work to a team who did NOT do the investigation — an external vendor, another team, a contractor — and who must be able to act on it alone. Use when the user says "write a spec for the X team", "document this for someone outside the team", "explainer doc", "implementation spec for a vendor", "hand this off to Y", or is about to write a design doc whose primary reader did not live through the debugging/design process. NOT for internal specs where the reader already has full context (use technical-writing or writing-plans instead) — this is specifically for the "stranger must follow it alone" case.
+---
+
+# explainer-doc — write for the reader who has no other context
+
+A spec written by the people who did the investigation is unreadable by the team who must implement
+it. The authors compress away the reasoning, so every design choice looks arbitrary, and the reader
+either follows it blindly or argues with it. **The fix is not "add more detail" — it is to lead with
+*why*, and to make the document survive being read alone.**
+
+Proven in anger on a Genesys→ETL cutover spec handed to an external vendor team. The user's verdict:
+*"nailed it — the document was perfect, simple, this should be the standard for explainer documents."*
+Reference implementation to study: `serve-sight/docs/genesys-cutover/etl-implementation-spec.md` (full
+spec) and `pega-cticallid-change-request.md` (the same pattern compressed to one page for a single ask).
+
+## When this is NOT the right skill
+
+If the reader already lived through the investigation (a teammate, your future self, an internal
+handoff with shared context), use `technical-writing` or `writing-plans` instead — those are lighter
+and don't need the "assume zero shared context" discipline below. Reach for `explainer-doc` specifically
+when the reader is a **stranger to the problem**: an external vendor, a different team, a contractor,
+anyone who will act on the document with no one in the room to ask.
+
+## The shape — in order. The order IS the pattern
+
+Do not reorder these. Each section's position is load-bearing: later sections lean on earlier ones for
+their justification, and a reader working top-to-bottom needs the "why" before the "what."
+
+| § | Section | Why it must come here |
+|---|---|---|
+| 1 | **Why this exists** — what broke, in a diagram | Every later decision is justified by this. Lead with the failure, not the solution. |
+| 2 | **What we're asking for, in one picture** + a size table | The reader decides here whether the ask is reasonable. Include what you are explicitly **not** asking for. |
+| 3 | **Understanding the source data** — the 3-5 things that catch people out | Each one should have already caused a real bug. Not a data dictionary. |
+| 4 | **The one thing that matters most** | Usually not the new build. Say so plainly, with the number that proves it. |
+| 5 | **Where it runs** + access needed | The blocker nobody writes down until the first deploy fails. |
+| 6 | **What to build**, with the reasoning *beside* each choice | Not in an appendix. Next to the DDL / the query / the config. |
+| 6b | **Changes to what already exists** | Always under-specified. Ask "what did I only half-mention?" — this is where the gaps hide. |
+| 7-8 | The actual implementation (extract/build queries, load procedure, etc.) | |
+| 9 | Schedule / retention / first load | The one-off backfill is always forgotten. |
+| 10 | **Validation, with EXPECTED VALUES** | "Run this, expect ~64%" beats "verify the data." |
+| 11 | Priority · acceptance (who signs off) · **what we excluded** | The exclusion list stops speculative building. |
+| 12 | **Glossary** | Every acronym, inline. Not a link. |
+
+Adapt section names to the domain (this table is ETL-flavored from its origin; a UI handoff, an API
+contract, or an infra runbook will rename §6-9) — but keep the **order and the intent of each slot**.
+
+## The ten rules
+
+1. **Self-contained.** If the reader needs another document to follow this one, the document has
+   failed. Companions are optional background, stated as such — never load-bearing.
+2. **Lead with the failure mode, not the solution.** State what actually went wrong, concretely, before
+   proposing anything. Everything cautious later inherits its justification from that paragraph.
+3. **Reasoning beside the artefact, not in an appendix.** "Cluster on the date not the GUID" with the
+   3-row comparison table right there. An appendix is never read.
+4. **Every number carries its measurement date and a way to reproduce it.** "1.4% of reality (measured
+   2026-07-14, `SELECT ...`)" — not "a small fraction."
+5. **Say what you are NOT asking for.** Prevents speculative work and pre-answers "why not X?" before
+   it's asked.
+6. **Name what is not the reader's fault.** If a gap traces to a third system or a decision made
+   elsewhere, say so explicitly. Saves the reader a week of misdirected chasing and buys credibility for
+   the rest of the document.
+7. **Diagrams for the shape, tables for the detail, prose only for judgement.** No diagram should repeat
+   what a table already says better.
+8. **Validation states expected values.** "It ran" and "it is right" must be two different checks — give
+   the reader the number to compare against.
+9. **Route by owner.** If an item belongs to a third team, mark it as theirs, explicitly, in the document
+   — don't let it read as part of the reader's scope.
+10. **Glossary inline.** The reader will not follow a link mid-implementation; every acronym gets defined
+    where it's used, plus a glossary section as the fallback lookup.
+
+## Process
+
+1. **Confirm the reader.** Ask (or infer from context) who this is actually for and how much they
+   already know. If they have real shared context, stop and suggest `technical-writing`/`writing-plans`
+   instead — this skill's discipline is overhead they don't need.
+2. **Draft §1 first, alone, and get it right before writing anything else.** Every other section's
+   justification traces back to it. If you can't state the failure mode plainly and concretely, the
+   rest of the document will inherit that vagueness.
+3. **Write the shape table above as your outline**, adapting section names to the domain, then fill it
+   in top to bottom. Keep reasoning next to the artefact it justifies (rule 3), not in a separate
+   "design decisions" section.
+4. **Before sending, ask the two questions below** — they are an exit gate, not a suggestion.
+
+## The two-question exit gate
+
+Ask both, honestly, before the document ships:
+
+- **"Could someone who has read nothing else follow this end to end?"** If the answer requires "well,
+  they'd also need to know X" — X is either missing or should be a stated, explicit companion doc.
+- **"What did I mention once and never specify?"** This is the question that surfaces the gaps — in the
+  origin case it found an entire missing section (§6b, changes to existing infrastructure) that had been
+  gestured at once and never actually written.
+
+If either question fails, fix the document — don't ship it and hope the reader asks.

package/bundles/codex/.codex/skills/docs/technical-writing/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: technical-writing
+context: fork
+description: Technical documentation best practices for READMEs, API docs, architecture docs, runbooks, and developer guides. Use when writing or reviewing documentation, creating onboarding guides, or establishing documentation standards.
+---
+
+# Technical Writing Skill
+
+Good documentation is the difference between a project that scales and one that stalls. Write for the reader who has zero context.
+
+## 1. When to Apply This Skill
+
+**Trigger conditions:**
+- Writing or updating a README
+- Creating API documentation
+- Writing architecture decision records (ADRs)
+- Building runbooks or incident playbooks
+- Creating onboarding/developer guides
+- Reviewing documentation for clarity
+
+## 2. Document Types and Templates
+
+### Document Provenance Frontmatter
+
+All descriptive Markdown docs must follow `.github/instructions/document-frontmatter.instructions.md`.
+
+- **New docs**: include `Original Author`, `Creation Date`, and `Creating Model` in YAML frontmatter.
+- **Updated docs**: preserve those original fields and add or update `Last Author`, `Last Updated`, and `Last Model Used`.
+- Use full ISO 8601 UTC timestamps for `Creation Date` and `Last Updated` values.
+- Merge these fields into existing frontmatter instead of replacing document-specific metadata.
+
+### README Structure
+
+Every project README follows this order:
+
+```markdown
+# Project Name
+One-sentence description of what this does and who it's for.
+
+## Quick Start
+Minimum steps to run the project locally (≤5 commands).
+
+## Prerequisites
+- Runtime versions (Python 3.12+, Node 22+)
+- Required tools (Docker, pnpm)
+- Required accounts/access
+
+## Installation
+Step-by-step setup with copy-pasteable commands.
+
+## Usage
+Common tasks with examples.
+
+## Architecture
+Brief overview with a diagram (link to detailed docs).
+
+## Contributing
+How to submit changes, run tests, and follow conventions.
+
+## License
+```
+
+**Rules:**
+- Quick Start must work on a fresh machine in under 5 minutes
+- Every command must be copy-pasteable (no `<placeholder>` without explanation)
+- Test the README by following it literally on a clean environment
+
+### Architecture Decision Record (ADR)
+
+```markdown
+# ADR-{NNN}: {Decision Title}
+
+## Status
+Accepted | Superseded by ADR-{NNN} | Deprecated
+
+## Context
+What problem are we solving? What constraints exist?
+
+## Decision
+What did we decide and why?
+
+## Alternatives Considered
+| Option | Pros | Cons | Why Not |
+|--------|------|------|---------|
+
+## Consequences
+What changes as a result? What new constraints are introduced?
+```
+
+### Runbook/Playbook
+
+```markdown
+# Runbook: {Incident Type}
+
+## Symptoms
+What does the user/monitor see?
+
+## Impact
+Who is affected? What's the blast radius?
+
+## Diagnosis Steps
+1. Check {metric/log/dashboard} — expected: {value}
+2. Run `{command}` — look for {pattern}
+3. ...
+
+## Resolution Steps
+1. {Step with exact command}
+2. {Verification step}
+3. ...
+
+## Escalation
+If not resolved in {time}, contact {team/person}.
+
+## Post-Incident
+- [ ] Update this runbook with new learnings
+- [ ] File ticket for permanent fix
+```
+
+## 3. Writing Principles
+
+### Know Your Reader
+
+| Reader | Needs | Writing Style |
+|--------|-------|--------------|
+| **New developer** | Setup, concepts, where things are | Step-by-step, no assumptions |
+| **Experienced dev** | API reference, edge cases, configuration | Concise, scannable, tables |
+| **Ops/SRE** | Runbooks, monitoring, deployment | Commands, checklists, decision trees |
+| **Stakeholder** | What it does, status, decisions | High-level, diagrams, outcomes |
+
+### The Inverted Pyramid
+
+Put the most important information first. Readers scan, they don't read.
+
+```
+┌─────────────────────────┐
+│    What + Why (lead)    │  ← First paragraph answers the key question
+├─────────────────────────┤
+│  How (details)          │  ← Supporting details, steps, configuration
+├─────────────────────────┤
+│  Reference (appendix)   │  ← Edge cases, history, alternatives
+└─────────────────────────┘
+```
+
+### Plain Language Rules
+
+| Do | Don't |
+|----|-------|
+| "This function returns the user's name" | "This function facilitates the retrieval of the nomenclature associated with the user entity" |
+| "Run `npm install`" | "Execute the package installation command" |
+| "Fails if the file doesn't exist" | "In the event that the specified file is not present in the filesystem, the operation will not succeed" |
+| Short sentences (< 25 words) | Run-on sentences with multiple clauses |
+| Active voice | Passive voice |
+
+## 4. Code Examples in Documentation
+
+### Rules for Code Samples
+
+```python
+# ✅ GOOD: Complete, runnable example with imports
+from datetime import datetime
+from myapp.models import User
+
+def create_user(name: str, email: str) -> User:
+    """Create a user and return the saved instance."""
+    user = User(name=name, email=email, created_at=datetime.now())
+    user.save()
+    return user
+
+# Usage
+user = create_user("Alice", "alice@example.com")
+print(user.id)  # => "usr_abc123"
+```
+
+```python
+# ❌ BAD: Incomplete snippet, no context
+def create_user(name, email):
+    user = User(name=name, email=email)  # What is User? Where is it imported?
+    user.save()  # Does this return something?
+```
+
+**Rules:**
+- Include imports
+- Show expected output in comments
+- Use realistic data (not "foo", "bar", "test")
+- Every example must be copy-pasteable and runnable
+
+## 5. Diagrams
+
+Use diagrams for architecture, data flow, and sequences. Text alone fails for spatial relationships.
+
+### When to Use Each Type
+
+| Diagram | Use For |
+|---------|---------|
+| **Flowchart** | Decision trees, process flows |
+| **Sequence** | API call chains, auth flows |
+| **Architecture** | System overview, service boundaries |
+| **ERD** | Database schema relationships |
+| **State** | Lifecycle transitions (order, ticket) |
+
+### Diagram Rules
+- Label every arrow (what data flows, what triggers the transition)
+- Include a legend if using color coding
+- Keep to 7±2 elements — decompose larger diagrams
+- Store diagrams as code (Mermaid, PlantUML) for version control
+
+## 6. API Documentation
+
+### Endpoint Documentation Template
+
+```markdown
+### `POST /api/v1/customers`
+
+Create a new customer record.
+
+**Auth:** Bearer token required
+
+**Request Body:**
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| name | string | Yes | Customer full name (1-200 chars) |
+| email | string | Yes | Valid email address |
+
+**Response:** `201 Created`
+```json
+{
+  "data": { "id": "cust_abc", "name": "Alice", "email": "alice@example.com" }
+}
+```
+
+**Errors:**
+| Code | When |
+|------|------|
+| 400 | Missing required field |
+| 409 | Email already exists |
+| 422 | Invalid email format |
+```
+
+## 7. Documentation Maintenance
+
+### Keep Docs Near Code
+
+```
+src/
+  auth/
+    login.py
+    README.md        ← Auth module docs live with auth code
+docs/
+  architecture.md    ← System-level docs in docs/
+  runbooks/          ← Operational docs
+```
+
+### Freshness Rules
+
+| Trigger | Action |
+|---------|--------|
+| API endpoint changed | Update API docs in same PR |
+| New environment variable | Update README + .env.example |
+| Architecture decision | Write or update ADR |
+| Production incident | Update or create runbook |
+| New developer onboarded | Test README, fix gaps found |
+
+## 8. Review Checklist
+
+When reviewing documentation:
+
+- [ ] Answers "what does this do?" in the first paragraph
+- [ ] Document frontmatter is present and current
+- [ ] Code examples are complete and runnable
+- [ ] Commands are copy-pasteable
+- [ ] No stale references to old code, endpoints, or config
+- [ ] Diagrams are up to date
+- [ ] Written for the target audience (not the author)
+- [ ] No jargon without definition
+- [ ] Links work and point to current resources
+
+## 9. Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|---|---|---|
+| Docs written once, never updated | Stale docs are worse than no docs | Update in same PR as code changes |
+| Wall of text | Nobody reads it | Use headings, tables, code blocks, diagrams |
+| Documenting obvious code | Noise, maintenance burden | Document "why", not "what" |
+| Screenshots of terminal output | Can't copy-paste, hard to update | Use code blocks with text output |
+| "See the code for details" | Reader has to reverse-engineer | Write the explanation |
+| Assuming reader context | "Just run the usual setup" | Spell out every step |