@hegemonart/get-design-done 1.28.0 → 1.28.6

package/skills/peer-cli-customize/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: peer-cli-customize
-description: "Rewire role→peer mappings on a per-agent basis. File-edit-driven (touches frontmatter delegate_to: per agent), no runtime config layer. Run when you want a specific agent to delegate to a different peer than the default capability-matrix mapping suggests."
+description: "Rewire role->peer mappings on a per-agent basis. File-edit-driven (touches frontmatter delegate_to: per agent), no runtime config layer. Run when you want a specific agent to delegate to a different peer than the default capability-matrix mapping suggests."
 argument-hint: "[<agent-name>] [<new-delegate-target>]"
 tools: Read, Edit, Bash, Grep
 ---
@@ -11,7 +11,7 @@ tools: Read, Edit, Bash, Grep
 
 ## Role
 
-You help the user rewire which peer-CLI delegate handles which agent's calls. The mechanism is direct file-edits to agent frontmatter (`delegate_to:` field added in Plan 27-06) — there is no runtime config layer. Your job is to make this safe and validatable.
+You help the user rewire which peer-CLI delegate handles which agent's calls. The mechanism is direct file-edits to agent frontmatter (`delegate_to:` field added in Plan 27-06) — there is no runtime config layer. Your job is to make this safe and validatable. The rewire discipline (per-edit validation, three frontmatter cases, validator gate) lives in `./../peer-cli-add/peer-cli-protocol.md` §"Rewire discipline" so the procedure stays canonical across consumers.
 
 ## Invocation Contract
 
@@ -22,83 +22,63 @@ You help the user rewire which peer-CLI delegate handles which agent's calls. Th
 
 ### Step 1 — Show current state
 
-Read the capability matrix from `scripts/lib/peer-cli/registry.cjs#describeCapabilities()`. Surface the 5 peers and their claimed roles to the user.
-
-Then scan `agents/*.md` and grep for `delegate_to:` frontmatter values. Render a table:
-
-```
-| Agent                      | delegate_to (current) |
-|----------------------------|------------------------|
-| design-reflector           | none                   |
-| design-context-checker     | (unset)                |
-| design-verifier            | gemini-research        |
-| ...                        | ...                    |
-```
+Read the capability matrix from `scripts/lib/peer-cli/registry.cjs#describeCapabilities()`. Surface the 5 peers and their claimed roles to the user. Then scan `agents/*.md` and grep for `delegate_to:` frontmatter values. Render a two-column table (`Agent | delegate_to (current)`) listing every agent's current setting (or `(unset)` for absent fields).
 
 ### Step 2 — Confirm rewire intent
 
-Either accept the user's explicit `<agent-name> <new-delegate-target>` arguments OR ask: "Which agent do you want to rewire? What should `delegate_to:` become?"
+Accept the user's explicit `<agent-name> <new-delegate-target>` arguments OR ask: "Which agent do you want to rewire? What should `delegate_to:` become?"
 
 Valid `<new-delegate-target>` values:
+
 - `<peer>-<role>` from the capability matrix (e.g., `gemini-research`, `codex-execute`, `cursor-debug`, `cursor-plan`, `copilot-review`, `copilot-research`, `qwen-write`).
-- `none` (explicit opt-out).
-- Empty / `(unset)` to remove the field entirely (revert to default behavior).
+- `none` — explicit opt-out.
+- Empty / `(unset)` — remove the field entirely; revert to default behavior.
 
 ### Step 3 — Validate the proposed rewire
 
-Cross-check the new value against the capability matrix:
+Cross-check against the capability matrix per `./../peer-cli-add/peer-cli-protocol.md` §"Rewire discipline":
+
 1. The peer must exist in the matrix.
 2. The role must be in the peer's `claims` list.
-3. The peer must (eventually, at runtime) be in `.design/config.json#peer_cli.enabled_peers` for dispatch to fire — but that's a runtime concern, not a frontmatter validation concern.
+3. Runtime allowlisting (`peer_cli.enabled_peers`) is a runtime concern, NOT a frontmatter validation concern.
 
 If validation fails, surface the error and stop. Do not edit the file.
 
 ### Step 4 — Apply the edit
 
-Use the `Edit` tool to modify the agent's frontmatter. Three cases:
-
-**Case A: Field is absent, user wants to add it.**
-Insert `delegate_to: <new-target>` into the frontmatter block (between the existing `default-tier:` and the next field, or at the end of frontmatter). Preserve YAML formatting.
-
-**Case B: Field is present, user wants to change the value.**
-Replace the existing value. If the existing value is `none` and the new value is `<peer>-<role>`, just swap. Mirror the existing indentation.
+Use the `Edit` tool. Three cases (per `./../peer-cli-add/peer-cli-protocol.md` §"Rewire discipline"):
 
-**Case C: Field is present, user wants to remove it.**
-Delete the entire `delegate_to:` line. The field is optional — absence === default behavior.
+- **Field absent, user wants to add:** insert `delegate_to: <new-target>` into frontmatter (between `default-tier:` and the next field, or at the end of frontmatter).
+- **Field present, user wants to change:** replace the value; preserve indentation.
+- **Field present, user wants to remove:** delete the entire `delegate_to:` line.
 
-### Step 5 — Re-validate via the frontmatter validator
+### Step 5 — Re-validate
 
-Run `npm run validate:frontmatter` (or whatever the project's frontmatter check is). Confirm the modified agent passes. If validation fails, surface the error and offer to revert.
+Run `npm run validate:frontmatter`. Confirm the modified agent passes. If validation fails, surface the error and offer to revert (re-run `Edit` with inverse old/new strings).
 
 ### Step 6 — Surface a diff summary
 
-Report back:
-
 ```
 ## Rewire summary
-
 ✓ design-verifier: delegate_to: gemini-research → cursor-debug
 ✓ design-reflector: delegate_to (unset) → codex-execute
 
 frontmatter validator: 0 violations (40 files checked)
-next time these agents are spawned, session-runner will dispatch through the new peer.
+Next time these agents are spawned, session-runner dispatches through the new peer.
 
-To verify: /gdd:peers (shows updated allowlist + capability matrix).
+Verify: /gdd:peers (shows updated allowlist + capability matrix).
 ```
 
 ## Edge cases
 
-- **User asks to rewire to a peer not in the capability matrix** (e.g., a peer they want to add later): direct them to `skills/peer-cli-add/SKILL.md` first; do not allow the frontmatter edit until the peer exists in the matrix.
-- **User asks to rewire to a role the peer doesn't claim** (e.g., `codex-debug` — codex only claims `execute`): refuse with a helpful message listing what the peer DOES claim. Suggest a closer match if obvious.
-- **User asks to rewire ALL agents to a peer at once** (bulk operation): support but require explicit confirmation. Show the diff of all proposed edits before applying.
-- **Validator fails after edit**: revert the edit (re-run `Edit` with the inverse old/new strings). Surface the original error.
+See `./../peer-cli-add/peer-cli-protocol.md` §"Edge cases" for: rewire-to-unmatrixed-peer (direct user to `peer-cli-add` first), rewire-to-unclaimed-role (refuse with helpful list), bulk-rewire (require explicit confirmation), validator-fails-post-edit (revert and surface).
 
 ## Cross-references
 
-- `scripts/validate-frontmatter.ts` (Plan 27-06) — `delegate_to` field validation.
+- `./../peer-cli-add/peer-cli-protocol.md` — rewire discipline, three frontmatter cases, edge cases.
+- `scripts/validate-frontmatter.ts` (Plan 27-06) — `delegate_to` validation.
 - `scripts/lib/peer-cli/registry.cjs` (Plan 27-05) — capability matrix.
-- `agents/README.md#peer-cli-delegation-delegate_to` — field documentation.
-- `skills/peer-cli-add/SKILL.md` — for adding a NEW peer (this skill is for rewiring among existing peers).
+- `skills/peer-cli-add/SKILL.md` — for adding a NEW peer (this skill rewires among existing peers).
 - `.planning/phases/27-peer-cli-delegation/CONTEXT.md` D-06 — decision lineage.
 
 ## Record

package/skills/peers/SKILL.md

@@ -9,24 +9,18 @@ tools: Read, Bash
 
 ## Role
 
-You are a deterministic discovery skill. You do not spawn agents and do not delegate to peers. You read `scripts/lib/install/runtimes.cjs`, `scripts/lib/peer-cli/registry.cjs`, `.design/config.json`, and (optionally) `.design/telemetry/posterior.json` (the canonical path declared by `scripts/lib/bandit-router.cjs`'s `DEFAULT_POSTERIOR_PATH`), then emit a single Markdown table summarizing peer-CLI status.
+You are a deterministic discovery skill. You do not spawn agents and do not delegate to peers. You read `scripts/lib/install/runtimes.cjs`, `scripts/lib/peer-cli/registry.cjs`, `.design/config.json`, and (optionally) `.design/telemetry/posterior.json` (canonical path declared by `bandit-router.cjs`'s `DEFAULT_POSTERIOR_PATH`), then emit a single Markdown table summarizing peer-CLI status. Protocol-level handshake details live in `./../peer-cli-add/peer-cli-protocol.md`.
 
 ## Invocation Contract
 
 - **Input**: none. The skill takes no arguments.
-- **Output**: a Markdown capability-matrix table to stdout. No JSON wrapper. The table is the entire output.
+- **Output**: a Markdown capability-matrix table to stdout. The table is the entire output.
 
 ## Procedure
 
-### 1. Load runtime matrix
+### 1. Load runtime + capability matrix
 
-Read `scripts/lib/install/runtimes.cjs` and extract the 14 runtime entries. The 5 peer-capable entries (`codex`, `gemini`, `cursor`, `copilot`, `qwen`) carry a `peerBinary?` field (added in Plan 27-11). Collect their IDs and binary paths.
-
-### 2. Load capability matrix
-
-Read `scripts/lib/peer-cli/registry.cjs`. The exported `describeCapabilities()` returns the per-peer claimed-roles map. The capability matrix is the source of truth for which roles each peer can take.
-
-Use the canonical declared matrix:
+Read `scripts/lib/install/runtimes.cjs` (14 entries; 5 carry `peerBinary`) and `scripts/lib/peer-cli/registry.cjs#describeCapabilities()`. The canonical declared matrix:
 
 | Peer    | Roles claimed            | Protocol |
 |---------|--------------------------|----------|
@@ -36,41 +30,28 @@ Use the canonical declared matrix:
 | copilot | review, research         | ACP      |
 | qwen    | write                    | ACP      |
 
-### 3. Detect installation
-
-For each peer, run `which <peerBinary>` (POSIX) or `where <peerBinary>` (Windows). If exit 0 → installed. If exit non-zero → not installed.
+### 2. Detect installation
 
-### 4. Read allowlist
+For each peer, run `which <peerBinary>` (POSIX) or `where <peerBinary>` (Windows). Exit 0 → installed; non-zero → not installed.
 
-Read `.design/config.json`. The path is `peer_cli.enabled_peers` — an array of peer-IDs. Default: `[]` (empty, opt-in required). If the file or path is missing, treat as empty.
+### 3. Read allowlist
 
-### 5. (Optional) Read posterior reward-delta
+Read `.design/config.json#peer_cli.enabled_peers` (array of peer-IDs). Default `[]` (opt-in required). Missing file or path = empty.
 
-Phase 27.5 (v1.27.5) wired the bandit posterior into production. Once 27.5-02 (budget-enforcer consultation) + 27.5-03 (session-runner outcome recording) have fired across enough spawns, the posterior at `.design/telemetry/posterior.json` (the canonical path declared by `bandit-router.cjs`'s `DEFAULT_POSTERIOR_PATH`) carries per-`(agent, bin, delegate, tier)` arms with measured reward.
+### 4. (Optional) Read posterior reward-delta
 
-For each peer-id in {gemini, codex, cursor, copilot, qwen}:
+Once Phase 27.5 has fired across enough spawns, `.design/telemetry/posterior.json` carries per-`(agent, bin, delegate, tier)` arms with measured reward. For each peer-id:
 
-1. Read `.design/telemetry/posterior.json`. If missing or malformed → render "(no data yet)".
-2. Filter the `arms` array into `peerArms` where `delegate === <peer-id>` and `localArms` where `delegate === 'none'` OR `delegate === undefined` (the Phase 23.5 legacy slice is treated as the local-call slice).
-3. If `peerArms` is empty OR `localArms` is empty → "(no data yet)".
-4. Compute pooled posterior means:
-   - `peerMean = sum(arm.alpha across peerArms) / (sum(arm.alpha across peerArms) + sum(arm.beta across peerArms))`
-   - `localMean = sum(arm.alpha across localArms) / (sum(arm.alpha across localArms) + sum(arm.beta across localArms))`
-5. Compute `delta_pct = (peerMean - localMean) / localMean`.
-6. Require minimum sample evidence: `sum(arm.count)` for `peerArms` AND for `localArms` must each be `>= 3`. Else "(no data yet)".
-7. Render delta as:
-   - `+X% reward` when `delta_pct > 0.01`
-   - `-X% reward` when `delta_pct < -0.01`
-   - `~equal` when `abs(delta_pct) < 0.01`
-   Where X = `Math.round(abs(delta_pct) * 100)`.
+1. Filter `arms` array: `peerArms` where `delegate === <peer-id>`; `localArms` where `delegate === 'none'` OR `delegate === undefined` (Phase 23.5 legacy slice treated as local-call).
+2. Require `peerArms` and `localArms` both non-empty. Else `(no data yet)`.
+3. Compute pooled means: `mean = sum(alpha) / (sum(alpha) + sum(beta))` over each slice.
+4. `delta_pct = (peerMean - localMean) / localMean`.
+5. Require `sum(arm.count)` ≥ 3 in each slice. Else `(no data yet)`.
+6. Render: `+X% reward` (delta > 0.01), `-X% reward` (delta < -0.01), or `~equal` (`abs(delta) < 0.01`), where `X = round(abs(delta_pct) * 100)`.
 
-The reward signal is the Phase 23.5 two-stage lexicographic (correctness first, cost as tiebreaker — see `scripts/lib/bandit-router.cjs` `computeReward()`). Cost-only deltas live in `scripts/lib/cost-arbitrage.cjs` (Phase 26-06) and are surfaced via the design-reflector.
+Reward is the Phase 23.5 lexicographic (correctness first, cost tiebreaker — see `scripts/lib/bandit-router.cjs` `computeReward()`). Cost-only deltas live in `cost-arbitrage.cjs` (Phase 26-06).
 
-If the posterior file does not exist (e.g., fresh install with no spawns yet, or `adaptive_mode` is `static`/`hedge`), surface "(no data yet)" for every peer.
-
-### 6. Render the table
-
-Emit the table in this exact shape:
+### 5. Render the table
 
 ```
 ## Peer-CLI Capability Matrix
@@ -85,36 +66,31 @@ Emit the table in this exact shape:
 
 > Tip: Enable peers via `.design/config.json#peer_cli.enabled_peers`.
 > See `reference/peer-cli-capabilities.md` for the full capability matrix.
-> See `skills/peer-cli-customize/SKILL.md` to rewire role→peer mappings per agent.
+> See `skills/peer-cli-customize/SKILL.md` to rewire role->peer mappings per agent.
 ```
 
-Rules for the third column ("Posterior delta vs local"):
-- If `Installed = ✗` → `(not installed)`.
-- Else if `Allowlisted = ✗` → `(opt-in disabled)`.
-- Else if `.design/telemetry/posterior.json` is missing → `(no data yet)`.
-- Else if either peer-side or local-side has fewer than 3 pulls → `(no data yet)`.
-- Else compute the reward-delta per Step 5 and render `+X% reward`, `-X% reward`, or `~equal`.
+**Third-column rules** (top-down precedence):
+
+- `Installed = ✗` → `(not installed)`.
+- `Allowlisted = ✗` → `(opt-in disabled)`.
+- Posterior missing → `(no data yet)`.
+- < 3 pulls per side → `(no data yet)`.
+- Else compute the reward-delta per Step 4.
 
-### 7. Done
+### 6. Done
 
-The table IS the output. No follow-up prose. Users can act on the data:
-- See "(opt-in disabled)" → enable in `.design/config.json`.
-- See "(not installed)" → install the peer CLI.
-- See concrete deltas → trust the bandit's recommendation, or override per-agent via `skills/peer-cli-customize`.
+The table IS the output. No follow-up prose. Users act on it: `(opt-in disabled)` → enable in `.design/config.json`; `(not installed)` → install the peer CLI; concrete deltas → trust the bandit or override per-agent via `skills/peer-cli-customize`.
 
 ## Cross-references
 
-- `scripts/lib/peer-cli/registry.cjs` (Plan 27-05) — capability matrix data source.
-- `scripts/lib/install/runtimes.cjs` (Plan 27-11) — `peerBinary` field per runtime.
-- `reference/peer-cli-capabilities.md` (Plan 27-05) — full capability matrix doc.
-- `skills/peer-cli-customize/SKILL.md` (Plan 27-10) — rewire role→peer mappings.
-- `skills/peer-cli-add/SKILL.md` (Plan 27-10) — add a brand-new peer.
-- `.planning/phases/27-peer-cli-delegation/CONTEXT.md` D-10 — decision lineage.
+- `./../peer-cli-add/peer-cli-protocol.md` — ACP/ASP handshake + adapter scaffold (procedure ref shared with peer-cli-add/customize).
+- `./reference/peer-cli-capabilities.md` (Plan 27-05) — full capability matrix doc.
+- `scripts/lib/peer-cli/registry.cjs` (Plan 27-05), `scripts/lib/install/runtimes.cjs` (Plan 27-11), `skills/peer-cli-customize/SKILL.md`, `skills/peer-cli-add/SKILL.md`, `.planning/phases/27-peer-cli-delegation/CONTEXT.md` D-10.
 
 ## Record
 
-After execution, append one JSONL line to `.design/skill-records.jsonl`:
+Append one JSONL line to `.design/skill-records.jsonl`:
 
 ```json
-{"skill": "gdd-peers", "ts": "<ISO timestamp>", "peers_detected": ["codex", "gemini"], "peers_allowlisted": ["codex"], "had_posterior": false}
+{"skill": "gdd-peers", "ts": "<ISO timestamp>", "peers_detected": ["codex"], "peers_allowlisted": ["codex"], "had_posterior": false}
 ```

package/skills/plan/SKILL.md

@@ -1,267 +1,80 @@
 ---
 name: plan
-description: "Stage 3 of 5 — reads DESIGN-CONTEXT.md, spawns design-phase-researcher (optional) + design-planner + design-plan-checker, writes DESIGN-PLAN.md. Thin orchestrator."
+description: "Stage 3 of 5 orchestrator that reads DESIGN-CONTEXT.md, runs optional research (phase-researcher / pattern-mapper / assumptions-analyzer / synthesizer), spawns design-planner + design-plan-checker, and writes DESIGN-PLAN.md. Use when DESIGN-CONTEXT.md is locked and you need a wave-ordered execution plan."
 argument-hint: "[--auto] [--parallel]"
 user-invocable: true
-tools: Read, Write, Bash, Glob, Task, AskUserQuestion, ToolSearch, mcp__gdd_state__get, mcp__gdd_state__transition_stage, mcp__gdd_state__add_decision, mcp__gdd_state__add_must_have, mcp__gdd_state__update_progress, mcp__gdd_state__set_status, mcp__gdd_state__add_blocker, mcp__gdd_state__checkpoint
+tools: Read, Write, Bash, Glob, Task, AskUserQuestion, ToolSearch, mcp__gdd_state__get, mcp__gdd_state__transition_stage, mcp__gdd_state__add_decision, mcp__gdd_state__add_must_have, mcp__gdd_state__update_progress, mcp__gdd_state__set_status, mcp__gdd_state__add_blocker, mcp__gdd_state__checkpoint, mcp__gdd_state__probe_connections
 ---
 
 # Get Design Done — Plan
 
-**Stage 3 of 5** in the get-design-done pipeline. Thin orchestrator. All planning intelligence lives in agents/design-planner.md.
+**Stage 3 of 5** in the get-design-done pipeline. Thin orchestrator. All planning intelligence lives in `agents/design-planner.md`.
 
-## Stage entry
-
-1. `mcp__gdd_state__transition_stage` with `to: "plan"`.
-   - Gate failure surfaces `error.context.blockers` to the user; do not advance.
-2. `mcp__gdd_state__get` → snapshot `state`. Use this snapshot for `<position>`, `<connections>`, `<must_haves>`, `<blockers>`, `<decisions>` in the current stage; do not re-read STATE.md directly.
-
-Abort with a clear error only if the user is trying to plan without DESIGN-CONTEXT.md — that is the true prerequisite, not STATE.md.
+Full procedure detail: `./plan-procedure.md`.
 
-## Flag Parsing
+---
 
-Parse $ARGUMENTS:
-- `--auto` → auto_mode=true (skip approvals, skip optional research)
-- `--parallel` → parallel_mode=true (planner fills Touches:/Parallel: fields)
+## Stage entry
 
-## Parallelism Decision (before any multi-agent spawn)
+1. `mcp__gdd_state__transition_stage` with `to: "plan"`. Gate failure surfaces `error.context.blockers`; do not advance.
+2. `mcp__gdd_state__get` -> snapshot `state` for `<position>`, `<connections>`, `<must_haves>`, `<blockers>`, `<decisions>`. Do not re-read STATE.md directly.
+3. Abort only if `.design/DESIGN-CONTEXT.md` is missing — that is the true prerequisite, not STATE.md.
 
-- Read `.design/config.json` `parallelism` (or defaults from `reference/config-schema.md`).
-- Apply rules from `reference/parallelism-rules.md`.
-- Plan's pipeline is inherently sequential (researcher → pattern-mapper → planner → checker). Expected verdict: **serial** (rule 1).
+---
 
-<!-- Parallelism decision is currently carried as the status string of an update_progress call. A dedicated tool may be added in a follow-on plan; until then, the status string is the canonical carrier. -->
+## Flags + parallelism
 
-After the parallelism decision is made:
-- Call `mcp__gdd_state__update_progress` with `task_progress: "<current>/<total>"` and `status: "plan_parallelism_decided: batch_size=<N>, reason=<short-reason>"`.
+- `--auto` -> `auto_mode=true` (skip approvals, skip optional research).
+- `--parallel` -> `parallel_mode=true` (planner fills `Touches:`/`Parallel:` fields).
+- **Parallelism decision**: read `.design/config.json` + `reference/parallelism-rules.md`. Plan pipeline is inherently sequential (researcher -> pattern-mapper -> planner -> checker) so the expected verdict is **serial** (rule 1). Record via `mcp__gdd_state__update_progress` with `status: "plan_parallelism_decided: batch_size=<N>, reason=<short-reason>"`.
 
 ## Probe Chromatic connection
 
-Run at stage entry, after reading STATE.md:
-
-Step C1 — CLI presence:
-  Bash: command -v chromatic 2>/dev/null || npx chromatic --version 2>/dev/null
-  → found → proceed to Step C2
-  → not found → chromatic: not_configured (skip all Chromatic steps)
-
-Step C2 — Token check:
-  Bash: test -n "${CHROMATIC_PROJECT_TOKEN}"
-  → true → chromatic: available
-  → false → chromatic: unavailable
-
-Also check: if storybook: not_configured → chromatic effectively unavailable (emit note, do not run).
-
-Write chromatic status to STATE.md `<connections>` via `mcp__gdd_state__probe_connections` — pass the single-entry probe result (`[{ name: "chromatic", status: "<verdict>" }]`). Do not edit `<connections>` directly.
-
-## Chromatic Change-Risk Scoping (when chromatic: available)
-
-Before writing DESIGN-PLAN.md, if chromatic: available:
-1. Identify token/component files to be changed (from DESIGN-CONTEXT.md scope)
-2. Run: Bash: npx chromatic --project-token $CHROMATIC_PROJECT_TOKEN --trace-changed=expanded --dry-run 2>&1
-3. Parse output — count story files that depend on changed source files
-4. Pass story count to design-planner.md (see design-planner.md Chromatic Change-Risk section)
-If unavailable: design-planner proceeds without story-count annotation.
+Probe `chromatic` (CLI presence + `CHROMATIC_PROJECT_TOKEN` check; auto-`unavailable` if `storybook: not_configured`), then write status via `mcp__gdd_state__probe_connections` (single-entry array, never edit `<connections>` directly). Detail: `./plan-procedure.md` §Probe Chromatic connection.
 
-## Step 1 — Optional Research (skip if auto_mode)
+When `chromatic: available`, run change-risk scoping before writing DESIGN-PLAN.md: identify token/component files in scope from DESIGN-CONTEXT.md, run `npx chromatic --trace-changed=expanded --dry-run`, count story files that depend on changed source files, and pass the story count to the design-planner spawn prompt. Detail: `./plan-procedure.md` §Chromatic Change-Risk Scoping.
 
-Complexity heuristic: if DESIGN-CONTEXT.md `<domain>` spans 3+ scopes OR `<decisions>` count > 6 → spawn design-phase-researcher. Otherwise skip.
-
-If spawning:
-
-```
-Task("design-phase-researcher", """
-<required_reading>
-@.design/STATE.md
-@.design/DESIGN-CONTEXT.md
-</required_reading>
-
-You are the design-phase-researcher agent. Identify the project type from DESIGN-CONTEXT.md
-and research relevant design patterns, pitfalls, and stack-specific conventions.
-
-Output file: .design/DESIGN-RESEARCH.md
-Target: ~100 lines, ~2 min budget.
+---
 
-Emit `## RESEARCH COMPLETE` when done.
-""")
-```
+## Step 1 — Optional Research (skip if `auto_mode`)
 
-Wait for `## RESEARCH COMPLETE`. Call `mcp__gdd_state__update_progress` with `task_progress: "1/3"` and a short `status` summary.
+Complexity heuristic: DESIGN-CONTEXT.md `<domain>` spans 3+ scopes OR `<decisions>` count > 6 -> spawn `design-phase-researcher` -> `.design/DESIGN-RESEARCH.md` (~100 lines, ~2 min). Wait for `## RESEARCH COMPLETE`, then `update_progress` `task_progress: "1/3"`. Full prompt: `./plan-procedure.md` §Step 1.
 
 ## Step 1.5 — Pattern Mapping (mandatory, brownfield protection)
 
-```
-Task("design-pattern-mapper", """
-<required_reading>
-@.design/STATE.md
-@.design/DESIGN-CONTEXT.md
-@reference/audit-scoring.md
-</required_reading>
-
-You are design-pattern-mapper. Grep the codebase for existing design patterns
-(color tokens, spacing scale, typography conventions, component styling) and
-write .design/DESIGN-PATTERNS.md. Classify by design concern — NOT by code
-architecture (no controllers, services, middleware vocabulary).
-
-Output file: .design/DESIGN-PATTERNS.md
-Emit `## MAPPING COMPLETE` when done.
-""")
-```
-
-Wait for `## MAPPING COMPLETE`. Call `mcp__gdd_state__update_progress` with `task_progress: "1/3"` and a short `status` summary.
-
-## Step 1.6 — Assumptions Analysis (optional, same flag as research)
-
-If assumptions analysis enabled (skip if auto_mode):
-
-```
-Task("design-assumptions-analyzer", """
-<required_reading>
-@.design/STATE.md
-@.design/DESIGN-CONTEXT.md
-@.design/DESIGN-PATTERNS.md
-</required_reading>
+Spawn `design-pattern-mapper` -> `.design/DESIGN-PATTERNS.md` (classify by design concern, not by code architecture — no controllers/services/middleware vocabulary). Wait for `## MAPPING COMPLETE`. Full prompt: `./plan-procedure.md` §Step 1.5.
 
-You are design-assumptions-analyzer. Surface hidden design assumptions with
-confidence levels and evidence citations.
+## Step 1.6 — Assumptions Analysis (skip if `auto_mode`)
 
-Emit `## ANALYSIS COMPLETE` when done.
-""")
-```
+If assumptions analysis is enabled: spawn `design-assumptions-analyzer` -> surfaces hidden design assumptions with confidence + evidence. Wait for `## ANALYSIS COMPLETE`. Full prompt: `./plan-procedure.md` §Step 1.6.
 
-Wait for `## ANALYSIS COMPLETE`.
+## Step 1.7 — Synthesize pre-plan inputs (Plan 10.1-04, D-13/D-15)
 
-## Step 1.7 — Synthesize pre-plan research inputs (Plan 10.1-04, D-13/D-15)
+If 2+ pre-plan agents ran (Step 1, 1.5, 1.6), invoke `Skill("synthesize", { outputs, directive, output_shape: "markdown" })` to merge their outputs into `.design/DESIGN-PREPLAN-BRIEF.md` (~150 lines, per-source headers preserved). Add the brief to the planner's `<required_reading>` in Step 2. If only one agent ran, skip. Full call signature + parallel-synthesizer note: `./plan-procedure.md` §Step 1.7.
 
-If 2+ of the pre-plan research agents ran (`design-phase-researcher` Step 1, `design-pattern-mapper` Step 1.5, `design-assumptions-analyzer` Step 1.6), invoke synthesize to merge their outputs into a single compact brief. If only one ran, skip this step.
+**Research-synthesis persistence:** for each D-XX the synthesizer produces, `mcp__gdd_state__add_decision`; for each M-XX, `mcp__gdd_state__add_must_have`. Issue sequentially (lockfile-bound). Detail: `./plan-procedure.md` §Research-synthesis persistence.
 
-    Skill("synthesize", {
-      outputs: [
-        (if Step 1 ran)   "=== from design-phase-researcher ===\n" + <read .design/DESIGN-RESEARCH.md>,
-        (if Step 1.5 ran) "=== from design-pattern-mapper ===\n"   + <read .design/DESIGN-PATTERNS.md>,
-        (if Step 1.6 ran) "=== from design-assumptions-analyzer ===\n" + <read .design/DESIGN-ASSUMPTIONS.md>
-      ],
-      directive: "Merge into a single compact pre-plan brief. Preserve per-source section headers so the planner can trace provenance. Consolidate duplicate recommendations with source tags. Target ~150 lines.",
-      output_shape: "markdown"
-    })
-
-Wait for `## SYNTHESIS COMPLETE`. Write to `.design/DESIGN-PREPLAN-BRIEF.md` (overwrite if present). Add `@.design/DESIGN-PREPLAN-BRIEF.md` to the planner's `<required_reading>` in Step 2 — individual files remain on disk for drill-down.
-
-**Parallel synthesizer note (future):** if a future plan variant spawns N parallel phase-researchers (e.g., one per project-type family), wire synthesize the same way as `skills/map/` Step 3.5.
-
-## Research-synthesis persistence (decisions + must-haves)
-
-When the synthesizer (design-phase-researcher / design-pattern-mapper / design-assumptions-analyzer) produces D-XX decisions and M-XX must-haves, persist each one through MCP instead of editing STATE.md directly.
-
-For each D-XX decision the synthesizer produces:
-- Call `mcp__gdd_state__add_decision` with `{ id: "D-XX", text: "...", status: "locked"|"tentative" }`.
-
-For each M-XX must-have the synthesizer produces:
-- Call `mcp__gdd_state__add_must_have` with `{ id: "M-XX", text: "...", status: "pending" }`.
-
-Issue these sequentially. Each call is event-emitting and lockfile-safe. Parallel issuance would serialize on the STATE.md lockfile with no throughput gain.
+---
 
 ## Step 2 — Plan
 
-```
-Task("design-planner", """
-<required_reading>
-@.design/STATE.md
-@.design/DESIGN-CONTEXT.md
-@reference/audit-scoring.md
-@.design/DESIGN-PATTERNS.md
-[@.design/DESIGN-RESEARCH.md — only include if research step ran]
-[@.design/DESIGN-ASSUMPTIONS.md — only include if assumptions analysis ran]
-[@.design/DESIGN-PREPLAN-BRIEF.md — include if Step 1.7 synthesize ran; planner prefers this compact brief over the individual files above]
-[@.design/sketches/*/WINNER.md — include all completed sketch winners if present]
-[@.design/spikes/*/FINDINGS.md — include all completed spike findings if present]
-[@./.claude/skills/design-*-conventions.md — include all project-local design conventions if present]
-[@~/.claude/gdd/global-skills/*.md — include all global skills if directory exists; global conventions inform but do not override project-local D-XX decisions]
-</required_reading>
-
-You are the design-planner agent. Read DESIGN-CONTEXT.md and produce .design/DESIGN-PLAN.md
-with wave-ordered tasks, acceptance criteria, and (if parallel mode) Touches:/Parallel: fields.
-
-Context:
-- Pipeline stage: plan
-- auto_mode: <true|false>
-- parallel_mode: <true|false>
-
-Output file: .design/DESIGN-PLAN.md
-Format: per agents/design-planner.md Output Format section.
-
-Emit `## PLANNING COMPLETE` when done.
-""")
-```
-
-Wait for `## PLANNING COMPLETE`. Call `mcp__gdd_state__update_progress` with `task_progress: "2/3"` and a short `status` summary.
+Spawn `design-planner` with `<required_reading>` covering STATE.md, DESIGN-CONTEXT.md, DESIGN-PATTERNS.md, plus (conditionally) DESIGN-RESEARCH.md, DESIGN-ASSUMPTIONS.md, DESIGN-PREPLAN-BRIEF.md (preferred when 1.7 ran), all `.design/sketches/*/WINNER.md`, all `.design/spikes/*/FINDINGS.md`, and all `./.claude/skills/design-*-conventions.md` + `~/.claude/gdd/global-skills/*.md` (project-local D-XX overrides globals). Wait for `## PLANNING COMPLETE`, then `update_progress` `task_progress: "2/3"`. Full prompt + conditional include syntax: `./plan-procedure.md` §Step 2.
 
 ## Step 3 — Check
 
-```
-Task("design-plan-checker", """
-<required_reading>
-@.design/STATE.md
-@.design/DESIGN-PLAN.md
-@.design/DESIGN-CONTEXT.md
-</required_reading>
-
-You are the design-plan-checker agent. Validate DESIGN-PLAN.md will achieve DESIGN-CONTEXT.md
-brief goals across 5 dimensions: requirement coverage, task completeness, wave ordering,
-must-have derivation, auto mode compliance.
-
-Context:
-- auto_mode: <true|false>
-
-Output: structured result as response text (no file). Start with `## PLAN CHECK RESULT: PASS`
-or `## PLAN CHECK RESULT: ISSUES FOUND`.
-
-Emit `## PLAN CHECK COMPLETE` when done.
-""")
-```
+Spawn `design-plan-checker` to validate DESIGN-PLAN.md against DESIGN-CONTEXT.md across 5 dimensions: requirement coverage, task completeness, wave ordering, must-have derivation, auto-mode compliance. Wait for `## PLAN CHECK COMPLETE`, then `update_progress` `task_progress: "3/3"`. On `## PLAN CHECK RESULT: ISSUES FOUND` + BLOCKER: offer revise/accept/abort (`auto_mode`: auto-accept WARN, abort on BLOCKER). Full prompt + branching: `./plan-procedure.md` §Step 3.
 
-Wait for `## PLAN CHECK COMPLETE`. Call `mcp__gdd_state__update_progress` with `task_progress: "3/3"` and a short `status` summary.
-
-If `## PLAN CHECK RESULT: ISSUES FOUND` and any BLOCKER issues:
-- Present issues to user and offer: (a) revise plan now — re-spawn design-planner with issue list, (b) accept and proceed, (c) abort.
-- If auto_mode: auto-accept WARNING issues, abort on BLOCKER issues.
+---
 
 ## Stage exit
 
-1. Call `mcp__gdd_state__set_status` with `status: "plan_complete"`.
-2. Call `mcp__gdd_state__checkpoint` to stamp `last_checkpoint` and finalize the plan stage.
+1. `mcp__gdd_state__set_status` -> `"plan_complete"`.
+2. `mcp__gdd_state__checkpoint` — stamps `last_checkpoint` and finalizes the plan stage.
 
-The next stage (design) calls `mcp__gdd_state__transition_stage` on entry — this skill does NOT issue the transition itself, preserving the stage-owned-transition discipline established by brief→explore and explore→plan.
+The next stage (design) calls `mcp__gdd_state__transition_stage` on entry — this skill does NOT issue the transition itself, preserving the stage-owned-transition discipline.
 
 ## After Completion
 
-Print user-facing summary:
-- Plan tasks: N waves, M total tasks
-- Files: .design/DESIGN-PLAN.md (and .design/DESIGN-RESEARCH.md if research ran)
-- Next: `/get-design-done:design` to execute the plan
+Print: plan tasks (N waves, M total tasks), files written (`.design/DESIGN-PLAN.md`, plus `.design/DESIGN-RESEARCH.md` if research ran), next step `/get-design-done:design`.
 
 ## PLAN COMPLETE
-
----
-
-## Exploration artifacts & project-local conventions
-
-When building the planner spawn prompt, also glob for:
-- `.design/sketches/*/WINNER.md` — winning sketch rationale (informs directional tasks)
-- `.design/spikes/*/FINDINGS.md` — spike verdicts (inform task feasibility)
-- `./.claude/skills/design-*-conventions.md` — project-local design conventions
-
-Include each matching file in `<files_to_read>` / `<required_reading>` so the planner sees them when creating tasks. Spike findings from `.design/spikes/` inform task feasibility; sketch winners inform directional choice; project-local conventions override defaults.
-
-## --research mode (removed)
-
-V2-04 deferred the `--research` flag. Rationale: complexity of an additional
-agent spawn + Context7 integration outweighs the benefit of discover-stage
-auto-detect for most projects. Use /discover's Auto Mode for research-assisted
-discovery instead.
-
-The optional research step that already exists (Step 1, triggered by complexity
-heuristic: 3+ domain scopes OR 6+ decisions) covers the core use case without
-a separate CLI flag.
-
-If --research is reintroduced in a future version, define its scope in
-ROADMAP.md V2+ and update this section.