@hegemonart/get-design-done 1.28.0 → 1.28.5

package/skills/settings/SKILL.md

@@ -3,6 +3,7 @@ name: gdd-settings
 description: "Manage .design/config.json settings. Subcommands: profile, parallelism, cleanup, show."
 argument-hint: "<profile <name>|parallelism <key> <value>|cleanup|show>"
 tools: Read, Write, AskUserQuestion, Bash, mcp__gdd_state__get, mcp__gdd_state__frontmatter_update
+disable-model-invocation: true
 ---
 
 # gdd-settings

package/skills/ship/SKILL.md

@@ -3,6 +3,7 @@ name: gdd-ship
 description: "Post-verify PR flow — creates a clean PR branch, invokes code review check, and prepares the PR for merge."
 argument-hint: "[--title <PR title>] [--draft]"
 tools: Read, Write, Bash, AskUserQuestion, Task
+disable-model-invocation: true
 ---
 
 # /gdd:ship

package/skills/sketch/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-sketch
-description: "Multi-variant HTML design exploration. Creates .design/sketches/<slug>/ with N standalone variants. Browser-openable directly — no build step."
+description: "Multi-variant HTML design exploration that creates .design/sketches/<slug>/ with N standalone variants (default 3), browser-openable directly via file:// without a build step. Use when answering 'what could this look like?' before committing to a direction."
 argument-hint: "[topic] [--variants N] [--quick]"
 tools: Read, Write, AskUserQuestion, Bash
 ---

package/skills/sketch-wrap-up/SKILL.md

@@ -7,32 +7,33 @@ tools: Read, Write, Glob, AskUserQuestion
 
 # Get Design Done — Sketch Wrap-Up
 
-**Role:** Close an open sketch — elicit the winner + rationale from the user, group the decision by design area, and codify it as a project-local skill at `./.claude/skills/design-<area>-conventions.md` so future gdd sessions auto-load the decision.
+**Role:** Close an open sketch — elicit the winner + rationale from the user, group the decision by design area, and codify it as a project-local skill at `./.claude/skills/design-<area>-conventions.md` so future gdd sessions auto-load the decision. See `./reference/cycle-handoff-preamble.md` for the cycle-handoff framing this decision-archive feeds into.
 
 ## Step 1 — Find sketches
 
 - Glob `.design/sketches/*/`.
 - If `[slug]` provided → use it directly.
 - If multiple pending (no `WINNER.md`) → AskUserQuestion: "Which sketch are you wrapping up?"
-- If none → print: "No open sketches. Run `/gdd:sketch` first." and exit.
+- If none → print `No open sketches. Run /gdd:sketch first.` and exit.
 
 ## Step 2 — Walk variants
 
 Read the sketch's `README.md`. For each `variant-N.html`:
+
 - Show the variant's one-line description from README.
 - AskUserQuestion: "Is variant-N a keeper, maybe, or rejected?"
 
 ## Step 3 — Elicit winner rationale
 
-AskUserQuestion:
+AskUserQuestion in sequence:
+
 1. "Which variant is the winner?"
 2. "What makes variant-N the winning direction? (grounds the decision for future sessions)"
 3. "Any token implications? (e.g., spacing scale clamp, color adjustment, font-weight shift)"
 
 ## Step 4 — Group by design area
 
-AskUserQuestion: "Which design area does this winner inform?"
-Options: typography / color / layout / motion / component / interaction
+AskUserQuestion: "Which design area does this winner inform?" Options: `typography / color / layout / motion / component / interaction`.
 
 ## Step 5 — Write project skill
 
@@ -51,64 +52,22 @@ Auto-loaded in gdd sessions. Captures decisions codified from `/gdd:sketch-wrap-
 
 ## Step 6 — Write WINNER.md
 
-Write `.design/sketches/<slug>/WINNER.md`:
-```markdown
-# Winner: variant-N
-
-**Slug**: <slug>
-**Area**: <area>
-**Rationale**: <user rationale>
-**Captured**: YYYY-MM-DD
-**Project skill written to**: ./.claude/skills/design-<area>-conventions.md
-```
+Write `.design/sketches/<slug>/WINNER.md` with: `# Winner: variant-N`, then bold-prefixed fields **Slug**, **Area**, **Rationale**, **Captured** (YYYY-MM-DD), **Project skill written to** (path from Step 5).
 
 ## Step 7 — Append D-XX + `<prototyping>` outcome to STATE.md
 
-Two coupled writes to `.design/STATE.md`. Both must succeed together so the
-sketch resolution is discoverable from both `<decisions>` (read by all
-downstream stages) and `<prototyping>` (read by planner-specific context via
-the decision-injector).
-
-Compute `D-XX` as the highest existing `D-NN` in `<decisions>` plus 1
-(scan `<decisions>` for `D-\d+:` entries and take `max + 1`, zero-padded
-to two digits — e.g. existing `D-07` → new entry is `D-08`). Use the same
-`D-XX` value in both writes below.
+Two coupled writes — both must succeed so the sketch resolution surfaces in both `<decisions>` (all downstream stages) and `<prototyping>` (planner-specific context via decision-injector). Compute `D-XX` as max existing `D-NN` + 1 (scan `<decisions>` for `D-\d+:`, zero-pad to 2 digits).
 
-**Write 1 — append a numbered decision under `<decisions>`:**
-```
-D-XX: sketch/<slug> — winner: variant-N — <one-line rationale> (locked)
-  Source: .design/sketches/<slug>/WINNER.md
-```
+- **Write 1 (`<decisions>`):** `D-XX: sketch/<slug> — winner: variant-N — <rationale> (locked)\n  Source: .design/sketches/<slug>/WINNER.md`
+- **Write 2 (`<prototyping>`):** `<sketch slug="<slug>" cycle="<cycle>" decision="D-XX" status="resolved"/>`. `<cycle>` from STATE.md frontmatter; empty string valid for single-cycle Wave A projects. If `<prototyping>` block does not exist, materialize between `<must_haves>` and `<connections>` per STATE template; append the `<sketch …/>` as first child.
 
-**Write 2 — append a `<sketch>` child element under `<prototyping>`:**
-```
-<sketch slug="<slug>" cycle="<cycle>" decision="D-XX" status="resolved"/>
-```
+Prefer MCP `gdd_state` typed mutators (byte-identical output): `mcp__gdd_state__add_decision({id, text, status})` + `mcp__gdd_state__add_prototyping({type:"sketch", slug, cycle, decision, status})`. Without MCP, edit `.design/STATE.md` directly via Read + Write.
 
-`<cycle>` is the current cycle id from `.design/STATE.md` frontmatter
-(`cycle:` field; empty string is valid for Wave A single-cycle projects).
+## Step 8 — Update sketches SUMMARY.md
 
-If a `<prototyping>` block does not yet exist in STATE.md, materialize it
-between `<must_haves>` and `<connections>` per the STATE template, then
-append the `<sketch …/>` line as its first child. The block is omitted on
-fresh files and only appears once the first sketch / spike / skipped entry
-lands.
+Append to `.design/sketches/SUMMARY.md` (create if missing):
 
-If MCP `gdd_state` tools are available, prefer the typed mutators (these
-wrap `scripts/lib/gdd-state/mutator.ts` and emit byte-identical output to
-manual edits):
 ```
-- mcp__gdd_state__add_decision({id: "D-XX", text: "sketch/<slug> — winner: variant-N — <rationale>", status: "locked"})
-- mcp__gdd_state__add_prototyping({type: "sketch", slug: "<slug>", cycle: "<cycle>", decision: "D-XX", status: "resolved"})
-```
-
-Without MCP, edit `.design/STATE.md` directly with `Read` + `Write`,
-inserting the two lines into the correct blocks.
-
-## Step 8 — Update sketches SUMMARY.md
-
-Append entry to `.design/sketches/SUMMARY.md` (create if missing):
-```markdown
 - <slug> (YYYY-MM-DD) — winner: variant-N — area: <area> — D-XX — <one-line rationale>
 ```
 

package/skills/spike/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-spike
-description: "Timeboxed feasibility experiment. Answers 'can this work?' questions. Creates .design/spikes/<slug>/ with hypothesis, timebox, scratch code, findings."
+description: "Timeboxed feasibility experiment that creates .design/spikes/<slug>/ with HYPOTHESIS.md, success/failure criteria, scratch/ subdirectory, and a default 60-minute timebox. Use when answering 'can this work?' before betting design or implementation effort on a risky approach."
 argument-hint: "[hypothesis] [--timebox <minutes>]"
 tools: Read, Write, Bash, AskUserQuestion
 ---

package/skills/spike-wrap-up/SKILL.md

@@ -7,14 +7,14 @@ tools: Read, Write, Glob, AskUserQuestion
 
 # Get Design Done — Spike Wrap-Up
 
-**Role:** Close an open spike — capture the verdict, write findings, record a D-XX decision in STATE.md so `plan` sees it when creating tasks.
+**Role:** Close an open spike — capture the verdict, write findings, record a D-XX decision in STATE.md so `plan` sees it when creating tasks. See `./reference/cycle-handoff-preamble.md` for the cycle-handoff framing this archive feeds into.
 
 ## Step 1 — Find spike
 
 - Glob `.design/spikes/*/`.
 - If `[slug]` provided → use it directly.
 - If multiple pending (no `FINDINGS.md`) → AskUserQuestion: "Which spike are you wrapping up?"
-- If none → print: "No open spikes. Run `/gdd:spike` first." and exit.
+- If none → print `No open spikes. Run /gdd:spike first.` and exit.
 
 ## Step 2 — Re-surface hypothesis
 
@@ -22,7 +22,8 @@ Read `.design/spikes/<slug>/HYPOTHESIS.md`. Show the hypothesis + success/failur
 
 ## Step 3 — Elicit findings
 
-AskUserQuestion:
+AskUserQuestion in sequence:
+
 1. "Did it meet success criteria? (yes / no / partial)"
 2. "What was learned? (1–3 sentences)"
 3. "Recommendation? (adopt / reject / needs more investigation)"
@@ -30,6 +31,7 @@ AskUserQuestion:
 ## Step 4 — Write FINDINGS.md
 
 Write `.design/spikes/<slug>/FINDINGS.md`:
+
 ```markdown
 # Findings: <slug>
 
@@ -46,57 +48,21 @@ Write `.design/spikes/<slug>/FINDINGS.md`:
 
 ## Step 5 — Record decision in STATE.md
 
-Append a `D-XX` entry under `<decisions>` in `.design/STATE.md`:
-```
-D-XX: spike/<slug> — <verdict> — <recommendation>
-  Rationale: <one line>
-  Source: .design/spikes/<slug>/FINDINGS.md
-```
-
-(Increment D-XX from the highest existing number — scan `<decisions>` for
-`D-\d+:` entries and take `max + 1`, zero-padded to two digits.)
-
-If MCP `gdd_state` tools are available, prefer the typed mutator:
-```
-- mcp__gdd_state__add_decision({id: "D-XX", text: "spike/<slug> — <verdict> — <recommendation> — <one-line rationale>", status: "locked"})
-```
+Append under `<decisions>`: `D-XX: spike/<slug> — <verdict> — <recommendation>\n  Rationale: <one line>\n  Source: .design/spikes/<slug>/FINDINGS.md`. Compute `D-XX` as max existing `D-NN` + 1 (scan for `D-\d+:`, zero-pad to 2 digits). Prefer MCP `gdd_state` typed mutator when available: `mcp__gdd_state__add_decision({id, text, status:"locked"})`.
 
 ## Step 6 — Append `<prototyping>` outcome to STATE.md
 
-Coupled with the Step 5 decision write — both must succeed together so the
-spike resolution is discoverable from both `<decisions>` (read by all
-downstream stages) and `<prototyping>` (read by planner-specific context via
-the decision-injector). Use the **same `D-XX`** as Step 5.
-
-Append a `<spike>` child element under `<prototyping>` in `.design/STATE.md`:
-```
-<spike slug="<slug>" cycle="<cycle>" decision="D-XX" verdict="yes|no|partial" status="resolved"/>
-```
-
-`<cycle>` is the current cycle id from `.design/STATE.md` frontmatter
-(`cycle:` field; empty string is valid for Wave A single-cycle projects).
-`verdict` is the answer from Step 3 (`yes` / `no` / `partial`).
+Coupled with Step 5 — both must succeed so the spike resolution surfaces in `<decisions>` (downstream stages) and `<prototyping>` (planner via decision-injector). Use **same `D-XX`**. Append under `<prototyping>`: `<spike slug="<slug>" cycle="<cycle>" decision="D-XX" verdict="yes|no|partial" status="resolved"/>`. `<cycle>` from STATE.md frontmatter (`cycle:` field; empty string valid for single-cycle Wave A); `verdict` from Step 3.
 
-If a `<prototyping>` block does not yet exist in STATE.md, materialize it
-between `<must_haves>` and `<connections>` per the STATE template, then
-append the `<spike …/>` line as its first child. The block is omitted on
-fresh files and only appears once the first sketch / spike / skipped entry
-lands.
+If `<prototyping>` block does not exist, materialize between `<must_haves>` and `<connections>` per STATE template; append `<spike …/>` as first child.
 
-If MCP `gdd_state` tools are available, prefer the typed mutator (it wraps
-`scripts/lib/gdd-state/mutator.ts` and emits byte-identical output to manual
-edits):
-```
-- mcp__gdd_state__add_prototyping({type: "spike", slug: "<slug>", cycle: "<cycle>", decision: "D-XX", verdict: "<verdict>", status: "resolved"})
-```
-
-Without MCP, edit `.design/STATE.md` directly with `Read` + `Write`,
-inserting the line into the `<prototyping>` block.
+Prefer MCP typed mutator (byte-identical output): `mcp__gdd_state__add_prototyping({type:"spike", slug, cycle, decision:"D-XX", verdict, status:"resolved"})`. Without MCP, edit `.design/STATE.md` directly via Read + Write.
 
 ## Step 7 — Update spikes SUMMARY.md
 
-Append entry to `.design/spikes/SUMMARY.md` (create if missing):
-```markdown
+Append to `.design/spikes/SUMMARY.md` (create if missing):
+
+```
 - <slug> (YYYY-MM-DD) — verdict: <yes|no|partial> — recommendation: <adopt|reject|more> — D-XX
 ```
 

package/skills/start/SKILL.md

@@ -3,19 +3,14 @@ name: start
 description: "First-Run Proof Path — one command that scans your UI code and returns one concrete first fix. Leaf command, no STATE.md writes, no pipeline entry. Writes .design/START-REPORT.md and exits."
 argument-hint: "[--budget <fast|balanced|thorough>] [--skip-interview] [--dismiss-nudge]"
 tools: Read, Grep, Glob, Bash, Write, Task
+disable-model-invocation: true
 ---
 
 # Get Design Done — /gdd:start
 
 **Role:** the canonical 0→1 proof path. A new user runs `/gdd:start`, answers five short questions, and receives `.design/START-REPORT.md` with three concrete findings in the user's own code, one `best_first_proof` selected by a deterministic rubric, and a single next command to run.
 
-**Non-goals** (do not do any of these):
-
-- Do NOT write or mutate `.design/STATE.md`.
-- Do NOT enter the pipeline state machine.
-- Do NOT modify source code.
-- Do NOT auto-install MCPs or run `/gdd:connections`.
-- Do NOT capture before/after screenshots — that belongs to the full pipeline.
+**Non-goals:** do NOT write/mutate `.design/STATE.md`, enter the pipeline state machine, modify source code, auto-install MCPs or run `/gdd:connections`, or capture before/after screenshots (that belongs to the full pipeline).
 
 ---
 
@@ -44,114 +39,20 @@ tools: Read, Grep, Glob, Bash, Write, Task
 
 ---
 
-## 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 `reference/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.
+## Workflow
 
-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.
-
----
+Six steps, all documented in `./reference/start-procedure.md`. Companion file `./reference/start-interview.md` holds the 5-question copy + defaults + validation.
 
-## Failure handling
+| Step | What it does | Where to look |
+|------|--------------|---------------|
+| 0 | Dismiss-only shortcut (if `--dismiss-nudge`) | `start-procedure.md#step-0-dismiss-only-shortcut` |
+| 1 | Detect UI root via `scripts/lib/detect-ui-root.cjs` (early-exit on backend-only or `kind: null`) | `start-procedure.md#step-1-detect-ui-root` |
+| 2 | Run 5-question interview (or use `--skip-interview` defaults); write `.design/.start-context.json` (NOT STATE.md) | `start-procedure.md#step-2-run-the-5-question-interview` + `start-interview.md` |
+| 3 | Invoke `scripts/lib/start-findings-engine.cjs` → up to 3 findings (`F1`..`F3`) + `bestFirstProofId` | `start-procedure.md#step-3-scan-findings` |
+| 4 | Spawn `design-start-writer` Task → emit `.design/START-REPORT.md` (7 H2 sections + JSON block, no STATE.md write) | `start-procedure.md#step-4-spawn-the-writer` |
+| 5 | Print one-line handoff with suggested command (fallback: `/gdd:brief` if `bestFirstProofId` is null); emit `## START COMPLETE` | `start-procedure.md#step-5-print-the-handoff` |
 
-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.
+Failure handling: every error path exits with `## START COMPLETE` plus a one-line pointer. Do not half-write files — if the writer 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/skills/stats/SKILL.md

@@ -2,6 +2,7 @@
 name: gdd-stats
 description: "Cycle stats — decisions made, tasks completed, commits, timeline, git metrics."
 tools: Read, Bash
+disable-model-invocation: true
 ---
 
 # /gdd:stats

package/skills/style/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: get-design-done:style
-description: "Generate a component handoff doc (.design/DESIGN-STYLE-[ComponentName].md) from existing pipeline artifacts or source files. Two modes: post-pipeline (uses DESIGN-SUMMARY.md) and pre-pipeline fallback (uses DESIGN.md + source). Invoke with a ComponentName argument, or with no argument to list available components."
+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
 ---
@@ -9,6 +9,8 @@ user-invocable: true
 
 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 `../../reference/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.
 
 ---
@@ -27,134 +29,24 @@ This separation is a pre-roadmap decision recorded in `.planning/STATE.md`: util
 
 ---
 
-## Argument Handling
-
-**If `$ARGUMENTS` contains a ComponentName** → proceed to Mode Detection with that name.
-
-**If `$ARGUMENTS` is empty** → do not generate a doc. Instead:
-
-1. List available component files by globbing:
-   - `src/components/*.tsx`
-   - `src/components/*.jsx`
-   - `src/**/*.vue`
-   - `src/**/*.svelte`
-   - `components/*.tsx`
-   - `components/*.jsx`
-2. Also list task names from `.design/tasks/*.md` (if directory exists).
-3. Display the list to the user and prompt: "Specify a ComponentName to generate a style spec. Example: `/get-design-done style Button`"
-4. Exit without generating any file.
-
----
-
-## Mode Detection
-
-Before spawning the agent, detect which mode to use:
-
-```
-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/."
-
----
-
-## Agent Spawn
-
-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)
-  - AI-Slop Detection (using reference/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.
-
----
-
-## Output Location
-
-Output is written by the agent to:
-
-```
-.design/DESIGN-STYLE-[ComponentName].md
-```
-
-This artifact is **outside the pipeline namespace**. The `DESIGN-STYLE-` prefix is distinct from all pipeline-owned artifacts (`DESIGN.md`, `DESIGN-CONTEXT.md`, `DESIGN-PLAN.md`, `DESIGN-SUMMARY.md`, `DESIGN-VERIFICATION.md`). There is no naming conflict.
+## Workflow
 
-The `.design/` directory is gitignored (developer tooling only — not shipped with the plugin).
+1. **Argument check** — if `$ARGUMENTS` is empty, enter list mode (see `../../reference/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 `../../reference/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 `../../reference/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:
+This command MUST NOT (per `../../reference/shared-preamble.md#output-contract-reminders`):
 
-- MUST NOT write to `DESIGN.md`, `DESIGN-SUMMARY.md`, `DESIGN-VERIFICATION.md`, `DESIGN-CONTEXT.md`, or `.design/STATE.md`
-- MUST NOT invoke the pipeline router (this command is a leaf invocation, not a pipeline stage)
-- MUST NOT require Figma or Refero MCPs — v3 uses only local source files and `.design/` artifacts (MCP enrichment is reserved for a future version)
-- MUST NOT produce more than one output file per invocation — no batch mode in v3
+- 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
 
 ---
 
@@ -166,12 +58,7 @@ This command MUST NOT:
 /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`
-
----
+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)**
 
@@ -179,15 +66,6 @@ This command MUST NOT:
 /get-design-done style
 ```
 
-- Globs component files from `src/components/`
-- Displays list to user:
-  ```
-  Available components:
-    Button
-    CardHeader
-    Input
-    Modal
-    Toast
-  Specify: /get-design-done style [ComponentName]
-  ```
-- Exits without generating any file.
+Globs component files and prompts the user to specify a ComponentName. Exits without generating any file. See `../../reference/style-doc-procedure.md#component-source-resolution` for the full glob path list.
+
+## STYLE COMPLETE

package/skills/synthesize/SKILL.md

@@ -3,6 +3,7 @@ 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

package/skills/timeline/SKILL.md

@@ -3,6 +3,7 @@ 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

package/skills/todo/SKILL.md

@@ -3,6 +3,7 @@ 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