@hegemonart/get-design-done 1.41.0 → 1.42.0

package/dist/claude-code/.claude/skills/start/start-procedure.md

@@ -0,0 +1,115 @@
+---
+name: start-procedure
+type: heuristic
+version: 1.0.0
+phase: 28.5
+tags: [start, first-run, proof-path, scan, writer-agent, handoff]
+last_updated: 2026-05-18
+---
+
+# Start Skill — Full Procedure
+
+Extracted from `skills/start/SKILL.md` per Phase 28.5 D-10 (extract-then-link, never delete
+content). The skill keeps its arguments table, step headings, and non-goals; the per-step
+operational detail (interview JSON shape, scan invocation, writer spawn payload, handoff
+template) lives here so the SKILL stays under the 100-line cap.
+
+The companion file `./start-interview.md` (Phase 27 ship) holds the 5-question copy,
+defaults, and validation rules. This file documents what `/gdd:start` does WITH the answers.
+
+## Step 0 — Dismiss-only shortcut
+
+If invoked with `--dismiss-nudge`:
+
+1. `touch ~/.claude/gdd-nudge-dismissed` (Windows: equivalent). Ignore errors silently.
+2. Print exactly: `Nudge dismissed. Delete ~/.claude/gdd-nudge-dismissed to re-enable.`
+3. Exit with `## START COMPLETE` marker.
+
+Do not proceed to any other step.
+
+## Step 1 — Detect UI root
+
+Run the detector:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/detect-ui-root.cjs" "$(pwd)"
+```
+
+Capture the JSON output. Branches:
+
+- `kind: "backend-only"` → print the frontend-only diagnostic below, write nothing, exit with `## START COMPLETE`. The diagnostic copy is:
+  > `/gdd:start` is for frontend codebases. This repo looks backend-only (detected `<framework>`). The plugin can still help with design references and component libraries imported by your clients — but there is no UI surface here to scan. Exiting without creating `.design/`.
+- `kind: null` (no package.json, no UI dir) → print a short "Nothing recognizable here — point me at a frontend repo and try again." and exit.
+- Any other `kind` → proceed with `detected.path` as the scan root.
+
+## Step 2 — Run the 5-question interview
+
+Read `./start-interview.md` for the exact question copy, defaults, and validation rules.
+
+If `--skip-interview`, skip this step and use the defaults documented in that file.
+
+Otherwise, ask the five questions in order using `AskUserQuestion`:
+
+1. Pain point (text, required, single-line cap 120 chars)
+2. Target area confirmation (detected path)
+3. Budget / latency preference (enum: fast / balanced / thorough)
+4. Framework + design-system confirmation (from detection)
+5. Figma / canvas workflow (enum: figma / canvas / neither / skip)
+
+Any early exit at Q1 → abort with a one-line pointer to `/gdd:scan`.
+
+Store the answers + detection result in `.design/.start-context.json`:
+
+```json
+{
+  "schema_version": "1.0",
+  "detected": { "kind": "...", "path": "...", "framework": "...", "design_system": "...", "confidence": 0.85 },
+  "interview": { "pain": "...", "target_area": "...", "budget": "balanced", "framework_confirmed": true, "design_system_confirmed": true, "figma_workflow": "skip" },
+  "generated_at": "<ISO-8601>"
+}
+```
+
+`.design/` is created here for the first time. `.design/STATE.md` is NOT written.
+
+## Step 3 — Scan findings
+
+Run the findings engine:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/start-findings-engine.cjs" \
+  --root "<detected.path>" \
+  --budget "<budget>" \
+  --pain "<pain_point>"
+```
+
+Capture the JSON. The output carries at most three findings, each with stable IDs `F1`..`F3`, plus `bestFirstProofId` (may be null).
+
+Append the engine output to `.design/.start-context.json` under a `scan` key.
+
+## Step 4 — Spawn the writer
+
+Dispatch `Task` with:
+
+- `subagent_type: design-start-writer`
+- `description: "Write .design/START-REPORT.md"`
+- `prompt:` a short instruction pointing the agent at `.design/.start-context.json` and asking it to emit the report per its Output contract. Include a reminder that it must produce exactly 7 H2 sections plus the JSON block, and must not write `STATE.md`.
+
+Wait for the agent to complete. The agent writes `.design/START-REPORT.md`.
+
+## Step 5 — Print the handoff
+
+Read the final line of `.design/START-REPORT.md` to capture the suggested command.
+
+Print exactly (one line, no emoji):
+
+```
+Report written to .design/START-REPORT.md. Next: run <suggested_command> to see the first proof.
+```
+
+If `bestFirstProofId` was null, the suggested command is `/gdd:brief` (the default fallback).
+
+Emit `## START COMPLETE` and exit.
+
+## Failure handling
+
+Every error path exits with `## START COMPLETE` and a one-line pointer. Do not half-write files: if the writer agent fails, keep `.design/.start-context.json` and tell the user they can rerun. Do not delete `.design/` unless it was empty before the run.

package/dist/claude-code/.claude/skills/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
+---
+
+# /gdd: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/dist/claude-code/.claude/skills/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/dist/claude-code/.claude/skills/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 load-bearing 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 load-bearing
+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/dist/claude-code/.claude/skills/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/discover/, 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/dist/claude-code/.claude/skills/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
+
+# /gdd: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 /gdd: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/dist/claude-code/.claude/skills/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
+---
+
+# /gdd: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