peaks-cli 1.3.2 → 1.3.4

package/skills/peaks-solo/references/headroom-integration.md

@@ -0,0 +1,107 @@
+# Headroom Integration — G7.7 opt-in compression channel
+
+> Slice #010 (G7.7 headroom-ai integration route).
+> Source: https://github.com/chopratejas/headroom
+> Package: `headroom-ai@0.22.4` (Apache-2.0, MIT-compatible).
+> See: `THIRD_PARTY_LICENSES.md` for the license record.
+
+## Why headroom-ai is justified (R-14)
+
+The dev-preference red line "非必要不添加新的 dep" is preserved:
+headroom-ai is the only opt-in mechanism for G7.7 + G9 to compress
+sub-agent prompts that exceed the 75% / 80% threshold. Without
+headroom-ai, `--use-headroom` is a no-op and the only fallback is
+`--force` override at CLI.
+
+The user's explicit reference (https://github.com/chopratejas/headroom)
+is the basis for the dev-preference override.
+
+## API shape (real SDK, not the PRD's spec)
+
+```ts
+import { compress } from 'headroom-ai';
+
+const result = await compress(messages, {
+  model: 'claude-sonnet-4-5-20250929',
+  baseUrl: 'http://localhost:8787',  // local proxy; not used in slice #010
+  apiKey: 'hr_...',                   // Headroom Cloud; not used in slice #010
+  timeout: 30_000,
+  fallback: true,                     // CRITICAL: return original messages if proxy is dead
+  retries: 1,
+  tokenBudget: 4000,                  // compress to fit this limit
+  hooks: new MyHooks(),               // pre/post compression hooks
+});
+
+result.messages          // compressed messages
+result.tokensBefore      // original token count
+result.tokensAfter       // compressed token count
+result.tokensSaved       // tokens removed
+result.compressionRatio  // tokensAfter / tokensBefore
+result.transformsApplied // e.g. ['router:smart_crusher:0.35']
+result.compressed        // false if fallback kicked in
+```
+
+`fallback: true` is the key option: if the proxy is unavailable, the SDK
+returns the original messages + `result.compressed: false` instead of
+throwing. This makes the failure mode non-blocking (RL-22d / RL-32).
+
+## Mode table (peaks wrapper)
+
+The peaks wrapper maps the user-facing `HeadroomMode` to the SDK's
+`tokenBudget` option. Slice #010 does not consume the SDK's internal
+"audit" / "optimize" / "simulate" modes (those are SDK-internal);
+
+| Mode | tokenBudget | Use case |
+|---|---|---|
+| `balanced` (default) | promptSize * 0.40 / 4 | General sub-agent dispatch |
+| `aggressive` | promptSize * 0.20 / 4 | Last-resort large prompt |
+| `conservative` | promptSize * 0.70 / 4 | Sensitive code analysis, accuracy-critical |
+
+The `0.40 / 4` factor approximates 60% byte reduction (1 token ≈ 4 bytes
+for English text). The SDK does its own tokenization internally; the
+`tokenBudget` is a hint, not a hard cap.
+
+## Failure semantics (RL-22d / RL-32)
+
+- `result.compressed === false` → `code: "HEADROOM_UNAVAILABLE"` warning
+- `compress()` throws (network error, JSON parse error) → caught and treated as `HEADROOM_UNAVAILABLE`
+- Import failure (headroom-ai not installed) → caught and treated as `HEADROOM_UNAVAILABLE`
+- **NOT blocking** — peak falls back to G7 metadata-only and continues dispatch
+
+## CCR reversible hydration (slice #011+ TODO)
+
+The PRD mentions "CCR (Cross-Context Reversible)" as a benefit of
+headroom. In the SDK, this is implemented via the `hooks` option on
+`compress()`. A pre/post hook can persist the `ccrHashes` to disk,
+and a later `rehydrate()` call can re-hydrate the compressed prompt
+to the original. Slice #010 does NOT consume CCR — it only uses
+compression. R-17 (CCR for aggressive / conservative modes) is
+deferred to slice #011+.
+
+## Cross-platform behavior (R-19)
+
+- In-process compression (the SDK's library mode) is platform-agnostic.
+- The long-running `headroom proxy` daemon is platform-specific
+  (Unix socket on Linux/macOS, named pipe on Windows). Slice #010
+  does NOT consume the proxy daemon.
+- All headroom-ai calls in slice #010 go through the in-process SDK
+  with `fallback: true`. The peak wrapper at
+  `src/services/context/headroom-client.ts` catches all errors and
+  treats them as fallback.
+
+## What slice #010 does NOT do
+
+- Does NOT install the `headroom proxy` daemon (N-7).
+- Does NOT consume headroom's `SharedContext` directly (G7.7.3 in the
+  PRD); the peak-internal `SharedChannel` (G8) is the cross-sub-agent
+  state store. `buildSharedContextBridge()` is a stub that returns
+  the peak-internal channel ID + a placeholder headroom context ID.
+- Does NOT use the SDK's `audit` / `optimize` / `simulate` modes
+  (those are SDK-internal; the peak wrapper exposes
+  `balanced` / `aggressive` / `conservative` to the user).
+
+## Security + license
+
+- License: Apache-2.0 (MIT-compatible) — see `THIRD_PARTY_LICENSES.md`.
+- Pinned version: exact `0.22.4` (no `^` / `~` range) per dev-preference.
+- `pnpm audit` ran on install; no new high-severity vulnerabilities.

package/skills/peaks-solo/references/runbook.md

@@ -53,10 +53,10 @@ peaks request lint <rid> --role prd --project <repo> --json
 peaks request transition <rid> --role prd --state confirmed-by-user --project <repo> --json
 peaks request transition <rid> --role prd --state handed-off --project <repo> --json
 
-# 3. Peaks-Cli Swarm parallel — sub-agent fan-out (Task tool, NOT Skill tool)
+# 3. Peaks-Cli Swarm parallel — sub-agent fan-out (peaks sub-agent dispatch, NOT Skill tool)
 #    Solo computes the swarm plan from --type + frontendOnly + frontend-keyword scan,
 #    writes it to .peaks/<sid>/sc/swarm-plan.json, then launches one
-#    Task(subagent_type="general-purpose", ...) call per sub-agent in the same message.
+#    `peaks sub-agent dispatch <role>` call per sub-agent in the same message.
 #    See "Peaks-Cli Swarm parallel phase" above for the full decision table and the
 #    prompt template; the role's required artefact paths are listed there.
 #    Hard rule: do NOT call Skill(skill="peaks-rd" | "peaks-qa" | "peaks-ui") from
@@ -75,7 +75,7 @@ peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate swarm-
 # e.g. if plan = [ui, rd, qa]: run init for ui, rd, qa.
 # If plan = [rd, qa]: run for rd, qa only.
 # If plan = [] (config|docs|chore skip): no inits here, jump to step 4 directly.
-# 3b. Solo issues N Task(subagent_type="general-purpose", ...) calls in ONE message
+# 3b. Solo issues N `peaks sub-agent dispatch <role>` calls in ONE message
 #     (N = len(swarm-plan.subAgents)). Each prompt embeds the role's body minus
 #     Step 0 / presence, plus the runtime args (rid / sid / mode / type / paths).
 # 3c. After fan-out, Solo restores presence once and runs Gate B (ls checks):

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

@@ -0,0 +1,261 @@
+# 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 + MCP-decoupled)
+
+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.
+```
+
+**Slice #007-007-2026-06-07-mcp-decouple (G3 prompt template addition)**:
+when the sub-agent is dispatched into a non-Claude IDE (Trae, Cursor,
+Codex, Qoder, Tongyi, ...) or into a Claude Code environment where the
+LLM cannot directly invoke the `mcp__<server>__*` tool prefix, the
+sub-agent prompt must additionally include the MCP-decouple instruction
+below. Without it, the sub-agent would either fall back to direct
+`mcp__` invocations (which fail in non-Claude IDEs) or skip MCP
+operations entirely (which breaks RD/QA/UI flows that depend on the
+Playwright, Chrome DevTools, Figma, or Context7 servers).
+
+```
+When you need to use an MCP server (playwright, chrome-devtools, figma, or
+context7), do NOT invoke the `mcp__<server>__*` tool prefix directly. The
+canonical path is `peaks mcp call`:
+
+  peaks mcp call --capability <capabilityId> --tool <toolName> --args-json '<argsObject>' --json
+
+where `<capabilityId>` is one of:
+  - playwright-mcp.browser-validation      (headed browser, primary E2E surface)
+  - chrome-devtools-mcp.browser-debug      (CDP to running Chrome on :9222, secondary)
+  - figma-context-mcp.design-context       (Figma design data, requires FIGMA_API_KEY)
+  - context7.docs-lookup                   (library docs, requires CONTEXT7_API_KEY)
+
+For install / plan / detect, use:
+  peaks mcp list   --json
+  peaks mcp plan   --capability <capabilityId> --json
+  peaks mcp apply  --capability <capabilityId> --yes --json
+
+The `peaks mcp plan` envelope's `envCheck.missing` field is the source of
+truth for required env vars. Do not bake the `mcp__<server>__*` prefix
+into any artifact or message; the prefix is owned by the LLM runtime, not
+by the skill. On Trae, `capabilities.mcpInstall` is `false`; do not
+attempt `peaks mcp apply` on Trae — surface the manual install path
+instead.
+```
+
+The MCP-decouple paragraph is required for any sub-agent dispatched
+into a non-Claude environment or any sub-agent that needs an MCP
+capability. The CLI auto-generates it for `role in (rd, qa, ui, txt)`
+when the active IDE is not `claude-code`; for `role = general-purpose`
+or unknown roles, the caller (the SKILL.md heart of the Dispatcher) must
+add it explicitly.
+
+`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

@@ -250,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

@@ -13,7 +13,7 @@ UI's headed-browser work (visual inspection, regression seed capture, Figma / li
 
 ### Contract 1 — Inspection screenshots must land under .peaks/<sid>/qa/screenshots/
 
-Every `mcp__playwright__browser_take_screenshot` call **MUST** pass `filename` inside `.peaks/<session-id>/qa/screenshots/`, named after the inspection target (e.g. `home-after-cta.png`, `empty-state-v2.png`). Do not let Playwright fall back to the project root. After every batch, run:
+Every Playwright screenshot tool call (via `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_take_screenshot --args-json '<args>' --json`) **MUST** pass `filename` (in the args object) inside `.peaks/<session-id>/qa/screenshots/`, named after the inspection target (e.g. `home-after-cta.png`, `empty-state-v2.png`). Do not let Playwright fall back to the project root. After every batch, run:
 
 ```bash
 ls .peaks/<sid>/qa/screenshots/*.png 2>&1
@@ -28,7 +28,7 @@ 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.
@@ -152,7 +152,8 @@ peaks mcp apply --capability playwright-mcp.browser-validation --yes --json
 
 # 5. drive the running page or prototype through Claude Code MCP tools
 #    (these are not Peaks-Cli CLI commands; they are invoked by the host MCP runtime)
-#    mcp__playwright__browser_navigate         → URL (after allow-list check), launches headed browser
+#    peaks mcp call --capability playwright-mcp.browser-validation --tool browser_navigate --args-json '{"url":"<url>"}' --json
+#    → URL (after allow-list check), launches headed browser
 #
 #    LOGIN GATE (MANDATORY checkpoint):
 #    After browser_navigate, check for login/CAPTCHA/SSO/MFA redirect.
@@ -161,11 +162,19 @@ peaks mcp apply --capability playwright-mcp.browser-validation --yes --json
 #    If user does not confirm within reasonable time → pause and ask.
 #    Only after user confirmation, continue to:
 #
-#    mcp__playwright__browser_take_screenshot  → visible-browser confirmation
-#    mcp__playwright__browser_snapshot         → accessibility tree for regression seeds
-#    mcp__playwright__browser_console_messages → console errors
-#    mcp__playwright__browser_network_requests → failed network
-#    mcp__playwright__browser_close            → end the session cleanly
+#    peaks mcp call --capability playwright-mcp.browser-validation --tool browser_take_screenshot --args-json '{"filename":"<abs-path>"}' --json
+#    → visible-browser confirmation
+#    peaks mcp call --capability playwright-mcp.browser-validation --tool browser_snapshot --args-json '{}' --json
+#    → accessibility tree for regression seeds
+#    peaks mcp call --capability playwright-mcp.browser-validation --tool browser_console_messages --args-json '{}' --json
+#    → console errors
+#    peaks mcp call --capability playwright-mcp.browser-validation --tool browser_network_requests --args-json '{}' --json
+#    → failed network
+#    peaks mcp call --capability playwright-mcp.browser-validation --tool browser_close --args-json '{}' --json
+#    → end the session cleanly
+# The skill body NEVER bakes in the `mcp__playwright__` prefix; the LLM's runtime
+# resolves the tool name from the registered server. The capability id
+# `playwright-mcp.browser-validation` is the contract; the registry is the source of truth.
 
 # 5. write design-draft artifact to .peaks/<session-id>/ui/design-draft.md
 
@@ -229,7 +238,7 @@ Use gstack as a concrete design-review workflow reference for the `Plan → Revi
 - map browser walkthrough concepts to UI regression seeds when runtime validation is approved;
 - keep accessibility, performance, and product-specific visual direction as Peaks-Cli UI acceptance inputs.
 
-For frontend work, especially full-auto mode, use Playwright MCP (`mcp__playwright__browser_navigate` / `browser_snapshot` / `browser_take_screenshot` / `browser_console_messages` / `browser_network_requests` / `browser_close`) to inspect the running page or prototype before accepting the UI direction. Playwright MCP launches a headed browser on demand; if `peaks mcp list --json` does not include `playwright`, install it through `peaks mcp plan/apply --capability playwright-mcp.browser-validation --yes` before attempting to inspect. (Chrome DevTools MCP is a secondary surface that connects to an already-running Chrome via `--remote-debugging-port=9222`; it does NOT launch a browser on its own.) If login, CAPTCHA, SSO, or MFA appears, the visible browser is already open; wait for the user to complete login and explicitly confirm completion before continuing. Capture only sanitized visible regressions, weak hierarchy, generic template patterns, console errors, and interaction problems as UI feedback that should return to design/RD before handing off to QA; do not retain login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material. Canonical browser workflow: `peaks-solo/references/browser-workflow.md`.
+For frontend work, especially full-auto mode, use Playwright MCP to inspect the running page or prototype before accepting the UI direction. The skill body never bakes in the `mcp__playwright__` prefix; it uses `peaks mcp call --capability playwright-mcp.browser-validation --tool <name> --args-json '<args>' --json` for every browser operation (browser_navigate / browser_snapshot / browser_take_screenshot / browser_console_messages / browser_network_requests / browser_close). Playwright MCP launches a headed browser on demand; if `peaks mcp list --json` does not include `playwright`, install it through `peaks mcp plan --capability playwright-mcp.browser-validation --json` then `peaks mcp apply --capability playwright-mcp.browser-validation --yes --json` before attempting to inspect. (Chrome DevTools MCP is a secondary surface that connects to an already-running Chrome via `--remote-debugging-port=9222`; it does NOT launch a browser on its own.) If login, CAPTCHA, SSO, or MFA appears, the visible browser is already open; wait for the user to complete login and explicitly confirm completion before continuing. Capture only sanitized visible regressions, weak hierarchy, generic template patterns, console errors, and interaction problems as UI feedback that should return to design/RD before handing off to QA; do not retain login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material. Canonical browser workflow: `peaks-solo/references/browser-workflow.md`.
 
 ## Prototype fidelity gate (MANDATORY — check BEFORE any design work)
 
@@ -239,7 +248,7 @@ For frontend work, especially full-auto mode, use Playwright MCP (`mcp__playwrig
 
 Check these sources in order:
 
-1. **Figma design file** — If the PRD links to a Figma file, use `mcp__Figma_AI_Bridge__get_figma_data` to fetch the design. The Figma data IS the design. Replicate layout, spacing, colors, typography, and component choices exactly as specified.
+1. **Figma design file** — If the PRD links to a Figma file, use `peaks mcp call --capability figma-context-mcp.design-context --tool get_figma_data --args-json '{"fileKey":"<key>"}' --json` to fetch the design (the skill body never bakes in the `mcp__Figma_AI_Bridge__` prefix; the prefix is owned by the LLM runtime, and `FIGMA_API_KEY` must be set in the env before `peaks mcp apply` — the plan envelope's `envCheck.missing` field is the source of truth). The Figma data IS the design. Replicate layout, spacing, colors, typography, and component choices exactly as specified.
 2. **PRD document screenshots** — If the PRD source (Feishu/Lark doc) contains screenshots or mockups, those ARE the visual target. Check `.peaks/<id>/prd/source/` for saved screenshots.
 3. **PRD visual descriptions** — If the PRD explicitly describes layout, component placement, or visual behavior, those descriptions are constraints, not suggestions.
 4. **Existing application pages** — If modifying an existing app, the existing visual language (component library, spacing patterns, color usage) is the fidelity baseline. New pages must match existing conventions.
@@ -355,3 +364,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.
+