peaks-loop 3.0.0

package/skills/peaks-solo/references/skill-presence-and-title.md

@@ -0,0 +1,31 @@
+# Step 2 + 2.5 — Skill presence and session title
+
+> Combined body for `### Peaks-Cli Step 2: Re-set skill presence with the chosen mode` and `### Peaks-Cli Step 2.5: Set session title`.
+
+## Step 2 — Re-set skill presence
+
+Step 0 already set presence with no mode. Now that the mode is known (user selected or explicitly named), re-run presence:set so the header/status line shows the profile:
+
+```bash
+peaks skill presence:set peaks-solo --project <repo> --mode <mode-value> --gate startup
+```
+
+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
+peaks statusline install --project <repo>   # idempotent; skips if already installed
+```
+
+Then display the compact status header: `Peaks-Cli Skill: peaks-solo | Peaks-Cli Gate: startup | Next: <one short action>`. Display this header on EVERY turn while the skill is active.
+
+Update with `peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate <gate>` when gates change. The presence file persists across the full workflow lifecycle — do NOT clear it at workflow end.
+
+## Step 2.5 — Set session title
+
+Extract a short (8-20 Chinese characters, or 4-10 English words) descriptive title from the user's first request. The title should capture the core task — e.g. "修复登录页OAuth回调异常", "添加暗色模式开关", "搭建项目基础架构". Then run:
+
+```bash
+peaks session title $(peaks session info --active --project "$(git rev-parse --show-toplevel)" --json | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['sessionId'])") "<title>"
+```
+
+If the session directory already has a title (check via `peaks session list --json`), skip this step — the title is already set.

package/skills/peaks-solo/references/standards-preflight.md

@@ -0,0 +1,23 @@
+# Project standards preflight
+
+> Body of `## Peaks-Cli Project standards preflight`. Before orchestrating an end-to-end code repository workflow, gather the project standards preflight status from RD and QA by calling the Peaks-Cli CLI:
+
+- `peaks standards init --project <path> --dry-run`
+- `peaks standards update --project <path> --dry-run`
+
+Use `standards init` for first-time creation and `standards update` for existing `CLAUDE.md` append/review behavior. In `full-auto` and `swarm` profiles, `--apply` runs automatically after `--dry-run` succeeds — these files live inside the target project, are required for downstream skill preflight, and producing them is part of finishing the workflow (Peaks-Cli Gate G enforces this). `assisted` and `strict` profiles pause for explicit user confirmation between dry-run and apply.
+
+**CRITICAL — Standards must reflect the project scan.** When generating or updating `CLAUDE.md`, the content must reference concrete findings from `.peaks/_runtime/<sessionId>/rd/project-scan.md`: the detected component library (e.g. "This project uses antd 5.x"), CSS solution (e.g. "Uses Less via Umi"), build tool, state management, and routing. Never emit a generic template that says "read .claude/rules/..." without naming the actual project stack. If the project-scan has not been run yet, run it before standards init/update.
+
+**Legacy projects additionally** — when archetype ∈ {legacy-frontend, legacy-fullstack, frontend-monorepo}, the `CLAUDE.md` Conventions section MUST extract concrete naming, directory, service-layer, and hooks conventions from `.peaks/_runtime/<sessionId>/system/existing-system.md` and record them as hard constraints for new code. It must also list the `## Legacy constraints` from `project-scan.md` (class components, moment, enzyme, etc.) and instruct that new code in the same module preserves those patterns unless PRD explicitly authorizes modernization. A `CLAUDE.md` for a legacy project that contains only generic rule pointers without naming the actual conventions is a blocking violation — regenerate it.
+
+Do not hand-write standards file mutations inside the skill.
+
+For project-analysis requests such as "分析项目" / "分析下这个项目", Step 0 still applies: the workspace is initialized and `peaks-solo` presence is set before any analysis output. These requests run the lightweight analysis branch (project scan + standards dry-run) rather than the full RD/QA pipeline, but they never skip workspace anchoring or exit the workflow. The handoff must include an explicit **Standards increment** section. Report the current `CLAUDE.md` and `.claude/rules/**` status from the dry-run output as incremental deltas, not just a generic preflight note:
+
+- whether `CLAUDE.md` is missing, existing, planned, skipped, appended, or review-only;
+- which `.claude/rules/**` files are planned, existing, skipped, appended, or review-only;
+- whether writes were applied or intentionally left as dry-run because authorization or scope was absent;
+- the exact next action if standards should be applied later.
+
+If the dry-run output lacks enough detail to explain those deltas, say that the standards increment is unknown and keep standards application blocked until another `peaks standards init/update --dry-run` provides evidence.

package/skills/peaks-solo/references/step-0-55-1x-detection.md

@@ -0,0 +1,82 @@
+# Step 0.55 — 1.x → 2.0 detection reference
+
+> Body of `### Peaks-Cli Step 0.55`. Slice: 2026-06-12-solo-step-0-55-1x-detection.
+
+## Why this step exists
+
+The peaks-cli 1.x → 2.0 closeout ships:
+
+1. A postinstall that auto-detects 1.x state and dispatches the upgrade (slice 1, commit `b6e34e6`).
+2. A standards-migrate path that thins `.claude/rules/**/*.md` and scaffolds `.peaks/standards/` (slice 2, commit `33dd392`).
+3. **THIS STEP** — a peaks-solo startup sequence probe that detects 1.x state when the user invokes `/peaks-solo` directly in a 1.x consumer project, and prompts the user to upgrade.
+
+The 1.x user experience is: "I just typed /peaks-solo. Why is it not working in 2.0 mode?" Step 0.55 catches this case and surfaces an `AskUserQuestion` with a one-click upgrade.
+
+## Detection algorithm
+
+```bash
+# 1. Read-only probe via the umbrella CLI
+peaks upgrade --detect-1x --project <root> --json
+```
+
+The CLI returns:
+```json
+{
+  "ok": true,
+  "command": "upgrade.detect-1x",
+  "data": {
+    "isOneX": true,
+    "signals": [
+      "<path> has schema_version 1.0.0, expected '2.0.0'",
+      "..."
+    ],
+    "projectRoot": "/path/to/project",
+    "configPath": null
+  },
+  "warnings": [],
+  "nextActions": [
+    "Detected 1.x state. peaks-solo Step 0.55 should present an AskUserQuestion to invoke `peaks upgrade --to 2.0 --auto --project /path/to/project`."
+  ]
+}
+```
+
+The detection logic mirrors `scripts/install-skills.mjs:detect1xProjectState` (canonical implementation) — it walks up to find `.peaks/_runtime/`, then sniffs:
+
+1. `~/.peaks/config.json` for `version: 1.x`
+2. `<projectRoot>/.claude/rules/common/dev-preference.md` for "peaks progress"
+3. `<projectRoot>/.peaks/preferences.json` for missing or non-`2.0.0` `schema_version`
+
+The TS mirror in `src/services/upgrade/1x-detector-service.ts` is the canonical entrypoint for the skill; the postinstall `.mjs` version is the canonical entrypoint for the npm-install flow. The two implementations MUST stay in parity (a parity test is in the slice's test suite).
+
+## AskUserQuestion (only when `isOneX: true`)
+
+| Option | What it does |
+|---|---|
+| Run `peaks upgrade --to 2.0 --auto --project <root>` (Recommended) | Invokes the umbrella. The user sees the 6 sub-step results in the terminal. After the upgrade, re-run peaks-solo with the standing 2.0 layout. Persist `autoUpgradePrompt: opt-in` to `.peaks/preferences.json`. |
+| Skip for this session | Continue with the standing 1.x layout. Persist `autoUpgradePrompt: skip-this-session` to `.peaks/preferences.json`. The next time the user invokes peaks-solo in this project, the question re-asks. |
+| Never ask again for this project | Persist `autoUpgradePrompt: skip-forever` to `.peaks/preferences.json`. Step 0.55 becomes a no-op for this project from now on. The user can re-enable later by removing the `autoUpgradePrompt` key from preferences.json. |
+
+## Persistence contract
+
+The decision is persisted via `peaks preferences set --project <root> --key autoUpgradePrompt --value <opt-in|skip-this-session|skip-forever> --apply`. Subsequent Step 0.55 invocations read the value first:
+
+- If `opt-in` (and Step 0.55 is the first invocation in the session), the user has already opted in; auto-run the umbrella without re-asking.
+- If `skip-this-session`, the user already said no this session; skip without re-asking (but re-ask next session).
+- If `skip-forever`, the user said no permanently; skip without re-asking.
+- If the key is absent, present the AskUserQuestion.
+
+## What is NOT in this step
+
+- The auto-upgrade execution itself: the umbrella is invoked via the AskUserQuestion's recommended option. The umbrella's behavior (6 sub-commands + write-upgrade-record) is documented in the umbrella's own help text.
+- The postinstall auto-dispatch: that's `scripts/install-skills.mjs:autoUpgrade1xProjectIfPresent`, which fires fire-and-forget on `npm i -g peaks-cli@2.0`. Step 0.55 is the user-invoked path.
+- Re-authoring the 1.x detector heuristics: the implementation is a 1:1 mirror of the canonical `.mjs` version. Drift is prevented by the parity test.
+
+## How this integrates with the rest of the workflow
+
+- Step 0.5 (OpenSpec opt-in) — runs first if `openspec/` is missing.
+- Step 0 (anchor) — runs always.
+- Step 0.7 (resume detection) — runs after Step 0.
+- **Step 0.55 (1.x detection) — runs after Step 0.7, only when the project is not on a 2.0 layout.**
+- Step 1 (mode selection) — runs after Step 0.55.
+
+The 1.x detection is intentionally placed AFTER Step 0.7 because the user might already have a 1.x-converted in-flight slice; the resume flow takes precedence over the upgrade prompt.

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

@@ -0,0 +1,334 @@
+# 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.
+
+**LLM anti-collision note:** Do NOT guess flag names. The ONLY prompt flag is `--prompt <text>`. If unsure, run `peaks sub-agent dispatch <role> --help` first (see canonical signature below).
+
+## 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) — **2.1.0** (slice 2026-06-23-audit-4th #E1):
+
+> **Audit-3rd #4 + audit-4th #E1**: the `data.prompt` field was
+> deliberately removed from the CLI envelope. Prompts can carry user
+> content (sometimes test credentials / internal URLs) that has no
+> business landing in shell history, log aggregators, or tmux
+> scrollback. The dispatch record on disk (gitignored under
+> `.peaks/_sub_agents/`) keeps the prompt for the sub-agent to read;
+> CLI stdout stays metadata-only. Surface `originalPromptSize` +
+> `promptSize` so the LLM-side runner can still reason about headroom
+> without seeing the content. The prompt content the LLM should pass
+> through lives in `data.toolCall.args.prompt` (the IDE-arg the
+> consumer passes to the tool), NOT in the outer envelope.
+
+```json
+{
+  "ok": true,
+  "command": "sub-agent.dispatch",
+  "data": {
+    "envelopeVersion": "2.1.0",
+    "role": "rd",
+    "ide": "claude-code",
+    "originalPromptSize": 4321,
+    "promptSize": 4321,
+    "toolCall": {
+      "name": "Task",
+      "args": {
+        "subagent_type": "general-purpose",
+        "description": "rd for rid=002-2026-06-07-...",
+        "prompt": "<complete prompt the LLM should pass through to the tool>"
+      }
+    },
+    "dispatchRecordPath": ".peaks/_sub_agents/2026-06-06-session-5b1095/dispatch-002-2026-06-07-...-...json",
+    "batchId": "<uuid>",
+    "dispatchedInBatch": 3,
+    "headroomCompressed": false,
+    "headroomResult": null,
+    "forcedAt": null,
+    "contextImpact": {
+      "promptBytes": 4321,
+      "artifactBytes": 0,
+      "totalBytes": 4321
+    },
+    "artifactMetas": []
+  },
+  "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.
+
+> **Slice 2026-06-23-audit-4th #F2 callout**: the prompt content the
+> LLM should pass through lives in `data.toolCall.args.prompt` (the
+> IDE-arg the consumer passes to the tool), NOT in the outer envelope
+> (`data.prompt` was removed in slice 2026-06-23-audit-3rd #4; see the
+> `envelopeVersion: '2.1.0'` marker and the `envelope-contract.md`
+> reference for the full contract). A reader skimming the example
+> should not conflate the two fields.
+
+**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 #016 retirement (G3 prompt template — MCP subsystem removed)**:
+The MCP-decouple paragraph from slice #007-007 no longer applies.
+peaks-cli no longer manages MCP install or invocation. Sub-agents
+check their own tool list for `mcp__<server>__*` entries and invoke
+the tool by name directly. The only prompt-template addition that
+remains is the tool-list self-check:
+
+```
+This task may need an MCP server (playwright, chrome-devtools, figma,
+or context7). Check your tool list for any `mcp__<server>__*` entry.
+If present, invoke the tool by name directly. If absent, tell the user
+the install command for their IDE (Claude Code:
+`claude mcp add <server> -- <npx-command>`) and stop the sub-task until
+the user installs the MCP. Do NOT hand-edit `.claude/settings.json` or
+auto-install on the user's behalf.
+```
+
+The tool-list self-check is required for any sub-agent that needs a
+browser, design, or docs-lookup 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)
+
+---
+
+### Sub-agent mechanism (IDE-agnostic dispatch, NOT Skill tool)
+
+> Body of `### Sub-agent mechanism`. **Solo is itself a skill running in the current session. To invoke a role in the Swarm, Solo MUST call the IDE-agnostic dispatch primitive `peaks sub-agent dispatch <role>` — NOT the `Skill` tool, NOT any IDE-private sub-agent literal.** The `Skill` tool is single-stack and blocking; using it for "parallel" work was the v1.x illusion of concurrency. The dispatch CLI is the only mechanism that keeps SKILL.md free of IDE-private tool names and lets the same prompt work on every registered IDE.
+
+Each sub-agent dispatch call looks like:
+
+```
+peaks sub-agent dispatch <role> \
+  --prompt "<paste peaks-<role>/SKILL.md body, minus the self-presence / Step 0 blocks,
+            plus the runtime arguments: project=<repo>, session-id=<session-id>, request-id=<rid>, mode=<mode>,
+            plus the explicit output contract: 'Write your artefacts to the paths listed below and
+            return only the list of paths. Do not call Skill(...). Do not set presence. Do not
+            hand back prose.', plus the heartbeat instruction: 'While running, call
+            peaks sub-agent heartbeat --record <dispatchRecordPath> --status <state> --progress <pct> --note \"<text>\"
+            at least every 30 seconds.'>" \
+  --request-id <rid> --session-id <session-id> --project <repo> --json
+```
+
+Then the LLM takes `data.toolCall` from the envelope (a `{name, args}` descriptor), looks up the tool by `name` in its environment, and invokes it with `args` — IDE-private, no SKILL.md hardcoding.
+
+The role's required artefact paths (also see peaks-ui/rd/qa SKILL.md and `references/swarm-dispatch-contract.md`):
+
+| Role | Writes | Reads (PRD-side) |
+|---|---|---|
+| `ui` | `.peaks/_runtime/<sessionId>/ui/design-draft.md`, `.peaks/_runtime/<sessionId>/ui/requests/<rid>.md` | PRD body, project-scan, archetype |
+| `rd-planning` | `.peaks/_runtime/<sessionId>/rd/tech-doc.md` (feature/refactor) or `.peaks/_runtime/<sessionId>/rd/bug-analysis.md` (bugfix) | PRD body, project-scan, existing-system, codegraph |
+| `qa-test-cases` | `.peaks/_runtime/<sessionId>/qa/test-cases/<rid>.md` | PRD body, RD planning artefact, project-scan, codegraph |
+
+**Solo launches all sub-agents in the swarm plan in a single message (multiple `peaks sub-agent dispatch` calls in parallel, each followed by execution of the returned toolCall)** — this is what gives real concurrency. Do not sequentialize them. The CLI returns N toolCall descriptors; the LLM fires all N in the same message; the IDE dispatches them concurrently; Solo then waits for all to return, runs `ls` checks against the paths above (Peaks-Cli Gate B), and only then advances to RD implementation.
+
+**Hard prohibitions on sub-agents** (also passed in each dispatch prompt):
+
+- Do NOT call `Skill(skill="...")` — sub-agents must not recursively activate skills, that defeats the fan-out.
+- Do NOT call `peaks skill presence:set` — only the main Solo loop owns `.peaks/.active-skill.json`. Sub-agents write to a per-agent marker file `.peaks/_runtime/<sessionId>/system/sub-agent-<role>.json` if they need to record state, but never the main presence file.
+- Do NOT open interactive user prompts. If a sub-agent needs clarification, it must return a `blocked` verdict in its return string and let Solo handle the user message.
+- Do NOT commit, push, install hooks, or apply settings.json mutations. Only Solo holds those permissions.
+  - **Reinforced (2026-06-28 incident):** an RD sub-agent silently auto-committed its own diff during a fix-callerid-leak dispatch (commit `bff4dff`). The orchestrator caught the unauthorized commit on the next turn but the user had to manually re-approve. **Every dispatch prompt MUST copy the verbatim block below into its `--prompt` argument** so the sub-agent sees the rule with full weight:
+
+    ```
+    ## Commit / push policy (verbatim, mandatory)
+    - Do NOT run `git commit`, `git push`, `git tag`, `git checkout -b`, or any
+      state-mutating git command. Leave the diff on disk and return the
+      diff summary in your final message. The orchestrator (Solo) owns the
+      commit / push decision; it will run `git status` and `git diff` after
+      your return and decide whether to commit.
+    - If you believe a commit is urgent (e.g. emergency hotfix), return
+      `verdict: blocked-by-orchestrator-policy` and explain. Do NOT commit
+      yourself even in emergencies.
+    ```
+- **Do write heartbeats** — call `peaks sub-agent heartbeat --record <dispatchRecordPath> --status running --progress <pct> --note "<text>"` at least every 30s (see `references/sub-agent-dispatch.md` §G6 for the full contract). The parent Dispatcher uses these to render the live status line during the wait.
+
+After every sub-agent dispatch returns, Solo **restores presence** once (not per-agent), then continues to Gate B verification:
+
+```bash
+peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate swarm-converged
+```