peaks-loop 3.1.2 → 4.0.0-beta.10

package/skills/peaks-code/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-code / 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-code, 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 Code / 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-loop
+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-code 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-loop 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-code] swarm 3/3 running | rd-planning 45% (12s ago) | qa-test-cases 30% (5s ago) | ui-design 20% (2s ago)
+[peaks-code] swarm 3/3 running | rd-planning 70% (8s ago) | qa-test-cases 50% (3s ago) | ui-design 30% (6s ago)
+...
+[peaks-code] 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-code 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-code 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-code/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`. **Code is itself a skill running in the current session. To invoke a role in the Swarm, Code 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 |
+
+**Code 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; Code then waits for all to return, runs `ls` checks against the paths above (Peaks-Loop 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 Code 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 Code handle the user message.
+- Do NOT commit, push, install hooks, or apply settings.json mutations. Only Code 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 (Code) 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, Code **restores presence** once (not per-agent), then continues to Gate B verification:
+
+```bash
+peaks skill presence:set peaks-code --project <repo> --mode <mode> --gate swarm-converged
+```

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

@@ -0,0 +1,230 @@
+# Swarm dispatch contract
+
+> Reference for `peaks-code` Swarm phase and the role sub-agents (`peaks-ui` / `peaks-rd` planning / `peaks-qa` test-cases). Defines the **mechanism** of fan-out: how Code launches sub-agents, what the sub-agent prompt must contain, what the sub-agent must return, and how Code reduces the result.
+
+## Peaks-Loop Swarm parallel phase (sub-agent fan-out, default)
+
+> **Slice 5 (2026-06-23) + slice 2026-06-23-audit-4th #F3:** the
+> previous "conditional swarm" framing is replaced by the **default
+> fan-out rule** in `skills/peaks-code/SKILL.md` §"Peaks-Loop Default
+> sub-agent fan-out". When the slice DAG has ≥ 2 leaves at the same
+> topological level, dispatch goes through
+> `peaks sub-agent dispatch --from-dag` (NOT one-at-a-time). The
+> gate logic below remains the canonical source for: PRD state,
+> request type, frontend touch, mode-driven shape, and degradation
+> rules. As of 2.8.4 the `'serial'` opt-out was removed by user
+> direction — single-sub-agent dispatch is no longer permitted when
+> ≥ 2 leaves exist at one topological level (see
+> `references/fanout-mandatory.md`).
+
+The Swarm phase is the **default** for any DAG with ≥ 2 leaves at
+the same topological level. Code derives the fan-out set from the
+DAG topology — not from a default of "always launch three", and
+not from a strict conditional check. The swarm gate (PRD state +
+request type + frontend touch), mode-driven fan-out shape, and
+degradation rules live in the references file.
+
+## 1. Why this exists
+
+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 (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 Code launching N dispatch calls in a single message and the platform scheduling the returned toolCalls concurrently.
+
+```
+You are a sub-agent invoked by peaks-code. You are NOT the main Claude session.
+Your job: execute ONE role from the peaks skill family and write its artefact(s).
+Return a compact JSON envelope — do not write prose.
+
+## Hard prohibitions
+- Do NOT call Skill(skill="..."). You are the role.
+- Do NOT call `peaks skill presence:set` — the main loop owns .peaks/.active-skill.json.
+  If you need to record state, write to .peaks/_runtime/<session-id>/system/sub-agent-<role>.json.
+- Do NOT commit, push, install hooks, or apply settings.json mutations.
+- Do NOT ask the user interactive questions. If you need clarification, return
+  {"status":"blocked","blockedReason":"<text>"} and let the main loop handle it.
+
+## Runtime arguments (provided by Code)
+- project: <repo>            (git repo root, NOT a sub-package)
+- session-id: <sid>          (from .peaks/.active-skill.json or .peaks/.session.json)
+- request-id: <rid>          (PRD id)
+- type: <type>               (feature | bugfix | refactor | config | docs | chore)
+- mode: <mode>               (full-auto | swarm | assisted | strict)
+- project-scan-path: <path>  (read this for component library / CSS / build tool)
+- existing-system-path: <path>  (legacy projects only)
+- frontendOnly: <bool>       (from project-scan)
+- frontendKeywordHit: <bool> (Code's PRD scan result)
+```
+
+### 3.2 peaks-ui sub-agent prompt
+
+Append after the common header:
+
+```
+## Role: UI design direction
+You are running peaks-ui. Produce design direction, not code. RD will implement.
+
+Steps:
+1. peaks request init --role ui --id <rid> --project <repo> --apply --type <type> --json
+2. peaks request show <rid> --role prd --project <repo> --json
+3. Read <project-scan-path> for component library / CSS framework.
+4. Run the prototype fidelity gate: Figma file? PRD visuals? Headed browser?
+5. Write TWO artefacts:
+   - .peaks/_runtime/<sid>/ui/design-draft.md
+   - .peaks/_runtime/<sid>/ui/requests/<rid>.md
+6. Return:
+   {
+     "role": "ui",
+     "rid": "<rid>",
+     "status": "ok" | "blocked" | "skipped",
+     "artefacts": [".peaks/_runtime/<sid>/ui/design-draft.md", ".peaks/_runtime/<sid>/ui/requests/<rid>.md"],
+     "warnings": [],
+     "blockedReason": null
+   }
+
+If you determine the request is non-visual (no UI surface, no design impact),
+return {"status":"skipped","reason":"non-frontend-request"} so Code can record
+the misfire in sc/swarm-plan.json.
+```
+
+### 3.3 peaks-rd (planning) sub-agent prompt
+
+```
+## Role: RD planning
+You are running peaks-rd's planning step. Produce the planning artefact, not code.
+Code is written in a later sub-agent or inline run.
+
+Steps:
+1. peaks request init --role rd --id <rid> --project <repo> --apply --type <type> --json
+2. peaks request show <rid> --role prd --project <repo> --json
+3. peaks request show <rid> --role ui  --project <repo> --json  (if ui in plan)
+4. Read <project-scan-path>. If absent and Code did not pre-create it, create it
+   by running `peaks scan archetype --project <repo> --json` and copying the JSON
+   into rd/project-scan.md.
+5. Read <existing-system-path> if archetype is legacy-*.
+6. Write the type-appropriate planning artefact:
+   - feature | refactor  → .peaks/_runtime/<sid>/rd/tech-doc.md
+   - bugfix              → .peaks/_runtime/<sid>/rd/bug-analysis.md
+   - config | docs | chore → no planning artefact required. Return skipped.
+7. Return:
+   {
+     "role": "rd-planning",
+     "rid": "<rid>",
+     "status": "ok" | "blocked" | "skipped",
+     "artefacts": [".peaks/_runtime/<sid>/rd/tech-doc.md"],   // or [] when skipped
+     "warnings": [],
+     "blockedReason": null
+   }
+```
+
+### 3.4 peaks-qa (test-cases) sub-agent prompt
+
+```
+## Role: QA test-case generation (planning, not execution)
+You are running peaks-qa's planning step. Produce test cases, do NOT execute them.
+The execution step runs after RD implementation in a separate sub-agent.
+
+Steps:
+1. peaks request init --role qa --id <rid> --project <repo> --apply --type <type> --json
+2. peaks request show <rid> --role prd --project <repo> --json
+3. peaks request show <rid> --role rd  --project <repo> --json
+4. Read <project-scan-path>.
+5. Write .peaks/_runtime/<sid>/qa/test-cases/<rid>.md with test cases linked to PRD
+   acceptance items (use **Acceptance:** A1, A2 style).
+6. Return:
+   {
+     "role": "qa-test-cases",
+     "rid": "<rid>",
+     "status": "ok" | "blocked" | "skipped",
+     "artefacts": [".peaks/_runtime/<sid>/qa/test-cases/<rid>.md"],
+     "warnings": [],
+     "blockedReason": null
+   }
+
+If --type is docs|chore, return {"status":"skipped","reason":"type=<type>"} —
+no acceptance surface to plan tests for.
+```
+
+## 4. Reducer (Code side)
+
+After all sub-agent dispatch calls return and the LLM has invoked the toolCalls, Code:
+
+1. Restores presence ONCE (not per-agent):
+   ```
+   peaks skill presence:set peaks-code --project <repo> --mode <mode> --gate swarm-converged
+   ```
+2. Runs `ls` checks against `sc/swarm-plan.json` — every promised artefact must exist (Gate B hard). If any are missing, apply the degradation rules in "Degradation when swarm roles fail or are absent" (main SKILL.md).
+3. Updates `sc/swarm-plan.json` with the final status of each sub-agent (ok / blocked / skipped / error).
+4. Advances to step 4 (RD implementation) with all the artefacts in hand.
+
+## 5. Presence restoration (single-shot)
+
+Sub-agents are explicitly forbidden from calling `peaks skill presence:set`. That means `.peaks/.active-skill.json` does not move during the fan-out. Code sets it to `gate=swarm-fan-out` before fan-out and to `gate=swarm-converged` once after all Tasks return. The status header (the `Peaks-Loop Skill: peaks-code | Peaks-Loop Gate: <gate>` line) therefore reads consistently across the fan-out window.
+
+If a sub-agent is misbehaving and writes to `.peaks/.active-skill.json` anyway, the next Code presence-set (after fan-out) overwrites it — the bug self-heals on the next gate advance, but the swarm-phase display may be off. The hard prohibition is there to prevent this; Code should still treat the file as a single-writer resource.
+
+## 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-code) 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-code where it belongs.
+
+## 7. Tests / dogfood
+
+- `peaks scan archetype --project <repo> --json` must keep emitting `frontendOnly` and `frontendOnlyReason`. Both fields are read here and by the existing pre-RD scan contract.
+- `peaks request show <rid> --role prd --json` must surface the `--type` chosen at `peaks request init`. Sub-agents pass it through unchanged.
+- `peaks skill presence:set` must remain single-writer-friendly (the sub-agents do not call it).
+- Smoke test: a full-auto peaks-code run on a `legacy-frontend` project with a UI-affecting PRD should produce `sc/swarm-plan.json` containing all three sub-agents and three corresponding artefacts in `ui/`, `rd/`, `qa/`.
+
+---
+
+### Swarm gate (decide BEFORE fan-out)
+
+> Body of `### Swarm gate`. Before launching any sub-agent, Code must compute the **swarm plan** from three signals:
+
+1. **PRD state** — `prd/requests/<rid>.md` must be in state `confirmed-by-user` or `handed-off`. If not, STOP. The Swarm is downstream of PRD, not a substitute for it.
+2. **Request type** (`--type` from `peaks request init`):
+   - `feature` / `refactor` / `bugfix` → RD(planning) and QA(test-cases) are always in the swarm
+   - `config` / `docs` / `chore` → no swarm. RD/QA artefacts are not required by Gates B/C/D for these types. Skip the Swarm phase entirely and proceed to step 4 (RD implementation) with only the PRD in hand.
+3. **Frontend touch** — does the request affect user-visible behavior? This is decided by:
+   - Reading `.peaks/project-scan/project-scan.md` `## Project mode` for `frontendOnly` (project-shape signal)
+   - **AND** scanning the PRD body for frontend keywords: 页面 / 组件 / 表单 / 弹窗 / 表格 / 样式 / 布局 / 交互 / UI / UX / page / component / form / modal / table / styling / layout / interaction
+   - UI joins the swarm when (a) is `true` OR (b) matches. Both signals required `false` to skip UI.
+
+Code records the swarm plan in `.peaks/_runtime/<sessionId>/sc/swarm-plan.json` so SC and TXT can audit what was launched:
+
+```json
+{
+  "rid": "<rid>",
+  "type": "feature",
+  "frontendOnly": true,
+  "frontendKeywordHit": true,
+  "subAgents": ["ui", "rd-planning", "qa-test-cases"]
+}
+```
+
+Sub-agent presence in this list = Code launched a Task for it. Absence = the role was skipped with documented reason.
+
+### Mode-driven fan-out shape
+
+> Body of `### Mode-driven fan-out shape`.
+
+| Mode | How the swarm plan is decided | What Code does |
+|---|---|---|
+| `full-auto` | Compute plan from signals above, no question to user | Auto-launch all sub-agents in the plan in parallel |
+| `swarm` | Same as `full-auto` | Same as `full-auto` (this profile name is historical — behavior is identical) |
+| `assisted` | `AskUserQuestion` with three options: (a) Full — UI + RD(planning) + QA(test-cases); (b) Backend-only — RD(planning) + QA(test-cases); (c) Sequential — run RD first, then QA, skip UI | Use the user's choice as the plan |
+| `strict` | Same as `assisted` (the question is informational; strict still enforces confirmation gates later) | Same as `assisted` |
+
+In all modes, **the plan must be written to `sc/swarm-plan.json` before any Task call.** Code updates `.peaks/.active-skill.json` to `gate=swarm-fan-out` at this point.
+
+### Degradation when swarm roles fail or are absent
+
+> Body of `### Degradation when swarm roles fail or are absent`.
+
+| Condition | Code action | TXT handoff note |
+|---|---|---|
+| UI sub-agent returns blocked/error | RD continues with PRD visual descriptions | `ui-design-missing` |
+| RD planning sub-agent returns blocked/error | RD continues with PRD-derived planning | `tech-doc-missing` |
+| QA test-cases sub-agent returns blocked/error | RD continues; QA backfills test cases before verdict | `qa-test-cases-missing` |
+| Two or more of the above | Fall back to sequential: `peaks request transition rd → spec-locked` then inline RD run, then QA | `swarm-degraded-to-sequential` |
+| All three fail | Pause workflow; surface to user; request confirmation to continue | `swarm-aborted` |
+
+Skipping the entire swarm (when `--type` is `config|docs|chore`) is not a degradation — record `swarm-skipped: type=<type>` and proceed.