@hegemonart/get-design-done 1.59.3 → 1.59.5

package/scripts/skill-templates/state/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: gdd-state
+description: "Query, recover, or roll back the Phase 57 SQLite state backbone. Use when you need to inspect the decisions/blockers/plans tables with a raw SELECT, rebuild a corrupt state.sqlite from the markdown STATE.md, or revert to the markdown-only source of truth by removing state.sqlite. Activates for requests involving querying the SQLite state database, recovering from SQLite corruption, or reverting the migration (demigrate)."
+argument-hint: "<query \"<sql>\" | recover | demigrate>"
+user-invocable: true
+tools: Read, Bash, Grep, Glob
+---
+
+# {{command_prefix}}state
+
+The Phase 57 SQLite state backbone is opt-in (`--migrate-state`) and fully reversible.
+Markdown `.design/STATE.md` is always the human-editable SoT; SQLite is a faster query
+layer derived from it. This skill exposes three subcommands for operating on that layer.
+
+## Subcommands
+
+| Subcommand | What it does |
+|---|---|
+| `{{command_prefix}}state query "<sql>"` | Run a read-only SELECT against `.design/state.sqlite`. |
+| `{{command_prefix}}state recover` | Rotate the current sqlite to a `.bak` and rebuild from markdown. |
+| `{{command_prefix}}state demigrate` | Remove `.design/state.sqlite`; markdown becomes the SoT again. |
+
+---
+
+## query
+
+Execute a read-only SELECT against the state database.
+
+The engine opens the file with `readonly:true` so all writes are rejected at the
+engine level. A first-token denylist (Set membership, no regex) additionally blocks
+DROP, DELETE, UPDATE, INSERT, ALTER, ATTACH, CREATE, PRAGMA, VACUUM, ANALYZE,
+REINDEX, and REPLACE before the connection is opened.
+
+```bash
+node -e '
+  const qs = require("./scripts/lib/state/query-surface.cjs");
+  const result = qs.query(process.argv[1], { projectRoot: process.cwd() });
+  console.log(JSON.stringify(result, null, 2));
+' "<sql>"
+```
+
+Outputs `{ rows: [...], backend: "sqlite" }` on success, or
+`{ degraded: true, message: "..." }` when SQLite is not active.
+
+Degrades gracefully (no throw) when `BACKEND==='markdown'` or when
+`.design/state.sqlite` has not been created yet (run `--migrate-state` first).
+
+---
+
+## recover
+
+Rotate the current (possibly corrupt) `.design/state.sqlite` to `.bak.0`, then
+rebuild a fresh database from the markdown `.design/STATE.md` using
+`migrate-to-sqlite.cjs` in force mode. Runs `PRAGMA integrity_check` on the
+result and reports the outcome.
+
+```bash
+node -e '
+  const qs = require("./scripts/lib/state/query-surface.cjs");
+  const result = qs.recover({ projectRoot: process.cwd() });
+  console.log(JSON.stringify(result, null, 2));
+'
+```
+
+Outputs `{ recovered: true, integrity: true, message: "..." }` on success.
+
+Backup rotation keeps at most 10 files (`.bak.0` through `.bak.9`). The oldest
+backup is overwritten when the cap is reached.
+
+---
+
+## demigrate
+
+Remove `.design/state.sqlite` so the markdown `STATE.md` becomes the SoT again.
+Idempotent: if the file does not exist, returns a clear no-op message without error.
+A backup is taken in `.bak.0` before removal.
+
+```bash
+node -e '
+  const qs = require("./scripts/lib/state/query-surface.cjs");
+  const result = qs.demigrate({ projectRoot: process.cwd() });
+  console.log(JSON.stringify(result, null, 2));
+'
+```
+
+Outputs `{ demigrated: true, message: "..." }` when the file was removed, or
+`{ demigrated: false, message: "..." }` when it was already absent (no-op).
+
+To re-enable SQLite after a demigrate, run `--migrate-state` again.
+
+---
+
+## Key design decisions
+
+- **Markdown is always the SoT.** SQLite is opt-in via `--migrate-state` and
+  reversible via `demigrate`. The markdown file is never silently overwritten.
+- **Read-only queries only.** The `query` subcommand enforces SELECT-only via both
+  the engine (`readonly:true`) and a defense-in-depth denylist. No writes
+  are possible through this skill.
+- **Backup rotation cap.** `rotateBak` shifts `.bak.0..8` up by one index and caps
+  at `.bak.9` (10 files total). The oldest backup is overwritten automatically.
+- **Graceful degradation.** All subcommands return a clear `{ degraded, message }`
+  object (no throw) when `better-sqlite3` is not installed or when
+  `GDD_STATE_BACKEND=markdown` is set.
+
+## STATE COMPLETE

package/scripts/skill-templates/stats/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: gdd-stats
+description: "Cycle stats - decisions made, tasks completed, commits, timeline, git metrics."
+tools: Read, Bash
+disable-model-invocation: true
+---
+
+# {{command_prefix}}stats
+
+**Role:** Print cycle metrics.
+
+## Step 1 - Read state
+
+Read `.design/STATE.md`. Extract:
+- `cycle:` and `started_at` (or per-cycle start date if present in CYCLES.md)
+- D-XX count under `<decisions>`
+
+## Step 2 - Collect git metrics
+
+Let `<since>` = cycle start date (fallback to STATE.md `started_at`).
+
+```bash
+git log --oneline --since="<since>" | wc -l          # commits
+git diff --stat HEAD~N HEAD                          # files changed since cycle start
+```
+
+If git unavailable, print `git: unavailable` and skip git metrics.
+
+## Step 3 - Count todos
+
+Read `.design/TODO.md` if present:
+- pending: count `- [ ]`
+- in-progress: count `- [-]`
+- done: count `- [x]`
+- group pending by P0/P1/P2/P3 section
+
+## Step 4 - Output
+
+```
+━━━ Cycle stats ━━━
+Cycle: cycle-1   Started: 2026-04-18
+Decisions made: 12 (D-01..D-12)
+Tasks completed: 8 / 10
+Git commits:     23
+Files changed:   47
+Open todos:      3 (P0: 1, P1: 2, P2: 0, P3: 0)
+Agents spawned:  — (no task log)
+━━━━━━━━━━━━━━━━━━
+```
+
+## STATS COMPLETE

package/scripts/skill-templates/style/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: gdd-style
+description: "Generate a component handoff doc at `.design/DESIGN-STYLE-<ComponentName>.md` by dispatching the `design-doc-writer` agent in one of two modes: post-pipeline (uses `DESIGN-SUMMARY.md`) or pre-pipeline fallback (uses `DESIGN.md` + source). Use when the user wants a single-component spec covering tokens, states, and AI-slop detection. Invoke with a ComponentName, or with no argument to list available components."
+argument-hint: "[ComponentName]"
+user-invocable: true
+---
+
+# gdd-style - Component Handoff Doc Generator
+
+Generates a per-component style spec at `.design/DESIGN-STYLE-[ComponentName].md`. This is a **standalone command**, not a pipeline stage.
+
+For the full mode-detection logic, source-resolution fallback chain (10 paths), agent-spawn payload, and STYL-05 section spec, see `./style-doc-procedure.md`. For the cross-skill output discipline (artifact prefix, completion marker, MUST-NOT-write list), see `../../reference/shared-preamble.md#output-contract-reminders`. For the raw-hex audit signal used in Token Semantic Health Score, see `../../reference/shared-preamble.md#token-first-reasoning`.
+
+Output artifact naming: `.design/DESIGN-STYLE-[ComponentName].md` - Title-cased component name, one file per invocation.
+
+---
+
+## Scope
+
+This command is **additive and non-destructive**:
+
+- It is NOT a pipeline stage - no `.design/STATE.md` read or write contract.
+- Output lives in the `DESIGN-STYLE-*.md` namespace - distinct from the pipeline namespace (`DESIGN.md`, `DESIGN-CONTEXT.md`, `DESIGN-PLAN.md`, `DESIGN-SUMMARY.md`, `DESIGN-VERIFICATION.md`).
+- It does not modify any pipeline artifact.
+- It does not invoke the pipeline router.
+- One doc per invocation - no batch mode in v3.
+
+This separation is a pre-roadmap decision recorded in `.planning/STATE.md`: utility commands use distinct prefixes (`DESIGN-STYLE-[Component].md`); the pipeline owns the `DESIGN-*.md` namespace without qualifiers.
+
+---
+
+## Workflow
+
+1. **Argument check** - if `$ARGUMENTS` is empty, enter list mode (see `./style-doc-procedure.md#component-source-resolution`); display available components from `src/components/` + `.design/tasks/`, then exit.
+2. **Mode detect** - `DESIGN-SUMMARY.md` exists → post-pipeline; else `DESIGN.md` exists → pre-pipeline; else abort with a "run /get-design-done scan first" message. Full decision tree at `./style-doc-procedure.md#mode-detection`.
+3. **Source resolve** - search the 10-path fallback chain for a file matching the ComponentName. On zero matches: abort. On multiple matches: prompt the user to disambiguate.
+4. **Agent spawn** - dispatch `design-doc-writer` with the mode-specific `<required_reading>` block and the STYL-05 section list. The full Task payload + STYL-05 spec live in `./style-doc-procedure.md#agent-spawn-payload`.
+5. **Confirm + report** - after the agent emits `## DOC COMPLETE`, verify the output path exists and report success.
+
+---
+
+## Constraints
+
+This command MUST NOT (per `../../reference/shared-preamble.md#output-contract-reminders`):
+
+- Write to `DESIGN.md`, `DESIGN-SUMMARY.md`, `DESIGN-VERIFICATION.md`, `DESIGN-CONTEXT.md`, or `.design/STATE.md`
+- Invoke the pipeline router (this command is a leaf invocation, not a pipeline stage)
+- Require Figma or Refero MCPs - v3 uses only local source files and `.design/` artifacts (MCP enrichment is reserved for a future version)
+- Produce more than one output file per invocation - no batch mode in v3
+
+---
+
+## Examples
+
+**Example 1: Named component**
+
+```
+/get-design-done style Button
+```
+
+Resolves `src/components/Button.tsx`, detects post-pipeline mode (DESIGN-SUMMARY.md exists), spawns `design-doc-writer` with `pipeline_complete: true`, writes `.design/DESIGN-STYLE-Button.md`.
+
+**Example 2: No argument (list mode)**
+
+```
+/get-design-done style
+```
+
+Globs component files and prompts the user to specify a ComponentName. Exits without generating any file. See `./style-doc-procedure.md#component-source-resolution` for the full glob path list.
+
+## STYLE COMPLETE

package/scripts/skill-templates/style/style-doc-procedure.md

@@ -0,0 +1,150 @@
+---
+name: style-doc-procedure
+type: meta-rules
+version: 1.0.0
+phase: 28.5
+tags: [style, handoff, component-spec, doc-writer, procedure, extracted]
+last_updated: 2026-05-18
+---
+
+Source: extracted from `skills/style/SKILL.md` (Phase 28.5 rework - D-10 extract-then-link).
+The skill's essential routing + mode-detection stays in `../skills/style/SKILL.md`; this file
+holds the agent-spawn payload, source-resolution paths, and the per-section spec the
+`design-doc-writer` agent produces. See `./shared-preamble.md#output-contract-reminders` for
+the cross-skill output discipline.
+
+# Style Doc Procedure
+
+Detailed procedure for the `gdd-style` standalone command - companion to
+`../skills/style/SKILL.md`. Read this file when executing the agent-spawn step (Step 4 in the
+skill) or when wiring the source-resolution fallback chain. The SKILL.md keeps the essential
+mode detection + decision tree; this file holds the deep methodology.
+
+---
+
+## Mode Detection
+
+```
+If .design/DESIGN-SUMMARY.md exists:
+  mode = post-pipeline   (STYL-03)
+  pipeline_complete = true
+
+Elif .design/DESIGN.md exists:
+  mode = pre-pipeline    (STYL-04)
+  pipeline_complete = false
+
+Else:
+  Abort: "No .design/ artifacts found. Run /get-design-done scan first to initialize."
+```
+
+The mode controls which files are supplied to the agent in `<required_reading>`.
+
+---
+
+## Component Source Resolution
+
+Search for a source file matching the provided ComponentName (case-insensitive):
+
+1. `src/components/[ComponentName].tsx`
+2. `src/components/[ComponentName].jsx`
+3. `src/components/[ComponentName].vue`
+4. `src/components/[ComponentName].svelte`
+5. `src/**/[ComponentName]/index.tsx`
+6. `src/**/[ComponentName]/index.jsx`
+7. `components/[ComponentName].tsx`
+8. `components/[ComponentName].jsx`
+9. `components/[ComponentName].vue`
+10. `components/[ComponentName].svelte`
+
+**If multiple matches found:** Present the list to the user and prompt them to specify the exact path. Do not proceed until a single file is selected.
+
+**If zero matches found:** Abort with: "Component [ComponentName] not found in expected paths. Verify the name matches a file in src/components/ or components/."
+
+When `$ARGUMENTS` is empty, the skill enters **list mode** - glob the same source roots, also list task names from `.design/tasks/*.md` (if directory exists), display the list, and prompt the user to specify a ComponentName. Exit without generating any file.
+
+---
+
+## Agent Spawn Payload
+
+Once mode and source path are resolved, spawn the `design-doc-writer` agent:
+
+```
+Task("design-doc-writer", """
+<required_reading>
+[If pipeline_complete=true:]
+@.design/STATE.md
+@.design/DESIGN-SUMMARY.md
+@.design/DESIGN-CONTEXT.md
+@<component_source_path>
+[Else (pipeline_complete=false):]
+@.design/DESIGN.md
+@<component_source_path>
+@reference/anti-patterns.md
+@reference/audit-scoring.md
+</required_reading>
+
+Generate a handoff spec for component <ComponentName>.
+
+Context:
+  component_name: <ComponentName>
+  component_source_path: <resolved absolute path>
+  pipeline_complete: <true|false>
+  output_path: .design/DESIGN-STYLE-<ComponentName>.md
+
+Produce the doc per STYL-05 sections:
+  - Spacing Tokens (used by component)
+  - Color Tokens (used by component)
+  - Typography Scale (used by component)
+  - Component States (default, hover, focus, active, disabled, etc.)
+  - Token Semantic Health Score (raw-hex-ratio formula — see ./shared-preamble.md#token-first-reasoning)
+  - AI-Slop Detection (using ./anti-patterns.md BAN/SLOP patterns)
+  [If pipeline_complete=true:]
+  - Decisions Applied (D-XX from DESIGN-SUMMARY.md that mention this component)
+
+Emit ## DOC COMPLETE when the output file is written.
+""")
+```
+
+After the agent emits `## DOC COMPLETE`, confirm the file exists at `output_path` and report success to the user.
+
+---
+
+## STYL-05 Section Spec
+
+Each generated `.design/DESIGN-STYLE-[ComponentName].md` SHOULD contain (in this order):
+
+1. **Spacing Tokens** - every spacing token the component uses (paddings, gaps, margins). Cross-reference `./composition.md` for the 4 px / 8 px modular scale discipline.
+2. **Color Tokens** - every color token the component uses (background, foreground, border, focus ring, state-overlays). Cross-reference `./palette-catalog.md` for naming convention and `./shared-preamble.md#token-first-reasoning` for the raw-hex audit threshold.
+3. **Typography Scale** - type ramps the component reaches into (label, body, code, etc.) with size + line-height + weight. Cross-reference `./typography.md`.
+4. **Component States** - default, hover, focus, active, disabled, loading, error. Each row: token diff vs default.
+5. **Token Semantic Health Score** - raw-hex ratio = `raw_hex_count / total_color_uses`. Healthy < 5 %.
+6. **AI-Slop Detection** - apply `./anti-patterns.md` `BAN-*` and `SLOP-*` patterns to the component source. List violations.
+7. **Decisions Applied** (post-pipeline only) - D-XX entries from `DESIGN-SUMMARY.md` that name or describe this component.
+
+---
+
+## Examples
+
+**Example 1: Named component**
+
+```
+/get-design-done style Button
+```
+
+- Resolves component: `src/components/Button.tsx`
+- Detects mode: DESIGN-SUMMARY.md exists → post-pipeline
+- Spawns `design-doc-writer` with `pipeline_complete: true`
+- Output: `.design/DESIGN-STYLE-Button.md`
+
+**Example 2: No argument (list mode)**
+
+```
+/get-design-done style
+```
+
+- Globs component files from `src/components/`
+- Displays available components and exits without generating any file.
+
+---
+
+*Imported by: `../skills/style/SKILL.md`. Maintained as part of Phase 28.5 (Bucket 2 rework).*

package/scripts/skill-templates/synthesize/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: synthesize
+description: "Streaming synthesizer - collapses N parallel-agent markdown outputs into one compact merged summary via a single Haiku 4.5 call. Invoked inline by orchestrators (skills/map/, skills/explore/, skills/plan/) after parallel spawns return. Not user-invocable."
+tools: Read, Task
+user-invocable: false
+disable-model-invocation: true
+---
+
+@reference/shared-preamble.md
+
+# synthesize
+
+## Role
+
+Reusable streaming synthesizer. You receive N markdown strings (parallel-agent outputs) plus a directive, emit one compact merged output in the format the directive specifies. Inline-invoked - no Task() spawn overhead; thin Haiku 4.5 merge call wrapped in a skill.
+
+You are not an orchestrator, not an auditor, not a second-pass reviewer. You preserve every distinct signal from the inputs, consolidate duplicates with source tags, and return a single merged artifact. The invoking orchestrator writes the result to disk; you do not touch the filesystem.
+
+## When to use
+
+**Use synthesize when:**
+- Parallel-mapper / parallel-researcher produced N overlapping outputs and main-context doesn't need them verbatim.
+- The downstream consumer wants one cross-cutting summary (e.g., `.design/DESIGN-PATTERNS.md` merged from 5 per-concern mappers).
+- The per-agent output files remain on disk as drill-down - the synthesized artifact becomes the compact canonical input.
+
+**Do NOT use synthesize when:**
+- A single-agent flow produced the output (nothing to merge).
+- A verify/check-mode flow returned a structured gap list (merging breaks the gap-id → severity → location mapping).
+- A downstream consumer needs every byte verbatim for grep (e.g., decision-wiring checker that matches exact D-XX anchors).
+
+## Input Contract
+
+The invoking orchestrator passes three fields:
+
+- `outputs: string[]` - N labeled strings, each pre-labeled with `=== from <agent-name> ===\n<content>` so the merge call can trace per-signal provenance.
+- `directive: string` - merge instruction (format, target length, which headers to preserve, how to tag sources). Default when empty: `"produce a single merged summary preserving all distinct signals, grouped by natural section headers"`.
+- `output_shape: "markdown" | "json"` - controls the output format. Defaults to `"markdown"`.
+
+## Implementation
+
+Single Haiku 4.5 call with this exact merge-prompt template:
+
+```
+You have received {N} outputs from parallel agents. Each output is labeled with its source.
+
+Directive: {directive}
+
+Outputs:
+{each labeled with === from <agent-name> === and its full content}
+
+Produce the merged result in the format specified by the directive.
+Preserve every distinct signal — do NOT drop content. Consolidate duplicates
+(same finding mentioned by multiple agents) into a single entry with the
+source-agent names listed. Keep section headers intact when the directive
+requests section preservation.
+
+Emit ONLY the merged output — no preamble, no meta-commentary.
+```
+
+Tier is hard-coded to `haiku` per D-14. Orchestrators should **not** re-route this to Sonnet - the merge is structure-preserving, not generative, and Haiku handles it without quality loss.
+
+## Output Contract
+
+- **Markdown shape (`output_shape: "markdown"`)** → emit the merged markdown inline, then `## SYNTHESIS COMPLETE` on its own final line. No code fence wrapping the merged output.
+- **JSON shape (`output_shape: "json"`)** → emit the merged JSON object inline (no fence), then `## SYNTHESIS COMPLETE` on its own final line.
+
+The orchestrator is responsible for:
+- Stripping the `## SYNTHESIS COMPLETE` marker before writing to the target file.
+- Persisting the merged artifact to disk (e.g., `.design/DESIGN-PATTERNS.md`).
+- Keeping per-agent files on disk as drill-down evidence.
+
+## Cost and Tier
+
+Hard-coded to Haiku 4.5 per D-14. `budget.json.tier_overrides.synthesize` can override. Typical cost per invocation: $0.002–$0.02 - dominated by input tokens (5 × ~1500-line mapper outputs ≈ 7.5k input tokens, merge output ≈ 1k output tokens).
+
+## Failure Modes
+
+- **Empty `outputs: []`** → emit an empty string followed immediately by `## SYNTHESIS COMPLETE`. Do NOT error - the orchestrator handles the empty case (e.g., `--only <name>` in map skipped the parallel dispatch).
+- **Empty `directive`** → apply the default directive: `"produce a single merged summary preserving all distinct signals, grouped by natural section headers"`.
+- **Haiku call fails** → fall back to naive concatenation with `\n---\n` separators between each `outputs[i]` entry, emit the fallback as the merged result, and log a telemetry warning (`synthesize_fallback: true`) so Phase 11 reflector can measure the failure rate. Always emit `## SYNTHESIS COMPLETE` after the fallback body.
+- **`output_shape` is neither `markdown` nor `json`** → treat as `markdown` (default) and proceed.
+
+## Non-Goals
+
+- Does **NOT** spawn Task() agents. Synthesize is a thin skill, not an orchestrator.
+- Does **NOT** write files. The invoking orchestrator owns the target path.
+- Does **NOT** validate directive semantics. If the directive is nonsensical, the merge output will reflect that - garbage in, garbage out is acceptable for an internal-use skill.
+- Does **NOT** re-rank or re-score the inputs. Preservation is the contract.
+
+## Completion Marker
+
+```
+## SYNTHESIS COMPLETE
+```

package/scripts/skill-templates/timeline/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: gdd-timeline
+description: "Narrative retrospective across cycles: reads EXPERIENCE.md files and git log to produce a timeline view."
+argument-hint: "[<cycle-N> | <from>-<to> | all]"
+tools: Read, Bash, Glob
+disable-model-invocation: true
+---
+
+@reference/retrieval-contract.md
+@reference/cycle-handoff-preamble.md
+
+# {{command_prefix}}timeline
+
+Generates a narrative retrospective across one or more completed cycles by reading `.design/archive/cycle-N/EXPERIENCE.md` files and correlating with `git log`.
+
+## Steps
+
+1. **Parse argument**: accepted forms:
+   - `cycle-N` or `N` - single cycle
+   - `N-M` - inclusive range
+   - `all` or no argument - all archived cycles
+
+2. **Discover archives**: glob `.design/archive/cycle-*/EXPERIENCE.md`. Sort by cycle number. Filter to requested range.
+
+3. **For each cycle archive**:
+   a. Read `EXPERIENCE.md` - extract sections: Goal, Decisions made, Learnings graduated, What died, Handoff to next cycle.
+   b. Read `DESIGN-SUMMARY.md` (if present) for shipped artifacts list.
+   c. Run:
+      ```bash
+      git log --oneline --after="<cycle start date>" --before="<cycle end date>" -- .design/ 2>/dev/null | head -10
+      ```
+      to correlate with commits. Use dates from `EXPERIENCE.md` Opened/Ended headers if present.
+
+4. **Print timeline** in this shape:
+
+   ```
+   ## Timeline: Cycle 1 → Cycle 3
+
+   ---
+
+   ### Cycle 1 — <goal headline>
+
+   **Opened with**: <first meaningful action>
+   **Key decisions**: <D-XX summary>, <D-XX summary>
+   **Surprises**: <what was unexpected>
+   **What we'd do differently**: <retrospective note>
+   **Shipped**: <artifact list or "see DESIGN-SUMMARY.md">
+
+   ---
+
+   ### Cycle 2 — <goal headline>
+   ...
+   ```
+
+5. **No archives found**: print
+   ```
+   No archived cycles found in .design/archive/.
+   Complete a cycle first with {{command_prefix}}complete-cycle.
+   ```
+
+## Do Not
+
+- Do not modify any file.
+- Do not run git commands that write or stage (only `git log` for read).
+
+## TIMELINE COMPLETE

package/scripts/skill-templates/todo/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: gdd-todo
+description: "Design backlog - add/list/pick design tasks. Writes to .design/TODO.md."
+argument-hint: "<add|list|pick> [text]"
+tools: Read, Write, AskUserQuestion, mcp__gdd_state__get, mcp__gdd_state__add_decision, mcp__gdd_state__add_must_have
+disable-model-invocation: true
+---
+
+# {{command_prefix}}todo
+
+**Role:** Design todo list. Three subcommands: `add`, `list`, `pick`. Backing store: `.design/TODO.md`. For items that are pipeline-level decisions or must-haves (not free-form backlog), route through the `gdd-state` MCP tools instead - see **Pipeline-linked items** below.
+
+## File format
+
+```markdown
+# Design Todos
+
+## P0 — Blocking
+- [ ] [2026-04-18] Fix contrast ratio on card headers
+
+## P1 — High
+- [ ] [2026-04-18] Align Button focus ring with tokens
+
+## P2 — Normal
+
+## P3 — Nice to have
+```
+
+Priority is encoded by section, not inline. Status markers: `[ ]` unchecked, `[x]` done, `[-]` `[in-progress]`, `[p]` `[promoted]`.
+
+## Subcommands
+
+### add [text]
+If text omitted, use `AskUserQuestion`: "What todo item? (include priority P0-P3 if known)". Parse leading `P[0-3]` token from text; default P2. Append under the right section as:
+```
+- [ ] [YYYY-MM-DD] <text without priority token>
+```
+Create TODO.md from the template above if missing.
+
+### list
+1. Call `mcp__gdd_state__get` → pipeline-level decisions + must-haves (shown as context at the top).
+2. Read `.design/TODO.md` (file outside the MCP catalog). Print all `- [ ]` and `- [-]` items grouped by priority section, with index numbers.
+
+### pick
+Read `.design/TODO.md`. Collect unchecked items. Use `AskUserQuestion` to let the user pick one. Rewrite the chosen line as:
+```
+- [-] [YYYY-MM-DD] [in-progress] <original text>
+```
+Print "Picked: <item>".
+
+## Pipeline-linked items
+
+When the user promotes a todo to a pipeline decision or must-have, route through MCP instead of TODO.md:
+
+- Decision → `mcp__gdd_state__add_decision` with `{ id: "D-XX", text: "...", status: "locked"|"tentative" }`.
+- Must-have → `mcp__gdd_state__add_must_have` with `{ id: "M-XX", text: "...", status: "pending" }`.
+
+## Constraints
+
+- Do not modify files outside `.design/`.
+- Preserve existing sections and ordering on write.
+- Do not mutate STATE.md directly - use the MCP tools above.
+
+## TODO COMPLETE