@hegemonart/get-design-done 1.28.0 → 1.28.6

package/skills/new-cycle/milestone-completeness-rubric.md

@@ -0,0 +1,87 @@
+---
+name: milestone-completeness-rubric
+type: heuristic
+version: 1.0.0
+phase: 28.5
+tags: [milestone, closeout, rubric, completion, turn-closeout, new-cycle, complete-cycle]
+last_updated: 2026-05-18
+---
+
+# Milestone Completeness Rubric
+
+What "complete" means at each layer of the gdd lifecycle. Used by `skills/turn-closeout/`,
+`skills/new-cycle/`, `skills/complete-cycle/`, the phase closeout discipline (Plan -12 of
+every phase), and the cycle wrap-up flow. Centralized here so the rubric stays consistent
+across consumers and updates land in one place rather than fanning out across N skills.
+
+## Layers
+
+The lifecycle has four nested layers. A layer is complete only when EVERY criterion at
+that layer is satisfied. Layers above can only flip complete when every layer below has
+flipped complete first — closeout walks bottom-up.
+
+### Task level
+
+The smallest unit of work — one row in a PLAN.md `<tasks>` list.
+
+- Verify command runs with exit 0 (the `<verify>` block's command).
+- The `<done>` criterion is observable (the file exists, the test passes, the output
+  matches the contract).
+- If the task is `tdd="true"`: tests pass after the GREEN step; tests fail before it.
+- File diff is scoped to the declared `files_modified` only — no collateral damage.
+- A single commit per task in conventional form `{type}({phase}-{plan}): {description}`.
+- Deviations (Rules 1, 2, 3) tracked for the SUMMARY.md "Deviations" section.
+
+### Plan level
+
+A self-contained chunk of work — one `XX-YY-PLAN.md`.
+
+- All tasks complete (per task level above).
+- Plan-level validator passes (e.g. `validate-skill-length.cjs` for Phase 28.5 buckets;
+  `validate-frontmatter.ts` for agent-frontmatter plans).
+- SUMMARY.md written at `.planning/phases/XX-name/XX-YY-SUMMARY.md` with the canonical
+  shape: deviations, files-modified table, commits, verification result, decisions.
+- No collateral damage outside the plan's declared `files_modified` list — out-of-scope
+  edits are forbidden (executor Rule 5 boundary).
+- A final docs commit aggregates `SUMMARY.md`, `STATE.md`, `ROADMAP.md`, and
+  `REQUIREMENTS.md` updates.
+
+### Phase level
+
+A coherent batch of plans — one `XX-name/` directory under `.planning/phases/`.
+
+- All plans complete (per plan level above).
+- Phase-level verification ALL pass (`<verification>` block in each PLAN.md).
+- ROADMAP.md flipped `[ ]` → `[x]` for all plans in this phase (rule #14: scoped flip
+  only — never flip plans outside this phase).
+- Phase SUMMARY ladder coherent — each `XX-YY-SUMMARY.md` exists and reads top-to-bottom
+  as a single story.
+- All decisions surfaced through the SUMMARY frontmatter and rolled up into STATE.md's
+  `<decisions>` block.
+
+### Cycle level
+
+A shipping milestone — typically one minor version bump in the gdd project.
+
+- All phases for the cycle's target version complete (per phase level above).
+- 4 manifests version-aligned: `plugin.json`, `marketplace.json`, `package.json`, and
+  the phase-20 manifests-version baseline (`test-fixture/baselines/phase-XX/manifests-version.txt`).
+- CHANGELOG.md entry written for the new version with one block per phase.
+- Off-cadence registration if applicable — `tests/semver-compare.test.cjs` adds
+  `OFF_CADENCE_VERSIONS.add('<version>')` for `.5`/`.6`/`.7` insertion-style versions.
+- Regression baseline at `test-fixture/baselines/phase-XX/` exists and the
+  `tests/phase-XX-baseline.test.cjs` suite passes (version-agnostic — reads
+  `package.json#version`).
+- NOTICE attribution updated if any third-party content was adopted in this cycle.
+- Closeout plan's scoped ROADMAP flip touches only this cycle's checkboxes (precedent:
+  Phase 28 closeout flipped exactly 7 inline + 1 overview entry).
+
+## Cross-references
+
+- `./STATE-TEMPLATE.md` — STATE.md schema; closeout updates the `<position>` block's
+  `last_checkpoint` field.
+- `../skills/turn-closeout/SKILL.md` — consumer at the turn boundary (within a stage).
+- `../skills/new-cycle/SKILL.md` — consumer at cycle ingress.
+- `../skills/complete-cycle/SKILL.md` — consumer at cycle egress.
+- `../skills/quality-gate/SKILL.md` — Stage 4.5 gate that gates the plan-level "verify
+  command runs with exit 0" criterion when project tooling exists.

package/skills/next/SKILL.md

@@ -2,6 +2,7 @@
 name: gdd-next
 description: "Routes to the next pipeline stage based on current STATE.md position"
 tools: Read, Write, mcp__gdd_status, mcp__gdd_phase_current, mcp__gdd_plans_list
+disable-model-invocation: true
 ---
 
 # Get Design Done — Next

package/skills/note/SKILL.md

@@ -3,6 +3,7 @@ name: gdd-note
 description: "Zero-friction idea capture during any stage. Appends to .design/NOTES.md. Subcommands: add, list, promote."
 argument-hint: "<add|list|promote> [text|line-number]"
 tools: Read, Write
+disable-model-invocation: true
 ---
 
 # /gdd:note

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 `./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 `./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 `./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 `./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 `./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 `./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-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.