@hegemonart/get-design-done 1.41.5 → 1.42.0

package/dist/claude-code/.claude/skills/pause/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: gdd-pause
+description: "Write a numbered checkpoint so work can resume in a new session without re-running completed stages."
+argument-hint: "[context note]"
+tools: Read, Write, Bash, AskUserQuestion, mcp__gdd_state__get, mcp__gdd_state__set_status, mcp__gdd_state__add_blocker, mcp__gdd_state__checkpoint
+disable-model-invocation: true
+---
+
+@reference/retrieval-contract.md
+@reference/cycle-handoff-preamble.md
+
+# /gdd:pause
+
+Captures enough state that a killed or stopped session can resume cleanly via `/gdd:resume` or `/gdd:continue`.
+
+Each invocation writes an **immutable numbered checkpoint** — it does not overwrite previous pauses. This enables branched cycles: you can pause, take a detour via `/gdd:sketch`, compare, and resume an older snapshot via `/gdd:resume N`.
+
+## Steps
+
+1. `mcp__gdd_state__get` → snapshot current pipeline state. Extract:
+   - Current `stage` and `cycle`
+   - `last_checkpoint` timestamp
+   - `task_progress` and `status` for the current run
+   - Open todos (from `.design/TODO.md` if present — this file is outside the MCP catalog, so `Read` is still used)
+   - Active sketch/spike directories (scan `.design/sketches/` and `.design/spikes/` for in-progress markers)
+
+2. **Determine checkpoint number**: run
+   ```bash
+   ls .design/checkpoints/ 2>/dev/null | grep -E '^[0-9]+' | sort -n | tail -1
+   ```
+   Next checkpoint = last number + 1 (or `01` if none exist).
+
+3. **Collect context**: if no context argument was passed, ask (AskUserQuestion):
+   "What are you in the middle of? (optional context to capture)"
+
+4. **Flip status via MCP** so `/gdd:resume` can detect the pause and recover the prior status:
+   1. `mcp__gdd_state__set_status` with `status: "paused:<prior-status>"` — the `paused:` prefix preserves the prior status for resume parsing.
+   2. If the user supplied a context/blocker message: `mcp__gdd_state__add_blocker` with `{ stage: <current>, date: <today>, text: <message> }`.
+   3. `mcp__gdd_state__checkpoint` to stamp `last_checkpoint` via MCP.
+
+5. **Write numbered checkpoint**: create `.design/checkpoints/` with `mkdir -p`, then write:
+   ```
+   .design/checkpoints/NN-<stage>-<ISO-date>.md
+   ```
+   e.g. `01-design-2026-04-24.md`
+
+   Content:
+   ```markdown
+   # Checkpoint NN
+   **Saved**: <ISO timestamp>
+   **Stage**: <stage>
+   **Cycle**: <cycle>
+   **In progress**: <task description + wave/index>
+   **Next**: <next step>
+   **Context**: <user note or "none">
+   **Active sketch**: <path or none>
+   **Open todos**: <N items (see .design/TODO.md)>
+   **Completed this session**: <list>
+   ```
+
+6. **Update HANDOFF.md pointer**: write `.design/HANDOFF.md` with:
+   ```markdown
+   # Session Handoff (pointer)
+   Latest checkpoint: `.design/checkpoints/NN-<stage>-<ISO-date>.md`
+   Run `/gdd:resume` to restore, or `/gdd:resume N` for a specific checkpoint.
+   ```
+
+7. Print: "Checkpoint NN saved. Run `/gdd:resume` or `/gdd:continue` to pick back up."
+
+## Do Not
+
+- Do not mutate STATE.md directly — all STATE.md writes go through the `gdd-state` MCP tools above. Checkpoint files + HANDOFF.md are sibling artifacts, written with `Write`.
+- Do not abort in-progress sketches; just record them.
+- Do not delete previous checkpoint files.
+- Do not call `mcp__gdd_state__transition_stage` — pause is status-only, never a stage transition.
+
+## PAUSE COMPLETE

package/dist/claude-code/.claude/skills/peer-cli-add/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: peer-cli-add
+description: "Guided ladder for adding a brand-new peer (not in the v1.27 capability matrix) to gdd's peer-CLI delegation layer. Walks the verification ladder, scaffolds an adapter, updates the capability matrix, and handles Windows quirks. Run when you discover a new peer CLI you want gdd to delegate to."
+argument-hint: "<new-peer-id> <peer-binary> <protocol: acp|asp>"
+tools: Read, Edit, Write, Bash, Grep
+---
+
+<!-- Procedural pattern adapted from greenpolo/cc-multi-cli's `multi-cli-anything` skill (Apache 2.0). See NOTICE for full attribution. -->
+
+# peer-cli-add
+
+## Role
+
+You add a brand-new peer-CLI to gdd's delegation layer. v1.27.0 ships 5 peers (codex, gemini, cursor, copilot, qwen). When the user wants a 6th — a peer that exists in the wild but isn't in our capability matrix — you walk them through the verification ladder and produce the 3-file footprint that integrates the peer cleanly. The procedural ladder, adapter scaffold shape, and verification gate live in `./peer-cli-protocol.md`.
+
+## Invocation Contract
+
+- **Required input:** `<new-peer-id>` (lowercase, e.g. `aider`), `<peer-binary>` (executable, e.g. `aider` or `aider.cmd`), `<protocol>` (`acp` or `asp`).
+- **Output:** a 3-file diff + a verification report.
+
+## Procedure
+
+### Step 1 — Verification ladder (no edits yet)
+
+Walk the four-rung ladder in `./peer-cli-protocol.md` §"Verification ladder":
+
+1. Binary on PATH (`which` / `where`).
+2. Handshake test (`initialize` JSON-RPC over stdin; capture reply).
+3. Model-ID `-preview`-suffix trap (capture model list).
+4. Windows quirks (confirm `spawn-cmd.cjs` picks up `.cmd`).
+
+Stop at the first failing rung. Do not proceed to scaffold a broken adapter.
+
+### Step 2 — Generate the adapter scaffold
+
+Copy one of `scripts/lib/peer-cli/adapters/{codex,gemini,cursor,copilot,qwen}.cjs` as the template (pick by protocol — ASP for `<protocol>=asp`, else ACP). Replace `ROLES_CLAIMED`, `ROLE_PREFIX`, `name`, `protocol` with the user's values from Step 1. The full adapter scaffold shape — `claims`, `dispatch`, exports — lives in `./peer-cli-protocol.md` §"Adapter scaffold shape" so consumers (codex/gemini/cursor/copilot/qwen) stay byte-similar.
+
+Write the result to `scripts/lib/peer-cli/adapters/<new-peer-id>.cjs`.
+
+### Step 3 — Three-file footprint
+
+Per `./peer-cli-protocol.md` §"Three-file footprint":
+
+1. New adapter at `scripts/lib/peer-cli/adapters/<new-peer-id>.cjs` (Step 2).
+2. Edit `scripts/lib/install/runtimes.cjs` — add `peerBinary` field (platform-aware: `<peer-binary>.cmd` on Windows, plain on POSIX).
+3. Edit `reference/peer-cli-capabilities.md` — add matrix row + per-peer section citing the Step 1 verification evidence.
+4. Edit `scripts/lib/peer-cli/registry.cjs` — append to `CAPABILITY_MATRIX` (and `KNOWN_PEERS` if separate).
+
+### Step 4 — Verification gate
+
+Run the four-check gate in `./peer-cli-protocol.md` §"Verification gate": `tsc --noEmit`, peer-cli tests, reference-registry round-trip, frontmatter validator. Any failure — surface error + offer revert.
+
+### Step 5 — Surface the summary
+
+```
+## peer-cli-add summary
+Added peer: <new-peer-id> (protocol: <protocol>)
+Roles claimed: <role-1>, <role-2>
+
+Files modified:
+✓ scripts/lib/peer-cli/adapters/<new-peer-id>.cjs (new)
+✓ scripts/lib/install/runtimes.cjs (added peerBinary entry)
+✓ reference/peer-cli-capabilities.md (added matrix row + per-peer section)
+✓ scripts/lib/peer-cli/registry.cjs (added to CAPABILITY_MATRIX)
+
+Verification:
+✓ tsc clean
+✓ existing peer-cli tests pass
+✓ reference-registry round-trip valid
+✓ frontmatter validator: 0 violations
+
+Next steps:
+- /gdd:peers to confirm the new peer appears in the matrix.
+- skills/peer-cli-customize/SKILL.md to wire delegate_to: <new-peer-id>-<role> on agents.
+- Phase 23.5 bandit needs ~5 cycles of data before a posterior recommendation surfaces.
+```
+
+## Edge cases
+
+See `./peer-cli-protocol.md` §"Edge cases" for: peer speaks neither protocol, claims unknown role, claims all roles (generalist), peer-ID conflicts, and testing-only peers.
+
+## Record
+
+Append one JSONL line to `.design/skill-records.jsonl`:
+
+```json
+{"skill": "peer-cli-add", "ts": "<ISO timestamp>", "new_peer": "<new-peer-id>", "protocol": "<protocol>", "roles_claimed": ["<role-1>"], "verification_passed": true}
+```

package/dist/claude-code/.claude/skills/peer-cli-add/peer-cli-protocol.md

@@ -0,0 +1,161 @@
+---
+name: peer-cli-protocol
+type: heuristic
+version: 1.0.0
+phase: 28.5
+tags: [peer-cli, acp, asp, protocol, verification-ladder, add-peer, customize, cc-multi-cli]
+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
+
+Procedural reference for the peer-CLI delegation layer. Centralizes the verification
+ladder, adapter scaffolding shape, rewire-discipline, and Windows quirks so the three
+peer-CLI skills (`peers`, `peer-cli-add`, `peer-cli-customize`) can cross-link rather
+than each carry the full procedure inline. See `./peer-protocols.md` for the protocol
+shape (JSON-RPC framing, initialize handshake, error envelope); this file is the
+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
+adapter.
+
+### 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
+
+Spawn the peer with the protocol entry point:
+
+- **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
+  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
+invocation.
+
+### 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
+list (most peers expose `<peer-binary> models` or similar) and document parent names in
+the new entry's `provider_model_id` field so the runtime-models entry survives the
+suffix flipping.
+
+### 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`
+detection per Plan 27-03 / D-04. Document any other Windows-specific quirks in the new
+adapter's leading comment.
+
+## Adapter scaffold shape
+
+Use the existing five adapters at `../scripts/lib/peer-cli/adapters/{codex,gemini,cursor,copilot,qwen}.cjs`
+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
+  `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.
+
+Canonical skeleton (ACP variant; for ASP swap to `createAspClient` from `asp-client.cjs`):
+
+```js
+'use strict';
+const { createAcpClient } = require('../acp-client.cjs');
+
+const ROLES_CLAIMED = ['<role-1>', '<role-2>'];
+const ROLE_PREFIX = { '<role-1>': '', '<role-2>': '' };
+
+function claims(role) { return ROLES_CLAIMED.includes(role); }
+async function dispatch({ command, args, cwd, env }, role, text, opts) {
+  if (!claims(role)) throw new Error(`<peer-id> does not claim role: ${role}`);
+  const client = createAcpClient({ command, args, cwd, env });
+  try {
+    await client.initialize({ protocolVersion: '2025-06-18' });
+    return await client.prompt((ROLE_PREFIX[role] || '') + text, { onNotification: opts?.onNotification });
+  } finally { await client.close(); }
+}
+module.exports = { claims, dispatch, ROLES_CLAIMED, ROLE_PREFIX, name: '<peer-id>', protocol: '<protocol>' };
+```
+
+## Three-file footprint (peer add)
+
+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:
+   `<binary>.cmd` on Windows, plain `<binary>` elsewhere).
+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
+   `KNOWN_PEERS` if separate).
+
+## Rewire discipline (customize)
+
+When rewiring `delegate_to:` on a specific agent's frontmatter:
+
+- Validate the new value against the capability matrix BEFORE editing the file. The
+  peer must exist; the role must be in the peer's `claims` list.
+- Three frontmatter cases: field absent + add it, field present + change it, field
+  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
+  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` —
+   no regression on existing tests.
+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.
+
+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
+  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
+  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.
+  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;
+  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
+  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.

package/dist/claude-code/.claude/skills/peer-cli-customize/SKILL.md

@@ -0,0 +1,90 @@
+---
+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."
+argument-hint: "[<agent-name>] [<new-delegate-target>]"
+tools: Read, Edit, Bash, Grep
+---
+
+<!-- Procedural pattern adapted from greenpolo/cc-multi-cli's `customize` skill (Apache 2.0). See NOTICE for full attribution. -->
+
+# peer-cli-customize
+
+## 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.
+
+## Invocation Contract
+
+- **Optional input**: agent-name + new delegate target. If absent, the skill runs in interactive discovery mode.
+- **Output**: a diff summary listing each `agents/*.md` file modified, the old vs new `delegate_to:` value, and the validation result.
+
+## Procedure
+
+### 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
+
+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.
+
+### Step 3 — Validate the proposed rewire
+
+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. 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. Three cases (per `./../peer-cli-add/peer-cli-protocol.md` §"Rewire discipline"):
+
+- **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
+
+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
+
+```
+## 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 dispatches through the new peer.
+
+Verify: /gdd:peers (shows updated allowlist + capability matrix).
+```
+
+## Edge cases
+
+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
+
+- `./../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
+
+After execution, append one JSONL line to `.design/skill-records.jsonl`:
+
+```json
+{"skill": "peer-cli-customize", "ts": "<ISO timestamp>", "agents_rewired": ["design-verifier", "design-reflector"], "validator_passed": true}
+```

package/dist/claude-code/.claude/skills/peers/SKILL.md

@@ -0,0 +1,96 @@
+---
+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."
+argument-hint: ""
+tools: Read, Bash
+---
+
+# gdd-peers
+
+## 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` (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. The table is the entire output.
+
+## Procedure
+
+### 1. Load runtime + capability 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 |
+|---------|--------------------------|----------|
+| codex   | execute                  | ASP      |
+| gemini  | research, exploration    | ACP      |
+| cursor  | debug, plan              | ACP      |
+| copilot | review, research         | ACP      |
+| qwen    | write                    | ACP      |
+
+### 2. Detect installation
+
+For each peer, run `which <peerBinary>` (POSIX) or `where <peerBinary>` (Windows). Exit 0 → installed; non-zero → not installed.
+
+### 3. Read allowlist
+
+Read `.design/config.json#peer_cli.enabled_peers` (array of peer-IDs). Default `[]` (opt-in required). Missing file or path = empty.
+
+### 4. (Optional) Read posterior reward-delta
+
+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. 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)`.
+
+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
+
+```
+## Peer-CLI Capability Matrix
+
+| Peer    | Installed | Allowlisted | Claimed roles            | Posterior delta vs local |
+|---------|-----------|-------------|--------------------------|--------------------------|
+| codex   | ✓         | ✓           | execute                  | -12% reward              |
+| gemini  | ✓         | ✓           | research, exploration    | -8% reward               |
+| cursor  | ✗         | ✗           | debug, plan              | (not installed)          |
+| copilot | ✓         | ✗           | review, research         | (opt-in disabled)        |
+| qwen    | ✓         | ✓           | write                    | (no data yet)            |
+
+> 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.
+```
+
+**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.
+
+### 6. Done
+
+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
+
+- `./../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
+
+Append one JSONL line to `.design/skill-records.jsonl`:
+
+```json
+{"skill": "gdd-peers", "ts": "<ISO timestamp>", "peers_detected": ["codex"], "peers_allowlisted": ["codex"], "had_posterior": false}
+```

package/dist/claude-code/.claude/skills/plan/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: plan
+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, 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`.
+
+Full procedure detail: `./plan-procedure.md`.
+
+---
+
+## Stage entry
+
+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.
+
+---
+
+## Flags + parallelism
+
+- `--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
+
+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.
+
+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.
+
+---
+
+## 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)
+
+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`)
+
+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)
+
+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.
+
+**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.
+
+---
+
+## 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
+
+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.
+
+---
+
+## Stage exit
+
+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.
+
+## After Completion
+
+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`.
+
+## Spec self-review (before transition)
+
+Run this final spec-quality pass over `.design/DESIGN-PLAN.md` before the plan→design transition:
+- Placeholder scan: no TBD / TODO / `<placeholder>` / lorem left in the artifact.
+- Internal consistency: sections don't contradict each other.
+- Scope check: nothing in the artifact exceeds (or silently drops) the agreed scope.
+- Ambiguity check: every requirement/decision is specific enough to act on without a follow-up question.
+
+<HARD-GATE>
+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
+
+The reasons an agent gives to skip planning or rush DESIGN-PLAN.md, and what each one costs:
+
+| Thought | Reality |
+|---------|---------|
+| "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. |
+| "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. |
+
+## PLAN COMPLETE