peaks-cli 1.3.1 → 1.3.3

package/skills/peaks-solo/references/sub-agent-dispatch.md

@@ -0,0 +1,218 @@
+# sub-agent-dispatch.md — peaks sub-agent dispatch orchestrator contract
+
+> **Slice**: 2026-06-07-sub-agent-dispatch-decouple (G3 + G6)
+> **Audience**: SKILL.md authors and LLM readers of peaks-solo / peaks-rd / peaks-qa
+> **Status**: stable
+
+This reference is the orchestrator-side contract for sub-agent dispatch.
+It explains why the peaks family uses `peaks sub-agent dispatch <role>` as
+the canonical primitive, how the dispatch envelope flows back to the LLM,
+and how the new G6 heartbeat channel keeps the user informed during the
+batch-sync wait. Read this before writing or extending any peaks-*
+SKILL.md that dispatches sub-agents.
+
+## Why a CLI primitive (skill-first / CLI-auxiliary)
+
+The peaks skill family is the **product**. The CLI is a thin atomic
+the skills compose. For sub-agent dispatch the relationship is:
+
+| Surface | Who owns | What it does | Who calls it |
+|---|---|---|---|
+| SKILL.md (主面) | peaks-solo, peaks-rd, peaks-qa | Tells the LLM when and why to dispatch a sub-agent; what prompt to pass; what artifacts to expect back | LLM (during normal Solo / RD / QA flow) |
+| CLI (副 / 原子) | `peaks sub-agent dispatch` | Validates the role, looks up the current IDE's `subAgentDispatcher`, returns a per-IDE tool-call descriptor + writes a dispatch record | LLM (read from the SKILL.md) |
+| Dispatcher 抽象 (per-IDE) | `src/services/dispatch/sub-agent-dispatcher.ts` | Encapsulates the IDE-private tool name (claude-code: `Task`, trae: UNVERIFIED placeholder) and arg shape | CLI (called by the CLI) |
+
+This is the **inverse** of the prior shape: SKILL.md used to hardcode
+`Task(subagent_type="general-purpose", ...)`, which made peaks-cli
+depend on Claude Code's specific tool name. Adding a new IDE meant
+editing every SKILL.md that mentioned sub-agents. With the new shape,
+the only per-IDE thing in the dispatch chain is the dispatcher — SKILL.md
+stays IDE-agnostic.
+
+> **Red line**: do not invoke `peaks sub-agent dispatch` from your own
+> shell. The CLI is a primitive the LLM composes. Users do not need it.
+
+## Dispatch contract
+
+**Command**:
+
+```
+peaks sub-agent dispatch <role> --prompt <text> [--request-id <rid>] [--session-id <sid>] [--project <repo>] [--batch-id <uuid>] --json
+```
+
+**Envelope** (AC-8):
+
+```json
+{
+  "ok": true,
+  "command": "sub-agent.dispatch",
+  "data": {
+    "role": "rd",
+    "ide": "claude-code",
+    "prompt": "<complete prompt the LLM should pass through>",
+    "toolCall": {
+      "name": "Task",
+      "args": {
+        "subagent_type": "general-purpose",
+        "description": "rd for rid=002-2026-06-07-...",
+        "prompt": "..."
+      }
+    },
+    "dispatchRecordPath": ".peaks/_sub_agents/2026-06-06-session-5b1095/dispatch-002-2026-06-07-...-...json",
+    "batchId": "<uuid>",
+    "dispatchedInBatch": 3
+  },
+  "warnings": [],
+  "nextActions": [
+    "Tool call is dry-run; LLM must execute the tool to actually dispatch the sub-agent.",
+    "After dispatching, the sub-agent should call `peaks sub-agent heartbeat --record <dispatchRecordPath>` periodically."
+  ]
+}
+```
+
+**LLM side**: read `data.toolCall` (the `{name, args}` descriptor), look
+up the tool by `name` in the current environment, and invoke it with
+`args`. The CLI does not spawn anything. The IDE (Claude Code, Trae,
+etc.) is the one that actually runs the sub-agent.
+
+**Side effect**: the CLI writes a dispatch record to
+`.peaks/_sub_agents/<sid>/dispatch-<rid>-<ts>.json` (R-2 path-guarded).
+The record starts with `heartbeats: []`, `lastBeatAt: null`, `status: 'queued'`
+and is updated by the heartbeat flow (§G6 below).
+
+## Role model
+
+`SubAgentRole` is a free-form string. The CLI **does not** enforce a
+hard whitelist. Recommended roles:
+
+- Top-level: `rd` | `qa` | `ui` | `txt` | `general-purpose`
+- QA sub-roles: `qa-business` | `qa-perf` | `qa-security`
+- Business sub-divisions: `qa-business-api` | `qa-business-frontend` |
+  `qa-business-regression` | ... (≤ 2 levels deep per RL-4)
+- Promotable Worker (architecture预留, slice #009 不实际提升): `prd-business` |
+  `prd-technical` | `prd-ux` | `ui-visual` | `ui-flow` | `ui-component`
+
+The only hard validation is: non-empty, ≤ 256 chars, no control
+characters. Any other string is a convention, not a contract.
+
+## Per-IDE dispatchers (G1)
+
+| IDE | Tool name | Args shape | Status |
+|---|---|---|---|
+| `claude-code` | `Task` | `{subagent_type: "general-purpose", description, prompt}` | verified |
+| `trae` | `Task` | byte-identical to claude-code by design | UNVERIFIED — pending real Trae dogfood |
+| `null` (no IDE detected) | — | throws `IDE_NOT_SUPPORTED` | fallback |
+
+Adding a new IDE means:
+
+1. Add a new adapter to `src/services/ide/adapters/<id>-adapter.ts`.
+2. Fill in `subAgentDispatcher: <yourDispatcher>` (implements
+   `SubAgentDispatcher`).
+3. Register the adapter in `ide-registry.ts`.
+
+SKILL.md and existing dispatcher implementations are untouched.
+
+## G6 — heartbeat + dynamic progress (RL-13..RL-16)
+
+Sub-agents run for 30 s to 2 min. During that wait, the LLM platform
+provides no progress signal to the Dispatcher. Without a heartbeat
+channel, the user sees a frozen terminal and reasonably assumes the
+system is dead. G6 is the rule that says: **no**.
+
+### The three-layer contract
+
+| Layer | Who | What | Cadence |
+|---|---|---|---|
+| **Sub-agent writes** | The sub-agent itself | Calls `peaks sub-agent heartbeat --record <dispatchRecordPath> --status <state> --progress <pct> --note "<text>"` to append a heartbeat | 30 s default; SKILL.md can override via `heartbeatIntervalSec: 15` |
+| **Dispatcher reads** | peaks-solo main loop, during the batch-sync wait | In-process async poller (`BatchHeartbeatPoller`) reads `heartbeats[]` + `lastBeatAt` from each record, emits a single-line status per G6.5 | 10 s (offset from 30 s to avoid jitter) |
+| **User / CLI reads** | Anyone, anytime | `peaks sub-agent list --session-id <sid> --json` (G5 RL-10, future slice) | manual |
+
+### Sub-agent prompt template (heartbeat-aware)
+
+Every sub-agent prompt dispatched via `peaks sub-agent dispatch` should
+include the heartbeat instruction so the LLM knows when and how to
+report progress. The recommended paragraph (auto-generated by the CLI
+and the SKILL.md heart of each Dispatcher) is:
+
+```
+While running, call `peaks sub-agent heartbeat --record <dispatchRecordPath>
+--status <state> --progress <pct> --note "<text>"` at least every 30 seconds
+(the Dispatcher expects 30s cadence). On completion call
+`--status done --progress 100 --note "completed"`. On failure,
+`--status failed`. Do not skip heartbeats; the parent Dispatcher uses them
+to keep the user informed during the wait.
+```
+
+`heartbeatIntervalSec` is overridable per SKILL.md (5..600). Default 30.
+
+### Status line shape (G6.5)
+
+Single line, 80-120 chars:
+
+```
+[peaks-solo] swarm 3/3 running | rd-planning 45% (12s ago) | qa-test-cases 30% (5s ago) | ui-design 20% (2s ago)
+[peaks-solo] swarm 3/3 running | rd-planning 70% (8s ago) | qa-test-cases 50% (3s ago) | ui-design 30% (6s ago)
+...
+[peaks-solo] swarm 3/3 done
+```
+
+If a sub-agent has not written a heartbeat in 5 minutes, the poller
+appends `⚠ stale` to that sub-agent's segment and marks
+`status: 'stale'` on the record. **It does not cancel, kill, or send
+SIGTERM** (RL-15). Stale is a user-visible warning, not a failure.
+The user decides.
+
+### Truncation (RL-16)
+
+`heartbeats[]` is append-only for audit, but capped at 100 entries.
+Past 100, the oldest are dropped and `truncated: true` is set. The
+record JSON can otherwise balloon to MB on long-running sub-agents.
+100 is the LLM-friendly limit — stale heartbeats are not informative
+once the poller has read them.
+
+### Acceptance criteria covered
+
+- AC-33 `peaks sub-agent heartbeat` CLI primitive (implemented)
+- AC-34 Dispatch record schema upgrade (`heartbeats[]` + `lastBeatAt` + `status` aggregate, backward-compat defaults)
+- AC-35 peaks-solo main loop batch-sync poller (10 s cadence, 5 min stale)
+- AC-36 SKILL.md fan-out sections include heartbeat instruction
+- AC-37 G6 E2E dogfood (3 heartbeats, 101 → truncated, stale simulation)
+
+## Acceptance criteria (overall G1-G6)
+
+- AC-1..AC-5: dispatcher interface + 3 adapter impls (`claudeCodeSubAgentDispatcher`, `traeSubAgentDispatcher`, `nullSubAgentDispatcher`)
+- AC-6: dispatcher unit tests
+- AC-7..AC-9: dispatch CLI signature + envelope + steps
+- AC-10: dispatch CLI unit tests
+- AC-11 / AC-11b / AC-11c: E2E dogfood on the live repo
+- AC-12: `peaks --help` byte-level delta is `+1` line (`sub-agent <cmd>`)
+- AC-13..AC-19: SKILL.md fan-out rewrites (peaks-solo 5 spots, peaks-rd 2, peaks-qa 3-way, peaks-ui 1; this reference is the canonical contract)
+- AC-22..AC-24: R-2 path guard, prompt size limit, atomic write
+- AC-25..AC-32: G5 resource lifecycle (RL-1 batch counter, dispatch record schema, reducer dispose, slice archive, cancel dispose)
+- AC-33..AC-37: G6 heartbeat CLI, schema, poller, status line, E2E
+
+## How to apply
+
+When writing a SKILL.md that fans out sub-agents:
+
+1. Use `peaks sub-agent dispatch <role>` (never `Task(...)`).
+2. Issue all dispatches in a single message; the LLM will fire all
+   returned toolCalls in parallel.
+3. Pass `--request-id` and `--session-id` (or omit and let the CLI
+   resolve the active session).
+4. The sub-agent prompt **must** include the heartbeat instruction
+   (30 s cadence; override via `heartbeatIntervalSec` if needed).
+5. After the fan-out returns, the Dispatcher reducer reads the
+   dispatch record + the artifacts the sub-agents wrote, marks
+   `disposed: true` on each record, and advances the state machine.
+6. The poller handles the 5-min stale case as a warning, never as a
+   failure. The user is the one who decides to cancel.
+
+## Cross-reference
+
+- PRD #009 G1-G6 (this slice's source of truth)
+- RD request #009 in-scope files (implementation contract)
+- `.peaks/memory/sub-agent-resource-lifecycle-red-line.md` (G5 red line)
+- `.peaks/memory/sub-agent-heartbeat-progress-red-line.md` (G6 red line)
+- `skills/peaks-solo/references/swarm-dispatch-contract.md` (predecessor contract)
+- `skills/peaks-qa/references/qa-fanout-contract.md` (QA-specific fan-out)

package/skills/peaks-solo/references/swarm-dispatch-contract.md

@@ -6,41 +6,7 @@
 
 The previous "Swarm" used `Skill(skill="peaks-rd")` calls. That is **single-stack and blocking** — there is no concurrency. Three sequential `Skill` calls run in order on the same main loop, not in parallel. The "parallel Agent calls" wording in the old SKILL.md was a v1.x illusion.
 
-This contract moves the Swarm to the `Task` tool with `subagent_type="general-purpose"`, which is the only Claude Code mechanism that gives real concurrent fan-out. Solo launches all sub-agents in a single message; the platform schedules them concurrently.
-
-## 2. When to swarm (decision)
-
-Solo runs the swarm only after `peaks request show <rid> --role prd` is in state `confirmed-by-user` or `handed-off`. Before that, there is nothing for the sub-agents to derive from.
-
-Solo computes the **swarm plan** from three signals (see "Swarm gate" in the main SKILL.md):
-
-1. `--type` from `peaks request init` (already on the PRD artefact).
-2. `frontendOnly` from `.peaks/<session-id>/rd/project-scan.md` `## Project mode`.
-3. Frontend keyword scan over the PRD body.
-
-The plan is written to `.peaks/<session-id>/sc/swarm-plan.json` before any Task call, so SC and TXT can audit what was launched. Solo updates `.peaks/.active-skill.json` to `gate=swarm-fan-out` at this point.
-
-| `--type` | Frontend signal | Plan |
-|---|---|---|
-| `feature` / `refactor` / `bugfix` | keyword hit OR `frontendOnly=true` | `[ui, rd-planning, qa-test-cases]` |
-| `feature` / `refactor` / `bugfix` | no keyword hit AND `frontendOnly=false` | `[rd-planning, qa-test-cases]` |
-| `config` / `docs` / `chore` | (any) | `[]` (swarm skipped, recorded in plan) |
-
-In `assisted` and `strict` modes, Solo replaces signal (3) with a three-option `AskUserQuestion` (see "Mode-driven fan-out shape" in the main SKILL.md) and uses the user's choice as the plan.
-
-## 3. Sub-agent invocation template
-
-Solo emits one Task call per sub-agent in the plan, all in the same message:
-
-```js
-Task({
-  subagent_type: "general-purpose",
-  description: "<role> for rid=<rid>",
-  prompt: <see role-specific sections below>
-})
-```
-
-### 3.1 Common prompt header (all sub-agents)
+This contract (slice #009) replaces the IDE-private sub-agent literal with the IDE-agnostic primitive `peaks sub-agent dispatch <role>`. The CLI returns a JSON `data.toolCall` descriptor; the LLM executes that tool in its own environment. SKILL.md is now free of IDE-private tool names and the same prompt works on every registered IDE. Real concurrent fan-out is achieved by Solo launching N dispatch calls in a single message and the platform scheduling the returned toolCalls concurrently.
 
 ```
 You are a sub-agent invoked by peaks-solo. You are NOT the main Claude session.
@@ -158,7 +124,7 @@ no acceptance surface to plan tests for.
 
 ## 4. Reducer (Solo side)
 
-After all sub-agent Tasks return, Solo:
+After all sub-agent dispatch calls return and the LLM has invoked the toolCalls, Solo:
 
 1. Restores presence ONCE (not per-agent):
    ```
@@ -176,7 +142,7 @@ If a sub-agent is misbehaving and writes to `.peaks/.active-skill.json` anyway,
 
 ## 6. Why not a `peaks-swarm` skill?
 
-A skill cannot itself trigger sub-agents — the Skill tool runs in the main loop. The orchestrator (peaks-solo) has to be in the main loop and has to use the Task tool directly. Putting swarm logic into a separate skill would either re-introduce the "single-stack blocking" anti-pattern or require a custom slash command that bypasses the Skill tool. The current design keeps swarm control in peaks-solo where it belongs.
+A skill cannot itself trigger sub-agents — the Skill tool runs in the main loop. The orchestrator (peaks-solo) has to be in the main loop and has to call `peaks sub-agent dispatch` directly. Putting swarm logic into a separate skill would either re-introduce the "single-stack blocking" anti-pattern or require a custom slash command that bypasses the Skill tool. The current design keeps swarm control in peaks-solo where it belongs.
 
 ## 7. Tests / dogfood
 

package/skills/peaks-txt/SKILL.md

@@ -15,6 +15,8 @@ Before any analysis or tool call, immediately run:
 peaks skill presence:set peaks-txt --project <repo> --mode <mode> --gate startup
 ```
 
+**When invoked as a sub-agent (peaks-solo swarm):** do NOT call `peaks skill presence:set` (Solo owns the active-skill marker) and do NOT spawn your own session. Use the parent's sid — read `.peaks/_runtime/session.json` or pass `--session-id <parent-sid>` to any session-creating CLI. The new `peaks session info --active` reads the canonical binding for you.
+
 On the first presence:set in a project, ensure the out-of-band status bar is installed so the user can see at a glance that Peaks is orchestrating — it renders the active skill in Claude Code's terminal status line, independent of model output:
 
 ```bash
@@ -248,3 +250,20 @@ find .peaks/<id>/txt/ -type f | sort
 Do not choose the refactor plan or install runtime resources. Use artifacts produced by other skills and CLI reports.
 
 Reference: `references/context-capsule.md`.
+
+## Sub-agent context governance (G8 + G9 — slice #010, TXT reducer view)
+
+> peaks-txt is the TXT reducer; it sees the metadata-only view from G7 + the share entries from G8. The TXT handoff summarizes the slice at the slice-close gate. Detailed: `skills/peaks-solo/references/context-governance.md`.
+
+### G8 — TXT reducer sees share entries on completion
+
+When TXT reduces a batch, it consumes:
+- The dispatch record's `artifactMetas[]` (G7.4.d) — paths + sizes + sha256s + summaries.
+- The shared channel's entries (G8) — sibling sub-agent status (`<role>.completed`, `<role>.found-blocker`).
+
+The TXT handoff summarizes the slice by listing the artifact metas + the share entries that arrived during the batch. Both are dispatcher-mediated (NOT inlined from the sub-agent prompt).
+
+### G9 — TXT prompt size self-check
+
+Same G9 threshold table. TXT handoff messages can grow large when the slice has many batches; use `--use-headroom` proactively for handoff prompts > 50%.
+

package/skills/peaks-ui/SKILL.md

@@ -28,8 +28,9 @@ UI's headed-browser inspection hits the same auth walls. The flow is identical t
 
 ## Sub-agent dispatch (when launched by peaks-solo swarm)
 
-When this skill is launched as a sub-agent via `Task(subagent_type="general-purpose", ...)` from `peaks-solo`, the following sections of THIS skill are **suspended** for the sub-agent run:
+When this skill is launched as a sub-agent via `peaks sub-agent dispatch <role>` (then the LLM executes the returned toolCall) from `peaks-solo`, the following sections of THIS skill are **suspended** for the sub-agent run:
 
+- **Session id** — use the parent's sid (read `.peaks/_runtime/session.json` or pass `--session-id <parent-sid>` to any session-creating CLI). Do NOT spawn your own session. The new `peaks session info --active` reads the canonical binding for you.
 - **Skill presence (MANDATORY first action)** — do NOT call `peaks skill presence:set peaks-ui`. The sub-agent must not overwrite `.peaks/.active-skill.json`; the main Solo loop owns that file. If you need to mark your own state, write a marker file at `.peaks/<session-id>/system/sub-agent-ui.json` and only that.
 - **Workspace initialization** — Solo has already run `peaks workspace init` before fan-out. Do not re-run it.
 - **Mode selection** — Solo has already chosen the mode.
@@ -354,3 +355,29 @@ Use `peaks capabilities --source access-repo --json` and `peaks capabilities --s
 Do not own backend architecture, non-UI implementation, runtime hook installation, or final QA acceptance.
 
 Reference: `references/workflow.md`.
+
+## Sub-agent context governance (G7 + G7.7 + G8 + G9 — slice #010)
+
+> UI sub-agents follow the same G7 metadata-only + G8.6 share protocol. UI artifacts (design drafts, component scaffolds) can be large binary-ish files; the 1MB artifact size limit (G7.3) applies. Detailed: `skills/peaks-solo/references/context-governance.md`.
+
+### G7 — UI sub-agent protocol
+
+1. Write design draft / component scaffold to `.peaks/_sub_agents/<sid>/artifacts/<rid>-ui-001.md` (path convention mandatory; size ≤ 1MB).
+2. Call `peaks sub-agent dispatch --write-artifact <path>` to register ArtifactMeta.
+3. Main LLM sees metadata-only view (~200 chars/UI sub-agent).
+
+### G8.6 — UI sub-agent prompt template
+
+```
+You are sub-agent role ui, batch <batchId>.
+
+PROTOCOL (mandatory):
+1. On start: `peaks sub-agent shared-read --batch <batchId> --json`.
+2. While running: write share entry `peaks sub-agent share --key "ui.design-blocker" --value {"reason": "..."}`.
+3. On completion: `peaks sub-agent share --key "ui.completed" --value <artifact-meta>` BEFORE final heartbeat (RL-23).
+```
+
+### G9 — UI prompt size self-check
+
+Same as RD/QA. UI design descriptions can grow large; use `--use-headroom` proactively.
+