@hegemonart/get-design-done 1.26.0 → 1.27.1

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Get Design Done — 5-stage agent-orchestrated design pipeline with 9 connections, handoff-first workflow, bidirectional Figma write-back, 22+ specialized agents, queryable knowledge layer (intel store, dependency analysis, learnings extraction), and a self-improvement loop (reflector, frontmatter + budget feedback, global-skills layer). v1.20.0 ships the SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream, and resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) for rate-limit + 429 + context-overflow recovery. Full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.26.0"
+    "version": "1.27.1"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
       "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), Claude Design handoff, bidirectional Figma write-back, and a queryable intel store (.design/intel/) for dependency and learnings queries. Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation. Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
-      "version": "1.26.0",
+      "version": "1.27.1",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.26.0",
+  "version": "1.27.1",
   "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
   "author": {
     "name": "hegemonart",

package/CHANGELOG.md

@@ -4,6 +4,80 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.27.1] — 2026-04-30
+
+Phase 27 wiring patch — closes the production-integration gaps left by v1.27.0's "structural ship". v1.27.0 landed all peer-CLI library code + tests + docs but the helpers were exported without callers, so `delegate_to:` on agent frontmatter was validated and then ignored at runtime. v1.27.1 wires the four integration points so delegation actually fires for users who set `delegate_to:` AND allowlist the peer.
+
+### Fixed
+
+- **`session-runner.run()` now invokes `tryDelegate` (Plan 27-06 wiring)** — when `opts.delegateTo` is set to a `<peer>-<role>` value AND the registry can route AND the peer is in `.design/config.json#peer_cli.enabled_peers`, the prompt runs on the peer-CLI and `run()` returns the peer result. On peer-absent / peer-error / null result, falls through transparently to the local Anthropic SDK loop (D-07). Previously the `tryDelegate` helper existed in the file but `run()` never called it.
+
+- **Real `appendEvent('peer_call_started|complete|failed', ...)` emission (Plan 27-08 wiring)** — replaced the stderr-only placeholder in session-runner with three real event-emission calls. Events flow through Phase 22's `appendEvent()` API using the constants registered in v1.27.0, tagged with `runtime_role: 'peer'` and `peer_id`. Reflector cross-runtime cost-arbitrage (Plan 26-06) now sees peer telemetry. `GDD_PEER_DEBUG=1` continues to mirror the failed events to stderr for live tailing.
+
+- **`install.cjs` interactive peer-detection nudge (Plan 27-11 wiring)** — after a successful (non-uninstall, non-dry-run) install in a TTY, scans `peerBinary` paths via `detectInstalledPeers()`. If 1+ peer detected, prompts via `@clack/prompts` with `confirm()` (default: NO). On yes, writes `.design/config.json#peer_cli.enabled_peers`. New `--no-peer-prompt` flag suppresses the prompt entirely (CI-friendly). Silent skip when zero peers detected. Default-NO preserves the opt-in trust contract (D-11).
+
+### Out of scope (known, deferred)
+
+- **Bandit `pullWithDelegate` caller (Plan 27-07 wiring)** — `pullWithDelegate` and `updateWithDelegate` ship in the bandit module surface (v1.27.0) but no production caller invokes them yet. Wiring requires `gdd-router` SKILL.md change (procedural, not code) which is out of scope for a wiring patch. Phase 28+ territory once the integration shape is decided. The `delegate?` dimension stays exported as a library extension for ad-hoc use.
+
+### Tests
+
+- Existing 23 peer-CLI session-runner / events / end-to-end tests pass after wiring.
+- Existing 33 install.cjs + peer-detect tests pass after the nudge addition.
+- Full Phase 27 surface tests stay green; no new test files (this is a wiring patch, not a new surface).
+
+---
+
+## [1.27.0] — 2026-04-30
+
+Phase 27 Peer-CLI Delegation Layer milestone — closes the **outbound** half of multi-runtime. Phase 24 made gdd installable on 14 runtimes; Phase 21 made the same pipeline run on each; Phase 26 made tier→model resolve correctly per runtime. v1.27.0 adds the missing piece: gdd agents OPTIONALLY delegate to local peer CLIs (Codex via App Server Protocol; Gemini/Cursor/Copilot/Qwen via Agent Client Protocol) when measurably cheaper or higher-quality for the role. Falls back to in-process Anthropic SDK when peer is unavailable. Honors Phase 26 tier maps + Phase 22 event chain + Phase 23.5 bandit posterior — `delegate?` becomes another arm in `(agent_type × tier × delegate)` Thompson sampling, no new ML.
+
+### Added
+
+- **ACP client** — `scripts/lib/peer-cli/acp-client.cjs` (Plan 27-01, commit `4a2d201`). Line-delimited JSON-RPC over stdio for Gemini/Cursor/Copilot/Qwen. `initialize` handshake, `prompt` method, notification stream, 16 MiB line-buffer overflow guard. 7 tests pass.
+- **ASP client** — `scripts/lib/peer-cli/asp-client.cjs` (Plan 27-02, commit `06fcdf6`). Codex App Server Protocol. `threadStart` + `threadResume` + `turn` lifecycle. `service_name = "gdd_peer_delegation"`. Error path resolves with `{status:"error"}` rather than throwing. 12 tests pass.
+- **spawn-cmd Windows fix + broker-lifecycle** — `scripts/lib/peer-cli/spawn-cmd.cjs` + `broker-lifecycle.cjs` (Plan 27-03, commit `f9228cf`). `.cmd` EINVAL workaround per cc-multi-cli `transport-decisions.md` (D-04). Long-lived broker per `(peer, workspace)` over Unix socket on POSIX, named pipe on Windows (D-03). 18 tests pass.
+- **Per-peer adapters** — `scripts/lib/peer-cli/adapters/{codex,gemini,cursor,copilot,qwen}.cjs` (Plan 27-04, commit `d58ab4f`). 5 thin wrappers with role→prompt-prefix maps + slash-command translation. 39 tests pass.
+- **Registry + capability matrix** — `scripts/lib/peer-cli/registry.cjs` + `reference/peer-cli-capabilities.md` (Plan 27-05, commit `6ef4d27`). `findPeerFor(role, tier)` central dispatch, per-peer health probe, deterministic alphabetical tie-break. Per-peer capability matrix (D-05): codex→execute, gemini→research/exploration, cursor→debug/plan, copilot→review/research, qwen→write. 32 tests pass.
+- **Agent `delegate_to:` frontmatter + session-runner peer-first dispatch** — `scripts/validate-frontmatter.ts` + `scripts/lib/session-runner/index.ts` (Plan 27-06, commit `4644d8e`). Optional additive frontmatter field; values are `<peer>-<role>` per capability matrix or `none` (explicit opt-out). Session-runner tries delegate first; transparent fallback on peer-absent OR peer-error per D-07. 8 tests pass.
+- **Bandit posterior `delegate?` context dimension** — `scripts/lib/bandit-router.cjs` (Plan 27-07, commit `824bcf5`). Arm space expands from `(agent_type, touches_size_bin)` to `(agent_type, touches_size_bin, delegate)` where `delegate ∈ {none, gemini, codex, cursor, copilot, qwen}`. Bootstrap: existing priors carry forward as the `none` arm; 5 delegation arms start neutral. Reward signal unchanged (two-stage lexicographic). 12 tests pass.
+- **Event chain `runtime_role` + `peer_id` + `peer_call_*` event types** — `scripts/lib/event-stream/types.ts` + `index.ts` + `scripts/lib/budget-enforcer.cjs` (Plan 27-08, commit `fd561ed`). Additive Phase 22 extension — every event optionally tags `runtime_role: "host" | "peer"` (defaults `"host"` for back-compat) and `peer_id`. 3 new event types: `peer_call_started`, `peer_call_complete`, `peer_call_failed`. costs.jsonl cost rows tag the same fields so Phase 26's reflector cost-arbitrage extends naturally. 8 tests pass.
+- **`/gdd:peers` capability matrix command** — `skills/peers/SKILL.md` (Plan 27-09, commit `51ae40e`). Single-command discoverability — markdown table with peer × installed? × allowlisted? × claimed roles × posterior delta vs local.
+- **`peer-cli-customize` + `peer-cli-add` skills** — `skills/peer-cli-customize/SKILL.md` + `skills/peer-cli-add/SKILL.md` (Plan 27-10, commit `4f07daf`). Customize rewires per-agent `delegate_to:` mappings; add walks the verification ladder for adding a brand-new peer (Apache 2.0 attribution comment in each — see NOTICE).
+- **`peerBinary?` field on runtimes + detection helpers** — `scripts/lib/install/runtimes.cjs` (Plan 27-11, commit `0e2fb92`). 5 peer-capable runtimes (codex, gemini, cursor, copilot, qwen) gain platform-aware `peerBinary` paths. `listPeerCapableRuntimes()` and `detectInstalledPeers()` exported for `/gdd:peers` and the install-time nudge. 8 tests pass.
+
+### Tests
+
+- 11 new test files (148 total new test cases) covering protocol clients, registry, adapters, frontmatter delegation, bandit dimension, event tagging, peer detection, end-to-end peer-call flow, and the phase-27 baseline.
+- Phase 24/25/26 baseline tests refactored to be **version-agnostic** (D-12) — they read `package.json#version` dynamically and assert all 4 manifests align. No more literal-version hardcodes that break every closeout (Phase 26 lesson applied).
+
+### Decisions
+
+D-01 through D-14 — see `.planning/phases/27-peer-cli-delegation/CONTEXT.md` for the full decision register. Highlights:
+
+- **D-01 / D-02** — ACP for 4 peers, ASP for Codex. Port shapes from cc-multi-cli (Apache 2.0) with `NOTICE` attribution; do NOT vendor their hub (Claude-as-host assumption is incompatible with our any-runtime-as-host model).
+- **D-03 / D-04** — Long-lived broker per `(peer, workspace)`. Windows `.cmd` EINVAL workaround documented in `spawn-cmd.cjs` so future maintainers don't "clean it up".
+- **D-05** — Per-peer capability matrix is the dispatch source-of-truth. Roles a peer doesn't claim → registry refuses dispatch.
+- **D-06 / D-07** — `delegate_to:` is additive optional; `none` is explicit opt-out; fallback on peer-absent OR peer-error is transparent to the calling skill.
+- **D-08** — Bandit posterior gains `delegate?` dimension. 6× context expansion (~78 → ~468 contexts). Bootstrap discipline: existing priors carry forward as `delegate=none`; 5 delegation arms start neutral.
+- **D-09** — Event chain extension is additive; `runtime_role` defaults `"host"` for back-compat; only the new `peer_call_*` events MUST carry `"peer"`.
+- **D-10 / D-11** — `/gdd:peers` is single-command discoverability; install-time nudge is OPT-IN (default empty `enabled_peers`); `--no-peer-prompt` flag suppresses for CI.
+- **D-12** — Version-agnostic baseline tests (Phase 26 closeout lesson). `phase-NN-baseline.test.cjs` no longer hardcodes literal versions.
+- **D-14** — `NOTICE` Apache 2.0 attribution for cc-multi-cli ships with v1.27.0 (mandatory per Apache 2.0 §4 for derivative-shape code).
+
+### Documentation
+
+- `docs/PEER-DELEGATION.md` (new) — ops guide covering when delegation fires, how to disable per-peer, fallback diagnostics, broker lifecycle troubleshooting, and Windows `.cmd` quirks.
+- `reference/peer-protocols.md` (new) — ACP + ASP protocol cheat sheet for protocol authors and skill writers.
+- `agents/README.md` — new `Peer-CLI delegation (delegate_to)` section documenting the field, valid values, opt-in gating, telemetry hookup, and cross-references.
+- `NOTICE` (new) — Apache 2.0 attribution for cc-multi-cli's `acp-client.mjs`, `asp-client.mjs`, `transport-decisions.md`, and `customize` / `multi-cli-anything` skill patterns.
+
+### Known gaps
+
+- Plan 27-11's interactive post-install peer-detection prompt (the `npx get-design-done` UX nudge: "I see you have Codex + Gemini installed — wire them as peers? [y/N]") is documented in CONTEXT.md D-11 but not yet wired into `scripts/install.cjs`. The detection helper (`detectInstalledPeers()`) IS shipped — what's missing is the `@clack/prompts` interactive integration. Users can manually populate `.design/config.json#peer_cli.enabled_peers` for now; `/gdd:peers` shows the current state. Tracked for Phase 28 hygiene or a 1.27.x patch if demand warrants.
+
+---
+
 ## [1.26.0] — 2026-04-29
 
 Phase 26 Headless Model Resolver milestone — closes the model-selection gap left by Phase 24's distribution headlessness. `default-tier: opus|sonnet|haiku` frontmatter now actually does something on the 13 non-Claude runtimes the multi-runtime installer ships to. Three layers gain runtime-awareness without a breaking change: the agent frontmatter (additive `reasoning-class` alias), the router output (additive `resolved_models` field), and the cost telemetry (per-runtime price tables + runtime-tagged events.jsonl rows). The phase ships **structure** — adapter layer, resolvers, schemas, contracts — not editorial picks for which model each runtime treats as opus/sonnet/haiku; those come from runtime adapter authors with provenance citations baked into `reference/runtime-models.md`.

package/README.md

@@ -87,20 +87,22 @@ Use it when you care that tokens match, contrast passes WCAG, motion feels cohes
 
 You do not need to be a designer to benefit from it. The pipeline carries the design discipline into the agent workflow: it extracts context, asks only for missing decisions, grounds the work in references, and catches the issues people usually find too late.
 
-### v1.26.0 Highlights — Headless Model Resolver
+### v1.27.0 Highlights — Peer-CLI Delegation Layer
 
-Closes the model-selection gap left by v1.24.0's distribution headlessness: `default-tier: opus|sonnet|haiku` frontmatter now actually does something on the 13 non-Claude runtimes the multi-runtime installer ships to. Three layers gain runtime-awareness without a breaking change — agent frontmatter, router output, and cost telemetry all keep their existing fields and gain new additive ones.
+Closes the **outbound** half of multi-runtime: gdd agents now OPTIONALLY delegate to local peer CLIs (Codex via App Server Protocol; Gemini/Cursor/Copilot/Qwen via Agent Client Protocol) when measurably cheaper or higher-quality for the role. Falls back to in-process Anthropic SDK when peer is unavailable. Honors v1.26.0's tier maps + v1.22.0's event chain + v1.23.5's bandit posterior — `delegate?` becomes another arm in `(agent_type × tier × delegate)` Thompson sampling.
 
-- **Per-runtime tier→model adapter** — `reference/runtime-models.md` is the single source of truth for all 14 runtimes (claude, codex, gemini, qwen, kilo, copilot, cursor, windsurf, antigravity, augment, trae, codebuddy, cline, opencode). Each row carries `tier_to_model`, `reasoning_class_to_model`, and a provenance array (source URL + retrieval timestamp + last-validated cycle). Strict pure-JS validator at `scripts/lib/install/parse-runtime-models.cjs` — no `ajv` dependency at the parser layer.
-- **`tier-resolver.cjs` + `runtime-detect.cjs`** — translates `opus|sonnet|haiku` frontmatter into the concrete model name a specific runtime understands (`gpt-5` under codex, `gemini-2.5-pro` under gemini, `claude-opus-4-7` under claude). Non-blocking fallback chain: runtime entry → claude row + warning event → null + fail event. Runtime detection reuses Phase 24's env-var lookup chain — single source of truth lives in `scripts/lib/install/runtimes.cjs`.
-- **`resolved_models` router field** — the router's JSON output now carries a per-agent map of concrete model IDs for the active runtime, alongside the legacy `model_tier_overrides` (which keeps its `opus|sonnet|haiku` enum for back-compat across all 14 runtimes). Strict superset over v1.25.0 — same back-compat discipline as Phase 25's `complexity_class` next to `path`. Installer also drops a `models.json` per runtime config-dir so runtime harnesses can read the map at session start without parsing markdown.
-- **Per-runtime price tables + cost arbitrage** — `reference/model-prices.md` becomes a router that links to per-runtime sub-tables (`reference/prices/{claude,codex,gemini,qwen,…}.md`). The shared `scripts/lib/budget-enforcer.cjs` backend reads them by runtime. events.jsonl cost rows tag `runtime`; the cost-aggregator rolls up per-runtime AND per-tier. Reflector surfaces a structured cross-runtime arbitrage proposal when one runtime's spend exceeds another's by >50% on the same `(agent, tier)`.
-- **`reasoning-class` runtime-neutral alias** — additive `reasoning-class: high|medium|low` frontmatter alias for `default-tier`. Both may coexist; equivalence is enforced (`high ↔ opus`, `medium ↔ sonnet`, `low ↔ haiku`). v1.26 ships the alias with full equivalence semantics and does **not** deprecate `default-tier` — long-term winner is data-gated by adoption signal through Phase 28.
+- **ACP + ASP protocol clients** — `scripts/lib/peer-cli/{acp-client,asp-client}.cjs` ship line-delimited JSON-RPC over stdio with 16 MiB line-buffer overflow guards. ACP serves Gemini/Cursor/Copilot/Qwen; ASP serves Codex (thread-oriented, multi-turn). Protocol shapes adapted from `greenpolo/cc-multi-cli` (Apache 2.0, see `NOTICE`). Long-lived broker per `(peer, workspace)` over Unix socket / named pipe — cold-spawn cost amortized across delegated calls in a cycle.
+- **5 per-peer adapters + central registry** — `scripts/lib/peer-cli/adapters/{codex,gemini,cursor,copilot,qwen}.cjs` thin-wrap the protocol clients with role→prompt-prefix maps and slash-command translation. Central dispatch via `registry.cjs#findPeerFor(role, tier)` consults the locked capability matrix (codex→execute; gemini→research/exploration; cursor→debug/plan; copilot→review/research; qwen→write).
+- **`delegate_to:` agent frontmatter** — additive optional field; values are `<peer>-<role>` per matrix or `none` for explicit opt-out. Session-runner tries delegate first; transparent fallback on peer-absent OR peer-error. `peer_call_failed` event logs to `events.jsonl` for reflector telemetry. v1.27.0 ships the field but no agent in the fleet uses it yet — opt-in per agent via `/gdd:run-skill peer-cli-customize`.
+- **Bandit posterior `delegate?` dimension** — Phase 23.5's `(agent_type, touches_size_bin)` arm space expands to `(agent_type, touches_size_bin, delegate)` where `delegate ∈ {none, gemini, codex, cursor, copilot, qwen}`. Existing priors carry forward as the `none` arm (no behavior change for unconfigured agents); 5 delegation arms start neutral. Reward signal unchanged (two-stage lexicographic). The bandit measures and learns which delegations actually pay off over cycles.
+- **Event chain `runtime_role` + `peer_id` tags** — additive Phase 22 extension. `events.jsonl` rows optionally tag `runtime_role: "host" | "peer"` (defaults `"host"` for back-compat) and `peer_id`. 3 new event types: `peer_call_started`, `peer_call_complete`, `peer_call_failed`. costs.jsonl threads the same fields so v1.26's cross-runtime cost-arbitrage reflector extends to host-vs-peer arbitrage naturally.
+- **`/gdd:peers` discoverability + skills for setup** — `/gdd:peers` shows a single-command capability matrix (peer × installed? × allowlisted? × claimed roles × posterior delta vs local). `peer-cli-customize` rewires per-agent `delegate_to:` mappings; `peer-cli-add` walks the verification ladder for adding a brand-new peer (model-ID `-preview`-suffix trap, Windows `.cmd` quirks, 3-file footprint). Install-time peer-detection helpers (`detectInstalledPeers()`) ship in `runtimes.cjs` ready for the interactive nudge (deferred to a 1.27.x patch).
 
-See [docs/MULTI-RUNTIME-MODELS.md](docs/MULTI-RUNTIME-MODELS.md) for the ops guide (adding a runtime, fallback chain, cost roll-up).
+See [docs/PEER-DELEGATION.md](docs/PEER-DELEGATION.md) for the ops guide (when delegation fires, fallback diagnostics, broker lifecycle, Windows quirks) and [reference/peer-protocols.md](reference/peer-protocols.md) for the ACP + ASP protocol cheat sheet.
 
 ### Previous releases
 
+- **v1.26.0** — Headless Model Resolver (per-runtime tier→model map, `resolved_models` router field, per-runtime price tables, `reasoning-class` runtime-neutral alias).
 - **v1.25.0** — Pipeline Hardening (prototype gate + STATE `<prototyping>` block, router S/M/L/XL `complexity_class`, quality-gate Stage 4.5, Stop-hook turn closeout).
 - **v1.24.0** — Multi-Runtime Installer (`@clack/prompts` interactive multi-select for all 14 runtimes, idempotent + foreign-AGENTS.md-safe, scripted CI surface preserved 1:1).
 - **v1.23.5** — No-Regret Adaptive Layer (Thompson sampling bandit + AdaNormalHedge ensemble + MMR rerank; single-user via informed-prior bootstrap, no opt-in telemetry).

package/SKILL.md

@@ -89,6 +89,9 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `skill-manifest [--refresh]` | `get-design-done:skill-manifest` | List or refresh the local skill manifest used by the router for discovery |
 | `quality-gate` | `get-design-done:quality-gate` | Phase 25 — parallel lint/type/test/visual command runner; classifies failures via quality-gate-runner agent |
 | `turn-closeout` | `get-design-done:turn-closeout` | Phase 25 — Stop-hook mirror skill; finalizes per-turn STATE blocks and emits closeout events |
+| `peers` | `get-design-done:peers` | Phase 27 — `/gdd:peers` capability matrix command; shows installed peer-CLIs (codex/gemini/cursor/copilot/qwen), allowlist status, claimed roles, posterior delta vs local |
+| `peer-cli-customize` | `get-design-done:peer-cli-customize` | Phase 27 — rewire role→peer mappings on a per-agent basis (edits frontmatter `delegate_to:` directly) |
+| `peer-cli-add` | `get-design-done:peer-cli-add` | Phase 27 — guided ladder for adding a brand-new peer (verification ladder + adapter scaffolding + capability-matrix update) |
 | `watch-authorities [--refresh] [--since <date>] [--feed <name>] [--schedule <cadence>]` | `get-design-done:gdd-watch-authorities` | Run design-authority-watcher — fetch curated feeds, diff snapshot, classify new entries → `.design/authority-report.md` (consumed by `/gdd:reflect`) |
 | `benchmark <component\|--wave N\|--list\|--refresh component>` | `get-design-done:gdd-benchmark` | Harvest + synthesize per-component design specs from 18 design systems → `reference/components/<name>.md` |
 | `benchmark <component\|--wave N\|--list\|--refresh component>` | `get-design-done:gdd-benchmark` | Harvest + synthesize per-component design specs from 18 design systems → `reference/components/<name>.md` |

package/agents/README.md

@@ -124,6 +124,35 @@ Downstream consumers (`skills/router/SKILL.md`, `hooks/budget-enforcer.ts`, `scr
 
 ---
 
+## Peer-CLI delegation (delegate_to)
+
+Phase 27 introduces an **optional** frontmatter field `delegate_to:` that lets an agent OPT IN to running on a peer CLI (Codex via ASP; Gemini/Cursor/Copilot/Qwen via ACP) instead of the in-process Anthropic SDK call.
+
+| Property | Value |
+|----------|-------|
+| Field | `delegate_to: <peer>-<role> \| none` |
+| Required | NO — optional, additive |
+| Default | absent = use local Anthropic call (existing behavior) |
+| Valid values | `gemini-research`, `gemini-exploration`, `codex-execute`, `cursor-debug`, `cursor-plan`, `copilot-review`, `copilot-research`, `qwen-write`, or `none` (explicit opt-out) |
+| Validator | `scripts/validate-frontmatter.ts` (Plan 27-06) — checks format + cross-references the capability matrix in `scripts/lib/peer-cli/registry.cjs`. Mismatched `<peer>-<role>` values that aren't in the matrix → validation error. |
+
+**Behavior at runtime:**
+- When session-runner spawns an agent with `delegate_to: gemini-research`, it tries `peer-cli/registry.dispatch('research', tier, prompt, opts)` first. On null result (peer absent OR peer error per D-07) it transparently falls back to the local Anthropic call. The skill never sees the peer failure.
+- `delegate_to: none` explicitly skips registry dispatch (security-sensitive agents).
+- Absent field = same as not setting it = local Anthropic call (unchanged behavior).
+
+**Opt-in gating:** Even with `delegate_to:` set on an agent, dispatch only fires if the peer is in `.design/config.json#peer_cli.enabled_peers` allowlist (populated by the install-time nudge in Plan 27-11; default empty). This keeps cost surprises off — users explicitly authorize each peer.
+
+**Telemetry:** Peer calls emit `peer_call_started` / `peer_call_complete` / `peer_call_failed` events in `events.jsonl`, tagged with `runtime_role: "peer"` and `peer_id` (Plan 27-08). Cost rows in `costs.jsonl` carry the same tags so reflector cross-runtime arbitrage (Phase 26) extends naturally.
+
+**Cross-references:**
+- `scripts/lib/peer-cli/registry.cjs` (Plan 27-05) — capability matrix + dispatch.
+- `scripts/lib/peer-cli/adapters/{codex,gemini,cursor,copilot,qwen}.cjs` (Plan 27-04) — per-peer thin adapters.
+- `reference/peer-cli-capabilities.md` (Plan 27-05) — full capability matrix doc.
+- `.planning/phases/27-peer-cli-delegation/CONTEXT.md` D-06, D-07, D-11 — decision lineage.
+
+---
+
 ## Required Reading Pattern
 
 When an agent must read specific files before acting, the orchestrating stage embeds a `<required_reading>` block in the prompt it passes to `Task`. The block is part of the **prompt string**, not the agent file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.26.0",
+  "version": "1.27.1",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -37,7 +37,7 @@
     "provenance": true
   },
   "scripts": {
-    "test": "node --test --experimental-strip-types \"tests/**/*.cjs\" \"tests/**/*.ts\"",
+    "test": "node --test --experimental-strip-types \"tests/**/*.test.cjs\" \"tests/**/*.test.ts\"",
     "typecheck": "tsc --noEmit",
     "codegen:schemas": "node --experimental-strip-types scripts/codegen-schema-types.ts",
     "lint:md": "npx --yes markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#.planning\" \"#.claude\" \"#test-fixture/baselines\"",

package/reference/peer-cli-capabilities.md

@@ -0,0 +1,151 @@
+# Peer-CLI Capabilities
+
+Last verified: 2026-04-29
+
+Authoritative capability matrix for the peer-CLI delegation layer (Phase 27).
+The registry at `scripts/lib/peer-cli/registry.cjs` reads this map (encoded as
+data in the `.cjs` source — this doc is the human-readable mirror) to decide
+which peer-CLI claims which agent role and which protocol to speak.
+
+If you change this matrix, you MUST also change `CAPABILITY_MATRIX` in
+`scripts/lib/peer-cli/registry.cjs` and re-run `tests/peer-cli-registry.test.cjs`.
+The two are version-locked by Phase 27 D-05.
+
+## Capability matrix
+
+Each peer claims a fixed set of agent roles. The registry refuses to dispatch
+a role to a peer that does not claim it — this prevents accidental
+mis-delegations like "let's try `design-auditor` against Qwen" that produce
+garbage output (Phase 27 CONTEXT D-05).
+
+| Peer | Protocol | Claimed roles | Slash commands (within peer CLI) |
+| --- | --- | --- | --- |
+| `codex` | ASP | `execute` | `/exec` |
+| `copilot` | ACP | `review`, `research` | `/review`, `/search` |
+| `cursor` | ACP | `debug`, `plan` | `/debug`, `/plan` |
+| `gemini` | ACP | `research`, `exploration` | `/search`, `/explore` |
+| `qwen` | ACP | `write` | `/write` |
+
+Slash-command translation lives in each per-peer adapter
+(`scripts/lib/peer-cli/adapters/<peer>.cjs`, landed by Plan 27-04). The
+registry never invokes slash commands directly — it routes the role and
+delegates prompt-prefixing + slash translation to the adapter.
+
+## Tie-breaking when two peers claim the same role
+
+`research` is claimed by both `gemini` and `copilot`. When the registry's
+`findPeerFor('research', tier)` runs, it walks peers in alphabetical order
+of peer ID — `codex` < `copilot` < `cursor` < `gemini` < `qwen` — and
+returns the first one that passes the health probe. So `copilot` wins
+`research` over `gemini` when both are installed and allowlisted.
+
+Users can override this by removing one of the two from
+`.design/config.json#peer_cli.enabled_peers` — the unlisted peer is treated
+as absent regardless of installation status (Phase 27 D-11 opt-in gating).
+
+## Opt-in gating (D-11)
+
+A peer is dispatched to ONLY when:
+
+1. The peer ID appears in `.design/config.json#peer_cli.enabled_peers`
+   (an array of allowlisted peer IDs). Default: `[]` — empty, nothing
+   dispatches.
+2. The peer's adapter module loads at `scripts/lib/peer-cli/adapters/<peer>.cjs`.
+3. The adapter's `peerBinary()` resolver returns a path that exists on disk.
+
+Failure on any of the three → registry returns `null` and the caller
+(session-runner, Plan 27-06) falls back to the local Anthropic SDK call.
+This is the **transparent-fallback** contract from Phase 27 D-07: a missing
+or broken peer must never break the cycle.
+
+## Per-peer notes
+
+### `codex` (ASP)
+
+OpenAI Codex CLI invoked as `codex app-server`. Speaks the App Server
+Protocol — thread-oriented, supports resume across calls (currently unused;
+v1.27 always starts fresh threads).
+
+- **Provenance:** runtime entry in `scripts/lib/install/runtimes.cjs` (`id: 'codex'`).
+- **Example invocation:** registry routes `(role='execute', tier='opus', text='apply this diff')`
+  through `adapters/codex.cjs`, which in turn drives `asp-client.cjs`.
+- **Known limitations:** Codex' app-server cold start is ~1-2s on macOS;
+  the broker (Plan 27-03) keeps the session warm across cycles to amortize.
+
+### `gemini` (ACP)
+
+Google Gemini CLI invoked in ACP mode. One-shot prompt per call from the
+host's perspective, but the adapter may multiplex many calls onto a single
+broker session.
+
+- **Provenance:** runtime entry in `scripts/lib/install/runtimes.cjs` (`id: 'gemini'`).
+- **Example invocation:** registry routes `(role='research', tier='sonnet', text='find prior art for X')`
+  through `adapters/gemini.cjs`.
+- **Known limitations:** rate-limit headers vary by Gemini auth tier. The
+  adapter surfaces a 429 as a peer-error → registry returns null → caller
+  falls back. No retry logic at the registry level.
+
+### `cursor` (ACP)
+
+Cursor's `cursor` CLI in ACP mode. Strong on `debug` and `plan` roles
+because Cursor's editor-side context tracking transfers well to those
+workflows.
+
+- **Provenance:** runtime entry in `scripts/lib/install/runtimes.cjs` (`id: 'cursor'`).
+- **Known limitations:** Cursor' ACP mode requires an active Cursor login
+  on the host; an unauthenticated session surfaces as a connect-time error.
+
+### `copilot` (ACP)
+
+GitHub Copilot CLI in ACP mode. Claims `review` and `research`. Tends to
+win `research` against `gemini` on alphabetical tie-break — users who
+prefer Gemini for research should remove `copilot` from `enabled_peers`.
+
+- **Provenance:** runtime entry in `scripts/lib/install/runtimes.cjs` (`id: 'copilot'`).
+- **Known limitations:** Copilot's `review` role expects a diff in the
+  prompt; the adapter handles the framing.
+
+### `qwen` (ACP)
+
+Alibaba Qwen Code CLI in ACP mode. Claims `write` only. Useful when the
+session-runner wants a long-form code-generation pass and the host runtime
+is on a low tier.
+
+- **Provenance:** runtime entry in `scripts/lib/install/runtimes.cjs` (`id: 'qwen'`).
+- **Known limitations:** Qwen's ACP implementation is the newest of the
+  five; expect occasional protocol-version drift. The adapter pins
+  `protocolVersion: '2025-06-18'` per `acp-client.cjs` defaults.
+
+## Adding a new peer
+
+To add a new peer-CLI to the matrix:
+
+1. Run the guided ladder in `skills/peer-cli-add/SKILL.md` (lands with
+   Plan 27-10). It walks the protocol-fit check, the role-claim audit, the
+   adapter scaffold, and the test coverage required.
+2. Append the peer to `CAPABILITY_MATRIX` in `scripts/lib/peer-cli/registry.cjs`
+   AND to the table at the top of this file. The two MUST stay in sync —
+   the test suite (`tests/peer-cli-registry.test.cjs`) asserts the matrix
+   shape.
+3. Add a `<peer>.cjs` adapter under `scripts/lib/peer-cli/adapters/`.
+4. Add a `peerBinary?: string` field on the corresponding entry in
+   `scripts/lib/install/runtimes.cjs` (Plan 27-11 introduces the field;
+   new peers added after that plan ships must include it).
+5. Update `tests/peer-cli-registry.test.cjs` and the phase-20 baseline locks.
+
+To temporarily disable a peer without removing the adapter, drop the peer
+ID from `.design/config.json#peer_cli.enabled_peers`. To permanently remove
+a peer, reverse the steps above plus update `tests/phase-27-baseline.test.cjs`.
+
+## Cross-references
+
+- `scripts/lib/peer-cli/registry.cjs` — central dispatch, single source of
+  truth for the capability matrix as code.
+- `scripts/lib/peer-cli/adapters/*.cjs` — per-peer thin adapters
+  (Plan 27-04).
+- `scripts/lib/peer-cli/{acp,asp}-client.cjs` — protocol clients
+  (Plans 27-01 / 27-02).
+- `scripts/lib/peer-cli/broker-lifecycle.cjs` — long-lived session per
+  `(peer, workspace)` (Plan 27-03).
+- Phase 27 CONTEXT.md — decision log including D-05 (this matrix),
+  D-07 (transparent fallback), D-11 (opt-in gating).