@hegemonart/get-design-done 1.28.0 → 1.28.6

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 `./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/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/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