@hegemonart/get-design-done 1.28.0 → 1.28.5

package/skills/optimize/SKILL.md

@@ -10,61 +10,42 @@ tools: Read, Bash, Grep, Write
 
 ## Role
 
-You are the optimization advisor. You read the telemetry ledger (`.design/telemetry/costs.jsonl`) and the per-agent metrics aggregate (`.design/agent-metrics.json`), apply a fixed set of rule-based heuristics, and emit recommendations to `.design/OPTIMIZE-RECOMMENDATIONS.md`. You never modify agent files, budget config, or cache state. Your output is a markdown table of proposals the user reviews manually, mirroring the Phase 11 `/gdd:apply-reflections` discipline.
-
-This skill is **advisory only**. It never edits `agents/*.md`, `.design/budget.json`, `.design/cache-manifest.json`, or any other configuration. The skill never makes model calls — every rule is deterministic.
+Read the telemetry ledger (`.design/telemetry/costs.jsonl`) and per-agent aggregate (`.design/agent-metrics.json`), apply a fixed set of rule-based heuristics, and emit recommendations to `.design/OPTIMIZE-RECOMMENDATIONS.md`. Never modify agent files, budget config, or cache state. Output is a markdown table of proposals the user reviews manually, mirroring Phase 11 `/gdd:apply-reflections`. **Advisory only**: never edits `agents/*.md`, `.design/budget.json`, `.design/cache-manifest.json`. Never makes model calls — every rule is deterministic. See `./reference/heuristics.md` §"Optimization rules" for the full rule catalog.
 
 ## Refresh Step
 
-Before analysis, invoke the aggregator to ensure metrics are current:
+Before analysis, invoke the aggregator:
 
 ```bash
 node --experimental-strip-types scripts/aggregate-agent-metrics.ts
 ```
 
-This is idempotent. If `--refresh` flag is absent and `.design/agent-metrics.json` was generated within the last 60 seconds, the skill may skip this step.
+Idempotent. If `--refresh` absent and `.design/agent-metrics.json` generated within 60s, skip.
 
 ## Inputs
 
-- `.design/telemetry/costs.jsonl` — append-only; skill reads tail. Tolerant of malformed lines.
-- `.design/agent-metrics.json` — per-agent aggregate produced by `scripts/aggregate-agent-metrics.ts`. Source of truth for `cache_hit_rate`, `lazy_skip_rate`, `total_cost_usd`, `total_spawns`.
-- `agents/*.md` — frontmatter cross-reference when checking tier override churn + typical-duration drift.
-- `.design/budget.json` — `tier_overrides` table for cross-check (optional; proceed if missing).
+- `.design/telemetry/costs.jsonl` — append-only; tolerant of malformed lines.
+- `.design/agent-metrics.json` — per-agent aggregate; source of truth for `cache_hit_rate`, `lazy_skip_rate`, `total_cost_usd`, `total_spawns`.
+- `agents/*.md` — frontmatter cross-reference for tier override churn + typical-duration drift.
+- `.design/budget.json` — `tier_overrides` table (optional).
 
 ## Optional Arguments
 
 - `--refresh` — force aggregator refresh even if metrics file is fresh.
-- `--min-spawns=N` — only emit recommendations for agents with ≥ N spawns (default: 5; raise for high-traffic projects to suppress noise).
+- `--min-spawns=N` — only emit recommendations for agents with ≥ N spawns (default 5).
 
 ## Rules
 
-Rule-based analysis, applied in this order. Each rule inspects per-agent aggregates and emits zero or more rows to the recommendations table.
-
-   **Rule R1 — Low cache hit rate.**
-   > IF an agent has `total_spawns >= --min-spawns` AND `cache_hit_rate < 0.20`
-   > THEN emit: `"Consider batching tasks for agent {agent} — cache hit rate is {rate*100}%. Investigate cache-aligned ordering (see reference/shared-preamble.md) and whether input paths can be normalized."`
-   > PROPOSED: Batch similar tasks; confirm shared-preamble import ordering.
-
-   **Rule R2 — Expensive and rarely lazy-skipped.**
-   > IF an agent has `total_cost_usd > 0.50` AND `lazy_skip_rate < 0.10`
-   > THEN emit: `"Agent {agent} is expensive (${cost}) and rarely skipped ({rate*100}% lazy-skip). Consider adding a lazy gate heuristic at agents/{agent}-gate.md (see plan 10.1-04 pattern)."`
-   > PROPOSED: Add lazy-gate agent.
+Rule-based analysis. Full thresholds + emission templates in `./reference/heuristics.md` §"Optimization rules"; here, the short rule catalog:
 
-   **Rule R3 — Tier override churn.**
-   > IF for multiple telemetry rows an agent's recorded `tier` differs from its frontmatter `default-tier` (e.g., frontmatter says `opus` but measured rows consistently show `haiku` from budget.json override or soft-threshold downgrade)
-   > THEN emit: `"Tier override churn detected for {agent}: frontmatter says {frontmatter-tier} but measured tier is {measured-tier} in {N} of last {M} rows. Consider updating frontmatter default-tier or removing the budget.json override."`
-   > PROPOSED: Update frontmatter default-tier OR prune budget.json tier_overrides entry.
-
-   **Rule R4 — Typical duration drift.**
-   > IF measured `typical_duration_seconds` (computed as average wall-clock duration from telemetry `ts` deltas when paired spawn/complete rows exist; fall back to frontmatter value if pairing unavailable in v1) differs from frontmatter `typical-duration-seconds` by more than 50%
-   > THEN emit: `"Typical duration for {agent} has drifted: frontmatter {old}s vs measured {new}s ({delta_pct}% drift). Update frontmatter typical-duration-seconds: {new}."`
-   > PROPOSED: Edit agents/{agent}.md frontmatter.
-
-   (Note: v1 only computes wall-clock duration if the telemetry ledger carries both spawn and complete rows with matching correlation IDs. If it doesn't — 10.1's PreToolUse-only writer doesn't — Rule R4 flags "insufficient data" for affected agents rather than emitting a false proposal. Phase 11 reflector can add a PostToolUse writer to close this gap; out of 10.1 scope.)
+- **R1 — Low cache hit rate.** IF `total_spawns >= --min-spawns` AND `cache_hit_rate < 0.20` → propose batching + investigate shared-preamble ordering.
+- **R2 — Expensive + rarely lazy-skipped.** IF `total_cost_usd > 0.50` AND `lazy_skip_rate < 0.10` → propose adding a lazy gate at `agents/{agent}-gate.md` (Plan 10.1-04 pattern).
+- **R3 — Tier override churn.** IF measured `tier` differs from frontmatter `default-tier` for multiple rows → propose updating frontmatter or removing budget.json override.
+- **R4 — Typical duration drift.** IF measured `typical_duration_seconds` differs from frontmatter by > 50% → propose frontmatter update. (v1 only computes wall-clock duration if both spawn + complete rows have matching correlation IDs; otherwise flag "insufficient data".)
 
 ## Output Format
 
-Write `.design/OPTIMIZE-RECOMMENDATIONS.md` with this exact structure:
+Write `.design/OPTIMIZE-RECOMMENDATIONS.md`:
 
 ```markdown
 # Optimization Recommendations
@@ -80,9 +61,7 @@ Write `.design/OPTIMIZE-RECOMMENDATIONS.md` with this exact structure:
 
 | Rule | Agent | Current | Proposed | Rationale |
 |------|-------|---------|----------|-----------|
-| R1 | design-verifier | cache_hit_rate: 8% | Batch tasks; audit shared-preamble ordering | Low cache reuse; likely causing 3× cost on repeated calls |
-| R2 | design-planner | $1.23 cost, 2% lazy-skip | Add agents/design-planner-gate.md | High spend with minimal gating |
-| R3 | design-verifier | frontmatter opus / measured haiku (9/12 rows) | Update frontmatter default-tier: haiku | budget.json overrides are effectively permanent |
+| R1 | ... | ... | ... | ... |
 
 ## Summary
 
@@ -94,17 +73,15 @@ Write `.design/OPTIMIZE-RECOMMENDATIONS.md` with this exact structure:
 ## OPTIMIZE COMPLETE
 ```
 
-The `## OPTIMIZE COMPLETE` marker is the completion sentinel — automated graders and downstream tools detect completion by grepping for this exact line.
+The `## OPTIMIZE COMPLETE` marker is the completion sentinel.
 
 ## No Auto-Apply
 
-This skill **never modifies** `agents/*.md`, `.design/budget.json`, `.design/cache-manifest.json`, or any other configuration. It **never auto-applies** proposals. It only writes `.design/OPTIMIZE-RECOMMENDATIONS.md`. If the user wants to act on a proposal, they do so manually (or via a future Phase 12 command that cross-references these proposals).
-
-The discipline mirrors `/gdd:apply-reflections` from Phase 11: advisory output, user review, manual application.
+This skill **never modifies** `agents/*.md`, `.design/budget.json`, `.design/cache-manifest.json`, or any other configuration. **Never auto-applies** proposals. If the user wants to act, they do so manually. Discipline mirrors `/gdd:apply-reflections` from Phase 11.
 
 ## Integration with Phase 11 Reflector
 
-The Phase 11 reflector (`agents/design-reflector.md`) reads both `costs.jsonl` and `agent-metrics.json` on its own cadence. `/gdd:optimize` is the user-facing advisor; the reflector is the automation-facing one. Both output to different files (`.design/OPTIMIZE-RECOMMENDATIONS.md` vs `.design/reflections/*.md`) and never collide.
+The Phase 11 reflector (`agents/design-reflector.md`) reads both `costs.jsonl` and `agent-metrics.json` on its own cadence. `/gdd:optimize` is user-facing; the reflector is automation-facing. Outputs land in different files (`.design/OPTIMIZE-RECOMMENDATIONS.md` vs `.design/reflections/*.md`) and never collide.
 
 ## Non-Goals
 
@@ -115,6 +92,6 @@ The Phase 11 reflector (`agents/design-reflector.md`) reads both `costs.jsonl` a
 
 ## Failure Modes
 
-- Missing `.design/telemetry/costs.jsonl` → emit a single line `"No telemetry data yet — run one or more /gdd:* commands to accumulate data, then retry."` and still write the `## OPTIMIZE COMPLETE` marker.
-- Missing `.design/agent-metrics.json` after refresh → emit `"Aggregator failed — check \`node --experimental-strip-types scripts/aggregate-agent-metrics.ts\` output manually."`.
-- Zero rules matched → still write the recommendations file with `"No recommendations — all agents within healthy thresholds."` and the `## OPTIMIZE COMPLETE` marker.
+- Missing `.design/telemetry/costs.jsonl` → emit `No telemetry data yet — run /gdd:* commands to accumulate data, then retry.` + `## OPTIMIZE COMPLETE`.
+- Missing `.design/agent-metrics.json` after refresh → emit `Aggregator failed — check node --experimental-strip-types scripts/aggregate-agent-metrics.ts output manually.`
+- Zero rules matched → write `No recommendations — all agents within healthy thresholds.` + `## OPTIMIZE COMPLETE`.

package/skills/pause/SKILL.md

@@ -3,6 +3,7 @@ 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

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

@@ -1,6 +1,6 @@
 ---
 name: peer-cli-add
-description: "Guided ladder for adding a brand-new peer (a peer not in the v1.27 capability matrix) to the gdd peer-CLI delegation layer. Verification ladder + adapter scaffolding + capability-matrix update + Windows quirks documented. Run when you discover a new peer CLI you want gdd to delegate to."
+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
 ---
@@ -11,118 +11,49 @@ tools: Read, Edit, Write, Bash, Grep
 
 ## 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 yet — they run this skill. It walks them through a verification ladder (does the peer actually speak ACP or ASP?) and produces the 3-file footprint that integrates the peer cleanly.
+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 `./reference/peer-cli-protocol.md`.
 
 ## Invocation Contract
 
-- **Required input**: `<new-peer-id>` (lowercase identifier, e.g., `aider`), `<peer-binary>` (the executable name, e.g., `aider` or `aider.cmd`), `<protocol>` (`acp` or `asp`).
-- **Output**: a 3-file diff + a verification report.
+- **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)
 
-Before touching any code, confirm the peer actually speaks the protocol it claims.
+Walk the four-rung ladder in `./reference/peer-cli-protocol.md` §"Verification ladder":
 
-#### 1a. Binary on PATH
+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`).
 
-`which <peer-binary>` (POSIX) or `where <peer-binary>` (Windows). If exit non-zero, stop and ask user to install the peer first.
-
-#### 1b. Handshake test
-
-Spawn the peer with the appropriate protocol entry point:
-- ACP peers: `<peer-binary> acp` (or whatever the peer documents as its ACP entry — Gemini uses `gemini acp`; some peers use a flag).
-- ASP peers: `<peer-binary> app-server` (Codex's 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. If the reply is a valid JSON-RPC response with `result.protocolVersion` (ACP) or `result.threadId` (ASP), the peer speaks the protocol.
-
-If no valid reply within 5 seconds, the peer either doesn't speak this protocol or uses a non-standard entry point. Stop and ask the user for the correct invocation.
-
-#### 1c. 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 current model list (most peers expose `<peer-binary> models` or similar). Note any model that has `-preview` in its name and document the parent name in the new entry's `provider_model_id` field — so the runtime-models.md entry can survive the suffix flipping.
-
-#### 1d. Windows quirks
-
-If the peer-binary ends in `.cmd` and the user is on Windows, confirm the spawn-cmd shell-escape logic from `scripts/lib/peer-cli/spawn-cmd.cjs` will pick it up (it should — that module already handles `.cmd` detection per Plan 27-03 / D-04). Document any other Windows-specific quirks in the new adapter's leading comment.
+Stop at the first failing rung. Do not proceed to scaffold a broken adapter.
 
 ### Step 2 — Generate the adapter scaffold
 
-Use the existing 5 adapters at `scripts/lib/peer-cli/adapters/{codex,gemini,cursor,copilot,qwen}.cjs` as templates. Pick the closest match to your new peer's protocol (ASP if `<protocol> = asp`, otherwise ACP).
+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 `./reference/peer-cli-protocol.md` §"Adapter scaffold shape" so consumers (codex/gemini/cursor/copilot/qwen) stay byte-similar.
 
-Use the `Write` tool to create `scripts/lib/peer-cli/adapters/<new-peer-id>.cjs`:
+Write the result to `scripts/lib/peer-cli/adapters/<new-peer-id>.cjs`.
 
-```js
-'use strict';
+### Step 3 — Three-file footprint
 
-const { createAcpClient } = require('../acp-client.cjs');
-// OR for ASP peers: const { createAspClient } = require('../asp-client.cjs');
+Per `./reference/peer-cli-protocol.md` §"Three-file footprint":
 
-const ROLES_CLAIMED = ['<role-1>', '<role-2>'];   // ASK USER which roles this peer claims
-const ROLE_PREFIX = {
-  '<role-1>': '<prompt prefix or empty string>',
-  '<role-2>': '<prompt prefix or empty string>',
-};
+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).
 
-function claims(role) { return ROLES_CLAIMED.includes(role); }
+### Step 4 — Verification gate
 
-async function dispatch({ command, args, cwd, env }, role, text, opts) {
-  if (!claims(role)) {
-    throw new Error(`<new-peer-id> does not claim role: ${role}`);
-  }
-  const client = createAcpClient({ command, args, cwd, env });
-  try {
-    await client.initialize({ protocolVersion: '2025-06-18' });
-    const prompt = (ROLE_PREFIX[role] || '') + text;
-    return await client.prompt(prompt, { onNotification: opts?.onNotification });
-  } finally {
-    await client.close();
-  }
-}
-
-module.exports = { claims, dispatch, ROLES_CLAIMED, ROLE_PREFIX, name: '<new-peer-id>', protocol: '<protocol>' };
-```
+Run the four-check gate in `./reference/peer-cli-protocol.md` §"Verification gate": `tsc --noEmit`, peer-cli tests, reference-registry round-trip, frontmatter validator. Any failure — surface error + offer revert.
 
-Replace placeholders with the user's input from Step 1's verification.
-
-### Step 3 — Add `peerBinary` to runtimes.cjs
-
-Edit `scripts/lib/install/runtimes.cjs` to add an entry for the new peer. Mirror the shape of the 5 existing peer entries. Add the `peerBinary` field with platform-aware resolution:
-
-```js
-{
-  id: '<new-peer-id>',
-  // ... existing fields per Phase 24 runtime matrix shape ...
-  peerBinary: process.platform === 'win32' ? '<peer-binary>.cmd' : '<peer-binary>',
-}
-```
-
-### Step 4 — Add the capability-matrix entry
-
-Edit `reference/peer-cli-capabilities.md`. Add a new row to the top capability matrix table AND a new per-peer section. Follow the existing format. Cite the verification evidence from Step 1.
-
-### Step 5 — Update the registry capability matrix
-
-Edit `scripts/lib/peer-cli/registry.cjs`. Add the new peer to the `CAPABILITY_MATRIX` constant (and `KNOWN_PEERS` if that's a separate list). Mirror the shape of the 5 existing entries.
-
-### Step 6 — Verify the integration
-
-Run, in this 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 registry.json (if you added it).
-4. `npm run validate:frontmatter` — no agent's `delegate_to:` field is broken by the new entry.
-
-If any step fails, surface the error and offer to revert the changes.
-
-### Step 7 — Surface a 3-file footprint summary
+### Step 5 — Surface the summary
 
 ```
 ## peer-cli-add summary
-
 Added peer: <new-peer-id> (protocol: <protocol>)
 Roles claimed: <role-1>, <role-2>
 
@@ -139,31 +70,18 @@ Verification:
 ✓ frontmatter validator: 0 violations
 
 Next steps:
-- Run /gdd:peers to confirm the new peer shows up in the capability matrix.
-- Run skills/peer-cli-customize/SKILL.md to wire delegate_to: <new-peer-id>-<role> on specific agents.
-- Phase 23.5 bandit will need ~5 cycles of data before the posterior surfaces a recommendation for this peer.
+- /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
 
-- **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 to consider adding a new protocol layer.
-- **Peer claims a role no existing peer claims** (e.g., `translate`) — fine, capability matrix is open. But document the role in `reference/peer-cli-capabilities.md` so future peers can compete on it.
-- **Peer claims ALL roles** (e.g., a generalist peer) — 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 name conflicts with an existing peer-id** — fail. Peer-IDs must be globally unique. Suggest a disambiguating suffix.
-- **User wants to add a peer for testing only** — same flow, but suggest committing under a separate branch and not adding to the install-time detection nudge until the peer is production-ready.
-
-## Cross-references
-
-- `scripts/lib/peer-cli/registry.cjs` (Plan 27-05) — capability matrix data.
-- `scripts/lib/peer-cli/adapters/*.cjs` (Plan 27-04) — adapter template.
-- `scripts/lib/peer-cli/spawn-cmd.cjs` (Plan 27-03) — Windows .cmd handling.
-- `reference/peer-cli-capabilities.md` (Plan 27-05) — capability-matrix doc.
-- `skills/peer-cli-customize/SKILL.md` — once new peer is added, use customize to wire it on specific agents.
-- `.planning/phases/27-peer-cli-delegation/CONTEXT.md` D-02, D-05 — decision lineage.
+See `./reference/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
 
-After execution, append one JSONL line to `.design/skill-records.jsonl`:
+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/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 `./reference/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 `./reference/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 `./reference/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 `./reference/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.
+- `./reference/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 `./reference/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.
+- `./reference/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}
 ```