@hegemonart/get-design-done 1.42.0 → 1.44.0

package/skills/peer-cli-add/peer-cli-protocol.md

@@ -9,7 +9,7 @@ last_updated: 2026-05-18
 
 <!-- Procedural patterns adapted from greenpolo/cc-multi-cli (Apache 2.0). See ../NOTICE for full attribution. -->
 
-# Peer-CLI Protocol — Add + Customize Procedures
+# Peer-CLI Protocol - Add + Customize Procedures
 
 Procedural reference for the peer-CLI delegation layer. Centralizes the verification
 ladder, adapter scaffolding shape, rewire-discipline, and Windows quirks so the three
@@ -21,31 +21,31 @@ procedure layer that sits above it.
 ## Verification ladder (run before any code edit when adding a peer)
 
 When a user wants to add a brand-new peer to the capability matrix, walk these four
-rungs in order. Stop at the first rung that fails — do not proceed to scaffold a broken
+rungs in order. Stop at the first rung that fails - do not proceed to scaffold a broken
 adapter.
 
-### Rung 1 — Binary on PATH
+### Rung 1 - Binary on PATH
 
 `which <peer-binary>` (POSIX) or `where <peer-binary>` (Windows). If exit non-zero, stop
 and ask the user to install the peer first. Adapters cannot be tested without the binary.
 
-### Rung 2 — Handshake test
+### Rung 2 - Handshake test
 
 Spawn the peer with the protocol entry point:
 
-- **ACP peers** — `<peer-binary> acp` (or whatever the peer documents — Gemini uses
+- **ACP peers** - `<peer-binary> acp` (or whatever the peer documents - Gemini uses
   `gemini acp`; some peers use a flag).
-- **ASP peers** — `<peer-binary> app-server` (Codex convention; other ASP peers may
+- **ASP peers** - `<peer-binary> app-server` (Codex convention; other ASP peers may
   differ).
 
 Send an `initialize` JSON-RPC message over stdin with `protocolVersion: '2025-06-18'`
 (ACP) or `service_name: 'gdd_peer_delegation'` (ASP). Capture the reply on stdout. A
 valid JSON-RPC response with `result.protocolVersion` (ACP) or `result.threadId` (ASP)
 means the peer speaks the protocol. No valid reply within 5 seconds means either
-wrong-protocol or non-standard entry point — stop and ask the user for the correct
+wrong-protocol or non-standard entry point - stop and ask the user for the correct
 invocation.
 
-### Rung 3 — Model-ID `-preview`-suffix trap
+### Rung 3 - Model-ID `-preview`-suffix trap
 
 Many peers expose preview models with a `-preview` suffix (e.g., `gpt-5-preview` vs
 `gpt-5`). The suffix drifts: today's preview is tomorrow's GA. Capture the peer's model
@@ -53,7 +53,7 @@ list (most peers expose `<peer-binary> models` or similar) and document parent n
 the new entry's `provider_model_id` field so the runtime-models entry survives the
 suffix flipping.
 
-### Rung 4 — Windows quirks
+### Rung 4 - Windows quirks
 
 If the peer-binary ends in `.cmd` and the user is on Windows, confirm
 `scripts/lib/peer-cli/spawn-cmd.cjs` will pick it up. That module handles `.cmd`
@@ -66,12 +66,12 @@ Use the existing five adapters at `../scripts/lib/peer-cli/adapters/{codex,gemin
 as templates. Pick the closest match by protocol (ASP if `<protocol> = asp`, otherwise
 ACP). Each adapter exports:
 
-- `claims(role)` — boolean predicate against `ROLES_CLAIMED`.
-- `dispatch({command, args, cwd, env}, role, text, opts)` — async dispatch with optional
+- `claims(role)` - boolean predicate against `ROLES_CLAIMED`.
+- `dispatch({command, args, cwd, env}, role, text, opts)` - async dispatch with optional
   `opts.onNotification` callback.
-- `ROLES_CLAIMED` — array of role identifiers the peer claims.
-- `ROLE_PREFIX` — per-role prompt prefix object (empty string when no prefix needed).
-- `name`, `protocol` — string identifiers.
+- `ROLES_CLAIMED` - array of role identifiers the peer claims.
+- `ROLE_PREFIX` - per-role prompt prefix object (empty string when no prefix needed).
+- `name`, `protocol` - string identifiers.
 
 Canonical skeleton (ACP variant; for ASP swap to `createAspClient` from `asp-client.cjs`):
 
@@ -98,12 +98,12 @@ module.exports = { claims, dispatch, ROLES_CLAIMED, ROLE_PREFIX, name: '<peer-id
 
 A new peer integrates cleanly with a 3-file diff plus the capability-matrix doc:
 
-1. **`scripts/lib/peer-cli/adapters/<new-peer-id>.cjs`** — new adapter.
-2. **`scripts/lib/install/runtimes.cjs`** — add a `peerBinary` field (platform-aware:
+1. **`scripts/lib/peer-cli/adapters/<new-peer-id>.cjs`** - new adapter.
+2. **`scripts/lib/install/runtimes.cjs`** - add a `peerBinary` field (platform-aware:
    `<binary>.cmd` on Windows, plain `<binary>` elsewhere).
-3. **`reference/peer-cli-capabilities.md`** — add a row to the capability matrix and a
+3. **`reference/peer-cli-capabilities.md`** - add a row to the capability matrix and a
    per-peer section with the verification evidence from Rung 1–4 above.
-4. **`scripts/lib/peer-cli/registry.cjs`** — append to `CAPABILITY_MATRIX` (and
+4. **`scripts/lib/peer-cli/registry.cjs`** - append to `CAPABILITY_MATRIX` (and
    `KNOWN_PEERS` if separate).
 
 ## Rewire discipline (customize)
@@ -116,46 +116,46 @@ When rewiring `delegate_to:` on a specific agent's frontmatter:
   present + remove it (revert to default).
 - Re-run `npm run validate:frontmatter` after every edit; offer to revert if it fails.
 - The peer must also be in `.design/config.json#peer_cli.enabled_peers` for dispatch
-  to fire at runtime — but that's a runtime concern, not a frontmatter validation
+  to fire at runtime - but that's a runtime concern, not a frontmatter validation
   concern.
 
 ## Verification gate (after any peer-CLI change)
 
 Run, in order, until each passes:
 
-1. `npx tsc --noEmit` — clean.
-2. `node --test tests/peer-cli-registry.test.cjs tests/peer-cli-adapters.test.cjs` —
+1. `npx tsc --noEmit` - clean.
+2. `node --test tests/peer-cli-registry.test.cjs tests/peer-cli-adapters.test.cjs` -
    no regression on existing tests.
-3. `node --test tests/reference-registry.test.cjs` — capability-matrix doc is in
+3. `node --test tests/reference-registry.test.cjs` - capability-matrix doc is in
    `reference/registry.json`.
-4. `npm run validate:frontmatter` — no agent's `delegate_to:` field is broken.
+4. `npm run validate:frontmatter` - no agent's `delegate_to:` field is broken.
 
 Any failure: surface the error and offer to revert.
 
 ## Edge cases
 
-- **Peer speaks neither ACP nor ASP** — gdd v1.27 ships only those two protocols. Stop
+- **Peer speaks neither ACP nor ASP** - gdd v1.27 ships only those two protocols. Stop
   and document the gap in `.design/RESEARCH.md` for a future phase.
-- **Peer claims a role no existing peer claims** — fine, capability matrix is open. But
+- **Peer claims a role no existing peer claims** - fine, capability matrix is open. But
   document the role in `peer-cli-capabilities.md` so future peers can compete on it.
-- **Peer claims ALL roles** (generalist) — accept, but flag in the per-peer section.
+- **Peer claims ALL roles** (generalist) - accept, but flag in the per-peer section.
   Generalist peers are usually weaker than specialist peers; the bandit will sort it
   out via measurement.
-- **Peer-ID collides with an existing peer** — fail. Peer-IDs must be globally unique.
-- **Rewire target peer not in capability matrix** — direct user to `peer-cli-add` first;
+- **Peer-ID collides with an existing peer** - fail. Peer-IDs must be globally unique.
+- **Rewire target peer not in capability matrix** - direct user to `peer-cli-add` first;
   do not allow the frontmatter edit until the peer exists in the matrix.
-- **Rewire target role peer does not claim** — refuse with a list of what the peer DOES
+- **Rewire target role peer does not claim** - refuse with a list of what the peer DOES
   claim. Suggest a closer match when obvious.
 
 ## Cross-references
 
-- `./peer-protocols.md` — protocol-level reference (JSON-RPC framing, handshake shape).
-- `./peer-cli-capabilities.md` — capability matrix doc (per-peer claimed roles).
-- `../scripts/lib/peer-cli/registry.cjs` (Plan 27-05) — capability-matrix data source.
-- `../scripts/lib/peer-cli/adapters/*.cjs` (Plan 27-04) — adapter template.
-- `../scripts/lib/peer-cli/spawn-cmd.cjs` (Plan 27-03) — Windows `.cmd` handling.
-- `../scripts/lib/install/runtimes.cjs` (Plan 27-11) — `peerBinary` field per runtime.
-- `../skills/peers/SKILL.md` — discovery surface.
-- `../skills/peer-cli-add/SKILL.md` — add-peer flow.
-- `../skills/peer-cli-customize/SKILL.md` — rewire flow.
-- `../NOTICE` — Apache 2.0 attribution to greenpolo/cc-multi-cli.
+- `./peer-protocols.md` - protocol-level reference (JSON-RPC framing, handshake shape).
+- `./peer-cli-capabilities.md` - capability matrix doc (per-peer claimed roles).
+- `../scripts/lib/peer-cli/registry.cjs` (Plan 27-05) - capability-matrix data source.
+- `../scripts/lib/peer-cli/adapters/*.cjs` (Plan 27-04) - adapter template.
+- `../scripts/lib/peer-cli/spawn-cmd.cjs` (Plan 27-03) - Windows `.cmd` handling.
+- `../scripts/lib/install/runtimes.cjs` (Plan 27-11) - `peerBinary` field per runtime.
+- `../skills/peers/SKILL.md` - discovery surface.
+- `../skills/peer-cli-add/SKILL.md` - add-peer flow.
+- `../skills/peer-cli-customize/SKILL.md` - rewire flow.
+- `../NOTICE` - Apache 2.0 attribution to greenpolo/cc-multi-cli.

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

@@ -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. 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.
+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
 
@@ -20,21 +20,21 @@ You help the user rewire which peer-CLI delegate handles which agent's calls. Th
 
 ## Procedure
 
-### Step 1 — Show current state
+### 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 two-column table (`Agent | delegate_to (current)`) listing every agent's current setting (or `(unset)` for absent fields).
 
-### Step 2 — Confirm rewire intent
+### Step 2 - Confirm rewire intent
 
 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)` — 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
+### Step 3 - Validate the proposed rewire
 
 Cross-check against the capability matrix per `./../peer-cli-add/peer-cli-protocol.md` §"Rewire discipline":
 
@@ -44,7 +44,7 @@ Cross-check against the capability matrix per `./../peer-cli-add/peer-cli-protoc
 
 If validation fails, surface the error and stop. Do not edit the file.
 
-### Step 4 — Apply the edit
+### Step 4 - Apply the edit
 
 Use the `Edit` tool. Three cases (per `./../peer-cli-add/peer-cli-protocol.md` §"Rewire discipline"):
 
@@ -52,11 +52,11 @@ Use the `Edit` tool. Three cases (per `./../peer-cli-add/peer-cli-protocol.md`
 - **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
+### Step 5 - Re-validate
 
 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
+### Step 6 - Surface a diff summary
 
 ```
 ## Rewire summary
@@ -75,11 +75,11 @@ See `./../peer-cli-add/peer-cli-protocol.md` §"Edge cases" for: rewire-to-unmat
 
 ## Cross-references
 
-- `./../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.
-- `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.
+- `./../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.
+- `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

@@ -1,6 +1,6 @@
 ---
 name: gdd-peers
-description: "Discover peer-CLI capability matrix — which of {codex, gemini, cursor, copilot, qwen} are installed, allowlisted in .design/config.json, and (if Phase 23.5 has data) their cost/quality delta vs local. Single command, no flags. Read by users investigating delegation setup."
+description: "Discover peer-CLI capability matrix - which of {codex, gemini, cursor, copilot, qwen} are installed, allowlisted in .design/config.json, and (if Phase 23.5 has data) their cost/quality delta vs local. Single command, no flags. Read by users investigating delegation setup."
 argument-hint: ""
 tools: Read, Bash
 ---
@@ -49,7 +49,7 @@ Once Phase 27.5 has fired across enough spawns, `.design/telemetry/posterior.jso
 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)`.
 
-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).
+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).
 
 ### 5. Render the table
 
@@ -83,8 +83,8 @@ The table IS the output. No follow-up prose. Users act on it: `(opt-in disabled)
 
 ## Cross-references
 
-- `./../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.
+- `./../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

package/skills/plan/SKILL.md

@@ -6,7 +6,7 @@ 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, mcp__gdd_state__probe_connections
 ---
 
-# Get Design Done — Plan
+# 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`.
 
@@ -18,7 +18,7 @@ Full procedure detail: `./plan-procedure.md`.
 
 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.
+3. Abort only if `.design/DESIGN-CONTEXT.md` is missing - that is the true prerequisite, not STATE.md.
 
 ---
 
@@ -36,19 +36,19 @@ When `chromatic: available`, run change-risk scoping before writing DESIGN-PLAN.
 
 ---
 
-## Step 1 — Optional Research (skip if `auto_mode`)
+## Step 1 - Optional Research (skip if `auto_mode`)
 
 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)
+## Step 1.5 - Pattern Mapping (mandatory, brownfield protection)
 
-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.
+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.
 
-## Step 1.6 — Assumptions Analysis (skip if `auto_mode`)
+## Step 1.6 - Assumptions Analysis (skip if `auto_mode`)
 
 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.
 
-## Step 1.7 — Synthesize pre-plan inputs (Plan 10.1-04, D-13/D-15)
+## Step 1.7 - Synthesize pre-plan 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.
 
@@ -56,11 +56,11 @@ If 2+ pre-plan agents ran (Step 1, 1.5, 1.6), invoke `Skill("synthesize", { outp
 
 ---
 
-## Step 2 — Plan
+## Step 2 - Plan
 
 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
+## Step 3 - Check
 
 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.
 
@@ -69,9 +69,9 @@ Spawn `design-plan-checker` to validate DESIGN-PLAN.md against DESIGN-CONTEXT.md
 ## Stage exit
 
 1. `mcp__gdd_state__set_status` -> `"plan_complete"`.
-2. `mcp__gdd_state__checkpoint` — stamps `last_checkpoint` and finalizes the plan stage.
+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.
+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
 
@@ -89,7 +89,7 @@ Run this final spec-quality pass over `.design/DESIGN-PLAN.md` before the plan
 Do NOT transition to design (or invoke `/gdd:design`) until `.design/DESIGN-PLAN.md` is committed AND the user has approved it. 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
+## Rationalizations - Thought to Reality
 
 The reasons an agent gives to skip planning or rush DESIGN-PLAN.md, and what each one costs:
 
@@ -98,7 +98,7 @@ The reasons an agent gives to skip planning or rush DESIGN-PLAN.md, and what eac
 | "This change is small, I can design straight from DESIGN-CONTEXT.md." | Plan-skipped tasks blow scope per cycle telemetry; the plan gate is for the typical case, not the exception you think you're in. |
 | "Pattern mapping is brownfield ceremony, I'll skip it." | Step 1.5 is mandatory because an unmapped brownfield is where the executor silently re-implements an existing pattern. |
 | "The plan-checker will just rubber-stamp it, skip the spawn." | The checker's 5 dimensions (coverage, wave order, must-have derivation) catch the gaps you can't see in your own plan. |
-| "I'll let the planner infer wave ordering at design time." | Unordered waves serialize work that could parallelize — or worse, run dependent tasks concurrently and corrupt the tree. |
+| "I'll let the planner infer wave ordering at design time." | Unordered waves serialize work that could parallelize - or worse, run dependent tasks concurrently and corrupt the tree. |
 | "Research is overkill for this scope." | The complexity heuristic exists precisely because agents under-estimate scope; skipping research on a 3+-scope domain guarantees a mid-design surprise. |
 | "I can record decisions in DESIGN-PLAN.md prose instead of D-XX." | Prose decisions never reach STATE.md, so verify's integration-checker can't trace them and flags them orphaned. |
 

package/skills/plan/plan-procedure.md

@@ -7,8 +7,8 @@ tags: [plan, procedure, extracted, pipeline-stage, research, planner, checker]
 last_updated: 2026-05-18
 ---
 
-Source: extracted from `skills/plan/SKILL.md` (Phase 28.5 rework — D-10 extract-then-link).
-The skill's load-bearing workflow stays in `../skills/plan/SKILL.md`; this file holds the
+Source: extracted from `skills/plan/SKILL.md` (Phase 28.5 rework - D-10 extract-then-link).
+The skill's essential workflow stays in `../skills/plan/SKILL.md`; this file holds the
 detail the agent reaches for when executing a specific step (agent spawn prompts, chromatic
 scoping, synthesizer wiring, research-synthesis persistence, exploration artifact globbing).
 
@@ -16,7 +16,7 @@ scoping, synthesizer wiring, research-synthesis persistence, exploration artifac
 
 Detailed procedure for the get-design-done `plan` Stage 3 orchestrator. Companion to
 `../skills/plan/SKILL.md`. Read this file when executing a specific plan step; the
-SKILL.md keeps the load-bearing workflow + decision tree, this file holds the deep
+SKILL.md keeps the essential workflow + decision tree, this file holds the deep
 agent prompts and pre-plan research wiring.
 
 ---
@@ -27,7 +27,7 @@ agent prompts and pre-plan research wiring.
    - 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.
+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.
 
 ## Flag Parsing
 
@@ -50,32 +50,32 @@ After the parallelism decision is made:
 
 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
+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:
+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.
+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
+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.
 
 ---
 
-## Step 1 — Optional Research (skip if auto_mode)
+## Step 1 - Optional Research (skip if auto_mode)
 
 Complexity heuristic: if DESIGN-CONTEXT.md `<domain>` spans 3+ scopes OR `<decisions>` count > 6 -> spawn design-phase-researcher. Otherwise skip.
 
@@ -100,7 +100,7 @@ Emit `## RESEARCH COMPLETE` when done.
 
 Wait for `## RESEARCH COMPLETE`. Call `mcp__gdd_state__update_progress` with `task_progress: "1/3"` and a short `status` summary.
 
-## Step 1.5 — Pattern Mapping (mandatory, brownfield protection)
+## Step 1.5 - Pattern Mapping (mandatory, brownfield protection)
 
 ```
 Task("design-pattern-mapper", """
@@ -122,7 +122,7 @@ 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)
+## Step 1.6 - Assumptions Analysis (optional, same flag as research)
 
 If assumptions analysis enabled (skip if auto_mode):
 
@@ -143,7 +143,7 @@ Emit `## ANALYSIS COMPLETE` when done.
 
 Wait for `## ANALYSIS COMPLETE`.
 
-## Step 1.7 — Synthesize pre-plan research 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+ 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.
 
@@ -157,7 +157,7 @@ If 2+ of the pre-plan research agents ran (`design-phase-researcher` Step 1, `de
       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.
+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.
 
@@ -173,7 +173,7 @@ For each M-XX must-have the synthesizer produces:
 
 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
+## Step 2 - Plan
 
 ```
 Task("design-planner", """
@@ -208,7 +208,7 @@ 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.
 
-## Step 3 — Check
+## Step 3 - Check
 
 ```
 Task("design-plan-checker", """
@@ -235,7 +235,7 @@ Emit `## PLAN CHECK COMPLETE` when done.
 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.
+- 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
@@ -243,7 +243,7 @@ If `## PLAN CHECK RESULT: ISSUES FOUND` and any BLOCKER issues:
 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.
 
-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 established by brief->explore and explore->plan.
 
 ## After Completion
 
@@ -257,13 +257,13 @@ Print user-facing summary:
 ## 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
+- `.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)
+## `--research` mode (removed)
 
 V2-04 deferred the `--research` flag. Rationale: complexity of an additional
 agent spawn + Context7 integration outweighs the benefit of discover-stage
@@ -274,5 +274,5 @@ 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
+If `--research` is reintroduced in a future version, define its scope in
 ROADMAP.md V2+ and update this section.

package/skills/plant-seed/SKILL.md

@@ -10,12 +10,12 @@ disable-model-invocation: true
 
 **Role:** Capture an idea that is too early to act on now but should surface when a future condition is met. Backing store: `.design/SEEDS.md`.
 
-## Step 1 — Gather inputs
+## Step 1 - Gather inputs
 
 - `<text>`: free-text idea. If empty, ask the user: "What's the seed idea?"
 - `--trigger <condition>`: the surfacing condition. If missing, ask: "What trigger condition should surface this idea? (e.g., 'when we add dark mode', 'when the nav component is redesigned', 'at next cycle start')"
 
-## Step 2 — Append to .design/SEEDS.md
+## Step 2 - Append to .design/SEEDS.md
 
 Create the file with `# Design Seeds` header if missing. Append:
 
@@ -30,11 +30,11 @@ Create the file with `# Design Seeds` header if missing. Append:
 ---
 ```
 
-## Step 3 — Surfacing contract
+## Step 3 - Surfacing contract
 
 Seeds are surfaced automatically by `/gdd:progress` and `/gdd:health`. Those commands do a keyword match of each seed's trigger text against current STATE.md + `.design/CYCLES.md` content and print any matches as `Seed ready to germinate: <text>`.
 
-This skill does NOT surface seeds itself — it only plants them.
+This skill does NOT surface seeds itself - it only plants them.
 
 ## Output
 

package/skills/pr-branch/SKILL.md

@@ -26,7 +26,7 @@ Produces a branch that contains only code changes (under `src/`) so reviewers ar
 ## Do Not
 
 - Do not rewrite history on the original branch.
-- Do not include `.design/` or `.planning/` paths — if a mixed commit contains them, the cherry-pick carries them through, but reviewers are warned.
-- Do not push the branch automatically — let `/gdd:ship` or the user push.
+- Do not include `.design/` or `.planning/` paths - if a mixed commit contains them, the cherry-pick carries them through, but reviewers are warned.
+- Do not push the branch automatically - let `/gdd:ship` or the user push.
 
 ## PR-BRANCH COMPLETE

package/skills/progress/SKILL.md

@@ -11,9 +11,9 @@ tools: Read, Bash, Grep, Glob, mcp__gdd_state__get, mcp__gdd_status, mcp__gdd_ph
 
 **Role:** Show current position in the pipeline and recommend the next action. With `--forensic`, run a 6-check integrity audit.
 
-## Step 1 — Read state
+## Step 1 - Read state
 
-Two paths — MCP preferred when available, file-read fallback otherwise.
+Two paths - MCP preferred when available, file-read fallback otherwise.
 
 ### MCP path (preferred)
 
@@ -23,19 +23,19 @@ When the harness exposes `mcp__gdd_status` (Phase 27.7+, registered via `npx @he
 2. If you need `stage` / `task_progress` for the output line, call `mcp__gdd_phase_current` (no args). Returns `{phase, stage, task_progress, status}`.
 3. Skip to Step 2.
 
-This path loads the full priming context in 1–2 MCP calls (~3s, ~32k tokens — Storybloq benchmark).
+This path loads the full priming context in 1–2 MCP calls (~3s, ~32k tokens - Storybloq benchmark).
 
 ### File-read path (fallback)
 
 When MCP tools are not available, fall back to the legacy flow:
 
 1. Call `mcp__gdd_state__get` if exposed (Phase 20 STATE.md mutator MCP) → parsed state object. Otherwise, `Read .design/STATE.md` and parse the frontmatter + `<position>`, `<decisions>`, `<plans>` sections.
-2. Extract: `stage`, `cycle`, `last_checkpoint`, `task_progress`, `status`, `decisions.length`, open todos from `.design/TODO.md` (count unchecked `- [ ]` — outside the MCP catalog, so `Read` is still used).
+2. Extract: `stage`, `cycle`, `last_checkpoint`, `task_progress`, `status`, `decisions.length`, open todos from `.design/TODO.md` (count unchecked `- [ ]` - outside the MCP catalog, so `Read` is still used).
 3. If STATE.md is missing, print: "No pipeline state. Run `/gdd:brief` first." and stop.
 
-This path loads the same context in 5–10 file reads (~100s, ~46.5k tokens — file-reading baseline).
+This path loads the same context in 5–10 file reads (~100s, ~46.5k tokens - file-reading baseline).
 
-## Step 2 — Default output
+## Step 2 - Default output
 
 ```
 ━━━ Pipeline state ━━━
@@ -52,16 +52,16 @@ Recommend next stage via the same logic as `/gdd:next` (route by which artifacts
 
 After the pipeline state block, if every `<connections>` entry from the snapshot is `not_configured` AND `.design/config.json > connections_onboarding` is absent, append once per session (transient marker `.design/.connections-nudge-shown`): `Tip: run /gdd:connections to see what integrations can plug in (Figma, Storybook, Chromatic, etc.).`
 
-## Step 3 — Forensic audit (only if `--forensic`)
+## Step 3 - Forensic audit (only if `--forensic`)
 
 Run these six checks and print PASS/WARN/FAIL per check:
 
-1. **Stale artifacts** — compare mtime of `.design/DESIGN.md` against most recent file under `src/` via `ls -lt`. WARN if DESIGN.md is older by >7 days.
-2. **Missing transitions** — `stage` from the `mcp__gdd_state__get` snapshot vs artifacts present. e.g. stage=`plan` requires DESIGN-CONTEXT.md. FAIL if expected artifact missing.
-3. **Token drift** — `wc -c .design/DESIGN.md .design/DESIGN-CONTEXT.md`; tokens ≈ bytes/4. WARN if combined >50000 tokens.
-4. **Aged DESIGN-DEBT** — read `.design/DESIGN-DEBT.md`; any item whose line predates HEAD by >14 days (check `git blame` or file mtime fallback) → WARN.
-5. **Cycle alignment** — if `cycle` from the snapshot is set but `.design/CYCLES.md` has no matching heading → FAIL.
-6. **Connection status** — re-probe figma/refero via ToolSearch; compare to the `<connections>` field in the snapshot. WARN on mismatch.
+1. **Stale artifacts** - compare mtime of `.design/DESIGN.md` against most recent file under `src/` via `ls -lt`. WARN if DESIGN.md is older by >7 days.
+2. **Missing transitions** - `stage` from the `mcp__gdd_state__get` snapshot vs artifacts present. e.g. stage=`plan` requires DESIGN-CONTEXT.md. FAIL if expected artifact missing.
+3. **Token drift** - `wc -c .design/DESIGN.md .design/DESIGN-CONTEXT.md`; tokens ≈ bytes/4. WARN if combined >50000 tokens.
+4. **Aged DESIGN-DEBT** - read `.design/DESIGN-DEBT.md`; any item whose line predates HEAD by >14 days (check `git blame` or file mtime fallback) → WARN.
+5. **Cycle alignment** - if `cycle` from the snapshot is set but `.design/CYCLES.md` has no matching heading → FAIL.
+6. **Connection status** - re-probe figma/refero via ToolSearch; compare to the `<connections>` field in the snapshot. WARN on mismatch.
 
 Also scan `.design/SEEDS.md` (if present) for seeds whose trigger keywords match the snapshot or CYCLES.md content; list them as "Seed ready to germinate: <text>".
 
@@ -78,7 +78,7 @@ Seeds ready: 0
 ━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-## Step 4 — Update notice (safe-window surface)
+## Step 4 - Update notice (safe-window surface)
 
 After printing the pipeline state, emit the plugin-update banner if one is present. This file is written by `hooks/update-check.sh` subject to the state-machine guard (mid-pipeline stages suppress it) and per-version dismissal.
 
@@ -90,6 +90,6 @@ No-op when: no new release exists, state-machine guard is active (stage in plan|
 
 ## Do Not
 
-- Do not mutate STATE.md — this skill is read-only. Only `mcp__gdd_state__get` is permitted.
+- Do not mutate STATE.md - this skill is read-only. Only `mcp__gdd_state__get` is permitted.
 
 ## PROGRESS COMPLETE