@caddis/cli 0.0.0 → 0.1.0

package/bundles/antigravity-plugin/skills/implement/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: implement
+description: Headless plan executor — implement an approved plan phase-by-phase on the current feature branch, TDD-first, committing per phase
+---
+
+# /caddis:implement — execute an approved plan (headless driver)
+
+Implement the plan at **$ARGUMENTS** (falls back to the `DOCKET_PLAN` env var if `$ARGUMENTS` is empty).
+
+This command is the **docket Implement lane's driver**. It is spawned autonomously by the docket runner —
+**no human is present**. It does not design or re-plan: the plan is the intelligence, you are the executor.
+The runner independently re-runs the tests and a fresh code-review after you finish and decides success
+itself — so your job is to implement faithfully, commit cleanly, and report honestly. Overstating success
+does not help you; the runner will catch it.
+
+## Non-negotiable safety rules (the runner enforces these too — violating them fails the whole run)
+These override everything below. They exist because branch isolation and the runner's post-run backstops
+depend on them:
+
+- **Work ONLY on the current branch.** You are already on the feature branch (`DOCKET_BRANCH`, e.g.
+  `agent/<slug>`). **NEVER** run `git checkout`, `git switch`, `git branch`, `git switch -c`, or any
+  command that changes, creates, or leaves the current branch. If you somehow find yourself on the default
+  branch (`DOCKET_DEFAULT_BRANCH`), **stop immediately, do not commit**, and emit the failure JSON below —
+  a commit on the default branch fails the run.
+- **NEVER touch git remotes.** No `git push`, `git pull`, `git fetch`, `git remote`, no PR, no merge. The
+  runner never pushes; neither do you.
+- **NEVER edit your own success criteria.** Do not modify `.caddis/PROJECT-FACTS.md`, and do not change
+  the project's test command anywhere (config, CI, package scripts). The runner treats any such edit as
+  tampering and fails the run. If the plan asks you to touch these, skip that step and note it in the
+  review file instead.
+- **Commit per phase, on this branch, with a normal commit.** Use `git add <paths> && git commit -m "…"`.
+  Do not use `--no-verify` (a pre-commit hook guards the branch — let it run). Do not amend or rebase
+  prior commits. One phase → one (or more) commit(s); never one giant end-of-run commit.
+- **Never ask a question, never pause, never wait for input.** No human will answer. Never use
+  AskUserQuestion. Where the plan leaves a genuine gap, make the smallest reasonable assumption, record it
+  in the review file, and proceed — asking is always wrong here.
+
+## What to do
+
+**1. Read the plan.** Load the plan file (`$ARGUMENTS` / `DOCKET_PLAN`). Read its `## Phases`, `## Affected
+files`, `## Constraints & decisions`, and `## Tracker`. Read the `AGENTS.md` at the repo root and in each
+folder you will touch (the canonical rules; `CLAUDE.md` is an `@AGENTS.md` shim), and
+`.caddis/PROJECT-FACTS.md` if present (for the real run/test commands) —
+**read it, never edit it**. Identify the test command the plan/facts specify so you can run it yourself.
+
+**2. Determine where to resume.** The `## Tracker` table is the resume signal. Start at the first phase whose
+status is not `done`/`✅`. If every phase is already done, verify the tests are green and go straight to the
+report — do not redo completed work.
+
+**3. Implement each remaining phase, TDD-first.** For each phase, in order:
+   - **RED** — write the failing test(s) the phase names (`<test file>::<case>`). Run them; confirm they
+     fail for the right reason (the missing behavior, not an import error). If a phase genuinely has no
+     testable surface, say so in the review file and implement the minimal change directly.
+   - **GREEN** — write the **minimum** code to pass. No speculative abstraction, no scope creep beyond the
+     phase. Run the phase's tests; confirm green.
+   - **REFACTOR** — clean names/structure/duplication while keeping green.
+   - **VERIFY** — run the phase's exit-gate check (the literal command the plan names) and the relevant
+     suite so you didn't regress. Do not claim a state you did not run.
+   - **COMMIT** — `git add` the phase's files and `git commit` with the phase's conventional-commit message
+     (from the plan, or a faithful equivalent). Stay on the current branch.
+   - **UPDATE THE TRACKER** — edit the plan's `## Tracker` row for this phase: set Status to `done`, fill
+     the short commit hash (`git rev-parse --short HEAD`) and a one-line note. This is what lets a future
+     session (or the runner) see progress. Commit the Tracker update with the phase (or as a tiny follow-up
+     commit) — it lives in the plan file, which is fine to commit on this branch.
+
+   If a phase cannot be completed (a blocking gap the plan did not resolve, or a rule above would be
+   violated), **stop there**: leave later phases untouched, record the blocker in the review file, mark the
+   Tracker row `blocked`, and report honestly with `"tests":"failed"` — never fake completion.
+
+**4. Run the tests yourself.** After the last phase you complete, run the project's full test command once
+more and record the real result. The runner will re-run it independently and that decides success — but
+you run it too so your reported `"tests"` value is truthful, not assumed. Never report `"passed"` on a
+suite you did not see go green.
+
+**5. Write a concise review file** to the path in the `DOCKET_REVIEW` env var (falls back to
+`.caddis/reviews/<slug>.md`, where `<slug>` is `DOCKET_SLUG`). Create `.caddis/reviews/` if needed.
+Keep it short and scannable — this is what the human reviewer reads before merging the branch:
+
+```markdown
+---
+type: implement-review
+feature: <slug>
+branch: <DOCKET_BRANCH>
+---
+
+# Implement review — <feature>
+**Branch:** `<DOCKET_BRANCH>`  •  **Phases done:** <N of M>  •  **Tests:** passed | failed
+
+## What changed
+- <phase 1 — one line: what shipped + commit hash>
+- <phase 2 — …>
+
+## Assumptions made
+- <any gap the plan left that you decided — or "none">
+
+## Not done / follow-ups
+- <phases skipped/blocked and why — or "none; all phases complete">
+
+## Test result
+`<the exact test command>` → <passed | failed (exit N)> — <one line>
+```
+
+**6. End with EXACTLY one fenced `json` block** as the final output — nothing after it. `phases_done` is the
+count of phases you actually completed (Tracker rows now `done`); `tests` is what your own run in step 4
+showed; `review` is the review-file path you wrote:
+
+```json
+{"implemented":true,"phases_done":<int>,"tests":"passed|failed","review":".caddis/reviews/<slug>.md"}
+```
+
+If you had to stop before implementing anything (e.g. you were on the default branch, or the plan was
+unreadable), still end with the block using `"implemented":false,"phases_done":0,"tests":"failed"` and put
+the reason in the review file. The only acceptable final output is the code + commits + review file + this
+one JSON block — never questions, never prose after the block.

package/bundles/antigravity-plugin/skills/javascript-typescript/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: javascript-typescript
+description: JavaScript and TypeScript development with ES6+, Node.js, React, and modern web frameworks. Use for frontend, backend, or full-stack JavaScript/TypeScript projects.
+source: wshobson/agents
+license: MIT
+---
+
+# JavaScript/TypeScript Development
+
+## TypeScript Configuration
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+## Type Patterns
+
+### Utility Types
+```typescript
+// Pick specific properties
+type UserPreview = Pick<User, 'id' | 'name'>;
+
+// Omit properties
+type CreateUser = Omit<User, 'id' | 'createdAt'>;
+
+// Make all properties optional
+type PartialUser = Partial<User>;
+
+// Make all properties required
+type RequiredUser = Required<User>;
+
+// Extract union types
+type Status = 'pending' | 'active' | 'inactive';
+type ActiveStatus = Extract<Status, 'active' | 'pending'>;
+```
+
+### Discriminated Unions
+```typescript
+type Result<T> =
+  | { success: true; data: T }
+  | { success: false; error: Error };
+
+function handleResult<T>(result: Result<T>) {
+  if (result.success) {
+    console.log(result.data); // T
+  } else {
+    console.error(result.error); // Error
+  }
+}
+```
+
+### Generic Constraints
+```typescript
+interface HasId {
+  id: string | number;
+}
+
+function findById<T extends HasId>(items: T[], id: T['id']): T | undefined {
+  return items.find(item => item.id === id);
+}
+```
+
+## Modern JavaScript
+
+### Destructuring & Spread
+```javascript
+const { name, ...rest } = user;
+const merged = { ...defaults, ...options };
+const [first, ...others] = items;
+```
+
+### Optional Chaining & Nullish Coalescing
+```javascript
+const city = user?.address?.city ?? 'Unknown';
+const count = data?.items?.length ?? 0;
+```
+
+### Array Methods
+```javascript
+const adults = users.filter(u => u.age >= 18);
+const names = users.map(u => u.name);
+const total = items.reduce((sum, item) => sum + item.price, 0);
+const hasAdmin = users.some(u => u.role === 'admin');
+const allActive = users.every(u => u.active);
+```
+
+## React Patterns
+
+```typescript
+// Props with children
+interface CardProps {
+  title: string;
+  children: React.ReactNode;
+}
+
+// Event handlers
+interface ButtonProps {
+  onClick: (event: React.MouseEvent<HTMLButtonElement>) => void;
+}
+
+// Custom hooks
+function useLocalStorage<T>(key: string, initial: T) {
+  const [value, setValue] = useState<T>(() => {
+    const stored = localStorage.getItem(key);
+    return stored ? JSON.parse(stored) : initial;
+  });
+
+  useEffect(() => {
+    localStorage.setItem(key, JSON.stringify(value));
+  }, [key, value]);
+
+  return [value, setValue] as const;
+}
+```
+
+## Node.js Patterns
+
+```typescript
+// ES Modules
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+// Error handling
+process.on('unhandledRejection', (reason) => {
+  console.error('Unhandled Rejection:', reason);
+  process.exit(1);
+});
+```

package/bundles/antigravity-plugin/skills/kb/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: kb
+description: Rebuild the KB index (.caddis/kb/DOC-MAP.md) — create it if missing, index un-indexed notes, report dangling links
+---
+
+# /kb — bring the knowledge-base index up to date
+
+Reconcile `.caddis/kb/DOC-MAP.md` (the KB index) with the notes on disk. Use this in a repo that
+has the harness but no KB yet (the KB was introduced recently), or after adding/removing KB notes.
+
+## Step 1 — locate the checker
+It ships with the harness. Try, in order:
+- `scripts/check_doc_coverage.py` — a project set up via `setup-project-ai` (checker copied in).
+- `claude-harness/scripts/check_doc_coverage.py` — the harness source repo itself.
+
+## Step 2 — run the reindexer
+```
+python <path>/check_doc_coverage.py --reindex
+```
+It is **additive and safe** — never deletes your rows:
+- **Missing map** → creates `.caddis/kb/DOC-MAP.md` from a scaffold, pre-linking the repo's obvious
+  reference docs (README, `docs/…`) and any existing `.caddis/kb/*.md` notes.
+- **Existing map** → indexes any KB note that isn't yet linked (adds a row with a placeholder description).
+- **Dangling links** (a linked file that's gone) → **reported, not removed** — handle them in Step 3.
+
+## Step 3 — finish by hand
+Read the `[kb]` summary it printed, then:
+- For each **newly auto-indexed** note, open it and replace the placeholder description with a real
+  one-line "what / when to read".
+- If it reported **dangling** links (a linked file that's gone), decide per link:
+  - The note was **moved/renamed** → fix the link target by hand.
+  - The note is **gone for good** → remove its row. To clear all dangling rows at once, use the
+    destructive opt-in — but **show the dangling list and confirm with the user first**:
+    ```
+    python <path>/check_doc_coverage.py --prune
+    ```
+    `--prune` removes *only* index rows that link to missing files (never valid rows, never prose),
+    and still indexes any orphan notes in the same run.
+
+## Step 4 — verify clean
+```
+python <path>/check_doc_coverage.py --check
+```
+Exit `0` = the index is honest (no dangling links; every note indexed). The SessionStart hook will now
+surface the `[DOC-MAP]` "read the index first" pointer for future sessions in this repo.
+
+## KB note format (OKF-lite — mandatory for every new note)
+
+Every new `.caddis/kb/*.md` note starts with this frontmatter block (`type` is required;
+the rest recommended). `DOC-MAP.md` is the index, not a note — it stays frontmatter-free:
+
+```yaml
+---
+type: note                 # note | runbook | design | reference
+title: <human title>
+description: <one line — keep it identical to the note's DOC-MAP row description>
+tags: [topic, topic]
+timestamp: 2026-01-01      # ISO date of last substantive update
+---
+```

package/bundles/antigravity-plugin/skills/mermaid-db/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: mermaid-db
+description: Turn a SQL artifact (proc, view, query, .sql file, or table name) into a Mermaid diagram that explains it — git-diffable, saved as .md
+---
+
+# /mermaid-db — diagram a SQL artifact as Mermaid
+
+Explain a SQL artifact to a human as a **Mermaid** diagram (the default format: plain text, diffs cleanly
+in git, renders natively in VS Code and Gitea, regenerable when the schema changes).
+
+Input: **$ARGUMENTS**
+
+## Do this
+
+Load and follow the **`db-diagram`** skill end-to-end. In short:
+
+1. **Get the SQL** — from a file path, a DB object name (look it up via a DB MCP tool if available, else
+   read-only `sqlcmd`/`psql`, else ask), the current file in context, or pasted SQL. Multiple objects →
+   ONE diagram of their relationships.
+2. **Extract deterministically** — run the skill's `scripts/sql_to_graph.py` (sqlglot-based) to get the
+   typed node/edge graph + a Mermaid skeleton. Don't hand-derive the nodes when the script can run.
+3. **Narrate** — add a business-terms paragraph above, a per-source-table description list below, the
+   source path/object name, a generation date, and the execution-plan caveat (verbatim, per the skill).
+4. **Validate + save** — confirm the Mermaid parses; save as `.md` (default `docs/diagrams/<object>.md`,
+   overridable by a second argument). If the file exists, **diff and report what changed** — never
+   silently overwrite.
+
+## Rules (from the skill — non-negotiable)
+
+- **Read-only.** Never run DDL/DML. The extractor only parses SQL text.
+- **Never guess schema.** Verify tables/columns against the real DB; mark anything inferred-from-SQL-only.
+- If the extractor reports `partial` confidence (or sqlglot is missing), say so — the diagram is
+  best-effort, not authoritative.

package/bundles/antigravity-plugin/skills/mermaid-diagrams/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: mermaid-diagrams
+context: fork
+description: Create software diagrams using Mermaid text-based syntax. Use for class diagrams (domain modeling, OOP design), sequence diagrams (API flows, interactions), flowcharts (processes, algorithms, user journeys), ERD (database schemas), C4 architecture diagrams, state diagrams, git graphs, gantt charts, and data visualization.
+---
+
+# Mermaid Diagramming
+
+**Works with:** Any AI coding agent (Claude, Cursor, GitHub Copilot, Windsurf, etc.)
+
+Create professional software diagrams using Mermaid's text-based syntax. Diagrams are version-controllable, easy to update, and render automatically in GitHub, GitLab, Notion, and more.
+
+## Triggers
+
+Use this skill when you need to:
+- "diagram this", "visualize this", "model this"
+- "show the flow", "map out the process"
+- "architecture diagram", "class diagram", "sequence diagram"
+- "database schema", "ERD", "entity relationship"
+- "flowchart", "user journey", "system design"
+
+## Quick Reference
+
+| Diagram Type | Use For | Syntax Starts With |
+|--------------|---------|-------------------|
+| **Class Diagram** | Domain models, OOP design | `classDiagram` |
+| **Sequence Diagram** | API flows, interactions | `sequenceDiagram` |
+| **Flowchart** | Processes, algorithms, user journeys | `flowchart TD` or `flowchart LR` |
+| **ERD** | Database schemas | `erDiagram` |
+| **C4 Diagram** | Architecture (context, container, component) | `C4Context`, `C4Container`, `C4Component` |
+| **State Diagram** | State machines, lifecycles | `stateDiagram-v2` |
+| **Git Graph** | Branching strategies | `gitGraph` |
+| **Gantt Chart** | Project timelines | `gantt` |
+
+## Core Syntax Pattern
+
+All Mermaid diagrams follow this structure:
+
+```mermaid
+diagramType
+  definition content
+```
+
+**Key principles:**
+- First line declares diagram type
+- Use `%%` for comments
+- Indentation improves readability
+- Misspellings break diagrams; validate at [mermaid.live](https://mermaid.live)
+
+## Quick Start Examples
+
+### Class Diagram
+```mermaid
+classDiagram
+    User --> Order : places
+    Order *-- LineItem
+    
+    class User {
+        +string email
+        +string name
+        +placeOrder()
+    }
+    
+    class Order {
+        +int id
+        +decimal total
+        +addItem()
+    }
+```
+
+### Sequence Diagram
+```mermaid
+sequenceDiagram
+    participant User
+    participant API
+    participant DB
+    
+    User->>API: POST /login
+    API->>DB: Query credentials
+    DB-->>API: Return user data
+    alt Valid
+        API-->>User: 200 OK + token
+    else Invalid
+        API-->>User: 401 Unauthorized
+    end
+```
+
+### Flowchart
+```mermaid
+flowchart TD
+    Start([User visits]) --> Auth{Authenticated?}
+    Auth -->|No| Login[Login page]
+    Auth -->|Yes| Dashboard[Dashboard]
+    Login --> Validate{Valid?}
+    Validate -->|Yes| Dashboard
+    Validate -->|No| Error[Error message]
+```
+
+### ERD
+```mermaid
+erDiagram
+    USER ||--o{ ORDER : places
+    ORDER ||--|{ LINE_ITEM : contains
+    
+    USER {
+        int id PK
+        string email UK
+        string name
+    }
+    
+    ORDER {
+        int id PK
+        int user_id FK
+        decimal total
+    }
+```
+
+### C4 Context
+```mermaid
+C4Context
+    title System Context
+    
+    Person(user, "User", "Customer")
+    System(app, "Web App", "E-commerce platform")
+    System_Ext(payment, "Payment Gateway")
+    
+    Rel(user, app, "Browses, purchases")
+    Rel(app, payment, "Processes payments", "HTTPS")
+```
+
+## Essential Syntax
+
+### Relationships (Class/ERD)
+```
+-->   Association
+..>   Dependency
+--|>  Inheritance/Generalization
+--*   Composition
+--o   Aggregation
+```
+
+### Arrows (Sequence/Flowchart)
+```
+->>   Solid arrow (sync message)
+-->>  Dashed arrow (response)
+-->   Flowchart connection
+```
+
+### Node Shapes (Flowchart)
+```
+[]    Rectangle
+()    Rounded
+{}    Diamond (decision)
+([])  Stadium/pill
+[()]  Cylinder (database)
+```
+
+### Cardinality (ERD)
+```
+||--||  One to one
+||--o{  One to many
+}o--o{  Many to many
+```
+
+## Configuration
+
+Add themes and styling:
+
+```mermaid
+---
+config:
+  theme: base
+  themeVariables:
+    primaryColor: "#ff6b6b"
+  look: handDrawn
+---
+flowchart LR
+    A --> B
+```
+
+**Themes:** default, forest, dark, neutral, base  
+**Look:** classic, handDrawn
+
+## Export & Rendering
+
+**Auto-renders in:**
+- GitHub/GitLab Markdown
+- VS Code (with Mermaid extension)
+- Notion, Obsidian, Confluence
+
+**Export to PNG/SVG:**
+- Online: [mermaid.live](https://mermaid.live)
+- CLI: `npm install -g @mermaid-js/mermaid-cli`
+  ```bash
+  mmdc -i diagram.mmd -o diagram.png
+  ```
+
+## Best Practices
+
+1. **Start simple** - Core elements first, add details incrementally
+2. **One concept per diagram** - Split complex views into focused diagrams
+3. **Use clear labels** - Meaningful names make diagrams self-documenting
+4. **Comment extensively** - Use `%%` to explain complex parts
+5. **Validate syntax** - Test at [mermaid.live](https://mermaid.live) before committing
+6. **Version control** - Store `.mmd` files with code
+7. **Keep updated** - Update diagrams when code changes
+
+## Common Issues
+
+**Diagram won't render:**
+- Check for typos in diagram type declaration
+- Validate syntax at [mermaid.live](https://mermaid.live)
+- Avoid special characters in labels (use quotes if needed)
+
+**Arrows not connecting:**
+- Verify node IDs match exactly
+- Check arrow syntax (`-->` vs `->>` vs `-->>`)
+
+**Layout looks wrong:**
+- Try different direction: `TD` (top-down), `LR` (left-right), `RL`, `BT`
+- Use subgraphs to group related elements
+- Consider splitting into multiple diagrams
+
+## Detailed References
+
+See `references/` for comprehensive syntax:
+
+- **[class-diagrams.md](references/class-diagrams.md)** - Relationships, multiplicity, methods, domain modeling
+- **[sequence-diagrams.md](references/sequence-diagrams.md)** - Messages, activations, loops, alt/opt blocks
+- **[flowcharts.md](references/flowcharts.md)** - Shapes, subgraphs, styling, complex flows
+- **[erd-diagrams.md](references/erd-diagrams.md)** - Entities, cardinality, keys, attributes
+- **[c4-diagrams.md](references/c4-diagrams.md)** - Context, container, component levels
+- **[architecture-diagrams.md](references/architecture-diagrams.md)** - Cloud services, infrastructure, deployment
+- **[advanced-features.md](references/advanced-features.md)** - Themes, configuration, layout options
+- **[workflows.md](references/workflows.md)** - Step-by-step examples
+- **[troubleshooting.md](references/troubleshooting.md)** - Common problems and solutions