@hegemonart/get-design-done 1.26.0 → 1.27.1

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}
+```

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

@@ -0,0 +1,110 @@
+---
+name: peer-cli-customize
+description: "Rewire role→peer mappings on a per-agent basis. File-edit-driven (touches frontmatter delegate_to: per agent), no runtime config layer. Run when you want a specific agent to delegate to a different peer than the default capability-matrix mapping suggests."
+argument-hint: "[<agent-name>] [<new-delegate-target>]"
+tools: Read, Edit, Bash, Grep
+---
+
+<!-- Procedural pattern adapted from greenpolo/cc-multi-cli's `customize` skill (Apache 2.0). See NOTICE for full attribution. -->
+
+# peer-cli-customize
+
+## Role
+
+You help the user rewire which peer-CLI delegate handles which agent's calls. The mechanism is direct file-edits to agent frontmatter (`delegate_to:` field added in Plan 27-06) — there is no runtime config layer. Your job is to make this safe and validatable.
+
+## Invocation Contract
+
+- **Optional input**: agent-name + new delegate target. If absent, the skill runs in interactive discovery mode.
+- **Output**: a diff summary listing each `agents/*.md` file modified, the old vs new `delegate_to:` value, and the validation result.
+
+## Procedure
+
+### Step 1 — Show current state
+
+Read the capability matrix from `scripts/lib/peer-cli/registry.cjs#describeCapabilities()`. Surface the 5 peers and their claimed roles to the user.
+
+Then scan `agents/*.md` and grep for `delegate_to:` frontmatter values. Render a table:
+
+```
+| Agent                      | delegate_to (current) |
+|----------------------------|------------------------|
+| design-reflector           | none                   |
+| design-context-checker     | (unset)                |
+| design-verifier            | gemini-research        |
+| ...                        | ...                    |
+```
+
+### Step 2 — Confirm rewire intent
+
+Either accept the user's explicit `<agent-name> <new-delegate-target>` arguments OR ask: "Which agent do you want to rewire? What should `delegate_to:` become?"
+
+Valid `<new-delegate-target>` values:
+- `<peer>-<role>` from the capability matrix (e.g., `gemini-research`, `codex-execute`, `cursor-debug`, `cursor-plan`, `copilot-review`, `copilot-research`, `qwen-write`).
+- `none` (explicit opt-out).
+- Empty / `(unset)` to remove the field entirely (revert to default behavior).
+
+### Step 3 — Validate the proposed rewire
+
+Cross-check the new value against the capability matrix:
+1. The peer must exist in the matrix.
+2. The role must be in the peer's `claims` list.
+3. The peer must (eventually, at runtime) be in `.design/config.json#peer_cli.enabled_peers` for dispatch to fire — but that's a runtime concern, not a frontmatter validation concern.
+
+If validation fails, surface the error and stop. Do not edit the file.
+
+### Step 4 — Apply the edit
+
+Use the `Edit` tool to modify the agent's frontmatter. Three cases:
+
+**Case A: Field is absent, user wants to add it.**
+Insert `delegate_to: <new-target>` into the frontmatter block (between the existing `default-tier:` and the next field, or at the end of frontmatter). Preserve YAML formatting.
+
+**Case B: Field is present, user wants to change the value.**
+Replace the existing value. If the existing value is `none` and the new value is `<peer>-<role>`, just swap. Mirror the existing indentation.
+
+**Case C: Field is present, user wants to remove it.**
+Delete the entire `delegate_to:` line. The field is optional — absence === default behavior.
+
+### Step 5 — Re-validate via the frontmatter validator
+
+Run `npm run validate:frontmatter` (or whatever the project's frontmatter check is). Confirm the modified agent passes. If validation fails, surface the error and offer to revert.
+
+### Step 6 — Surface a diff summary
+
+Report back:
+
+```
+## Rewire summary
+
+✓ design-verifier: delegate_to: gemini-research → cursor-debug
+✓ design-reflector: delegate_to (unset) → codex-execute
+
+frontmatter validator: 0 violations (40 files checked)
+next time these agents are spawned, session-runner will dispatch through the new peer.
+
+To verify: /gdd:peers (shows updated allowlist + capability matrix).
+```
+
+## Edge cases
+
+- **User asks to rewire to a peer not in the capability matrix** (e.g., a peer they want to add later): direct them to `skills/peer-cli-add/SKILL.md` first; do not allow the frontmatter edit until the peer exists in the matrix.
+- **User asks to rewire to a role the peer doesn't claim** (e.g., `codex-debug` — codex only claims `execute`): refuse with a helpful message listing what the peer DOES claim. Suggest a closer match if obvious.
+- **User asks to rewire ALL agents to a peer at once** (bulk operation): support but require explicit confirmation. Show the diff of all proposed edits before applying.
+- **Validator fails after edit**: revert the edit (re-run `Edit` with the inverse old/new strings). Surface the original error.
+
+## Cross-references
+
+- `scripts/validate-frontmatter.ts` (Plan 27-06) — `delegate_to` field validation.
+- `scripts/lib/peer-cli/registry.cjs` (Plan 27-05) — capability matrix.
+- `agents/README.md#peer-cli-delegation-delegate_to` — field documentation.
+- `skills/peer-cli-add/SKILL.md` — for adding a NEW peer (this skill is for rewiring among existing peers).
+- `.planning/phases/27-peer-cli-delegation/CONTEXT.md` D-06 — decision lineage.
+
+## Record
+
+After execution, append one JSONL line to `.design/skill-records.jsonl`:
+
+```json
+{"skill": "peer-cli-customize", "ts": "<ISO timestamp>", "agents_rewired": ["design-verifier", "design-reflector"], "validator_passed": true}
+```

package/skills/peers/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: gdd-peers
+description: "Discover peer-CLI capability matrix — which of {codex, gemini, cursor, copilot, qwen} are installed, allowlisted in .design/config.json, and (if Phase 23.5 has data) their cost/quality delta vs local. Single command, no flags. Read by users investigating delegation setup."
+argument-hint: ""
+tools: Read, Bash
+---
+
+# gdd-peers
+
+## Role
+
+You are a deterministic discovery skill. You do not spawn agents and do not delegate to peers. You read `scripts/lib/install/runtimes.cjs`, `scripts/lib/peer-cli/registry.cjs`, `.design/config.json`, and (optionally) `.design/intel/bandit-posterior.json`, then emit a single Markdown table summarizing peer-CLI status.
+
+## Invocation Contract
+
+- **Input**: none. The skill takes no arguments.
+- **Output**: a Markdown capability-matrix table to stdout. No JSON wrapper. The table is the entire output.
+
+## Procedure
+
+### 1. Load runtime matrix
+
+Read `scripts/lib/install/runtimes.cjs` and extract the 14 runtime entries. The 5 peer-capable entries (`codex`, `gemini`, `cursor`, `copilot`, `qwen`) carry a `peerBinary?` field (added in Plan 27-11). Collect their IDs and binary paths.
+
+### 2. Load capability matrix
+
+Read `scripts/lib/peer-cli/registry.cjs`. The exported `describeCapabilities()` returns the per-peer claimed-roles map. The capability matrix is the source of truth for which roles each peer can take.
+
+Use the canonical declared matrix:
+
+| Peer    | Roles claimed            | Protocol |
+|---------|--------------------------|----------|
+| codex   | execute                  | ASP      |
+| gemini  | research, exploration    | ACP      |
+| cursor  | debug, plan              | ACP      |
+| copilot | review, research         | ACP      |
+| qwen    | write                    | ACP      |
+
+### 3. Detect installation
+
+For each peer, run `which <peerBinary>` (POSIX) or `where <peerBinary>` (Windows). If exit 0 → installed. If exit non-zero → not installed.
+
+### 4. Read allowlist
+
+Read `.design/config.json`. The path is `peer_cli.enabled_peers` — an array of peer-IDs. Default: `[]` (empty, opt-in required). If the file or path is missing, treat as empty.
+
+### 5. (Optional) Read posterior win-rate
+
+If `.design/intel/bandit-posterior.json` exists, look up the per-peer last-N-cycle delta (cost or correctness, whichever is the bandit's primary signal). For each peer, compute the average reward delta vs the `delegate=none` arm. Render as `-12% cost (last 5 cycles)` or `(no data yet)` when fewer than 3 cycles of evidence exist.
+
+If the posterior file does not exist, surface "(no data yet)" for every peer.
+
+### 6. Render the table
+
+Emit the table in this exact shape:
+
+```
+## Peer-CLI Capability Matrix
+
+| Peer    | Installed | Allowlisted | Claimed roles            | Posterior delta vs local |
+|---------|-----------|-------------|--------------------------|--------------------------|
+| codex   | ✓         | ✓           | execute                  | -12% cost (last 5 cycles)|
+| gemini  | ✓         | ✓           | research, exploration    | -8%                      |
+| cursor  | ✗         | ✗           | debug, plan              | (not installed)          |
+| copilot | ✓         | ✗           | review, research         | (opt-in disabled)        |
+| qwen    | ✓         | ✓           | write                    | (no data yet)            |
+
+> Tip: Enable peers via `.design/config.json#peer_cli.enabled_peers`.
+> See `reference/peer-cli-capabilities.md` for the full capability matrix.
+> See `skills/peer-cli-customize/SKILL.md` to rewire role→peer mappings per agent.
+```
+
+Rules for the third column ("Posterior delta vs local"):
+- If `Installed = ✗` → `(not installed)`.
+- Else if `Allowlisted = ✗` → `(opt-in disabled)`.
+- Else if posterior data has fewer than 3 cycles → `(no data yet)`.
+- Else compute and render the delta.
+
+### 7. Done
+
+The table IS the output. No follow-up prose. Users can act on the data:
+- See "(opt-in disabled)" → enable in `.design/config.json`.
+- See "(not installed)" → install the peer CLI.
+- See concrete deltas → trust the bandit's recommendation, or override per-agent via `skills/peer-cli-customize`.
+
+## Cross-references
+
+- `scripts/lib/peer-cli/registry.cjs` (Plan 27-05) — capability matrix data source.
+- `scripts/lib/install/runtimes.cjs` (Plan 27-11) — `peerBinary` field per runtime.
+- `reference/peer-cli-capabilities.md` (Plan 27-05) — full capability matrix doc.
+- `skills/peer-cli-customize/SKILL.md` (Plan 27-10) — rewire role→peer mappings.
+- `skills/peer-cli-add/SKILL.md` (Plan 27-10) — add a brand-new peer.
+- `.planning/phases/27-peer-cli-delegation/CONTEXT.md` D-10 — decision lineage.
+
+## Record
+
+After execution, append one JSONL line to `.design/skill-records.jsonl`:
+
+```json
+{"skill": "gdd-peers", "ts": "<ISO timestamp>", "peers_detected": ["codex", "gemini"], "peers_allowlisted": ["codex"], "had_posterior": false}
+```