@hegemonart/get-design-done 1.57.1 → 1.57.2

package/connections/cursor.md

@@ -0,0 +1,73 @@
+# Cursor — Runtime Install Notes
+
+This file documents the get-design-done install path on Cursor and one known limitation.
+
+Cursor is one of the 14 first-class runtimes for `gdd install` (see `reference/runtimes.md` for the full set). It uses the `multi-artifact` install kind: skills land as `~/.cursor/skills/<gdd-name>/SKILL.md` after passing through `scripts/lib/install/converters/cursor.cjs`.
+
+## Install
+
+```
+gdd install --runtime cursor          # global → ~/.cursor/skills/
+gdd install --runtime cursor --local  # repo-local → .cursor/skills/
+```
+
+Each installed skill is name-prefixed with `gdd-` (e.g. `gdd-explore`, `gdd-discover`) so it cannot collide with user-authored Cursor skills.
+
+## Converter behavior
+
+`converters/cursor.cjs#convert` is a pure string→string transform that:
+
+- Normalizes the frontmatter `name:` field to `gdd-<skill>` (no double-prefix).
+- Rewrites mixed-shape slash references (`gdd-x`, `/gdd:x`) to a consistent `/gdd-<name>` shape.
+- Passes the Claude tool vocabulary through unchanged (Read / Write / Bash / Edit / Grep / Glob — Cursor accepts these).
+- Injects a 1-line HTML adapter header recording auto-generation.
+
+The output is byte-stable per source — re-running `gdd install --runtime cursor` is a no-op when nothing has changed.
+
+## Known limitation — sibling .md files are NOT installed
+
+Some skills ship procedure detail in sibling `.md` files next to `SKILL.md`. For example:
+
+```
+skills/discover/
+├── SKILL.md                      ← installed
+└── discover-procedure.md         ← NOT installed (sibling)
+```
+
+`SKILL.md` references the sibling via a relative link (e.g. `./discover-procedure.md`). On Cursor, that link resolves to nothing.
+
+This is a systemic limitation of the current `multi-artifact` install pipeline (`scripts/lib/install/runtime-artifact-layout.cjs#skillsKind`), not a Cursor-specific bug. It affects every runtime that uses `skillsKind`: claude global, cursor, codex, copilot, antigravity, windsurf, augment, trae, qwen, codebuddy. Skills with sibling files currently affected:
+
+- `apply-reflections/apply-reflections-procedure.md`
+- `cache-manager/cache-policy.md`
+- `compare/compare-rubric.md`
+- `connections/connections-onboarding.md`
+- `darkmode/darkmode-audit-procedure.md`
+- `debug/debug-feedback-loops.md`
+- `design/design-procedure.md`
+- `discover/discover-procedure.md`
+- `explore/explore-procedure.md`
+- `health/health-mcp-detection.md`
+- `health/health-skill-length-report.md`
+- `new-cycle/milestone-completeness-rubric.md`
+- `peer-cli-add/peer-cli-protocol.md`
+- `plan/plan-procedure.md`
+- `quality-gate/threat-modeling.md`
+- `report-issue/report-issue-procedure.md`
+- `router/capability-gap-emitter.md`
+- `router/router-pick-emitter.md`
+- `router/router-rules.md`
+- `scan/scan-procedure.md`
+- `start/start-procedure.md`
+- `style/style-doc-procedure.md`
+- `verify/verify-procedure.md`
+
+### Workarounds until a fix lands
+
+1. **Use the cursor-marketplace distribution channel** — `scripts/lib/install/converters/cursor-marketplace.cjs` copies the entire `skills/` tree byte-for-byte (siblings included). Install through the marketplace plugin rather than per-skill if you need the full procedure detail.
+2. **Clone the repo locally** — Cursor can read sibling files directly from the source checkout if you point it at the repo tree.
+3. **Inline-grep the source** — for one-off questions, read the source `SKILL.md` directly; siblings are short and self-contained.
+
+### Fix scope (tracked as follow-up beyond batch H6)
+
+Properly enumerating siblings requires extending the StagedArtifact contract to emit multiple files per skill (one SKILL.md + N siblings), updating `computeDestPath` for non-SKILL.md paths inside a skill subdir, the foreign-file detection in `installer.cjs#detectMultiArtifactInstalled`, and the uninstall enumeration in `uninstallMultiArtifact`. See the `KNOWN LIMITATION` block at the top of `scripts/lib/install/converters/cursor.cjs` for the technical detail.

package/connections/preview.md

@@ -107,10 +107,10 @@ When preview is `not_configured` or `unavailable`, stages degrade gracefully —
 
 **verify stage (`skills/verify/SKILL.md` + `agents/design-verifier.md`):**
 
-- Skip Phase 4B screenshot evidence loop entirely
+- Skip Stage 4B screenshot evidence loop entirely
 - Keep existing `? VISUAL` static analysis path for H-02, H-06, H-07 heuristics
-- Mark all Phase 4B checks: `[SKIPPED — browser not available]`
-- Design-verifier continues to Phase 5 gap analysis with partial scores
+- Mark all Stage 4B checks: `[SKIPPED — browser not available]`
+- Design-verifier continues to Stage 5 gap analysis with partial scores
 
 **compare stage (`skills/compare/SKILL.md`):**
 

package/dist/claude-code/.claude/skills/cache-manager/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-cache-manager
-description: "Maintains .design/cache-manifest.json for Layer B explicit cache per D-08. Computes deterministic SHA-256 input-hash from (agent-path + sorted-input-file-paths + input-content-hashes). On spawn: lookup key → return cached blob if within TTL, else miss. On completion: write result + TTL. Consulted by hooks/budget-enforcer.js before every Agent spawn."
+description: "Maintains .design/cache-manifest.json for Layer B explicit cache per D-08. Computes deterministic SHA-256 input-hash from (agent-path + sorted-input-file-paths + input-content-hashes). On spawn: lookup key → return cached blob if within TTL, else miss. On completion: write result + TTL. Consulted by hooks/budget-enforcer.ts before every Agent spawn."
 user-invocable: false
 tools: Read, Bash, Write
 disable-model-invocation: true
@@ -38,11 +38,11 @@ You are the deterministic cache-key computer and cache-manifest writer for the o
 
 ## Deterministic Input-Hash Algorithm
 
-The canonical reference implementation (single source of truth; `hooks/budget-enforcer.js` imports the same primitive via a shared helper) lives in `./cache-policy.md#deterministic-input-hash-algorithm-layer-b` - it documents the JS implementation, the maintainer notes (sorted-unique paths, MISSING-file sentinel, agent-path bust behavior), the manifest shape, and TTL semantics in one place. Conform to the algorithm exactly so the hook and any orchestrator agree byte-for-byte.
+The canonical reference implementation (single source of truth; `hooks/budget-enforcer.ts` imports the same primitive via a shared helper) lives in `./cache-policy.md#deterministic-input-hash-algorithm-layer-b` - it documents the JS implementation, the maintainer notes (sorted-unique paths, MISSING-file sentinel, agent-path bust behavior), the manifest shape, and TTL semantics in one place. Conform to the algorithm exactly so the hook and any orchestrator agree byte-for-byte.
 
 ## Integration Points
 
-- **`hooks/budget-enforcer.js`** (Plan 10.1-01) reads the manifest on every Agent spawn. The hook already calls `cacheLookup(agent, inputHash)` against `.design/cache-manifest.json`. This skill is the authority on how `inputHash` is computed so the hook and any orchestrator agree byte-for-byte.
+- **`hooks/budget-enforcer.ts`** (Plan 10.1-01) reads the manifest on every Agent spawn. The hook already calls `cacheLookup(agent, inputHash)` against `.design/cache-manifest.json`. This skill is the authority on how `inputHash` is computed so the hook and any orchestrator agree byte-for-byte.
 - **Orchestrators** (e.g., `skills/map/`, `skills/discover/`, `skills/plan/`) invoke Phase 1 (compute-key) + Phase 4 (write-result-on-completion) around each Agent spawn they launch. Phase 2 + Phase 3 are executed by the hook.
 - **Warm-cache command** (`skills/warm-cache/SKILL.md`, Task 02) does not touch Layer B - it only primes Anthropic's 5-min prompt cache (Layer A). Do not confuse the two.
 

package/dist/claude-code/.claude/skills/cache-manager/cache-policy.md

@@ -21,7 +21,7 @@ The two layers (D-08):
 
 ## Deterministic Input-Hash Algorithm (Layer B)
 
-The canonical reference implementation (the single source of truth; `hooks/budget-enforcer.js` imports the same primitive via a shared helper):
+The canonical reference implementation (the single source of truth; `hooks/budget-enforcer.ts` imports the same primitive via a shared helper):
 
 ```js
 // Deterministic cache-key primitive (reference implementation)

package/dist/claude-code/.claude/skills/design/SKILL.md

@@ -79,6 +79,25 @@ Print the `=== Design stage complete ===` summary (tasks complete/total, deviati
 
 After all tasks finish, if STATE.md `<connections>` has `figma: available`, offer the user the figma-write opt-in prompt (modes: annotate / tokenize / mappings, with optional `--dry-run`). Spawn `design-figma-writer` with the selected mode on "yes"; skip silently on "no". NEVER auto-run without confirmation. Full prompt + dispatch logic: `./design-procedure.md` §Figma Write Dispatch.
 
+## Component Generator Dispatch
+
+If the DESIGN-PLAN has a `task_type: component` task without a matching `src/components/*.tsx`, OR the brief / DESIGN-CONTEXT.md explicitly asks for a new component, AND STATE.md `<connections>` shows a generator connection (`21st-dev: available`, `magic-patterns: available`, `plasmic: available`, `builder-io: available`, or `v0-dev: available`); offer the component-generator opt-in.
+
+```
+Task("design-component-generator", """
+mode: <21st|magic-patterns|plasmic|builder-io|v0-dev>
+component_spec: <DESIGN-PLAN task summary + DESIGN-CONTEXT acceptance criteria>
+required_reading:
+  - .design/STATE.md
+  - .design/DESIGN-PLAN.md
+  - .design/DESIGN-CONTEXT.md
+""")
+```
+
+Sequential (the agent is `parallel-safe: never`). Wait for the agent's `## design-component-generator complete.` marker. Skip silently when no generator connection is available OR no component task is pending. Auto-mode bypasses the prompt; otherwise prompt "Generate component via [tool]? (y/n)" and only spawn on "y".
+
+The dispatch fires AFTER `design-executor` completes the hand-coded plan tasks. The agent's output (component file path + tokens used + provenance) is appended to `.design/DESIGN-SUMMARY.md` as a single `## Generated Components` section so verify can audit it.
+
 <HARD-GATE>
 Do NOT transition to verify (or invoke `/gdd:verify`) until `.design/DESIGN-SUMMARY.md` is committed. If this project uses a custom `.design` location, read the artifact path from `.design/STATE.md` rather than assuming the default.
 </HARD-GATE>

package/dist/claude-code/.claude/skills/explore/SKILL.md

@@ -61,6 +61,16 @@ Run the canonical scan grep/glob inventory (POSIX ERE, preserving PLAT-01/02): c
 - **Project-local skills**: read `./.claude/skills/design-*-conventions.md` -> include in DESIGN-CONTEXT.md `<project_conventions>` (these override defaults).
 - **Global skills**: `~/.claude/gdd/global-skills/*.md` (other than README) -> prepend to `<project_conventions>` under `<global_conventions>` sub-block. Project-local D-XX wins on conflict.
 
+## Step 2.6 - Graph review (gate then reviewer)
+
+Runs only when Step 2's mapper batch + synthesizer produced `.design/context-graph.json`. Skip the whole step if the file is absent (pre-Phase-52 project, or `--skip-scan`).
+
+1. **Gate first (cheap Haiku check).** Spawn `design-context-reviewer-gate` via `Task()` with the classifier signal from Step 2's incremental batching pass: `change_pct` (fingerprint classifier `pct`), `classifier_action` (`SKIP` / `PARTIAL_UPDATE` / `ARCHITECTURE_UPDATE` / `FULL_UPDATE`), and `graph_path: ".design/context-graph.json"`. Gate emits a single-line `{spawn, rationale}` JSON decision then `## GATE COMPLETE`.
+2. **If `spawn: false`**: record `mcp__gdd_state__set_status: "explore_graph_review_skipped"`, log the gate `rationale` (e.g., "project change 3% < 5% threshold"), set telemetry `lazy_skipped: true`. Done - proceed to Step 3.
+3. **If `spawn: true`**: spawn `design-context-reviewer` via `Task()` with `<required_reading>` pointing at `.design/STATE.md`, `.design/context-graph.json`, `reference/design-context-schema.md`, `reference/design-context-tag-vocab.md`. The reviewer runs `scripts/validate-design-context.cjs --json` as the deterministic floor (checks 1/2/3/5) then layers the semantic checks (4/6/7/8/9) and returns the 9-check verdict inline (`APPROVED` or `REJECT`).
+4. **Capture verdict (read-only contract).** The reviewer does NOT write `.design/DESIGN-CONTEXT-REVIEW.md` - it is `reads-only: true, writes: []`. WARN findings surface through `scripts/lib/health-mirror#getHealthChecks` as `status: 'warn'`; a hard-reject maps to `status: 'fail'`. Record the overall verdict via `mcp__gdd_state__set_status: "explore_graph_review_approved"` (or `"_rejected"`).
+5. **On REJECT**: record `mcp__gdd_state__add_blocker` with the reviewer's blocking-issues list verbatim. Do not advance to Step 3 until the synthesizer or the implicated mapper is re-run. On `APPROVED` (with or without WARNs): proceed.
+
 ---
 
 ## Step 3 - Design interview (unless `--skip-interview`)
@@ -80,6 +90,7 @@ Full interview protocol + JSON line schema: `./explore-procedure.md` §Step 3.
 ## Step 4 - Close out explore
 
 - If the synthesizer / mapper batch ran in Step 2: `mcp__gdd_state__update_progress` with `task_progress: "<done>/<total>"`, `status: "explore_mappers_done"`.
+- If Step 2.6 ran the graph review: ensure the verdict status is recorded (`explore_graph_review_approved` / `_rejected` / `_skipped`); on `_rejected` do NOT checkpoint until re-run.
 - `mcp__gdd_state__checkpoint` - bumps `last_checkpoint`.
 - Stage advance to `plan` happens at the next stage's entry (plan owns its own `transition_stage`); do not edit frontmatter directly.
 

package/dist/claude-code/.claude/skills/figma-write/SKILL.md

@@ -34,6 +34,17 @@ Read `.design/STATE.md` and `.design/DESIGN-CONTEXT.md` before dispatching the a
 
 ## Dispatch
 
-<agent>design-figma-writer</agent>
+```
+Task("design-figma-writer", """
+mode: <annotate|tokenize|mappings>
+dry_run: <true|false>
+confirm_shared: <true|false>
+required_reading:
+  - .design/STATE.md
+  - .design/DESIGN-CONTEXT.md
+""")
+```
 
-Pass through all flags and arguments from the invocation to the agent.
+Pass `mode` from the first positional argument; `dry_run` from `--dry-run`;
+`confirm_shared` from `--confirm-shared`. Wait for the agent's completion
+marker before returning.

package/dist/claude-code/.claude/skills/paper-write/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: gdd-paper-write
+description: "Push design decisions from `.design/DESIGN-CONTEXT.md` into the active paper.design canvas by dispatching the `design-paper-writer` agent in one of three modes (annotate / tokenize / roundtrip). Use when the user has completed a design pipeline cycle and wants the decisions reflected in their paper.design canvas. Operates proposal->confirm with `--dry-run`."
+argument-hint: "<annotate|tokenize|roundtrip> [--dry-run]"
+user-invocable: true
+tools: Read, Write, Bash, Grep, Glob
+---
+
+# gdd-paper-write
+
+Dispatches the `design-paper-writer` agent to write design decisions back to the active paper.design canvas. The shared probe pattern (ToolSearch → live call → STATE.md write) and connection handshake are documented at `../../reference/shared-preamble.md#connection-handshake-summary` and `../../connections/paper-design.md`.
+
+## Usage
+
+```
+/get-design-done paper-write <mode> [--dry-run]
+```
+
+Modes:
+- `annotate` - add design decision comments to canvas nodes
+- `tokenize` - sync CSS token values to paper.design node styles
+- `roundtrip` - write implementation status back as text/HTML layers
+
+Flags:
+- `--dry-run` - emit the proposal without executing any paper.design writes
+
+paper.design has no team-library concept, so there is no `--confirm-shared` flag. Every write still requires an explicit `yes` confirmation (unless `--dry-run` is set).
+
+## Prerequisites
+
+1. paper.design MCP registered. Install: `claude mcp add paper-design --transport http https://mcp.paper.design/sse` then restart the session. See `../../connections/paper-design.md` for the full probe pattern and budget rules.
+2. `.design/DESIGN-CONTEXT.md` exists (run `discover` first)
+3. `.design/STATE.md` `<connections>` shows `paper-design: available`. If `not_configured` or `unavailable`, the agent will STOP with a diagnostic.
+
+Budget: the agent tracks `budget_used` in STATE.md `<connections>` and warns when usage reaches 90/100 on the free tier.
+
+## Required Reading
+
+Read `.design/STATE.md` and `.design/DESIGN-CONTEXT.md` before dispatching the agent.
+
+## Dispatch
+
+```
+Task("design-paper-writer", """
+mode: <annotate|tokenize|roundtrip>
+dry_run: <true|false>
+required_reading:
+  - .design/STATE.md
+  - .design/DESIGN-CONTEXT.md
+""")
+```
+
+Pass `mode` from the first positional argument; `dry_run` from `--dry-run`.
+Wait for the agent's completion marker before returning.

package/dist/claude-code/.claude/skills/pencil-write/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: gdd-pencil-write
+description: "Update local `.pen` source files with design decisions from `.design/DESIGN-CONTEXT.md` by dispatching the `design-pencil-writer` agent in one of two modes (annotate / roundtrip). Use when the user has completed a design pipeline cycle and wants the decisions reflected in their `.pen` files. Operates proposal->confirm with `--dry-run`."
+argument-hint: "<annotate|roundtrip> [--dry-run]"
+user-invocable: true
+tools: Read, Write, Bash, Grep, Glob
+---
+
+# gdd-pencil-write
+
+Dispatches the `design-pencil-writer` agent to write design decisions back to `.pen` spec files. Unlike Figma/paper.design, pencil.dev keeps `.pen` YAML specs as the project's git-tracked source of truth; no MCP is required and every write is committed atomically. The probe pattern (file-based, no ToolSearch) and integration contract are documented at `../../connections/pencil-dev.md`.
+
+## Usage
+
+```
+/get-design-done pencil-write <mode> [--dry-run]
+```
+
+Modes:
+- `annotate` - append DESIGN-DEBT findings as comments to the relevant `.pen` files
+- `roundtrip` - update `.pen` spec frontmatter (design-tokens, state) from verified implementation
+
+There is no `tokenize` mode; `.pen` files are source-of-truth specs, not derived artifacts.
+
+Flags:
+- `--dry-run` - emit the proposal without writing or committing any `.pen` changes
+
+## Prerequisites
+
+1. pencil.dev workspace detected; one or more `.pen` files in `cwd` (no MCP install required):
+   ```bash
+   find . -name "*.pen" -not -path "*/node_modules/*" | head -5
+   ```
+2. `.design/DESIGN-CONTEXT.md` exists (run `discover` first). For `annotate` mode, `.design/DESIGN-DEBT.md` is also required. For `roundtrip` mode, `.design/DESIGN-VERIFICATION.md` is also required.
+3. `.design/STATE.md` `<connections>` shows `pencil-dev: available`. If `not_configured`, no `.pen` files were found at probe time; re-run `discover` or `connections` after adding `.pen` specs.
+
+## Required Reading
+
+Read `.design/STATE.md` and `.design/DESIGN-CONTEXT.md` before dispatching the agent.
+
+## Dispatch
+
+```
+Task("design-pencil-writer", """
+mode: <annotate|roundtrip>
+dry_run: <true|false>
+required_reading:
+  - .design/STATE.md
+  - .design/DESIGN-CONTEXT.md
+""")
+```
+
+Pass `mode` from the first positional argument; `dry_run` from `--dry-run`.
+Wait for the agent's completion marker before returning.

package/dist/claude-code/.claude/skills/report-issue/SKILL.md

@@ -15,7 +15,7 @@ If invoked without an error context (the user just typed `/gdd:report-issue` col
 
 ## Steps
 
-0. **Kill-switch** (D-08). Call `isDisabled()` from `scripts/lib/issue-reporter/kill-switch.cjs` FIRST. Either env (`GDD_DISABLE_ISSUE_REPORTER=1`) OR config (`.design/config.json` with `{ "issue_reporter": false }`) makes the command unavailable. Surface the disable line via `getDisableReason()` ('env' wins when both set) and stop. No draft, no triage, no payload. `gsd-health` mirrors the same line for at-a-glance verification.
+0. **Kill-switch** (D-08). Call `isDisabled()` from `scripts/lib/issue-reporter/kill-switch.cjs` FIRST. Either env (`GDD_DISABLE_ISSUE_REPORTER=1`) OR config (`.design/config.json` with `{ "issue_reporter": false }`) makes the command unavailable. Surface the disable line via `getDisableReason()` ('env' wins when both set) and stop. No draft, no triage, no payload. `/gdd:health` mirrors the same line for at-a-glance verification.
 1. **Triage**. Call `matchKnownFailure(errorContext)` from `scripts/lib/issue-reporter/triage-matcher.cjs` (Plan 30-03). If `matched === true` and `--force-report` is NOT set: print the suggested diagnosis + remedy, stop. Do NOT write a draft. (D-07)
 2. **Assemble**. Call `assemble(commandName, errorContext, trajectoryRef?, capabilityGapEvent?)` from `scripts/lib/issue-reporter/payload-assembly.cjs` (Plan 30-02). This layers Phase 22 redact → Phase 30 pseudonymize, computes the fingerprint, and renders bilingual disclaimer + sections.
 3. **Draft**. Call `writeDraft({title, body, fingerprint})` from `scripts/lib/issue-reporter/draft-writer.cjs`. Print the absolute path: `Draft written to .design/issue-drafts/<timestamp>-<fp8>.md`. The file persists across decline - the user keeps their work either way. (D-04)
@@ -48,6 +48,6 @@ Available on `/gdd:report-issue`. Overrides the triage gate (Step 1) but does NO
 - **No `EDITOR` set.** The path is printed; open it in whatever editor you prefer, save, then return to the consent prompt.
 - **Triage matched something irrelevant.** Pass `--force-report` to bypass the gate. Consent is still required.
 - **`gh` not installed (D-10).** After consent, the payload is copied to your clipboard and an issue-template URL is printed. Paste into the URL to file manually. Install `gh` later and the existing draft can be re-submitted.
-- **Command unavailable / disabled (D-08).** Run `gsd-health`. The `issue reporter:` line shows the active disable surface - either `disabled by env (GDD_DISABLE_ISSUE_REPORTER=1)` or `disabled by config (.design/config.json: issue_reporter=false)`. Unset the env var or flip the config key to re-enable.
+- **Command unavailable / disabled (D-08).** Run `/gdd:health`. The `issue reporter:` line shows the active disable surface - either `disabled by env (GDD_DISABLE_ISSUE_REPORTER=1)` or `disabled by config (.design/config.json: issue_reporter=false)`. Unset the env var or flip the config key to re-enable.
 
 See [report-issue-procedure.md](./report-issue-procedure.md) for the full procedure with rationale per decision (D-02, D-03, D-04, D-05, D-07, D-11).

package/dist/claude-code/.claude/skills/router/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-router
-description: "Routes a /gdd command to fast|quick|full path + S|M|L|XL complexity_class and returns {path, complexity_class, model_tier_overrides, resolved_models, estimated_cost_usd, cache_hits}. Deterministic - no model call. Invoked once at command entry before any Agent spawn. Read by hooks/budget-enforcer.js."
+description: "Routes a /gdd command to fast|quick|full path + S|M|L|XL complexity_class and returns {path, complexity_class, model_tier_overrides, resolved_models, estimated_cost_usd, cache_hits}. Deterministic - no model call. Invoked once at command entry before any Agent spawn. Read by hooks/budget-enforcer.ts."
 argument-hint: "<intent-string> [<target-artifacts-csv>]"
 tools: Read, Bash, Grep
 ---
@@ -9,7 +9,7 @@ tools: Read, Bash, Grep
 
 ## Role
 
-You are a deterministic routing skill. You do not spawn agents. You read `.design/budget.json`, `reference/model-prices.md`, `.design/cache-manifest.json` (if present), and the agent frontmatter list, then emit a single JSON object describing the planned spawn graph. The budget-enforcer hook (`hooks/budget-enforcer.js`) consumes your output on every `Agent` tool call.
+You are a deterministic routing skill. You do not spawn agents. You read `.design/budget.json`, `reference/model-prices.md`, `.design/cache-manifest.json` (if present), and the agent frontmatter list, then emit a single JSON object describing the planned spawn graph. The budget-enforcer hook (`hooks/budget-enforcer.ts`) consumes your output on every `Agent` tool call.
 
 ## Invocation Contract
 

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

@@ -2,12 +2,11 @@
 name: verify-procedure
 type: meta-rules
 version: 1.0.0
-phase: 28.5
 tags: [verify, procedure, extracted, pipeline-stage, gap-loop, must-have, quality-gate]
 last_updated: 2026-05-18
 ---
 
-Source: extracted from `skills/verify/SKILL.md` (Phase 28.5 rework - D-10 extract-then-link).
+Source: extracted from `skills/verify/SKILL.md` to keep the SKILL focused on the essential workflow.
 The skill's essential workflow stays in `../skills/verify/SKILL.md`; this file holds the
 detail the agent reaches for when executing a specific step (state integration, quality-gate
 decision tree, agent spawn protocols, gap-response loop, must-have flipping).
@@ -28,9 +27,9 @@ methodology, agent prompts, and gap-loop semantics.
 1. `mcp__gdd_state__transition_stage` with `to: "verify"`.
 2. `mcp__gdd_state__get` → snapshot `state`. Read `state.must_haves` - this is the verification checklist; each M-XX starts at `status: pending` and will be flipped to `pass` or `fail` as verification concludes.
 
-#### Step 2.5 - Quality-gate gate (D-08, D-09)
+#### Step 2.5 - Quality-gate gate
 
-Before resume detection, inspect `state.quality_gate` from the same snapshot. The Stage 4.5 quality-gate skill (see `skills/quality-gate/SKILL.md`) writes a single `<run/>` element capturing the most recent run; this step is the verify-side consumer of that result. Three branches, evaluated in order:
+Before resume detection, inspect `state.quality_gate` from the same snapshot. The quality-gate skill (see `skills/quality-gate/SKILL.md`) writes a single `<run/>` element capturing the most recent run; this step is the verify-side consumer of that result. Three branches, evaluated in order:
 
 - **`state.quality_gate?.run?.status === "fail"`** → Refuse to advance. The fix loop in `quality-gate/SKILL.md` Step 4 reached `max_iters` without converging, and the verify stage MUST NOT paper over it. Print a blocker reason that includes the iteration count and the `commands_run` field from the run, then call:
 
@@ -43,9 +42,9 @@ Before resume detection, inspect `state.quality_gate` from the same snapshot. Th
 
   Exit immediately with the failure surface visible to the user. Do NOT call `mcp__gdd_state__update_progress` to open the verify stage; the gate refused entry, so the stage was never opened.
 
-- **`state.quality_gate?.run?.status === "timeout"` OR `=== "skipped"`** → Print a one-line warning naming the status and the `commands_run` value, then continue normally. Per D-07 these are signals, not walls: a slow test suite must not hostage the pipeline, and a project with no detectable quality commands must not block verify entry. The warning surfaces the degraded state without halting.
+- **`state.quality_gate?.run?.status === "timeout"` OR `=== "skipped"`** → Print a one-line warning naming the status and the `commands_run` value, then continue normally. These are signals, not walls: a slow test suite must not hostage the pipeline, and a project with no detectable quality commands must not block verify entry. The warning surfaces the degraded state without halting.
 
-- **`state.quality_gate?.run?.status === "pass"` OR `state.quality_gate === null`** → Continue silently. `pass` is the happy path; `null` means the gate has never been run for this cycle (the user skipped Stage 4.5 entirely, which is permitted - verify only *checks* the gate result, never *runs* the gate itself, per the 25-07 out-of-scope clause).
+- **`state.quality_gate?.run?.status === "pass"` OR `state.quality_gate === null`** → Continue silently. `pass` is the happy path; `null` means the gate has never been run for this cycle (the user skipped the quality-gate stage entirely, which is permitted - verify only *checks* the gate result, never *runs* the gate itself).
 
 This step is a pure read against the snapshot already loaded in Step 2 - no extra MCP call is required.
 
@@ -93,7 +92,7 @@ Step P2 — Live tool call:
 Record the preview probe result via `mcp__gdd_state__probe_connections` (batched with the storybook and chromatic probes below — one call per stage, see "Batched connections write" at the end of this section).
 ```
 
-When `preview: available`, the design-verifier agent runs Phase 4B - Screenshot Evidence to resolve `? VISUAL` heuristic flags with real screenshot evidence. See `agents/design-verifier.md` Phase 4B for the screenshot evidence loop.
+When `preview: available`, the design-verifier agent runs Stage 4B - Screenshot Evidence to resolve `? VISUAL` heuristic flags with real screenshot evidence. See `agents/design-verifier.md` Stage 4B for the screenshot evidence loop.
 
 ### Probe Storybook connection
 
@@ -202,7 +201,7 @@ Initialize iteration counter to 0 (used for fix loop limit in Step 3).
 
 Three agents run in sequence. Each waits for its completion marker before the next is spawned.
 
-**Note on lazy gates (Plan 10.1-04 / D-21):** Each full checker is preceded by a cheap Haiku gate that reads the diff and may return `{spawn: false}` to short-circuit. When gated out, `lazy_skipped: true` is appended to `.design/telemetry/costs.jsonl`. Gates: `design-verifier-gate` (before 1b), `design-integration-checker-gate` (before 1c). `design-context-checker-gate` is wired into `skills/discover/SKILL.md` Step 1.75.
+**Note on lazy gates:** Each full checker is preceded by a cheap Haiku gate that reads the diff and may return `{spawn: false}` to short-circuit. When gated out, `lazy_skipped: true` is appended to `.design/telemetry/costs.jsonl`. Gates: `design-verifier-gate` (before 1b), `design-integration-checker-gate` (before 1c). `design-context-checker-gate` is wired into `skills/discover/SKILL.md` Step 1.75.
 
 ### 1a. Run design-auditor first (retrospective 7-pillar audit)
 
@@ -274,9 +273,9 @@ Task("design-verifier", """
 You are the design-verifier agent. Run the 5-phase verification against completed design work.
 
 DESIGN-AUDIT.md (above) contains a retrospective 7-pillar qualitative audit from design-auditor.
-Read it as supplementary signal — incorporate the priority fix list into your Phase 5 gap analysis
+Read it as supplementary signal — incorporate the priority fix list into your Stage 5 gap analysis
 where relevant. The auditor's 1-4 scores complement your 0-10 category scores; they do not
-replace your Phase 1 category scoring.
+replace your Stage 1 category scoring.
 
 Context:
   auto_mode: <true|false>
@@ -432,7 +431,7 @@ Task("design-fixer", """
 @.design/DESIGN-CONTEXT.md
 </required_reading>
 
-Fix all BLOCKER and MAJOR gaps from ## Phase 5 - Gaps in DESIGN-VERIFICATION.md.
+Fix all BLOCKER and MAJOR gaps from ## Stage 5 - Gaps in DESIGN-VERIFICATION.md.
 For each gap: apply the targeted fix to the file/location in the gap's Location field.
 After each fix, make an atomic commit: fix(design-gap-GNN): [gap title].
 

package/dist/claude-code/.claude/skills/warm-cache/SKILL.md

@@ -62,7 +62,7 @@ Full + filtered command-output examples live in `./../cache-manager/cache-policy
 
 - **Pre-sprint**: `/gdd:warm-cache` is the recommended first line of a `/gdd:discover`, `/gdd:plan`, or `/gdd:verify` sprint. Users type it before the real command, or an orchestrator-level wrapper runs it automatically if `agent-metrics.json` (Plan 10.1-05) indicates the last sprint was > 5 min ago.
 - **`reference/shared-preamble.md`** (authored in Plan 10.1-04) is the essential file for this command - agents import it first per D-17, which makes the first N tokens of every agent's rendered system prompt identical, which is what Anthropic's prompt cache keys on.
-- **No interaction with `hooks/budget-enforcer.js`** - the hook is a PreToolUse gate; warm-cache runs as an ordinary Agent tool call itself and is subject to the hook (each no-op Haiku ping is budgeted and logged like any other spawn). This is intentional: warm-cache's own telemetry rows in `.design/telemetry/costs.jsonl` are the evidence that cache priming happened.
+- **No interaction with `hooks/budget-enforcer.ts`** - the hook is a PreToolUse gate; warm-cache runs as an ordinary Agent tool call itself and is subject to the hook (each no-op Haiku ping is budgeted and logged like any other spawn). This is intentional: warm-cache's own telemetry rows in `.design/telemetry/costs.jsonl` are the evidence that cache priming happened.
 
 ## Cost Model
 

package/hooks/first-run-nudge.cjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * get-design-done — first-run nudge (Phase 14.7)
+ *
+ * Port of hooks/first-run-nudge.sh to pure Node CommonJS (Phase 28.x).
+ * SessionStart hook. Silent-on-failure by policy: exits 0 on every error path.
+ * Prints exactly one restrained line pointing at /gdd:start when all gates
+ * pass, and nothing otherwise.
+ *
+ * Non-obvious behavior preserved:
+ *  - Logger is silent unless GDD_NUDGE_DEBUG=1 (matches bash `${VAR:-0}`).
+ *  - HOME falls back to USERPROFILE (Windows). Mirrors bash `${HOME:-$USERPROFILE}`.
+ *  - read_state_stage uses the same regex shape as the bash sed: drops an
+ *    optional surrounding double-quote and stops at the first whitespace.
+ *  - has_recent_gdd_command is a placeholder that always returns false (matches
+ *    the bash `return 1` → `is_active` boolean false).
+ *  - Sourcing guard: helpers are exported on module.exports; main() only runs
+ *    when invoked as the entry point (require.main === module).
+ *  - Always exit 0 — every error path is swallowed.
+ *  - The locked nudge copy appears exactly once in this file (test asserts
+ *    the nudge string occurs exactly once in the hook source).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const NUDGE_LINE =
+  'Tip: run /gdd:start to let GDD inspect this codebase and suggest one first fix.\n';
+
+function log(msg) {
+  if (process.env.GDD_NUDGE_DEBUG === '1') {
+    process.stderr.write(`[gdd first-run-nudge] ${msg}\n`);
+  }
+}
+
+/**
+ * Gate 1 — repo already has GDD state, suppress.
+ * @param {string} designDir absolute path to <cwd>/.design
+ * @returns {boolean}
+ */
+function hasDesignState(designDir) {
+  try {
+    const config = path.join(designDir, 'config.json');
+    const state = path.join(designDir, 'STATE.md');
+    return isFile(config) || isFile(state);
+  } catch (_e) {
+    return false;
+  }
+}
+
+/**
+ * Gate 2 — per-install dismissal flag.
+ * @param {string} homeDir resolved HOME (or USERPROFILE on Windows)
+ * @returns {boolean}
+ */
+function isDismissed(homeDir) {
+  try {
+    if (!homeDir) return false;
+    return isFile(path.join(homeDir, '.claude', 'gdd-nudge-dismissed'));
+  } catch (_e) {
+    return false;
+  }
+}
+
+/**
+ * Reads the first `stage:` line out of STATE.md and strips surrounding quoting
+ * the way the bash sed expression does (drops an optional surrounding double
+ * quote, captures non-quote/non-whitespace chars, ignores any trailing text).
+ *
+ * @param {string} stateFilePath absolute path to STATE.md
+ * @returns {string} the captured stage value, or '' if unavailable
+ */
+function readStateStage(stateFilePath) {
+  try {
+    if (!isFile(stateFilePath)) return '';
+    const text = fs.readFileSync(stateFilePath, 'utf8');
+    const lines = text.split(/\r?\n/);
+    for (const line of lines) {
+      if (/^stage:/.test(line)) {
+        const m = line.match(/^stage:[ \t]*"?([^"\s]+)"?.*/);
+        if (m && m[1]) return m[1];
+        return '';
+      }
+    }
+    return '';
+  } catch (_e) {
+    return '';
+  }
+}
+
+const ACTIVE_STAGES = new Set(['plan', 'design', 'verify', 'executing', 'discussing']);
+
+/**
+ * Gate 3 — STATE.md stage belongs to an active pipeline window.
+ * @param {string} stateFilePath absolute path to STATE.md
+ * @returns {boolean}
+ */
+function isActiveStage(stateFilePath) {
+  const s = readStateStage(stateFilePath);
+  return ACTIVE_STAGES.has(s);
+}
+
+/**
+ * Gate 4 — recent session history has a gdd:* command.
+ * Placeholder: no portable transcript path exposed to SessionStart hooks today.
+ * Mirrors the bash version's `return 1` (false) so we never falsely suppress.
+ * @returns {boolean}
+ */
+function hasRecentGddCommand() {
+  return false;
+}
+
+function isFile(p) {
+  try {
+    const st = fs.statSync(p);
+    return st.isFile();
+  } catch (_e) {
+    return false;
+  }
+}
+
+function resolveHomeDir() {
+  // bash: ${HOME:-$USERPROFILE} — HOME wins if set (even on Windows), else USERPROFILE.
+  return process.env.HOME || process.env.USERPROFILE || '';
+}
+
+function main() {
+  try {
+    const cwd = process.cwd();
+    const designDir = path.join(cwd, '.design');
+    const stateFile = path.join(designDir, 'STATE.md');
+    const homeDir = resolveHomeDir();
+
+    if (hasDesignState(designDir)) {
+      log('design state present — suppress');
+      process.exit(0);
+    }
+    if (isDismissed(homeDir)) {
+      log('dismissal flag present — suppress');
+      process.exit(0);
+    }
+    if (isActiveStage(stateFile)) {
+      log('active stage — suppress');
+      process.exit(0);
+    }
+    if (hasRecentGddCommand()) {
+      log('recent gdd:* command detected — suppress');
+      process.exit(0);
+    }
+    // All gates passed — emit the locked one-line nudge.
+    process.stdout.write(NUDGE_LINE);
+    process.exit(0);
+  } catch (_e) {
+    // Silent-on-failure: every error path exits 0.
+    process.exit(0);
+  }
+}
+
+module.exports = {
+  hasDesignState,
+  isDismissed,
+  readStateStage,
+  isActiveStage,
+  hasRecentGddCommand,
+};
+
+if (require.main === module) {
+  main();
+}