@hegemonart/get-design-done 1.25.0 → 1.27.0

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

package/skills/router/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-router
-description: "Routes a /gdd command to fast|quick|full path + S|M|L|XL complexity_class and returns {path, complexity_class, model_tier_overrides, estimated_cost_usd, cache_hits}. Deterministic — no model call. Invoked once at command entry before any Agent spawn. Read by hooks/budget-enforcer.js."
+description: "Routes a /gdd command to fast|quick|full path + S|M|L|XL complexity_class and returns {path, complexity_class, model_tier_overrides, resolved_models, estimated_cost_usd, cache_hits}. Deterministic — no model call. Invoked once at command entry before any Agent spawn. Read by hooks/budget-enforcer.js."
 argument-hint: "<intent-string> [<target-artifacts-csv>]"
 tools: Read, Bash, Grep
 ---
@@ -20,16 +20,37 @@ You are a deterministic routing skill. You do not spawn agents. You read `.desig
     "path": "fast",
     "complexity_class": "M",
     "model_tier_overrides": {"design-verifier": "haiku"},
+    "resolved_models": {
+      "design-reflector": "gpt-5",
+      "design-context-checker": "gpt-5-nano",
+      "design-verifier": "gpt-5-nano"
+    },
     "estimated_cost_usd": 0.034,
     "cache_hits": ["design-context-builder:abc123"]
   }
   ```
 - `path` enum: `fast` (single Haiku + no checkers), `quick` (Sonnet mappers + Haiku verify), `full` (Opus planners + full quality gates). Stays unchanged for back-compat per D-05.
 - `complexity_class` enum: `S | M | L | XL` (Phase 25 / D-04, D-05). Additive to `path` — existing consumers reading only `path` keep working. Mapping is documented in the Path Selection Heuristic table below.
-- `model_tier_overrides` merges agent frontmatter `default-tier` with `.design/budget.json.tier_overrides` — budget.json wins per D-04.
+- `model_tier_overrides` merges agent frontmatter `default-tier` with `.design/budget.json.tier_overrides` — budget.json wins per D-04. Enum stays `opus|sonnet|haiku` for back-compat across all 14 runtimes; consumers that need the **concrete** model name for the active runtime read `resolved_models` instead.
+- `resolved_models` is a per-agent map of concrete model IDs for the runtime in use (Phase 26 / D-07). Keys are agent names; values are runtime-specific model strings (e.g. `"gpt-5"` under codex, `"gemini-2.5-pro"` under gemini, `"claude-opus-4-7"` under claude) or `null` when the resolver can supply no model (missing tier-map row, missing tier on the row). Additive to `model_tier_overrides` — existing consumers reading the tier-name map keep working unchanged; new consumers (budget-enforcer cost computation, cost telemetry, bandit posterior store) read `resolved_models` for runtime-correct cost. See **Runtime-aware model resolution** below for the computation contract.
 - `estimated_cost_usd` is the sum of per-spawn estimates using the D-06 formula and `reference/model-prices.md`.
 - `cache_hits` is a list of `{agent}:{input-hash}` strings that exist in `.design/cache-manifest.json` and are within TTL; emitting a hit lets the hook short-circuit that spawn per D-05.
 
+### Output schema versioning
+
+The router output contract is additive across phases. The current shape (Phase 26, v1.26.0) carries:
+
+| Field | Added in | Status |
+|-------|----------|--------|
+| `path` | v1.10.1 (10.1-01) | stable |
+| `model_tier_overrides` | v1.10.1 (10.1-01) | stable, enum unchanged |
+| `estimated_cost_usd` | v1.10.1 (10.1-01) | stable |
+| `cache_hits` | v1.10.1 (10.1-01) | stable |
+| `complexity_class` | v1.25.0 (25-02) | stable, additive |
+| `resolved_models` | v1.26.0 (26-04) | stable, additive |
+
+Existing consumers reading any subset of the older fields keep working unchanged across these bumps — the schema is a strict superset at every phase boundary. New fields are documented inline in this skill rather than in a separate JSON-schema file (the SKILL is the contract — same convention Phase 25 followed for `complexity_class`).
+
 ## Path Selection Heuristic
 
 The router emits both `path` (legacy 3-tier enum) and `complexity_class` (Phase 25 4-tier enum). The canonical mapping is:
@@ -70,6 +91,34 @@ for each agent in planned spawn graph:
 return total
 ```
 
+## Runtime-aware model resolution
+
+The router emits `resolved_models` alongside `model_tier_overrides` so downstream consumers (budget-enforcer cost computation, Phase 22 cost telemetry, Phase 23.5 bandit posterior store) can read the **concrete model ID** for the active runtime without re-deriving it from the tier name. The resolution is per-agent and additive — `model_tier_overrides` keeps its `opus|sonnet|haiku` enum for back-compat across all 14 runtimes, and `resolved_models` runs the runtime-specific translation on top of it.
+
+Computation contract (per D-07):
+
+```
+runtime = runtimeDetect.detect() ?? 'claude'
+for each agent in planned spawn graph:
+  tier = resolve_tier(agent)                          # same merge as model_tier_overrides
+  resolved_models[agent] = tierResolver.resolve(runtime, tier)
+                                                       # → concrete model string OR null
+```
+
+Implementation surfaces (Phase 26 / Wave A):
+
+- `scripts/lib/runtime-detect.cjs` — `detect() → runtime-id | null`. Reads the same `*_CONFIG_DIR` / `*_HOME` env-vars Phase 24's installer uses (single source of truth in `scripts/lib/install/runtimes.cjs`). Returns `null` when no recognized runtime env-var is set; the router falls back to `'claude'` so the resolver always has a runtime ID to work with.
+- `scripts/lib/tier-resolver.cjs` — `resolve(runtime, tier, opts?) → model | null`. Translates `opus|sonnet|haiku` to the concrete model the runtime understands using the `reference/runtime-models.md` mapping (Phase 26 / Wave A). Fallback chain (D-04): runtime-specific entry → `claude` row default with `tier_resolution_fallback` event → `null` with `tier_resolution_failed` event. Never throws; `null` is a valid output the consumer must handle.
+
+Per-agent emission rules:
+
+- One key per agent in the planned spawn graph (same key set the cost-estimation loop iterates over). Keys MUST match agent names exactly so consumers can join `resolved_models` against `model_tier_overrides` and the spawn graph by name.
+- Value is the concrete model string returned by `tier-resolver.resolve(runtime, tier)`.
+- When the resolver returns `null` (missing tier-map row, missing tier, garbage input), the value is JSON `null` — NOT omitted, NOT the empty string. Consumers (budget-enforcer, telemetry) MUST handle `null`: typically by skipping the cost row for that spawn and emitting their own diagnostic event, never by crashing.
+- When `complexity_class` is `S` and the router itself short-circuits (see **S-class short-circuit** above), no payload is emitted at all and `resolved_models` does not exist for that invocation — the budget-enforcer's "no router decision payload" branch already handles this case.
+
+Back-compat assertion: a router invocation in a Claude runtime (or any environment where `runtime-detect.detect()` returns `null` and the router falls back to `'claude'`) produces `resolved_models` values that are the canonical Anthropic model IDs (`claude-opus-4-7`, `claude-sonnet-4-6`, `claude-haiku-4-5`) for the corresponding tiers. Pre-Phase-26 consumers that ignore `resolved_models` see the same `model_tier_overrides` they always saw (Plan 26-09 owns the runtime fixture diff that asserts this).
+
 ## Cache-Hit Detection
 
 Delegate to `skills/cache-manager/SKILL.md` (Plan 10.1-02). The router lists candidate `{agent}:{input-hash}` tuples; the cache-manager confirms freshness against TTL from `budget.json.cache_ttl_seconds`.