@hegemonart/get-design-done 1.26.0 → 1.27.0

package/scripts/lib/session-runner/index.ts

@@ -86,6 +86,221 @@ const RATE_GUARD_PROVIDER = 'anthropic';
 /** Default retries (first attempt + 1 retry). */
 const DEFAULT_MAX_RETRIES = 2;
 
+// ── Plan 27-06 — Peer-CLI delegation primitives ─────────────────────────────
+//
+// Lazy registry loader: the registry is a .cjs module under scripts/lib/peer-cli
+// landed by Plan 27-05. Tests inject a stub via SessionRunnerOptions.registryOverride;
+// real callers fall through to the live module. Resolution is anchored to the
+// repo root via the same `_nodeRequire` we use for jittered-backoff/rate-guard
+// so the runner survives test sandboxes that chdir.
+//
+// We swallow load errors and return null → caller treats as "no peer available"
+// → falls back to local SDK. This keeps the session-runner functional even on
+// fresh checkouts where Plan 27-05 hasn't landed yet.
+
+interface PeerRegistry {
+  dispatch: (
+    role: string,
+    tier: string | null,
+    text: string,
+    opts: { cwd?: string; [k: string]: unknown },
+  ) => Promise<{ result: unknown; peer: string; protocol: 'acp' | 'asp' } | null>;
+}
+
+let _peerRegistryCache: PeerRegistry | null | undefined;
+
+/**
+ * Resolve the peer-CLI registry. Memoized; returns null if the module
+ * isn't installable (missing file, require throws, shape mismatch).
+ * Tests bypass this entirely by passing `registryOverride` on the
+ * SessionRunnerOptions.
+ */
+function loadPeerRegistry(): PeerRegistry | null {
+  if (_peerRegistryCache !== undefined) return _peerRegistryCache;
+  try {
+    const mod = _nodeRequire(
+      _resolve(_REPO_ROOT, 'scripts/lib/peer-cli/registry.cjs'),
+    );
+    if (mod && typeof mod === 'object' && typeof (mod as { dispatch?: unknown }).dispatch === 'function') {
+      _peerRegistryCache = mod as PeerRegistry;
+      return _peerRegistryCache;
+    }
+  } catch {
+    // registry.cjs missing or threw on require — treat as "no peers available"
+  }
+  _peerRegistryCache = null;
+  return _peerRegistryCache;
+}
+
+/**
+ * Visible-for-testing reset of the peer-registry cache. The session-runner
+ * caches the registry module after first resolve so production runs don't
+ * re-require it per call; tests that swap process state (chdir into a
+ * sandbox, write a different registry.cjs, etc.) can call this between
+ * tests to force reload. Production code never calls this.
+ */
+export function _resetPeerRegistryCache(): void {
+  _peerRegistryCache = undefined;
+}
+
+/**
+ * Parse a `delegate_to` value into (peer, role). Returns null when the
+ * value is missing, the literal "none" opt-out, or doesn't match the
+ * `<peer>-<role>` shape. The session-runner uses this to figure out
+ * which role to ask the registry for.
+ *
+ * Note: validate-frontmatter.ts already enforces the value shape at lint
+ * time — by the time a `delegate_to` reaches session-runner it's been
+ * validated against the capability matrix. We re-parse here defensively
+ * because the runner is consumed by tests that may pass arbitrary
+ * strings, and the cost of an extra split is trivial.
+ */
+function parseDelegateTo(value: string | undefined): { peer: string; role: string } | null {
+  if (typeof value !== 'string' || value.length === 0) return null;
+  if (value === 'none') return null;
+  const dashIdx = value.indexOf('-');
+  if (dashIdx <= 0 || dashIdx >= value.length - 1) return null;
+  return {
+    peer: value.slice(0, dashIdx),
+    role: value.slice(dashIdx + 1),
+  };
+}
+
+/**
+ * Try to dispatch a session via peer-CLI before falling back to the
+ * Anthropic SDK. Returns either a fully-built SessionResult on peer
+ * success, or null when the caller should continue to the local path.
+ *
+ * Per CONTEXT D-07 (transparent fallback): every failure path inside
+ * this helper returns null — peer-absent, registry-load-failure,
+ * adapter-error, dispatch-throw, anything. The local SDK path then
+ * runs as if the delegation never happened. Failure is observable
+ * only as a placeholder log call (and, once Plan 27-08 wires real
+ * events, as a `peer_call_failed` chain entry).
+ */
+async function tryDelegate(args: {
+  opts: SessionRunnerOptions;
+  sanitizedPrompt: string;
+  transcriptPath: string;
+  sessionId: string;
+  sanitizer: { sanitized: string; applied: readonly string[]; removedSections: readonly string[] };
+}): Promise<SessionResult | null> {
+  const { opts, sanitizedPrompt, transcriptPath, sanitizer } = args;
+  const parsed = parseDelegateTo(opts.delegateTo);
+  if (parsed === null) return null; // not configured / explicit opt-out
+
+  const role = typeof opts.delegateRole === 'string' && opts.delegateRole.length > 0
+    ? opts.delegateRole
+    : parsed.role;
+  const tier = opts.delegateTier === undefined ? null : opts.delegateTier;
+
+  const dispatcher: PeerRegistry['dispatch'] | null = (() => {
+    if (typeof opts.registryOverride === 'function') return opts.registryOverride;
+    const reg = loadPeerRegistry();
+    return reg !== null ? reg.dispatch : null;
+  })();
+  if (dispatcher === null) {
+    // No registry available at all — fall through to local. Phase 22
+    // event emission (Plan 27-08) hooks here as `peer_call_failed`
+    // with reason="registry_missing". For now, a placeholder stderr
+    // breadcrumb so operators can grep for delegation drops without
+    // CI-failing on stdout pollution.
+    _logPeerCallFailed({ peer: parsed.peer, role, errorClass: 'registry_missing' });
+    return null;
+  }
+
+  let dispatchResult: { result: unknown; peer: string; protocol: 'acp' | 'asp' } | null = null;
+  try {
+    dispatchResult = await dispatcher(role, tier, sanitizedPrompt, { cwd: process.cwd() });
+  } catch (err) {
+    _logPeerCallFailed({
+      peer: parsed.peer,
+      role,
+      errorClass: 'dispatch_threw',
+      message: err instanceof Error ? err.message : String(err),
+    });
+    return null; // transparent fallback
+  }
+
+  if (dispatchResult === null) {
+    // Registry returned null — peer absent, capability mismatch, or
+    // adapter-side error. Per D-07 we fall back silently.
+    _logPeerCallFailed({ peer: parsed.peer, role, errorClass: 'registry_returned_null' });
+    return null;
+  }
+
+  // Peer succeeded. Build a SessionResult that mirrors the local path's
+  // shape so downstream consumers (stage-handlers, transcript readers,
+  // tests) treat both paths uniformly. We do NOT write a transcript file
+  // for delegated calls in v1.27.0 — the peer broker (Plan 27-03) keeps
+  // its own logs and Plan 27-08 wires the events that observers need.
+  // The transcript_path field still points at the would-be path so any
+  // consumer that probes it sees a stable string (existsSync will be
+  // false, which is correct: the file isn't ours to write).
+  const finalText = _coerceFinalText(dispatchResult.result);
+  return {
+    status: 'completed',
+    transcript_path: transcriptPath,
+    turns: 1,
+    usage: { input_tokens: 0, output_tokens: 0, usd_cost: 0 },
+    ...(finalText !== undefined ? { final_text: finalText } : {}),
+    tool_calls: [],
+    sanitizer: {
+      applied: [...sanitizer.applied],
+      removedSections: [...sanitizer.removedSections],
+    },
+  };
+}
+
+/** Best-effort extract a final text string from the adapter's free-form result. */
+function _coerceFinalText(result: unknown): string | undefined {
+  if (typeof result === 'string' && result.length > 0) return result;
+  if (result !== null && typeof result === 'object') {
+    const obj = result as Record<string, unknown>;
+    if (typeof obj['final_text'] === 'string' && obj['final_text'].length > 0) {
+      return obj['final_text'] as string;
+    }
+    if (typeof obj['text'] === 'string' && obj['text'].length > 0) {
+      return obj['text'] as string;
+    }
+    if (typeof obj['output'] === 'string' && obj['output'].length > 0) {
+      return obj['output'] as string;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Placeholder for Plan 27-08's `peer_call_failed` event. Until 27-08
+ * wires real `appendEvent('peer_call_failed', ...)`, we write a single
+ * stderr line so operators can grep for silent delegation drops. We
+ * deliberately don't go through `appendEvent` here because the Phase 22
+ * event-stream hasn't gained a `peer_call_failed` type yet (that's
+ * 27-08's job) and pushing an unknown event type today would create a
+ * migration mess for the reflector.
+ */
+function _logPeerCallFailed(args: {
+  peer: string;
+  role: string;
+  errorClass: string;
+  message?: string;
+}): void {
+  // One-line, machine-greppable. Quiet by default in test runs (NODE_ENV)
+  // so the test output stays clean. Operators set GDD_PEER_DEBUG=1 to see
+  // the breadcrumb in production logs.
+  if (process.env['GDD_PEER_DEBUG'] !== '1') return;
+  const payload = JSON.stringify({
+    type: 'peer_call_failed',
+    peer_id: args.peer,
+    role: args.role,
+    error_class: args.errorClass,
+    ...(args.message !== undefined ? { message: args.message } : {}),
+    ts: new Date().toISOString(),
+  });
+  // eslint-disable-next-line no-console
+  console.error(`[peer-cli] ${payload}`);
+}
+
 /** Baseline retry backoff parameters (matches jittered-backoff defaults for
  *  the SDK-retry case; 1s base → 30s cap). */
 const RETRY_BACKOFF = { baseMs: 1000, maxMs: 30_000 } as const;

package/scripts/lib/session-runner/types.ts

@@ -118,6 +118,66 @@ export interface SessionRunnerOptions {
     applied: readonly string[];
     removedSections: readonly string[];
   };
+
+  /**
+   * Phase 27 (Plan 27-06) — peer-CLI delegation.
+   *
+   * Optional. When set to `<peer>-<role>` (e.g. `gemini-research`), the
+   * session-runner attempts to dispatch the call to the named peer-CLI
+   * via `scripts/lib/peer-cli/registry.cjs#dispatch` BEFORE invoking the
+   * local Anthropic SDK. The peer's response, when successful, becomes
+   * the SessionResult — no SDK call is made.
+   *
+   * Fallback (CONTEXT D-07): if the registry returns `null` (peer
+   * absent / opt-out / adapter error / dispatch error) OR throws, the
+   * session-runner silently retries with the local Anthropic SDK. The
+   * caller never sees the peer failure — failure is a measurement
+   * signal, not a cycle-breaker.
+   *
+   * Special values:
+   *   - `none`      → explicit opt-out; never delegate. Same as omitting the field.
+   *   - undefined   → default behavior; never delegate.
+   *
+   * The session-runner never reads agent frontmatter on its own. Callers
+   * (pipeline-runner, explore, discuss, etc.) are responsible for
+   * resolving the agent's `delegate_to:` frontmatter and passing it
+   * through this option.
+   */
+  delegateTo?: string;
+
+  /**
+   * Phase 27 (Plan 27-06) — role hint for peer-CLI dispatch.
+   *
+   * Used only when `delegateTo` is set. Defaults to the role parsed out
+   * of `delegateTo` (e.g. `delegateTo: "gemini-research"` → role
+   * `"research"`). Provide explicitly when the caller wants to override
+   * the parsed value (rare).
+   */
+  delegateRole?: string;
+
+  /**
+   * Phase 27 (Plan 27-06) — tier hint for peer-CLI dispatch.
+   *
+   * Currently advisory; the registry's capability matrix doesn't gate
+   * on tier. Used by adapters for telemetry and by Plan 27-08 events.
+   * Defaults to null (let the adapter pick).
+   */
+  delegateTier?: string | null;
+
+  /**
+   * Phase 27 (Plan 27-06) — registry override for tests.
+   *
+   * Default loads `scripts/lib/peer-cli/registry.cjs` lazily on first
+   * delegation attempt. Tests inject a stub `dispatch()` to avoid
+   * spawning real peers. The override mirrors the registry's `dispatch`
+   * signature: `(role, tier, text, opts) => Promise<{result,peer,protocol} | null>`.
+   */
+  registryOverride?: (
+    role: string,
+    tier: string | null,
+    text: string,
+    opts: { cwd?: string; [k: string]: unknown },
+  ) => Promise<{ result: unknown; peer: string; protocol: 'acp' | 'asp' } | null>;
 }
 
 /**

package/scripts/validate-frontmatter.ts

@@ -14,10 +14,100 @@
  */
 
 import { existsSync, statSync, readdirSync } from 'node:fs';
-import { join, basename } from 'node:path';
+import { join, basename, dirname, resolve } from 'node:path';
+import { createRequire } from 'node:module';
 
 import { readFrontmatter } from '../tests/helpers.ts';
 
+// ── delegate_to capability matrix loader (Plan 27-06) ──────────────────────
+//
+// The `delegate_to: <peer>-<role> | none` field is validated against the
+// capability matrix exported by scripts/lib/peer-cli/registry.cjs (Plan
+// 27-05). Loading the .cjs from a .ts module under the strip-types loader
+// requires createRequire — and we anchor it to the repo root so the
+// validator survives being invoked from any cwd.
+//
+// Loading is lazy + defensive: if the registry module isn't on disk yet
+// (e.g. during a fresh clone before Plan 27-05 lands, or in a partial
+// checkout), we fall back to an inline literal mirror of the locked D-05
+// capability matrix so this validator never crashes a CI run on a
+// missing dependency. The literal mirror MUST stay in sync with
+// registry.cjs's CAPABILITY_MATRIX — tests assert equivalence.
+function _findRepoRootFromHere(): string {
+  // process.argv[1] is the validator script path under strip-types; walk
+  // up from its directory looking for package.json. Fall back to cwd.
+  const start: string = (() => {
+    const argv1 = process.argv[1];
+    if (typeof argv1 === 'string' && argv1.length > 0) return dirname(argv1);
+    return process.cwd();
+  })();
+  let dir = resolve(start);
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(dir, 'package.json'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return process.cwd();
+}
+
+/** Locked D-05 capability matrix mirror — fallback when registry.cjs unloadable. */
+const _DELEGATE_MATRIX_FALLBACK: Readonly<Record<string, readonly string[]>> = Object.freeze({
+  codex: Object.freeze(['execute']),
+  copilot: Object.freeze(['review', 'research']),
+  cursor: Object.freeze(['debug', 'plan']),
+  gemini: Object.freeze(['research', 'exploration']),
+  qwen: Object.freeze(['write']),
+});
+
+let _delegateMatrixCache: Readonly<Record<string, readonly string[]>> | null = null;
+
+/**
+ * Return the live capability matrix as a `peer -> roles[]` map. Cached
+ * after first call. Uses registry.cjs as the source of truth; falls back
+ * to the inline mirror only if the registry module fails to load.
+ */
+export function loadDelegateMatrix(): Readonly<Record<string, readonly string[]>> {
+  if (_delegateMatrixCache !== null) return _delegateMatrixCache;
+  try {
+    const root = _findRepoRootFromHere();
+    const req = createRequire(join(root, 'package.json'));
+    const reg = req(resolve(root, 'scripts/lib/peer-cli/registry.cjs')) as {
+      CAPABILITY_MATRIX?: Record<string, { roles: readonly string[] }>;
+    };
+    if (reg && typeof reg.CAPABILITY_MATRIX === 'object' && reg.CAPABILITY_MATRIX !== null) {
+      const out: Record<string, readonly string[]> = {};
+      for (const [peer, cap] of Object.entries(reg.CAPABILITY_MATRIX)) {
+        if (cap && Array.isArray(cap.roles)) {
+          out[peer] = Object.freeze([...cap.roles]);
+        }
+      }
+      _delegateMatrixCache = Object.freeze(out);
+      return _delegateMatrixCache;
+    }
+  } catch {
+    // fall through to fallback
+  }
+  _delegateMatrixCache = _DELEGATE_MATRIX_FALLBACK;
+  return _delegateMatrixCache;
+}
+
+/**
+ * Build the flat set of valid `<peer>-<role>` IDs from the capability
+ * matrix. e.g. `gemini-research`, `codex-execute`, etc. The literal
+ * string `"none"` is the explicit opt-out and is accepted separately.
+ */
+export function validDelegateIds(): readonly string[] {
+  const matrix = loadDelegateMatrix();
+  const out: string[] = [];
+  for (const [peer, roles] of Object.entries(matrix)) {
+    for (const role of roles) {
+      out.push(`${peer}-${role}`);
+    }
+  }
+  return Object.freeze(out.sort());
+}
+
 // Importing a type from generated.d.ts satisfies the Plan 20-00 rule that
 // every Tier-1 TS file participates in the codegen graph. We don't use
 // IntelSchema at runtime; the re-export keeps it visible for static checks.
@@ -42,6 +132,22 @@ export interface AgentFrontmatter {
   'default-tier'?: 'haiku' | 'sonnet' | 'opus';
   'reasoning-class'?: 'high' | 'medium' | 'low';
   'size_budget'?: 'S' | 'M' | 'L' | 'XL';
+  /**
+   * Phase 27 (Plan 27-06) — peer-CLI delegation hint.
+   *
+   * Optional. Default unset = use local Anthropic call. Setting
+   * `delegate_to: gemini-research` tells session-runner "try delegate
+   * first, fall back to local on peer-absent / peer-error". Setting
+   * `delegate_to: none` explicitly opts out (e.g. security-sensitive
+   * agents). See agents/README.md "Peer-CLI delegation (delegate_to)"
+   * for the additive-superset rationale (CONTEXT D-06).
+   *
+   * Valid values are `<peer>-<role>` IDs that the peer-CLI registry
+   * capability matrix knows (e.g. `gemini-research`, `codex-execute`,
+   * `cursor-debug`, `cursor-plan`, `copilot-review`, `copilot-research`,
+   * `qwen-write`) plus the literal string `"none"`.
+   */
+  'delegate_to'?: string;
 }
 
 const REQUIRED_FIELDS: readonly (keyof AgentFrontmatter)[] = [
@@ -169,6 +275,48 @@ export function validateReasoningClass(
   return violations;
 }
 
+/**
+ * Validate the optional Phase 27 (Plan 27-06) `delegate_to` field. Returns
+ * an array of violation messages; empty means the agent passes.
+ *
+ * Rules (CONTEXT D-06):
+ *   1. `delegate_to` is OPTIONAL. Absence = use local Anthropic call.
+ *   2. If present, value MUST be a string.
+ *   3. The literal value `"none"` is accepted as the explicit opt-out.
+ *   4. Any other value MUST match a `<peer>-<role>` ID drawn from the
+ *      peer-CLI capability matrix (Plan 27-05's registry.cjs is the
+ *      source of truth; loadDelegateMatrix() resolves it lazily with
+ *      a literal fallback if the registry is unloadable).
+ *
+ * The 26 v1.26 baseline agents do not carry this field; this helper
+ * returns `[]` for them. The validator runs trivially clean on them.
+ */
+export function validateDelegateTo(
+  fm: Record<string, unknown>,
+  agentName: string,
+): string[] {
+  const violations: string[] = [];
+  const has = 'delegate_to' in fm && !isMissing(fm['delegate_to']);
+  if (!has) return violations;
+
+  const raw = fm['delegate_to'];
+  if (typeof raw !== 'string') {
+    violations.push(
+      `delegate_to: invalid value "${String(raw)}" for agent "${agentName}" — must be a string ("none" or "<peer>-<role>" e.g. "gemini-research")`,
+    );
+    return violations;
+  }
+  if (raw === 'none') return violations; // explicit opt-out
+
+  const valid = validDelegateIds();
+  if (!valid.includes(raw)) {
+    violations.push(
+      `delegate_to: invalid value "${raw}" for agent "${agentName}" — must be "none" or one of: ${valid.join(', ')} (peer-CLI capability matrix; see scripts/lib/peer-cli/registry.cjs)`,
+    );
+  }
+  return violations;
+}
+
 function walkMd(dir: string): string[] {
   const out: string[] = [];
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
@@ -234,6 +382,16 @@ function main(): void {
       console.log(`${f}:${msg}`);
       violations++;
     }
+
+    // Plan 27-06 — peer-CLI delegate_to validation (additive optional field).
+    const delegateViolations = validateDelegateTo(
+      fm as Record<string, unknown>,
+      agentName,
+    );
+    for (const msg of delegateViolations) {
+      console.log(`${f}:${msg}`);
+      violations++;
+    }
   }
 
   console.log(`summary: ${files.length} file(s) checked, ${violations} violation(s)`);

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

@@ -0,0 +1,170 @@
+---
+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."
+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 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.
+
+## 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.
+
+## Procedure
+
+### Step 1 — Verification ladder (no edits yet)
+
+Before touching any code, confirm the peer actually speaks the protocol it claims.
+
+#### 1a. Binary on PATH
+
+`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.
+
+### 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).
+
+Use the `Write` tool to create `scripts/lib/peer-cli/adapters/<new-peer-id>.cjs`:
+
+```js
+'use strict';
+
+const { createAcpClient } = require('../acp-client.cjs');
+// OR for ASP peers: const { createAspClient } = require('../asp-client.cjs');
+
+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>',
+};
+
+function claims(role) { return ROLES_CLAIMED.includes(role); }
+
+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>' };
+```
+
+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
+
+```
+## 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:
+- 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.
+```
+
+## 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.
+
+## Record
+
+After execution, 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}
+```