@hegemonart/get-design-done 1.59.2 → 1.59.4

package/scripts/skill-templates/design/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: design
+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. Activates for requests involving implementing UI, building components, or turning a plan into working interface code."
+argument-hint: "[--auto] [--parallel] [--variants N]"
+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
+---
+
+# Get Design Done - Design
+
+**Stage 4 of 5** in the get-design-done pipeline. Thin orchestrator. All design execution intelligence lives in `agents/design-executor.md`.
+
+Full procedure detail: `./design-procedure.md`.
+
+---
+
+## Stage entry
+
+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."
+
+Detail: `./design-procedure.md` §Stage entry.
+
+---
+
+## Flags + pre-execution checks
+
+- `--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).
+- `--variants N` -> `variants_mode` (default N=2): for tasks that build a user-facing surface, the executor emits **N competing, hypothesis-tagged variants** (`<variant id component pattern hypothesis>`) instead of one. Before generating, consult the `design_arms` posterior (`scripts/lib/ds-arms/design-arms-store.cjs`) to bias toward patterns that have won prior A/B / user-research outcomes - **advisory, never directive** (the user's explicit choice always wins). The tagged variants flow to A/B (LaunchDarkly/Statsig/GrowthBook) for outcome ingestion. Full schema + the outcome loop: `../../reference/design-variants.md`.
+- **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 `{{command_prefix}}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 the `task_progress` denominator. If resuming, skip tasks whose `.design/tasks/task-NN.md` already exists.
+
+---
+
+## Step 2 - Wave-by-Wave Execution
+
+For each wave in order:
+
+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.
+
+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_mode=true`, prompt: "Ready for Wave [N+1]? (yes / review first)". Skip in `auto_mode`.
+
+## Step 4 - Handle Deviations
+
+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. `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 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 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 `{{command_prefix}}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>
+
+## Rationalizations - Thought to Reality
+
+The excuses an agent uses to cut corners during design implementation, and the cost of each:
+
+| Thought | Reality |
+|---------|---------|
+| "I can skip planning for this small task and just implement it." | Plan-skipped tasks blow scope per cycle telemetry; the gate is for the typical case, not the exception. |
+| "These two tasks touch nearby files but I'll run them in parallel anyway." | Overlapping `Touches:` in a parallel batch produce merge conflicts that silently drop one task's work - split into sequential sub-waves. |
+| "Hardcoding this value is faster than wiring the token." | A hardcoded value is a stub the verifier catches as drift from the design tokens; you pay for it twice. |
+| "I'll emit the `.stories.tsx` stub later when Storybook is back up." | The CSF stub must land with the component or the next cycle's visual-regression scope misses it entirely. |
+| "This deviation is minor, I won't record a blocker." | An unrecorded deviation can't be resolved by a follow-up task, so it leaks into verify as an unexplained gap. |
+| "Auto-mode means I can ignore the wave checkpoints." | Auto-mode skips prompts, not the wave structure; ignoring wave order still corrupts dependent-task ordering. |
+
+## DESIGN COMPLETE

package/scripts/skill-templates/design/design-procedure.md

@@ -0,0 +1,304 @@
+---
+name: design-procedure
+type: meta-rules
+version: 1.0.0
+phase: 28.5
+tags: [design, procedure, extracted, pipeline-stage, execute, wave-coordination]
+last_updated: 2026-05-18
+---
+
+Source: extracted from `skills/design/SKILL.md` (Phase 28.5 rework - D-10 extract-then-link).
+The skill's essential workflow stays in `../skills/design/SKILL.md`; this file holds the
+detail the agent reaches for when executing a specific step (agent spawn prompts, wave
+coordination, executor STATE.md protocol, figma-write dispatch).
+
+# Design Procedure
+
+Detailed procedure for the get-design-done `design` Stage 4 orchestrator. Companion to
+`../skills/design/SKILL.md`. Read this file when executing a specific design step; the
+SKILL.md keeps the essential wave-iteration workflow + decision tree, this file holds
+the full executor prompts and parallelism semantics.
+
+---
+
+## 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)
+
+---
+
+## 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 `{{command_prefix}}sketch` first to explore variants before implementation."
+
+Skip if `auto_mode=true`.
+
+## Pre-execution - Project-local conventions
+
+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.
+
+---
+
+## .stories.tsx Stub (when storybook project detected)
+
+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.
+
+---
+
+## 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.
+
+---
+
+## 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")
+```
+
+Wait for all parallel tasks to emit `## EXECUTION COMPLETE`.
+
+**Merge worktrees** (preserved from v2.1.0 - do not redesign):
+
+```
+=== Parallel batch complete ===
+[check/warn/cross] Task 01 — [type]
+[check/warn/cross] 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`.
+
+---
+
+## Step 3 - Wave Checkpoint
+
+After each wave (unless `--auto` flag was passed):
+
+```
+=== Wave [N] complete ===
+  check [N] tasks complete
+  warn  [N] deviations (see .design/tasks/ files)
+
+Ready for Wave [N+1]? (yes / review first)
+=========================
+```
+
+Skip checkpoint if `auto_mode=true`.
+
+---
+
+## 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.
+
+---
+
+## 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>`.
+
+---
+
+## 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.
+==============================
+```
+
+---
+
+## 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):
+   ```
+
+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.

package/scripts/skill-templates/discuss/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: gdd-discuss
+description: "Adaptive design interview command that spawns design-discussant in normal / --all / --spec mode to gather decisions via one-question-at-a-time AskUserQuestion, writing D-XX entries to STATE.md <decisions>. Use when locking design decisions outside the main pipeline or backfilling missing context."
+argument-hint: "[topic] [--all] [--spec] [--cycle <name>]"
+tools: Read, Write, Task
+---
+
+# {{command_prefix}}discuss
+
+**Role:** You are the `{{command_prefix}}discuss` command. You spawn the `design-discussant` agent with the right mode and context.
+
+## Step 1 - Read state
+
+Read `.design/STATE.md`. Note:
+- Current `cycle:` frontmatter value
+- Highest existing `D-XX` number under `<decisions>`
+
+If `.design/STATE.md` does not exist, tell the user to run `{{command_prefix}}brief` first and stop.
+
+## Step 2 - Parse arguments
+
+Inspect `$ARGUMENTS`:
+- Free-text before flags → `<topic>`
+- `--all` → batch gray-areas mode
+- `--spec` → Socratic ambiguity scoring mode
+- `--cycle <name>` → scope decisions to that cycle
+
+## Step 3 - Spawn design-discussant
+
+```
+Task("design-discussant", """
+<required_reading>
+@.design/STATE.md
+@.design/BRIEF.md
+@.design/DESIGN-CONTEXT.md
+@./.claude/skills
+</required_reading>
+
+<mode>{normal|--all|--spec}</mode>
+<topic>{topic or omit}</topic>
+<cycle>{cycle-name or omit}</cycle>
+
+Run an adaptive design interview. Append D-XX decisions to STATE.md <decisions> block.
+Emit `## DISCUSS COMPLETE` when done.
+""")
+```
+
+Use only the modes the user actually passed. Missing flags → `<mode>normal</mode>`.
+
+## Step 4 - Inline glossary maintenance (CONTEXT.md)
+
+When a fuzzy phrase is resolved into a sharper term, or a new domain concept is named
+during the interview: write to `./CONTEXT.md` IMMEDIATELY (do NOT batch). Use the schema
+in `./../../reference/context-md-format.md` - H2 heading per term, body paragraph,
+optional `**Aliases:**` line for term-merging. Multi-context repos use `CONTEXT-MAP.md`
+plus per-area `<area>/CONTEXT.md`. CONTEXT.md is lazy-created on the first term write.
+
+## Step 5 - Session wrap: ADR-offer scan
+
+For each decision recorded this session, check ALL three criteria from
+`./../../reference/adr-format.md`: (a) **hard-to-reverse**, (b) **surprising-without-context**,
+(c) **real-tradeoff**. If ALL three hold, offer to author `docs/adr/NNNN-<slug>.md`. If
+ANY criterion fails, the decision stays in STATE.md `<decisions>`. Routine choices are
+NEVER auto-promoted.
+
+## Step 6 - Report
+
+Wait for `## DISCUSS COMPLETE`. Re-read STATE.md. Count new D-XX entries since Step 1. Print:
+
+```
+━━━ Discuss complete ━━━
+New decisions: N (D-XX through D-YY)
+Mode: normal | --all | --spec
+Cycle: <name or "default">
+━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Constraints
+
+- Do not run the interview yourself - always spawn the agent.
+- Do not touch files outside `.design/`.
+
+## Rationalizations - Thought to Reality
+
+The shortcuts an agent takes during a discuss session, and what each one costs the decision record:
+
+| Thought | Reality |
+|---------|---------|
+| "I'll ask all eight questions at once to save time." | Batched questions overwhelm the user; one-at-a-time keeps each decision clean and prevents coupled answers. |
+| "I can run the interview inline instead of spawning the discussant." | The skill's contract is to always spawn the agent - running it yourself skips the discussant's mode handling and D-XX numbering. |
+| "This answer is good enough, I'll record it as a decision without follow-up." | A vague answer ("modern", "clean") recorded as a D-XX locks in an undecided premise; reject and re-ask once. |
+| "I'll batch all the new D-XX entries into STATE.md at the end." | Decisions written atomically per answer survive an interrupted session; batching loses everything if the session drops. |
+| "The glossary term can wait until I write the summary." | CONTEXT.md is written immediately per term - a deferred glossary entry is a naming inconsistency the next cycle inherits. |
+| "Every decision this session is worth an ADR." | ADRs require all three criteria (hard-to-reverse, surprising, real-tradeoff); auto-promoting routine choices buries the genuinely essential ones. |
+
+## DISCUSS COMMAND COMPLETE

package/scripts/skill-templates/do/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: gdd-do
+description: "Natural-language design task router. Parses your intent, maps to the right gdd command(s), confirms before executing. Activates for requests involving a natural-language design request, routing intent to the right command, or not knowing which skill to use."
+argument-hint: "<natural language description>"
+tools: Read, Write, AskUserQuestion
+---
+
+# {{command_prefix}}do
+
+Takes a free-form description, maps it to a `{{command_prefix}}*` command, confirms with the user, then routes.
+
+## Intent parsing table
+
+| Intent signals | Maps to |
+|---|---|
+| "explore", "scan", "what design patterns", "what components" | `{{command_prefix}}explore` |
+| "discuss", "decide", "what should we use for", "help me decide" | `{{command_prefix}}discuss` |
+| "plan", "create tasks", "what tasks do we need" | `@get-design-done plan` |
+| "design", "implement", "build", "execute" | `@get-design-done design` |
+| "verify", "check", "audit", "review" | `{{command_prefix}}audit` |
+| "sketch", "explore directions", "try designs", "variant" | `{{command_prefix}}sketch` |
+| "spike", "experiment", "feasibility", "test if" | `{{command_prefix}}spike` |
+| "fix [specific thing]" | `{{command_prefix}}fast` |
+| "pause", "stop", "save my place" | `{{command_prefix}}pause` |
+| "resume", "pick back up", "continue where I left off" | `{{command_prefix}}resume` |
+| "ship", "PR", "submit", "merge" | `{{command_prefix}}ship` |
+| "undo", "revert", "roll back" | `{{command_prefix}}undo` |
+
+## Steps
+
+1. Parse the argument text. Match it against the intent signals table. Choose the best fit.
+2. If two intents tie, ask (AskUserQuestion): "Did you mean <option A> or <option B>?"
+3. Print the routing decision in this exact shape:
+   ```
+   I'll run `{{command_prefix}}<command>` — "<one-line rationale>". Confirm? (yes/no)
+   ```
+4. On confirmation: invoke the target skill with any parameters extracted from the input (e.g., topic for `discuss`, symptom for `debug`).
+5. On rejection: ask "What did you mean instead?" and retry once, then abort gracefully.
+
+## Do Not
+
+- Do not execute the target command without confirmation.
+- Do not invent new commands - if no intent matches, say so and list the closest options.
+
+## DO COMPLETE