@hegemonart/get-design-done 1.26.0 → 1.27.0

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