@hegemonart/get-design-done 1.27.7 → 1.28.5

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: `../../reference/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: `../../reference/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: `../../reference/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: `../../reference/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: `../../reference/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: `../../reference/design-procedure.md` §Figma Write Dispatch.
 
 ## DESIGN COMPLETE

package/skills/discover/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: discover
-description: "Stage 1.5 of 4 — thin orchestrator that spawns design-context-builder (auto-detect + interview) and design-context-checker (6-dimension validator) to produce DESIGN-CONTEXT.md."
+description: "Stage 1.5 of 4 orchestrator that probes Figma / Refero / Pinterest connections, spawns design-context-builder (auto-detect + interview) and (via lazy gate) design-context-checker (6-dimension validator), producing .design/DESIGN-CONTEXT.md. Use after /gdd:scan when a fast-path context build is wanted instead of the full /gdd:explore."
 argument-hint: "[--auto]"
 user-invocable: true
 ---
@@ -9,171 +9,64 @@ user-invocable: true
 
 **Stage 1.5 of 4.** Produces `.design/DESIGN-CONTEXT.md`.
 
+Full procedure detail: `../../reference/discover-procedure.md`.
+
 ---
 
 ## State Integration
 
 1. Read `.design/STATE.md`.
-   - If missing: create minimal skeleton from `reference/STATE-TEMPLATE.md` with stage=discover, status=in_progress, task_progress=0/1, and log warning: "STATE.md not found — created fresh. If this is a resumed session, run /get-design-done:scan first."
-   - If present and stage==discover and status==in_progress: RESUME — continue existing interview; do not reset.
-   - Otherwise: normal transition — set frontmatter stage=discover, <position> stage=discover, status=in_progress, task_progress=0/1.
-2. **Probe connection availability** — ToolSearch runs FIRST because MCP tools may be in the deferred tool set. This is the canonical probe pattern (spec lives in `connections/connections.md`; copied inline because SKILL.md has no include mechanism — if the probe pattern changes, update all stages that copied it).
-
-   **A — Figma probe (variant-agnostic):**
-
-   ```
-   A1. ToolSearch({ query: "figma get_metadata use_figma", max_results: 10 })
-   A2. Parse tool names matching /^mcp__([^_]*figma[^_]*)__(get_metadata|use_figma)$/i
-       into read-capable and write-capable prefix sets.
-   A3. Empty read set → figma: not_configured (skip all Figma paths)
-       One or more matches → pick prefix via tiebreaker:
-         (1) both-sets > reads-only,
-         (2) `figma` > others,
-         (3) non-`figma-desktop` > desktop,
-         (4) alphabetical.
-   A4. Call {prefix}get_metadata:
-         Success → figma: available (prefix=mcp__<prefix>__, writes=<true|false>)
-         Error   → figma: unavailable
-   ```
-
-   **B — Refero probe (ToolSearch presence is sufficient — no tool call needed):**
-
-   ```
-   B1. ToolSearch({ query: "refero", max_results: 5 })
-   B2. Empty result  → refero: not_configured
-       Non-empty     → refero: available
-   ```
-
-   **C — Pinterest probe (ToolSearch-only, same pattern as Refero):**
-
-   ```
-   C1. ToolSearch({ query: "mcp-pinterest", max_results: 5 })
-   C2. Empty result  → pinterest: not_configured
-       Non-empty     → pinterest: available
-   ```
-
-   No live `pinterest_search` call at probe time — ToolSearch presence is sufficient. The synthesizer makes the actual search calls.
-
-   After all probes (A, B, C), update `.design/STATE.md` `<connections>` with the results and continue. Downstream stages (design-context-builder) read `<connections>` from STATE.md rather than re-probing.
-3. Update last_checkpoint. Write STATE.md.
-
-## Auto Mode
-
-Auto Mode CSS detection (when `auto_mode: true` is passed to the builder):
-  1. If tailwind.config.{js,cjs,mjs,ts} exists → Tailwind-only project
-     - Skip CSS file grep
-     - Parse tailwind.config for color palette, spacing scale, font families
-     - Use tailwind.config values as the baseline style signal
-  2. Else → fall through to existing CSS file grep logic
-
-## Step 1 — Spawn design-context-builder
+   - **Missing** -> create minimal skeleton from `reference/STATE-TEMPLATE.md` (stage=discover, status=in_progress, task_progress=0/1) and log warning "STATE.md not found — created fresh. If this is a resumed session, run /get-design-done:scan first."
+   - **Present + stage==discover + status==in_progress** -> RESUME (continue interview; do not reset).
+   - **Otherwise** -> normal transition: set frontmatter stage=discover, `<position>` stage=discover, status=in_progress, task_progress=0/1.
+2. Probe connection availability. ToolSearch runs FIRST (MCP tools may be in the deferred tool set). Run three probes — A (Figma, variant-agnostic with prefix tiebreaker), B (Refero, ToolSearch-only), C (Pinterest, ToolSearch-only). After all probes, write `<connections>` to STATE.md so the builder doesn't re-probe. Full probe specs: `../../reference/discover-procedure.md` §Connection Probes.
+3. Update `last_checkpoint`. Write STATE.md.
 
-Task("design-context-builder", """
-<required_reading>
-@.design/STATE.md
-@reference/audit-scoring.md
-@reference/anti-patterns.md
-</required_reading>
+---
 
-You are the design-context-builder agent. Auto-detect existing design system
-state via grep/glob before asking questions. Interview the user ONLY for areas
-where auto-detect returned no confident answer. Write .design/DESIGN-CONTEXT.md.
+## Auto Mode
 
-Baseline audit directory detection (ordered fallback chain):
-  1. If src/ exists → use src/
-  2. Elif app/ exists → use app/ (Next.js App Router)
-  3. Elif pages/ exists → use pages/ (Next.js Pages Router)
-  4. Elif lib/ exists → use lib/ (library-only projects)
-  5. Else → flag "layout unknown", skip baseline, note in DESIGN-CONTEXT.md
+When `--auto` is passed to the builder: if `tailwind.config.{js,cjs,mjs,ts}` exists -> Tailwind-only project (skip CSS file grep, parse tailwind.config for palette/spacing/font, use those as the baseline style signal). Else fall through to the existing CSS file grep logic. Detail: `../../reference/discover-procedure.md` §Auto Mode.
 
-Common gray areas to probe during discovery (Area 7):
-  1. font-change risk — switching type families when existing UI has body copy in a specific family. Ask: "Is the current body font intentional or inherited? OK to change?"
-  2. token-layer introduction risk — adding CSS custom properties to a codebase that uses direct values. Ask: "Do you want design tokens (--primary, --surface) or inline values (hex, rgb)?"
-  3. Component rebuild vs restyle — when to keep existing component, when to rebuild from scratch. Ask: "For <component>, restyle in place or rebuild?"
+---
 
-Context:
-  auto_mode: <true|false>
+## Step 1 — Spawn design-context-builder
 
-Output file: .design/DESIGN-CONTEXT.md
-Emit `## CONTEXT COMPLETE` when done.
-""")
+Spawn `design-context-builder` -> `.design/DESIGN-CONTEXT.md`. The agent auto-detects via grep/glob first and interviews only for areas where auto-detect returned no confident answer. Baseline audit directory chain: `src/` -> `app/` -> `pages/` -> `lib/` -> flag "layout unknown". Common gray areas to probe (Area 7): font-change risk, token-layer introduction risk, component rebuild-vs-restyle. Wait for `## CONTEXT COMPLETE`, then update STATE.md `task_progress = 0.5`. Full prompt: `../../reference/discover-procedure.md` §Step 1.
 
-Wait for `## CONTEXT COMPLETE`. Update STATE.md task_progress = 0.5.
+---
 
 ## Step 1.75 — Lazy gate: should design-context-checker run? (Plan 10.1-04, D-21)
 
-Spawn the cheap Haiku gate before the full context-checker:
-
-    Task("design-context-checker-gate", """
-    <required_reading>
-    @.design/STATE.md
-    </required_reading>
+Spawn the cheap Haiku gate `design-context-checker-gate` before the full checker. It applies the single-file heuristic (is `DESIGN-CONTEXT.md` in `git diff --name-only HEAD~1..HEAD`?) and emits JSON + `## GATE COMPLETE`. On `spawn: false`: append `lazy_skipped: true` telemetry row, skip Step 2, set STATE.md `<position>` as if checker passed. On `spawn: true`: proceed to Step 2. On first-run discover the gate always returns `spawn: true` (builder just wrote the file); the gate meaningfully short-circuits only on re-runs where the builder made no changes. Full prompt: `../../reference/discover-procedure.md` §Step 1.75.
 
-    You are the design-context-checker-gate.
+**Parallel synthesizer note:** discover does not spawn parallel researchers in v1, so `skills/synthesize/` is not wired here. If future variants spawn N parallel interviewers, wire synthesize between dispatch and collate as in `skills/map/` Step 3.5.
 
-    Context:
-      diff_files: <git diff --name-only HEAD~1..HEAD>
-      diff_body: (not needed — single-file heuristic)
-      baseline_sha: <HEAD~1>
-
-    Apply the heuristic (DESIGN-CONTEXT.md in diff_files?). Emit JSON + `## GATE COMPLETE`.
-    """)
-
-Wait for `## GATE COMPLETE`. Parse JSON:
-
-- `spawn: false` → append `lazy_skipped: true` telemetry row for `design-context-checker`, skip Step 2, set STATE.md `<position>` as if checker passed (rationale: DESIGN-CONTEXT.md didn't change, last validation still holds), emit `design-context-checker skipped — <rationale>`.
-- `spawn: true` → proceed to Step 2 as currently written.
-
-**Note:** On first-run discover, the builder just wrote DESIGN-CONTEXT.md so the gate returns `spawn: true`. The gate meaningfully short-circuits only on re-runs where the builder made no changes.
-
-**Parallel synthesizer note:** discover does not spawn parallel researchers in v1, so `skills/synthesize/` is not wired here. If future variants spawn N parallel interviewers/auto-detectors, wire synthesize between dispatch and collate as in `skills/map/` Step 3.5.
+---
 
 ## Step 2 — Spawn design-context-checker
 
-Task("design-context-checker", """
-<required_reading>
-@.design/STATE.md
-@.design/DESIGN-CONTEXT.md
-</required_reading>
+Spawn `design-context-checker` with `<required_reading>` on STATE.md + DESIGN-CONTEXT.md. The agent validates DESIGN-CONTEXT.md across 6 dimensions and returns APPROVED or BLOCKED with per-dimension verdicts. Wait for `## CONTEXT CHECK COMPLETE`. Full prompt: `../../reference/discover-procedure.md` §Step 2.
 
-You are the design-context-checker agent. Validate DESIGN-CONTEXT.md across
-6 dimensions. Return APPROVED or BLOCKED with per-dimension verdicts.
-
-Emit `## CONTEXT CHECK COMPLETE` when done.
-""")
-
-Wait for `## CONTEXT CHECK COMPLETE`.
+---
 
 ## Step 3 — Handle checker verdict
 
-If APPROVED: proceed to state update.
-If BLOCKED: present dimensions that BLOCKED to user, offer fix-and-retry loop
-(re-spawn builder with specific fix instructions). Do not proceed to planning.
+- **APPROVED** -> proceed to state update.
+- **BLOCKED** -> present blocked dimensions to user, offer fix-and-retry loop (re-spawn builder with specific fix instructions). Do not proceed to planning.
 
 ---
 
 ## State Update (exit)
 
-1. Set <position> status=completed, task_progress=1/1.
-2. Set <timestamps> discover_completed_at=<ISO 8601 now>.
-3. Update last_checkpoint. Write STATE.md.
+1. Set `<position>` `status=completed`, `task_progress=1/1`.
+2. Set `<timestamps>` `discover_completed_at=<ISO 8601 now>`.
+3. Update `last_checkpoint`. Write STATE.md.
 
 ---
 
 ## After Writing
 
-```
-━━━ Discovery complete ━━━
-Saved: .design/DESIGN-CONTEXT.md
-
-Baseline score: [N]/100 ([grade])
-Key issues: [top issue 1], [top issue 2], [top issue 3]
-
-Next: /get-design-done:plan
-  → Decomposes your context into executable design tasks.
-━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-Do not proceed to planning automatically unless `--auto` was passed.
+Print the "=== Discovery complete ===" block with saved path, baseline score, top key issues, and next step (`/get-design-done:plan`). Do not proceed to planning automatically unless `--auto` was passed. Template: `../../reference/discover-procedure.md` §After Writing.
 
 ## DISCOVER COMPLETE

package/skills/discuss/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-discuss
-description: "Adaptive design interview — spawns design-discussant to gather decisions via one-question-at-a-time questioning. Writes D-XX decisions to STATE.md <decisions> block."
+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
 ---
@@ -47,7 +47,23 @@ Emit `## DISCUSS COMPLETE` when done.
 
 Use only the modes the user actually passed. Missing flags → `<mode>normal</mode>`.
 
-## Step 4 — Report
+## 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: