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