@hegemonart/get-design-done 1.28.0 → 1.28.6

package/skills/debug/SKILL.md

@@ -1,33 +1,36 @@
 ---
 name: gdd-debug
-description: "Symptom-driven design investigation with persistent state. Writes findings to .design/DEBUG.md."
+description: "Symptom-driven design debugger with persistent state. Phase 1 builds a feedback loop; Phase 2 hypothesizes. Writes findings to .design/DEBUG.md. Use when a symptom needs systematic, one-variable-at-a-time tracking."
 argument-hint: "[<symptom description>]"
 tools: Read, Write, Grep, Glob, AskUserQuestion, Task
 ---
 
 # /gdd:debug
 
-Systematic, checkpoint-driven design debugger. Loads philosophy from `reference/debugger-philosophy.md` and writes every investigation step to `.design/DEBUG.md` so killed sessions can resume.
+Systematic, checkpoint-driven design debugger. Loads framing from `./../reference/debugger-philosophy.md` (five principles) and the feedback-loop construction catalog from `./debug-feedback-loops.md` (10 priority-ordered loop paths). Phase 1 builds the loop; Phase 2 generates hypotheses. Writes every step to `.design/DEBUG.md` so killed sessions can resume.
 
 ## Steps
 
-1. **Load philosophy**: Read `reference/debugger-philosophy.md` and keep its five principles in mind for the entire session.
+1. **Load philosophy + feedback-loop catalog**: Read `reference/debugger-philosophy.md` (five principles) and `./debug-feedback-loops.md` (10 construction paths; iterate-on-loop discipline). Keep both in mind for the entire session.
 2. **Symptom**: If no symptom argument was passed, ask (AskUserQuestion): "What design symptom are you investigating? (observable only — 'cards look crowded', not 'padding is wrong')"
 3. **Resume check**: Read `.design/DEBUG.md` if it exists. If there is an open session with no `### Fix Proposal` block, ask: "Resume existing session '<symptom>' or start a new one?"
-4. **Ground truth load**: Read `.design/DESIGN-PLAN.md` (goals), `.design/STATE.md` `<decisions>` block (D-XX items), and any relevant source files pointed at by the symptom.
-5. **Optional rendered-output check**: Use ToolSearch to see if Playwright/Preview MCP tools are available. If yes, capture rendered state. If no, fall back to code-only analysis.
-6. **Investigation loop** — for each step:
+4. **Ground truth load**: Read `.design/DESIGN-PLAN.md` (goals), `.design/STATE.md` `<decisions>` block (D-XX items), and any source files pointed at by the symptom.
+5. **Phase 1 — Build a feedback loop**: Before ANY hypothesizing, build a deterministic, fast, agent-runnable pass/fail signal that reproduces the symptom. See `./debug-feedback-loops.md` for the 10 construction paths in priority order (failing test > curl > CLI fixture > headless browser > trace replay > throwaway harness > fuzz > bisect > differential > HITL bash). Iterate on the loop itself (cache setup, narrow scope, pin time, seed RNG, isolate filesystem, freeze network) before iterating on the bug. For non-deterministic bugs: raise reproduction rate to at least 30%, not clean repro. **Do not proceed to Phase 2 (hypothesis generation) until you have a loop you believe in.**
+6. **Optional rendered-output check**: Use ToolSearch to see if Playwright/Preview MCP tools are available. If yes, capture rendered state. If no, fall back to code-only analysis.
+7. **Phase 2 — Investigation loop** (one hypothesis at a time) — for each step:
    - Form one hypothesis (one variable).
-   - Investigate (read files, grep, measure).
+   - Investigate (read files, grep, measure). Re-run the Phase 1 feedback loop to confirm the hypothesis pinpoints the symptom.
    - Append to `.design/DEBUG.md`:
+
      ```markdown
      ## <symptom> — <date>
      ### Hypothesis <N>
      ### Investigation
      ### Finding
      ```
+
    - Ask (AskUserQuestion): "Continue investigating? (yes / found it / dead end)"
-7. **When found**: Write `### Fix Proposal` block with a concrete patch description. Ask: "Create a todo with `/gdd:todo add`, or execute the fix now?"
+8. **When found**: Write `### Fix Proposal` block with a concrete patch description. Re-run the Phase 1 loop to confirm the fix flips it from fail to pass. Ask: "Create a todo with `/gdd:todo add`, or execute the fix now?"
 
 ## Do Not
 

package/skills/debug/debug-feedback-loops.md

@@ -0,0 +1,119 @@
+---
+name: debug-feedback-loops
+type: heuristic
+version: 1.0.0
+phase: 28.5
+tags: [debug, feedback-loop, deterministic-signal, iterate-on-loop, mit-port, mattpocock]
+last_updated: 2026-05-18
+---
+
+Source: mattpocock/skills (MIT) — engineering/diagnose Phase 1 — adapted with permission. See `../NOTICE` for the full attribution block.
+
+# Debug Feedback Loops
+
+Build a feedback loop before any hypothesizing. A feedback loop is a deterministic, fast, agent-runnable pass/fail signal that tells you whether the bug is reproduced right now, every time, in well under a minute. Without it, debugging degenerates to speculation.
+
+**Do not proceed to Phase 2 (hypothesis generation) until you have a loop you believe in.**
+
+## The 10 construction paths
+
+Listed in priority order — try the cheaper, faster paths first. Each entry: when to reach for it, the shape of the loop, and the verification snippet.
+
+### 1. Failing test
+
+The strongest signal. Write the failing test in the project's native test framework (pytest, jest, vitest, go test, cargo test, junit, rspec). Assert the buggy behavior; run with watch mode if available. When the test goes green, the bug is fixed. Best case: reproduces in under 2 seconds, runnable by a fresh agent with one command.
+
+When to reach: the project already has a test runner the agent can invoke; the bug is in a unit/integration-testable code path; the symptom is expressible as a deterministic assertion.
+
+### 2. `curl` against a running endpoint
+
+For HTTP endpoints, a `curl` against the staging or local server with assertion on body/status. Pipe to `jq` for structured assertions. Cheap, reliable, framework-free. Wrap in a 3-line bash script so the loop is one command.
+
+When to reach: the bug is in an HTTP endpoint; the server is already runnable locally; the symptom shows up in response body/status/headers.
+
+### 3. CLI fixture
+
+For CLI tools, a small shell script that invokes the binary with fixture inputs and `grep`s for the symptom in stdout/stderr. Bash one-liner is enough; no test framework. Capture exit code, stdout, and stderr separately.
+
+When to reach: the bug is in a CLI tool; the symptom shows up in stdout/stderr/exit-code; the failure mode is reproducible from a fixed input.
+
+### 4. Headless browser
+
+For UI bugs, a Playwright or Puppeteer script that opens the page, performs the trigger action, and screenshots the symptom region. Compare against a known-good fixture or assert on a DOM selector's text/attribute. Use a deterministic seed for any randomness (animations, IDs, dates).
+
+When to reach: the bug is visible only in a rendered browser context; DOM-level inspection isn't enough; the symptom involves layout, paint, or interaction timing.
+
+### 5. Trace replay
+
+For bugs reproducible from a captured execution trace, replay the trace deterministically. `rr` on Linux for native binaries, record-and-replay plugins for some browsers, Chrome DevTools recording for web, or a captured production trace for distributed systems. Replays are bit-for-bit reproducible — the gold standard for non-deterministic bugs that have been captured once.
+
+When to reach: the bug is hard to reproduce live but you have a captured trace; the trace runtime is available; bit-identical replay is achievable.
+
+### 6. Throwaway harness
+
+Write a minimal `main()` that calls the buggy function with known inputs and prints the output. ~10 lines. Side-step framework startup costs entirely. Throw away when fixed. Useful when the test framework's setup is too heavy to iterate quickly.
+
+When to reach: the bug is in a single function with a clear input/output contract; framework setup dominates iteration time; you'd rather iterate on a 10-line script than wait for the framework to boot.
+
+### 7. Fuzz
+
+When the bug surfaces unpredictably, use property-based testing (Hypothesis, fast-check, jqwik) or AFL/libfuzzer for native code. The fuzzer narrows on the failing input across runs. Combine with a "minimize" pass to shrink the failing input to its smallest form.
+
+When to reach: the input space is exotic (parsers, serializers, network protocols); the bug isn't tied to a specific input you can name; you suspect a class of inputs but can't enumerate it.
+
+### 8. Bisect
+
+When you know "it worked on commit X, fails on commit Y," `git bisect` is the loop. Each iteration runs the test/curl/CLI from a higher path. Reproduces in O(log N) commits. Combine with `git bisect run <script>` to fully automate.
+
+When to reach: the bug regressed between two known commits; you have a binary pass/fail script from one of the earlier paths; you don't yet know which commit introduced the regression.
+
+### 9. Differential
+
+When you have two systems and one's correct, write a differential harness: feed the same input to both, assert outputs match. Cheap for migration bugs (old → new implementation) and protocol bugs (your client vs reference client). The harness becomes the regression test once the bug is fixed.
+
+When to reach: a known-good reference implementation exists; the buggy code is supposed to match the reference; input space is enumerable enough to drive both implementations side by side.
+
+### 10. HITL bash (Human In The Loop)
+
+Last resort. A documented sequence of bash commands a human runs that produces a pass/fail signal. Slower (human in the path), but better than no loop. The agent reads stdout/stderr; the human reads the screen and reports. Use only when no automatable signal is available — physical hardware, vendor portals, manual eyeball checks.
+
+When to reach: every other path is blocked by an unautomatable surface; the human cost is acceptable for the duration of the investigation; the loop will be retired or upgraded the moment any earlier path becomes possible.
+
+## Iterate on the loop itself
+
+The loop is a first-class artifact. Iterate on it before iterating on hypotheses. A 5-minute loop run 20 times costs 100 minutes; a 5-second loop run 20 times costs 100 seconds. Spending 30 minutes tightening the loop pays back inside the same session.
+
+- **Cache setup**: hoist expensive setup (DB seed, fixture load, container start) out of the loop body. Run the loop only on the fast inner part. Use `--no-rebuild`, persistent containers, or test-runner watch modes.
+- **Narrow scope**: if the loop runs the full test suite to verify one bug, narrow to just the failing test/group. Fewer side-effects, faster iterations. `pytest -k`, `jest -t`, `vitest --testNamePattern`, `go test -run` are your friends.
+- **Pin time**: when the bug is time-dependent, freeze the clock (`sinon.useFakeTimers`, `jest.useFakeTimers`, `freezegun`, `time-machine`). Removes wallclock as a variable.
+- **Seed RNG**: every random source gets a fixed seed in the loop. `Math.random`, `crypto.randomBytes`, `random.seed(...)`, `rand::SeedableRng`. Determinism over coverage — the loop must be bit-identical given the same code state.
+- **Isolate filesystem**: run in a `tmpdir`; reset between iterations. Avoids "fixed on my machine" via stale state. Bind-mount or copy fixtures into the tmpdir per iteration.
+- **Freeze network**: mock or record/replay all outbound calls (`nock`, `vcr`, `polly.js`, `mitmproxy --replay`). Real-network loops are non-deterministic by definition.
+
+The discipline: every iteration of the loop should be bit-identical given the same code state. If two iterations differ without a code change, the loop has a hidden input — find it and pin it before continuing.
+
+## Non-deterministic bugs
+
+Some bugs surface only sometimes. The goal is NOT a clean repro — the goal is to raise the reproduction rate to debuggable.
+
+- **Measure baseline rate**: run the loop N=20 times. Note pass/fail count. Record the rate so you can tell whether later changes helped.
+- **Raise stressors**: add concurrency, contention, memory pressure, network jitter (use `tc qdisc add dev lo root netem delay 100ms 50ms` on Linux, `Network Link Conditioner` on macOS). Re-measure.
+- **Target the suspect axis**: if you suspect a race, add a deterministic sleep at the suspect point and measure. If reproduction jumps to 100% with sleep, the race is in that region. If it stays at baseline, the race is elsewhere.
+- **A 30% reproduction rate is debuggable.** A 5% rate isn't — keep raising stressors until you cross 30%. At 30% you can iterate; at 5% you're guessing whether your fix helped or you got lucky.
+
+## When the loop is good enough
+
+The loop is good enough when:
+
+- It runs in under a minute (preferably under 10 seconds).
+- It's deterministic (or, for non-determinism, reproduces at least 30% of the time).
+- It's automatable — no human in the inner loop except by explicit choice (Path 10).
+- A fresh agent could pick up the loop and run it without context.
+
+Only after the loop is good enough should you proceed to hypothesizing the fix. The hypothesis cycle is governed by `./debugger-philosophy.md` (one variable at a time, do not stop at first plausible cause, the bug is where you didn't look).
+
+## Cross-references
+
+- `./debugger-philosophy.md` — companion framing; the hypothesis-cycle discipline that runs in Phase 2 once the loop is in place.
+- `../skills/debug/SKILL.md` — Phase 1 of the debug skill mandates this catalog before any hypothesis generation.
+- `../NOTICE` — full mattpocock/skills MIT attribution.

package/skills/design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design
-description: "Stage 4 of 5 — reads DESIGN-PLAN.md, spawns design-executor per task with wave coordination and parallel/sequential routing. Thin orchestrator."
+description: "Stage 4 of 5 orchestrator that reads DESIGN-PLAN.md, partitions tasks by wave + parallel-safe flag, and spawns design-executor agents with the appropriate isolation (worktree for parallel batches, in-place for sequential tail). Use when DESIGN-PLAN.md is approved and ready for implementation."
 argument-hint: "[--auto] [--parallel]"
 user-invocable: true
 tools: Read, Write, Bash, Grep, Glob, Task, AskUserQuestion, mcp__gdd_state__get, mcp__gdd_state__transition_stage, mcp__gdd_state__update_progress, mcp__gdd_state__set_status, mcp__gdd_state__add_blocker, mcp__gdd_state__resolve_blocker, mcp__gdd_state__checkpoint
@@ -10,290 +10,72 @@ tools: Read, Write, Bash, Grep, Glob, Task, AskUserQuestion, mcp__gdd_state__get
 
 **Stage 4 of 5** in the get-design-done pipeline. Thin orchestrator. All design execution intelligence lives in `agents/design-executor.md`.
 
----
-
-## Stage entry
-
-1. Call `mcp__gdd_state__transition_stage` with `to: "design"`.
-   - Gate failure surfaces `error.context.blockers` to the user; do not advance.
-   - If the transition succeeds and the prior stage was already `design` with `status: in_progress`, this is a RESUME — use `task_progress` numerator as source of truth and skip tasks that already have a corresponding `.design/tasks/task-NN.md` file.
-2. Call `mcp__gdd_state__get` → snapshot `state`; read `state.position.wave` to decide execution plan.
-
-Abort only if `.design/DESIGN-PLAN.md` is missing:
-> "No plan found. Run `/get-design-done:plan` first."
-
----
-
-## Flag Parsing
-
-- `--auto` → `auto_mode=true` (no mid-stage prompts; architectural deviations still stop the individual task but continue with remaining tasks)
-- `--parallel` → `parallel_mode=true` (use worktree isolation for `Parallel: true` tasks)
+Full procedure detail: `./design-procedure.md`.
 
 ---
 
-## Pre-execution — Directionally-open check
-
-Scan DESIGN-PLAN.md for tasks marked as "directionally open" (exploration-appropriate — e.g., tasks whose acceptance criteria read "explore N directions" or "pick a visual approach"). If any are found, print:
-
-> "Tasks [IDs] appear directionally open — consider running `/gdd:sketch` first to explore variants before implementation."
-
-Skip if `auto_mode=true`.
+## Stage entry
 
-## Pre-execution — Project-local conventions
+1. `mcp__gdd_state__transition_stage` with `to: "design"`. Gate failure surfaces `error.context.blockers`; do not advance. Resume case: prior stage `design` + `status: in_progress` -> skip tasks where `.design/tasks/task-NN.md` already exists.
+2. `mcp__gdd_state__get` -> snapshot `state`; read `state.position.wave` for execution plan.
+3. Abort only if `.design/DESIGN-PLAN.md` is missing: "No plan found. Run `/get-design-done:plan` first."
 
-When spawning the executor, include any `./.claude/skills/design-*-conventions.md` files in `<required_reading>` so the executor sees project-local design conventions (typography, color, layout, motion, component, interaction decisions codified from prior sketch wrap-ups). Also include any `~/.claude/gdd/global-skills/*.md` files if the directory exists � global skills are cross-project conventions that inform but do not override project-local D-XX decisions.
+Detail: `./design-procedure.md` §Stage entry.
 
 ---
 
-### .stories.tsx Stub (when storybook project detected)
+## Flags + pre-execution checks
 
-After every new component file is created by the design-executor:
-
-Step 1 — Check project detection (does not require server running):
-  Bash: ls .storybook/ 2>/dev/null || grep '"storybook"' package.json 2>/dev/null
-  → Found → storybook_project: true
-  → Not found → skip .stories.tsx emission
-
-Step 2 — When storybook_project: true, emit a CSF stub alongside the component:
-  File: `<same directory as component>/<ComponentName>.stories.tsx`
-  Content follows CSF format (see `connections/storybook.md` for full template):
-  - Import `Meta` and `StoryObj` from `@storybook/react`
-  - Import the new component
-  - `meta: Meta<typeof ComponentName>` with `title` and `parameters.a11y.test = 'error'`
-  - Export `Default`, `Primary`, `Disabled` story variants
-  Adjust `title` to match directory structure (e.g., `'Components/Button'` or `'Features/Auth/LoginForm'`)
-
-Note: the `.stories.tsx` stub is emitted whenever `storybook_project: true` regardless of whether
-the dev server is running. New components need stories even in offline/CI contexts.
+- `--auto` -> `auto_mode=true` (no mid-stage prompts; architectural deviations stop the individual task but continue the rest).
+- `--parallel` -> `parallel_mode=true` (use worktree isolation for `Parallel: true` tasks).
+- **Directionally-open check** (skipped if `auto_mode`): scan DESIGN-PLAN.md for tasks whose criteria read "explore N directions" / "pick a visual approach" and suggest `/gdd:sketch` first.
+- **Project-local conventions**: include any `./.claude/skills/design-*-conventions.md` and `~/.claude/gdd/global-skills/*.md` in every executor's `<required_reading>` — global conventions inform but do not override project-local D-XX decisions.
+- **`.stories.tsx` stub**: after each new component file is created by the executor, emit a CSF stub alongside if `.storybook/` exists or `"storybook"` is in `package.json`, even with the dev server offline. Detail: `./design-procedure.md` §.stories.tsx Stub.
 
 ---
 
 ## Step 1 — Parse DESIGN-PLAN.md
 
-Read `.design/DESIGN-PLAN.md`. Partition tasks by `## Wave N` heading. Within each wave, partition by `Parallel: true` vs `Parallel: false`. Compute `total_tasks` for `task_progress` denominator.
-
-If resuming: skip tasks where `.design/tasks/task-NN.md` already exists.
+Read `.design/DESIGN-PLAN.md`. Partition tasks by `## Wave N` heading. Within each wave, partition by `Parallel: true` vs `Parallel: false`. Compute `total_tasks` for the `task_progress` denominator. If resuming, skip tasks whose `.design/tasks/task-NN.md` already exists.
 
 ---
 
-## Parallelism Decision (per wave, before spawning)
-
-For each wave:
-1. Read `.design/config.json` `parallelism` (or defaults from `reference/config-schema.md`).
-2. Collect candidates in the wave; check `Touches:`, `writes:`, `parallel-safe`, and `typical-duration-seconds` fields.
-3. Apply rules in order from `reference/parallelism-rules.md` (hard → soft). Overlapping Touches split into sequential sub-waves.
-4. Record the parallelism decision for this wave via `mcp__gdd_state__update_progress` with `task_progress: "<completed>/<total>"` and `status: "design_wave_<N>_parallelism: <parallel|serial>, reason=<short-reason>"` — the status string is the canonical carrier (mirrors the plan-stage convention from Plan 20-09; a dedicated tool may be added in a follow-on plan).
-5. If `parallel`: spawn all candidates via concurrent `Task()` calls in one response. If `serial`: spawn sequentially.
-
-### Executor prompt template (applies to every spawned design-executor)
-
-Every spawned executor receives the following STATE.md contract in its prompt:
-
-> **STATE.md mutation protocol** — When you complete a task in your assigned batch, update STATE.md ONLY via the `gdd-state` MCP tools. Specifically:
-> - Report task progress: `mcp__gdd_state__update_progress` with your new `task_progress` fraction.
-> - Add blockers: `mcp__gdd_state__add_blocker` with `{ stage: "design", date: <today>, text: "..." }`.
-> - Resolve your own blockers on fix: `mcp__gdd_state__resolve_blocker` with the blocker id.
->
-> Do NOT `Read` + `Write` `.design/STATE.md` directly — the MCP tools enforce the lockfile and emit mutation events. Direct writes corrupt parallel state.
-
-Inline this protocol block verbatim inside every design-executor prompt in both the parallel-batch and sequential-tail spawns below. Concurrent executors (Phase 10.1 parallel mode) each emit `update_progress` calls; the lockfile (Plan 20-01) and event stream (Plan 20-06) serialize them safely.
-
 ## Step 2 — Wave-by-Wave Execution
 
-For each Wave in order (Wave 1, Wave 2, ...):
-
-### Parallel batch (if `parallel_mode=true` AND any `Parallel: true` tasks in wave)
-
-Report the partition before spawning:
-
-```
-━━━ Wave [N] — parallel mode ━━━
-Parallel batch ([N] tasks — spawning concurrently):
-  [01] [type]: [scope] — touches: [files]
-  [02] [type]: [scope] — touches: [files]
-
-Sequential tail ([N] tasks):
-  [03] [type]: [scope] — touches: [files]
-
-Spawning agents now...
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-Spawn ALL `Parallel: true` tasks in this wave as concurrent `Task()` calls in ONE response. Each call uses `isolation: "worktree"`:
-
-```
-Task("design-executor", """
-<required_reading>
-@.design/STATE.md
-@.design/DESIGN-PLAN.md
-@.design/DESIGN-CONTEXT.md
-@reference/[type-relevant].md
-</required_reading>
-
-You are the design-executor agent. Execute Task NN from DESIGN-PLAN.md.
-
-Prompt context:
-  task_id: NN
-  task_type: [type]
-  task_scope: [scope]
-  task_acceptance_criteria:
-    - [criterion 1]
-    - [criterion 2]
-  wave: N
-  is_parallel: true
-  auto_mode: [true|false]
-
-Write .design/tasks/task-NN.md and make an atomic commit `feat(design-NN): [type] — [scope]`.
-
-Emit `## EXECUTION COMPLETE` when done.
-""", subagent_type="design-executor", isolation="worktree")
-```
+For each wave in order:
 
-Wait for all parallel tasks to emit `## EXECUTION COMPLETE`.
+1. **Parallelism decision (per wave)**: read `.design/config.json` `parallelism`, collect candidates, check `Touches:` / `writes:` / `parallel-safe` / `typical-duration-seconds`, apply `reference/parallelism-rules.md` hard->soft. Overlapping `Touches:` split into sequential sub-waves. Record verdict via `mcp__gdd_state__update_progress` with `status: "design_wave_<N>_parallelism: <parallel|serial>, reason=<short-reason>"`.
+2. **Executor STATE.md protocol** (inlined verbatim into every `design-executor` prompt): executors update STATE.md ONLY via `gdd-state` MCP tools — `update_progress`, `add_blocker`, `resolve_blocker`. NEVER `Read`+`Write` `.design/STATE.md` directly. The MCP tools enforce the lockfile (Plan 20-01) and emit mutation events (Plan 20-06) so concurrent executors serialize safely.
+3. **Parallel batch** (when `parallel_mode=true` AND any `Parallel: true` tasks in wave): announce the partition, spawn all `Parallel: true` tasks via concurrent `Task("design-executor", ..., isolation: "worktree")` calls in ONE response, wait for all `## EXECUTION COMPLETE` markers, merge worktrees (non-overlapping `Touches:` guarantees no conflicts; surface any conflict to the user before continuing), then `update_progress` + `checkpoint`.
+4. **Sequential tail** (`Parallel: false` or `parallel_mode=false`): spawn one `design-executor` at a time (no worktree isolation), waiting for each `## EXECUTION COMPLETE` and emitting `update_progress` per task; `checkpoint` after the final task of the wave.
 
-**Merge worktrees** (preserved from v2.1.0 — do not redesign):
-
-```
-━━━ Parallel batch complete ━━━
-[✓/⚠/✗] Task 01 — [type]
-[✓/⚠/✗] Task 02 — [type]
-
-Merging worktrees...
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-Merge each worktree branch back into the working directory. Each agent touched non-overlapping files (guaranteed by the conflict check on `Touches:` fields). If an unexpected merge conflict appears, flag it and ask the user to resolve before continuing.
-
-After merge, roll up the batch's progress:
-
-- Call `mcp__gdd_state__update_progress` with `task_progress: "<completed>/<total>"` and `status: "design_wave_<N>_parallel_batch_complete"`.
-- Call `mcp__gdd_state__checkpoint` — records the wave boundary in `<timestamps>` and bumps `last_checkpoint`.
-
-### Sequential tail (Parallel: false tasks, or all tasks if `parallel_mode=false`)
-
-Announce each wave before starting:
-
-```
-━━━ Wave [N] — [N tasks] — sequential ━━━
-Tasks:
-  [01] [type]: [scope]
-  [02] [type]: [scope]
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-Run one at a time. Same `Task("design-executor", ...)` pattern with `is_parallel: false` (no worktree isolation):
-
-```
-Task("design-executor", """
-<required_reading>
-@.design/STATE.md
-@.design/DESIGN-PLAN.md
-@.design/DESIGN-CONTEXT.md
-@reference/[type-relevant].md
-</required_reading>
-
-You are the design-executor agent. Execute Task NN from DESIGN-PLAN.md.
-
-Prompt context:
-  task_id: NN
-  task_type: [type]
-  task_scope: [scope]
-  task_acceptance_criteria:
-    - [criterion 1]
-    - [criterion 2]
-  wave: N
-  is_parallel: false
-  auto_mode: [true|false]
-
-Write .design/tasks/task-NN.md and make an atomic commit `feat(design-NN): [type] — [scope]`.
-
-Emit `## EXECUTION COMPLETE` when done.
-""", subagent_type="design-executor")
-```
-
-After each task completes, call `mcp__gdd_state__update_progress` with the new `task_progress: "<completed>/<total>"` and `status: "design_wave_<N>_task_<NN>_complete"`.
-
-After the final sequential task of the wave, call `mcp__gdd_state__checkpoint` — records the wave boundary in `<timestamps>` and bumps `last_checkpoint`.
+Full executor prompts (parallel + sequential variants) and the merge-worktrees protocol: `./design-procedure.md` §Step 2.
 
 ---
 
 ## Step 3 — Wave Checkpoint
 
-After each wave (unless `--auto` flag was passed):
-
-```
-━━━ Wave [N] complete ━━━
-  ✓ [N] tasks complete
-  ⚠ [N] deviations (see .design/tasks/ files)
-
-Ready for Wave [N+1]? (yes / review first)
-━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-Skip checkpoint if `auto_mode=true`.
-
----
+After each wave, unless `auto_mode=true`, prompt: "Ready for Wave [N+1]? (yes / review first)". Skip in `auto_mode`.
 
 ## Step 4 — Handle Deviations
 
-After each wave, check task-NN.md files for `status: deviation`. If any found:
-
-- Call `mcp__gdd_state__get` → read `state.blockers`; present affected task IDs and their blocker descriptions from the returned snapshot.
-- Offer: (a) stop stage, (b) continue remaining tasks
-- In `auto_mode`: continue automatically, log all deviations
-- When a blocker is addressed (fix committed by a follow-up task), call `mcp__gdd_state__resolve_blocker` with the blocker id to clear it from the live state.
+Check task-NN.md files for `status: deviation`. If found: `mcp__gdd_state__get` -> read `state.blockers`, present affected task IDs + blocker descriptions, offer (a) stop, (b) continue. `auto_mode`: continue, log. When a blocker is later fixed by a follow-up task: `mcp__gdd_state__resolve_blocker`.
 
 ---
 
 ## State Update (exit)
 
-1. Call `mcp__gdd_state__set_status` with `status: "design_complete"` — marks the stage completed without transitioning; verify calls `transition_stage` on its entry, keeping the transition atomic with the owning stage.
-2. Call `mcp__gdd_state__checkpoint` — stamps `last_checkpoint` and appends a `design_completed_at` entry to `<timestamps>`.
-
----
+1. `mcp__gdd_state__set_status` -> `"design_complete"` — marks the stage complete WITHOUT transitioning (verify owns its own `transition_stage` on entry).
+2. `mcp__gdd_state__checkpoint` — stamps `last_checkpoint`, appends `design_completed_at` to `<timestamps>`.
 
 ## After Completion
 
-Print summary:
-
-```
-━━━ Design stage complete ━━━
-Tasks: [N] complete / [M] total
-Deviations: [N]
-Commits: [git log --oneline since stage start]
-
-Next: /get-design-done:verify
-  → Scores the result against baseline, checks must-haves,
-    runs NNG heuristic evaluation, and identifies gaps.
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
+Print the `=== Design stage complete ===` summary (tasks complete/total, deviations, commits since stage start, next step `/get-design-done:verify`). Template: `./design-procedure.md` §After Completion.
 
 ---
 
-### Figma Write Dispatch (after design-executor completes)
-
-After design-executor has finished and DESIGN-PLAN.md tasks are complete:
-
-1. Read `figma:` status from `.design/STATE.md` `<connections>` (the unified remote MCP covers both reads and writes as of v1.0.7.1):
-   - If `figma: not_configured` or `figma: unavailable` or absent → skip this block entirely (no prompt, no output)
-   - If `figma: available` → proceed to step 2
-
-2. Offer the user a prompt:
-   ```
-   figma write-back is available — propagate design decisions back to Figma?
-   Modes: annotate (layer comments) | tokenize (variable bindings) | mappings (Code Connect)
-   Run figma-write? (y/N):
-   ```
+## Figma Write Dispatch
 
-3. If user answers "y" or "yes":
-   - Ask which mode: annotate / tokenize / mappings (or all)
-   - Spawn `design-figma-writer` agent with the selected mode
-   - Pass `--dry-run` flag if user requests preview first
-
-4. If user answers "n", "N", or no response: skip silently.
-
-Note: This dispatch is always opt-in. The design stage never auto-runs figma-writer without user confirmation.
-
----
+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.
 
 ## DESIGN COMPLETE