@hegemonart/get-design-done 1.26.0 → 1.27.1

package/reference/peer-protocols.md

@@ -0,0 +1,266 @@
+# Peer-CLI Protocols — ACP + ASP Cheat Sheet
+
+**Phase 27 (v1.27.0).** This file is the protocol-level reference for gdd's peer-CLI delegation layer. If you're authoring a new peer adapter or debugging a protocol-level issue, start here.
+
+For ops-level guidance (when delegation fires, how to enable/disable, fallback diagnostics), see `docs/PEER-DELEGATION.md`.
+
+Protocol shapes are adapted from [`greenpolo/cc-multi-cli-plugin`](https://github.com/greenpolo/cc-multi-cli-plugin) under Apache 2.0 — see `NOTICE` for full attribution.
+
+---
+
+## Two protocols, two transports
+
+| Protocol | Used by | Transport | Lifecycle |
+|----------|---------|-----------|-----------|
+| **ACP** (Agent Client Protocol) | Gemini, Cursor, Copilot, Qwen | Line-delimited JSON-RPC over stdio | Per-prompt request/response |
+| **ASP** (App Server Protocol) | Codex | Line-delimited JSON-RPC over stdio | Thread-oriented, multi-turn |
+
+Both protocols use the same line-delimited JSON-RPC framing (one JSON message per `\n`-terminated line on stdin/stdout). Both can be wrapped by gdd's broker (`scripts/lib/peer-cli/broker-lifecycle.cjs`) for long-lived sessions per `(peer, workspace)`.
+
+Line-buffer overflow guard: 16 MiB per line (both clients reject lines longer than this with a structured error).
+
+---
+
+## ACP — Agent Client Protocol
+
+### Initialize handshake
+
+Client → server, first message after spawn:
+
+```json
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "method": "initialize",
+  "params": {
+    "protocolVersion": "2025-06-18",
+    "clientCapabilities": {}
+  }
+}
+```
+
+Server → client (reply correlated by `id`):
+
+```json
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "result": {
+    "protocolVersion": "2025-06-18",
+    "serverCapabilities": { "...": "..." }
+  }
+}
+```
+
+If `serverCapabilities.protocolVersion` does not match the client's, the client logs a `protocol_mismatch` event and aborts the session.
+
+### Prompt method
+
+Client → server:
+
+```json
+{
+  "id": 2,
+  "jsonrpc": "2.0",
+  "method": "prompt",
+  "params": {
+    "text": "Research best React state libs"
+  }
+}
+```
+
+Server → client streams notifications (no `id`, no `result`) until the final `result` for the prompt's `id`:
+
+```json
+{ "jsonrpc": "2.0", "method": "agent_message_chunk", "params": { "text": "..." } }
+{ "jsonrpc": "2.0", "method": "tool_call",          "params": { "tool": "...", "input": "..." } }
+{ "jsonrpc": "2.0", "method": "file_change",        "params": { "path": "...", "diff": "..." } }
+{ "id": 2, "jsonrpc": "2.0", "result": { "content": "...", "finish_reason": "stop", "usage": { "input_tokens": 1234, "output_tokens": 5678 } } }
+```
+
+Notifications are surfaced via the `onNotification` callback the gdd caller passes:
+
+```js
+const result = await acpClient.prompt('Research ...', {
+  onNotification: (n) => console.log(n.method, n.params),
+});
+```
+
+### Per-peer ACP entry points
+
+Each peer documents its own way to enter ACP mode:
+
+- **Gemini**: `gemini acp` (subcommand).
+- **Cursor**: `cursor-agent acp` (subcommand on the CLI binary, not the IDE).
+- **Copilot**: `copilot --acp` (flag).
+- **Qwen**: `qwen acp` (subcommand).
+
+Verify via the `peer-cli-add` skill's verification ladder (Step 1) before adding a new peer.
+
+---
+
+## ASP — App Server Protocol (Codex)
+
+### Service identification
+
+Client → server, declared during initial communication:
+
+- `service_name = "gdd_peer_delegation"` (the canonical service identifier gdd uses)
+- `experimentalRawEvents = false` (we don't want raw model-token events; just structured turn output)
+
+These fields appear in both `threadStart` params and (where relevant) in handshake metadata.
+
+### Thread lifecycle
+
+ASP is thread-oriented. Each conversation has a `threadId`; turns happen within a thread.
+
+#### threadStart
+
+Client → server:
+
+```json
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "method": "threadStart",
+  "params": {
+    "service_name": "gdd_peer_delegation",
+    "experimentalRawEvents": false
+  }
+}
+```
+
+Server → client:
+
+```json
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "result": {
+    "threadId": "thread-abc123"
+  }
+}
+```
+
+#### threadResume
+
+Useful for cross-cycle conversation continuity (out of scope for v1.27.0 — gdd always creates fresh threads per delegated call — but the API surface exists):
+
+```json
+{
+  "id": 2,
+  "jsonrpc": "2.0",
+  "method": "threadResume",
+  "params": { "threadId": "thread-abc123" }
+}
+```
+
+Server replies with the thread's current state (turn history, last-known result).
+
+#### turn
+
+Client → server:
+
+```json
+{
+  "id": 3,
+  "jsonrpc": "2.0",
+  "method": "turn",
+  "params": {
+    "threadId": "thread-abc123",
+    "text": "Execute the build command"
+  }
+}
+```
+
+Server streams turn-progress notifications, ends with a structured result:
+
+**Completion path:**
+
+```json
+{
+  "id": 3,
+  "jsonrpc": "2.0",
+  "result": {
+    "threadId": "thread-abc123",
+    "turnId": "turn-xyz",
+    "status": "complete",
+    "content": "...",
+    "usage": { "input_tokens": 1234, "output_tokens": 5678 }
+  }
+}
+```
+
+**Error path** (does NOT throw on the client side — resolves with the error structure):
+
+```json
+{
+  "id": 3,
+  "jsonrpc": "2.0",
+  "result": {
+    "threadId": "thread-abc123",
+    "turnId": "turn-xyz",
+    "status": "error",
+    "error": {
+      "code": "rate_limit",
+      "message": "Rate limit exceeded for thread-abc123"
+    }
+  }
+}
+```
+
+The caller decides retry vs fallback per session-runner contract — gdd's session-runner falls back to local Anthropic on `status: "error"` per D-07.
+
+### Codex ASP entry point
+
+`codex app-server` (subcommand on the Codex CLI binary).
+
+---
+
+## Common framing rules (both protocols)
+
+### Line-delimited JSON-RPC
+
+- Each message is a single JSON object on stdin/stdout, terminated by `\n`.
+- Multiple messages may arrive in one chunk → client buffers until `\n`.
+- One message may split across chunks → client buffers until `\n`.
+- Lines longer than **16 MiB** are rejected with a structured error (the line buffer overflows, the client tears down and rejects all pending promises).
+
+### Request/response correlation
+
+- Requests carry `id` (monotonic integer per session).
+- Responses carry the same `id` in `result` or `error`.
+- Notifications have no `id` and no `result` — they are routed to the active request's `onNotification` callback (each protocol allows only one "active" request at a time per session — half-duplex).
+
+### Process lifecycle
+
+- The peer process is spawned via `scripts/lib/peer-cli/spawn-cmd.cjs` (handles Windows `.cmd` EINVAL workaround per D-04).
+- The client connects directly OR through gdd's broker (`broker-lifecycle.cjs`) — both surfaces present the same `{initialize, prompt, close}` (ACP) or `{threadStart, threadResume, turn, close}` (ASP) API.
+- On process death mid-request, the client rejects the in-flight promise with a structured `{error_class: "process_exited"}` event for telemetry.
+
+---
+
+## Adding a new protocol
+
+gdd v1.27.0 ships only ACP and ASP. If a new peer speaks neither (e.g., a future REST-only or HTTP/2-streaming protocol), the path forward is:
+
+1. Document the gap in `.design/RESEARCH.md` for a future phase to scope a new protocol layer.
+2. Do **not** stretch ACP/ASP to fit — they're documented contracts, not generalist multiplexers.
+3. The `peer-cli-add` skill (Step 1's verification ladder) refuses to scaffold a peer that doesn't speak ACP or ASP — by design.
+
+A future phase may add a new `scripts/lib/peer-cli/<protocol>-client.cjs` mirror following the same shape (line-buffer + JSON-RPC framing if applicable, or whatever the new protocol natively uses).
+
+---
+
+## Cross-references
+
+- `scripts/lib/peer-cli/acp-client.cjs` — ACP client implementation.
+- `scripts/lib/peer-cli/asp-client.cjs` — ASP client implementation.
+- `scripts/lib/peer-cli/spawn-cmd.cjs` — Windows `.cmd` EINVAL workaround.
+- `scripts/lib/peer-cli/broker-lifecycle.cjs` — long-lived broker.
+- `scripts/lib/peer-cli/adapters/*.cjs` — per-peer thin wrappers.
+- `scripts/lib/peer-cli/registry.cjs` — central dispatch.
+- `tests/peer-cli-{acp,asp,spawn,registry,adapters}.test.cjs` — protocol-level tests.
+- `docs/PEER-DELEGATION.md` — ops guide.
+- `NOTICE` — Apache 2.0 attribution for cc-multi-cli.
+- `.planning/phases/27-peer-cli-delegation/CONTEXT.md` — decision lineage (D-01, D-02, D-03, D-04).

package/reference/registry.json

@@ -45,6 +45,13 @@
       "phase": 19.6,
       "description": "3-invariant framework (body/attention/memory) with grep-able principle→code pairs and reducibility test; wired into design-discussant brief stage"
     },
+    {
+      "name": "peer-protocols",
+      "path": "reference/peer-protocols.md",
+      "type": "meta-rules",
+      "phase": 27,
+      "description": "Phase 27 ACP + ASP protocol cheat sheet for peer-CLI delegation — line-delimited JSON-RPC framing, initialize/prompt/threadStart/turn lifecycle, per-peer ACP entry points, error-path resolution semantics"
+    },
     {
       "name": "DEPRECATIONS",
       "path": "reference/DEPRECATIONS.md",
@@ -638,6 +645,13 @@
       "type": "heuristic",
       "description": "Rules for serial/parallel agent dispatch and Touches conflict detection"
     },
+    {
+      "name": "peer-cli-capabilities",
+      "path": "reference/peer-cli-capabilities.md",
+      "type": "meta-rules",
+      "phase": 27,
+      "description": "Phase 27 peer-CLI delegation capability matrix — which peer (codex/copilot/cursor/gemini/qwen) claims which agent role, protocol (ACP/ASP), tie-break order, and opt-in gating semantics"
+    },
     {
       "name": "performance",
       "path": "reference/performance.md",

package/reference/runtime-models.md

@@ -8,7 +8,7 @@ This file is parsed by `scripts/lib/install/parse-runtime-models.cjs` and consum
 - `scripts/lib/install/installer.cjs` (26-03) — emits `models.json` per runtime config-dir at install time.
 - `hooks/budget-enforcer.ts` + `scripts/lib/budget-enforcer.cjs` (26-05) — concrete model name for cost lookup.
 
-**Strict schema** (D-03): each runtime block is a fenced ```json ... ``` block validated against `reference/schemas/runtime-models.schema.json`. Schema version is locked at `1` until a breaking change forces a version bump.
+**Strict schema** (D-03): each runtime block is a fenced `json` code block validated against `reference/schemas/runtime-models.schema.json`. Schema version is locked at `1` until a breaking change forces a version bump.
 
 **Provenance discipline** (D-01): every row carries a `source_url` (runtime-author docs), `retrieved_at` (ISO timestamp), and `last_validated_cycle` (current GDD cycle ID). Placeholder URLs are tagged `<TODO: confirm at <runtime-author-docs-url>>` and validated by Phase 13.2 authority-watcher on later cycles.
 
@@ -118,7 +118,7 @@ Google's Gemini CLI runtime. Public tier docs at https://ai.google.dev/gemini-ap
 
 ## qwen — Qwen Code
 
-Alibaba's Qwen Code runtime. Public tier docs at https://qwenlm.github.io/qwen-code/. Seed picks per CONTEXT.md D-02.
+Alibaba's Qwen Code runtime. Public tier docs at https://github.com/QwenLM/qwen-code. Seed picks per CONTEXT.md D-02.
 
 ```json
 {
@@ -135,7 +135,7 @@ Alibaba's Qwen Code runtime. Public tier docs at https://qwenlm.github.io/qwen-c
   },
   "provenance": [
     {
-      "source_url": "https://qwenlm.github.io/qwen-code/",
+      "source_url": "https://github.com/QwenLM/qwen-code",
       "retrieved_at": "2026-04-29T00:00:00.000Z",
       "last_validated_cycle": "2026-04-29-v1.26",
       "note": "Qwen Code public model catalog."

package/scripts/install.cjs

@@ -18,8 +18,9 @@
 
 const path = require('node:path');
 
-const { listRuntimes, listRuntimeIds } = require('./lib/install/runtimes.cjs');
+const { listRuntimes, listRuntimeIds, detectInstalledPeers, listPeerCapableRuntimes } = require('./lib/install/runtimes.cjs');
 const { installRuntime, uninstallRuntime } = require('./lib/install/installer.cjs');
+const fs = require('node:fs');
 
 function parseArgs(argv) {
   const args = argv.slice(2);
@@ -60,6 +61,7 @@ function helpText() {
     '  --uninstall     Remove the plugin from selected runtimes',
     '  --dry-run       Print the diff without writing',
     '  --config-dir D  Override the config directory',
+    '  --no-peer-prompt  Suppress the post-install peer-CLI detection nudge',
     '  --help, -h      Show this message',
     '',
     'Environment overrides (per-runtime):',
@@ -196,6 +198,103 @@ async function main() {
       '',
     ].join('\n'),
   );
+
+  // v1.27.1 — Plan 27-11 wiring: post-install peer-CLI detection nudge.
+  // Fires only on real install (not uninstall, not dry-run) when not
+  // suppressed by --no-peer-prompt. Silently skips when no peers detected.
+  // Always opt-in: writes .design/config.json#peer_cli.enabled_peers
+  // ONLY on explicit y/Y; default is no.
+  if (!uninstall && !dryRun && !flags.has('--no-peer-prompt')) {
+    try {
+      await maybeNudgePeerCli({ flags });
+    } catch (e) {
+      // Nudge is non-critical. Surface a one-line warning but don't fail
+      // the install — the plugin is fully functional without peer-CLI.
+      process.stderr.write(
+        `\n[peer-cli] post-install nudge skipped: ${e && e.message ? e.message : e}\n`,
+      );
+    }
+  }
+}
+
+// v1.27.1 — Plan 27-11: post-install nudge. Detects installed peer CLIs,
+// asks the user (interactive y/N) whether to wire them as peers, writes
+// .design/config.json#peer_cli.enabled_peers on yes. Default = NO (opt-in).
+async function maybeNudgePeerCli({ flags }) {
+  const detected = detectInstalledPeers();
+  if (!detected || detected.length === 0) {
+    // Nothing detected — silent skip. (No bad UX of "we found 0 peers".)
+    return;
+  }
+
+  // Build the human-readable peer line for the prompt.
+  const allPeerCapable = listPeerCapableRuntimes();
+  const detectedDisplay = detected
+    .map((id) => {
+      const r = allPeerCapable.find((x) => x.id === id);
+      return r && r.displayName ? r.displayName : id;
+    })
+    .join(', ');
+
+  process.stdout.write(
+    [
+      '',
+      '✓ Detected peer CLIs: ' + detectedDisplay,
+      '',
+      'gdd v1.27.0 introduced optional peer-CLI delegation. With your',
+      'agents\\u2019 frontmatter `delegate_to:` set, gdd can route specific',
+      'roles through these peer CLIs (cost or quality wins per Phase 23.5',
+      'bandit). You can change this anytime via .design/config.json.',
+      '',
+    ].join('\n'),
+  );
+
+  // Decide interactive vs scripted. shouldUseInteractive lives in this
+  // file; reuse it. If non-TTY, default to no (silent opt-out) so CI
+  // installers don't hang waiting for input.
+  let confirmed = false;
+  if (shouldUseInteractive(flags)) {
+    try {
+      const clack = require('@clack/prompts');
+      const ans = await clack.confirm({
+        message: 'Enable peer-CLI delegation for these peers?',
+        initialValue: false,
+      });
+      confirmed = (ans === true);
+    } catch {
+      // @clack/prompts unavailable — silently default to no.
+      confirmed = false;
+    }
+  }
+
+  if (!confirmed) {
+    process.stdout.write(
+      'Skipped — peer-CLI delegation remains disabled.\n' +
+      'Enable later by adding to .design/config.json:\n' +
+      '  { "peer_cli": { "enabled_peers": ' + JSON.stringify(detected) + ' } }\n\n',
+    );
+    return;
+  }
+
+  // Write the allowlist. Merge with any existing .design/config.json.
+  const cfgPath = path.join(process.cwd(), '.design', 'config.json');
+  let cfg = {};
+  try {
+    if (fs.existsSync(cfgPath)) {
+      cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+    }
+  } catch {
+    cfg = {};
+  }
+  if (!cfg.peer_cli || typeof cfg.peer_cli !== 'object') cfg.peer_cli = {};
+  cfg.peer_cli.enabled_peers = detected;
+  fs.mkdirSync(path.dirname(cfgPath), { recursive: true });
+  fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
+  process.stdout.write(
+    `✓ Wrote .design/config.json — peer-CLI enabled for: ${detected.join(', ')}\n` +
+    '  Set delegate_to: <peer>-<role> on agent frontmatter to opt agents in.\n' +
+    '  See docs/PEER-DELEGATION.md for the full ops guide.\n\n',
+  );
 }
 
 main().catch((err) => {