peaks-cli 1.2.4 → 1.2.6

package/skills/peaks-solo/SKILL.md

@@ -9,6 +9,16 @@ Peaks-Cli Solo is the orchestration facade for the Peaks-Cli short skill family.
 
 Use this skill to identify the user scenario, recommend an execution mode, coordinate role skills, and produce the final handoff report. Do not collapse role responsibilities into this skill.
 
+## Skill-first architecture note (read once, internalise)
+
+This skill is the **primary surface**. The `peaks <cmd>` CLI is **auxiliary** — invoked by the skill prompt when a primitive is the right tool (atomic side effect, machine-enforced gate, structured JSON for a downstream decision, or backstop the LLM cannot skip). Concretely:
+
+- Behaviour that only an LLM in a skill prompt would use (e.g. "scan a handoff for memory blocks", "decide if a stable fact deserves persistence") lives **here in the SKILL.md**, not as a new CLI command.
+- The CLI earns its keep when it is (a) hook- / script- / CI-invokable, (b) the consumer needs a structured JSON envelope to gate a downstream decision, or (c) it is a destructive side effect that needs an explicit `--apply` opt-in.
+- When you reach for `peaks <X> --project <repo> --json` in a runbook step, that command is the **contract** you are calling; the LLM work around it (deciding what to pass, interpreting the response, deciding the next step) is what this skill owns.
+
+See `.claude/rules/common/dev-preference.md` for the full dev policy and the decision template. The user-facing consequence: every iteration on this skill and the rest of the peaks-* family is judged first by "is this skill work or CLI work?", and only the latter opens a new command.
+
 ## Code-Change Red Line (BLOCKING — read before ANY tool call)
 
 **Peaks-Cli Solo is an orchestrator, NOT an implementer. You MUST NOT write, edit, or modify any application source code directly.**
@@ -17,12 +27,12 @@ Every code change — bugfix, feature, refactor, or config — MUST go through t
 
 ```
 peaks-solo (orchestrate only)
-  → Skill(skill="peaks-rd")  ← ALL code changes happen HERE
+  → RD work   ← ALL code changes happen HERE
     → Unit tests written + pass (Peaks-Cli Gate B2)
     → Karpathy standards enforced (file-size ≤800 lines, TypeScript rules)
     → Code review evidence (Peaks-Cli Gate B3)
     → Security review evidence (Peaks-Cli Gate B4)
-  → Skill(skill="peaks-qa")  ← ALL validation happens HERE
+  → QA work  ← ALL validation happens HERE
     → Functional test execution (Peaks-Cli Gate A2)
     → Performance check (Peaks-Cli Gate A4)
     → Security test (Peaks-Cli Gate A3)
@@ -30,35 +40,83 @@ peaks-solo (orchestrate only)
     → Verdict: pass | return-to-rd | blocked
 ```
 
+**Mechanism for "RD work" / "QA work" depends on the orchestration mode** (full details in "Peaks-Cli Swarm parallel phase" and "How Solo invokes another role"):
+
+| Mode | Swarm side (after PRD) | Repair loop side (RD↔QA) |
+|---|---|---|
+| `full-auto` / `swarm` | `Task(subagent_type="general-purpose")` sub-agent running `peaks-rd`/`peaks-qa`/`peaks-ui` body | `Task(...)` sub-agent per cycle |
+| `assisted` / `strict` / inline-fallback | Solo executes the role steps inline in the main loop (the `peaks-solo` skill IS the role's owner) | Solo executes inline |
+
+In all modes, the work itself follows the same `peaks-rd` and `peaks-qa` contracts. The only difference is whether the role's body is being read by a sub-agent Task prompt or by Solo's own main loop. **Never bypass the role contracts regardless of which path runs.**
+
 **Violations (BLOCKING — Solo must refuse to proceed):**
 
-1. Writing implementation code directly instead of calling `Skill(skill="peaks-rd")`
-2. Declaring work "done" without invoking `Skill(skill="peaks-qa")` after RD
+1. Writing implementation code directly instead of routing through the RD contract (whether inline or via sub-agent)
+2. Declaring work "done" without producing QA evidence after RD
 3. Skipping unit tests ("it's a small change")
 4. Skipping code review or security review
 5. Skipping QA functional/performance/security validation
 
-**If you catch yourself about to write code in this skill, STOP. Call `Skill(skill="peaks-rd")` instead.**
+**If you catch yourself about to write code in this skill, STOP. Hand off to the RD contract path immediately** (sub-agent Task in full-auto, inline execution in assisted/strict).
 
 **Before declaring workflow complete, run:** `peaks workflow verify-pipeline --rid <rid> --project <repo> --json`
 
 ## Peaks-Cli Startup sequence (MANDATORY — execute in order)
 
-### Peaks-Cli Step 0: Anchor the workflow (MANDATORY FIRST ACTIONS — no bail-out)
+### Peaks-Cli Step 0.5: OpenSpec first-run opt-in (conditional)
 
-The instant Peaks-Cli Solo is invoked, **before** the mode-selection question, before any analysis, and before you decide whether the request "needs" the full pipeline, you MUST run these two commands and see their output:
+After the workspace is anchored, before project scan, Solo checks whether
+the project already has an `openspec/` directory. The lifecycle
+(`render → validate → show → to-rd → validate → archive`) only applies
+when `openspec/` exists; without it, RD/QA/SC silently skip the
+openspec-aware paths and you lose change-proposal tracking, commit
+boundaries from `tasks.md`, and the historical archive.
+
+To make that opt-in visible instead of silent, Solo runs:
 
 ```bash
-# Session ID is auto-generated when omitted; the command returns it in the JSON output
-peaks workspace init --project <repo> --json
-peaks skill presence:set peaks-solo --project <repo> --gate startup
+# 1. Detect whether the project already has openspec/.
+ls <repo>/openspec/changes 2>&1
+# 2. If absent, ask the user once — only on the first Solo run in this
+#    project. The decision is sticky: write it to .peaks/.peaks-openspec-opt-in.json
+#    so subsequent Solo invocations do not re-ask.
+test -f <repo>/.peaks/.peaks-openspec-opt-in.json || \
+  echo "{\"enabled\": <bool>}" > <repo>/.peaks/.peaks-openspec-opt-in.json
 ```
 
-If `workspace init` fails with "required option '--session-id' not specified", the CLI version predates auto-generation. Generate a session ID manually and pass it:
+**AskUserQuestion** (only when `openspec/` is absent and the opt-in
+file is missing):
+
+| Option | What it does |
+|---|---|
+| Enable OpenSpec for this project (Recommended) | Run `peaks openspec init --project <repo> --apply`. After that, every Solo run uses the change-proposal lifecycle for the same project. |
+| Skip for now | Do nothing. Solo proceeds without openspec; the question is re-asked on the next first-run detection. |
+| Never ask again for this project | Write `{enabled: false, sticky: true}`. Solo stops asking. The user can re-enable later by removing `.peaks/.peaks-openspec-opt-in.json` and re-running. |
+
+The first option is the recommended default because it gives Solo the
+full change-proposal lifecycle (proposal / tasks / design / specs
+deltas, archive on ship, commit boundaries from `tasks.md`). It costs
+only a single scaffolded directory and pays back the first time the
+project needs a real review trail.
+
+If the user picks "Enable", the only required follow-up is to make
+sure `openspec/changes/` is added to git (it is part of the project
+repo, not a tool-managed artefact). Solo does not run `git add` for
+the user; that is the user's commit boundary.
+
+### Peaks-Cli Step 0: Anchor the workflow (MANDATORY FIRST ACTIONS — no bail-out)
+
+The instant Peaks-Cli Solo is invoked, **before** the mode-selection question, before any analysis, and before you decide whether the request "needs" the full pipeline, you MUST run these two commands and see their output:
 
 ```bash
-SESSION_ID="$(date +%Y-%m-%d)-session-$(openssl rand -hex 3)"
-peaks workspace init --project <repo> --session-id "$SESSION_ID" --json
+# Session ID is auto-generated when omitted; the command returns it in the JSON output.
+# Do NOT pass --session-id manually — the CLI is the single source of truth for the
+# project session binding. If you forge a session id with `openssl rand` and pass it
+# via --session-id, peaks workspace init will write it to .peaks/.session.json but
+# the binding only sticks if no prior session is open. To avoid the "two sessions
+# in .peaks/" confusion that bites Solo, always omit --session-id here and let the
+# CLI auto-generate.
+peaks workspace init --project <repo> --json
 peaks skill presence:set peaks-solo --project <repo> --gate startup
 ```
 
@@ -68,6 +126,9 @@ peaks skill presence:set peaks-solo --project <repo> --gate startup
 
 **Anti-bail-out rule (BLOCKING):** You MUST NOT exit the peaks-solo workflow, hand control back, or produce a final answer before Step 0 has run. If you catch yourself thinking "this is just analysis, I don't need the workflow" — STOP. Run Step 0, set presence, then continue. A pure-analysis request runs the **lightweight analysis branch** (project scan + standards dry-run + handoff with a Standards-increment section), but it still anchors the workspace and keeps presence active. Declining to anchor is a workflow violation.
 
+**Session conflict resolution (read once, internalise):** If `peaks workspace init` returns `code: "CONFLICTING_SESSION"` with a body like
+`{"existingSessionId":"<Y>","requestedSessionId":"<X>"}`, the project is already bound to a different in-flight session `<Y>` (the one you or a prior run was working on). The fix is **NOT** to pass `--allow-session-rebind` to clobber `<Y>` — that destroys an active session's data. Instead: finish or abandon `<Y>` first (use `peaks session list --json` to see what it is, then `peaks session finish --id <Y>` or `peaks session abandon --id <Y>` — see your session command's help for the exact verbs). Only after `<Y>` is closed should you re-run `peaks workspace init`. The same rule applies to `peaks workspace init --session-id "<manually-forged>"` — do not pre-forge session ids; the CLI's auto-generated value is the binding.
+
 `presence:set` accepts no `--mode` here on purpose — mode is unknown until Step 1. It is re-run with the selected mode in Step 2. Setting presence early guarantees the status header/line shows `peaks-solo` from the very first turn even if the user never reaches mode selection.
 
 ### Peaks-Cli Step 1: Mode selection
@@ -595,19 +656,112 @@ ls <repo>/.claude/rules/common/coding-style.md \
 ```
 
 
-## Peaks-Cli Swarm parallel phase
+## Peaks-Cli Swarm parallel phase (sub-agent fan-out, conditional)
+
+The Swarm phase is **conditional**, not unconditional. It only runs when there is a real, user-confirmed requirement. Solo derives the fan-out set from the PRD type and the request content — never from a default of "always launch three".
 
-After PRD reaches `confirmed-by-user`, Solo launches peaks-ui, peaks-rd(planning), and peaks-qa(test-cases) simultaneously using parallel Agent calls. All three derive independently from the same PRD and write to separate artifact paths. Solo waits for all three, checks convergence (Peaks-Cli Gate B), then enters RD implementation.
+### Swarm gate (decide BEFORE fan-out)
 
-### Degradation when swarm roles fail
+Before launching any sub-agent, Solo must compute the **swarm plan** from three signals:
 
-1. **UI missing**: RD continues with PRD visual descriptions; note "ui-design-missing" in TXT.
-2. **RD planning missing**: RD continues; note "tech-doc-missing" in TXT.
-3. **QA test-cases missing**: RD continues; QA must backfill test cases before issuing verdict.
-4. **Two or more missing**: Fall back to sequential mode (PRD → RD → QA); note "swarm-degraded-to-sequential".
-5. **All three missing**: Pause workflow; report to user; request confirmation to continue.
+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/<session-id>/rd/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.
 
-**UI phase mandatory for frontend**: When the request affects user-visible behavior (pages, components, forms, modals, tables, styling, interaction, or layout), Peaks-Cli Solo MUST invoke `peaks-ui` in the swarm parallel phase alongside RD planning and QA test-case generation. UI produces design drafts that RD implementation later consumes. Skipping UI for frontend work is a blocking violation. The only valid reason to skip UI is when the request is purely backend (API, database, CLI, config, or build tooling).
+Solo records the swarm plan in `.peaks/<session-id>/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 = Solo launched a Task for it. Absence = the role was skipped with documented reason.
+
+### Mode-driven fan-out shape
+
+| Mode | How the swarm plan is decided | What Solo 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.** Solo updates `.peaks/.active-skill.json` to `gate=swarm-fan-out` at this point.
+
+### Sub-agent mechanism (Task tool, NOT Skill tool)
+
+**Solo is itself a skill running in the current session. To invoke a role in the Swarm, Solo MUST use the `Task` tool with `subagent_type="general-purpose"` and a prompt that embeds the role's contract — NOT the `Skill` tool.** The `Skill` tool is single-stack and blocking; using it for "parallel" work was the v1.x illusion of concurrency. The Task tool is the only mechanism that gives real fan-out in Claude Code.
+
+Each sub-agent Task call looks like:
+
+```
+Task(
+  subagent_type="general-purpose",
+  description="<role> for rid=<rid>",
+  prompt="<paste peaks-<role>/SKILL.md body, minus the self-presence / Step 0 blocks, plus
+          the runtime arguments: project=<repo>, session-id=<sid>, 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.'"
+)
+```
+
+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/<sid>/ui/design-draft.md`, `.peaks/<sid>/ui/requests/<rid>.md` | PRD body, project-scan, archetype |
+| `rd-planning` | `.peaks/<sid>/rd/tech-doc.md` (feature/refactor) or `.peaks/<sid>/rd/bug-analysis.md` (bugfix) | PRD body, project-scan, existing-system, codegraph |
+| `qa-test-cases` | `.peaks/<sid>/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 Task tool calls in parallel)** — this is what gives real concurrency. Do not sequentialize them. 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 Task 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/<sid>/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.
+
+After every sub-agent Task 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
+```
+
+### Degradation when swarm roles fail or are absent
+
+| Condition | Solo 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.
+
+### Frontend-only trigger pre-flight
+
+Before computing the swarm plan, Solo runs the keyword scan deterministically:
+
+1. Read `.peaks/<session-id>/prd/requests/<rid>.md` body.
+2. Lowercase + strip markdown; check regex `\b(页面|组件|表单|弹窗|表格|样式|布局|交互|UI|UX|page|component|form|modal|table|styling|layout|interaction|frontend|前端)\b`.
+3. If match count ≥ 1 → `frontendKeywordHit=true`.
+4. If `frontendOnly` (from project-scan) is `true` and no keyword hit → UI joins anyway (frontend-only project, even non-visual changes may need visual sanity for regressions).
+5. If `frontendOnly` is `false` and no keyword hit → UI skipped.
+
+Solo records the pre-flight result in `sc/swarm-plan.json` so the audit trail shows why UI was or was not included.
 
 ## Peaks-Cli Mandatory RD QA repair loop (AUTO-PROCEED)
 
@@ -622,19 +776,24 @@ After PRD reaches `confirmed-by-user`, Solo launches peaks-ui, peaks-rd(planning
 
 After `peaks-rd` finishes any implementation, repair, or code-output slice, Peaks-Cli Solo MUST automatically route the result to `peaks-qa` without waiting for user confirmation. This is not optional in full-auto mode. Solo must not declare the workflow complete, emit a TXT handoff, or stop at RD completion.
 
-**How Solo invokes another role skill (mechanism, not metaphor):**
+**How Solo invokes another role (mechanism, not metaphor):**
+
+Solo is itself a skill running in the current session. There are **two distinct mechanisms** in this skill, and they MUST NOT be confused:
+
+1. **Swarm fan-out (planning side, after PRD confirmed)** — uses the `Task` tool with `subagent_type="general-purpose"` to launch real concurrent sub-agents. See "Peaks-Cli Swarm parallel phase" above for the full contract. Sub-agents do NOT call Skill(...) back into the role; they execute the role's instructions inline from the prompt.
+2. **Sequential handoff (execution side, RD↔QA repair loop)** — Solo is the only loop, and after RD or QA finishes (whether as a sub-agent or directly), Solo drives the next step from the orchestrator seat. Do NOT use the `Skill` tool to "reactivate" peaks-rd or peaks-qa in the main loop; doing so is the v1.x anti-pattern that masqueraded as "calling the role" but actually just re-prompted the same session. From v1.3 onward, the main loop drives roles via the CLI gate (`peaks request transition`) and reads back artefacts (`peaks request show ... --json`); the actual RD/QA work is either done inline by Solo (when Solo has just been re-invoked by the user) or by a Task sub-agent (in swarm mode).
 
-Solo is itself a skill running in the current session. To "invoke peaks-rd" or "peaks-qa", Solo MUST use the `Skill` tool with the role's name (e.g. `Skill(skill="peaks-rd")` or `Skill(skill="peaks-qa")`), passing the `<request-id>` and `<session-id>` as arguments so the role reads the same artifacts Solo wrote. Do NOT re-implement the role's logic inline in Solo. Do NOT use the `Agent` tool with a sub-agent — role skills are skills, not agents. After the role skill returns, Solo reads the artifacts the role wrote (via the request artifact path or `peaks request show <rid> --role <role>`) to decide the next step.
+After RD completes (whether inline or sub-agent), Solo does not stop — it must advance to QA. There is no "RD done, ask the user" state in full-auto mode. The only valid stops are: (a) QA verdict=pass, (b) repair cap hit, (c) explicit user cancel.
 
-**Presence restoration after role skill returns (MANDATORY):** Role skills (peaks-rd, peaks-qa, peaks-ui) call `peaks skill presence:set <role>` internally, which overwrites `.peaks/.active-skill.json`. After EVERY role skill returns — whether success, repair-needed, or failure — Solo MUST immediately restore the orchestrator presence by re-running the same presence command from Step 2:
+**Presence restoration after RD/QA work returns (MANDATORY):** In v1.x, role skills called `peaks skill presence:set <role>` internally and stomped on `.peaks/.active-skill.json`. From v1.3 onward, sub-agents in the Swarm path are forbidden from calling `peaks skill presence:set` (see "Sub-agent dispatch" in each role's SKILL.md), so the main loop's presence file is preserved across the fan-out window by construction. The one place Solo still has to actively restore presence is **once after the fan-out returns** (gate=swarm-converged) and again **after each RD↔QA repair iteration** (gate=repair-cycle-<N>). Use the same command from Step 2 with the current mode and the gate that has just advanced:
 
 ```bash
 peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate <current-gate>
 ```
 
-This keeps the CLAUDE.md status header accurate (`Peaks-Cli Skill: peaks-solo`) instead of showing a stale role name. Use the current mode and gate values; the gate may have advanced since startup. Skipping this step causes the header to display the last role skill name permanently.
+This keeps the CLAUDE.md status header accurate (`Peaks-Cli Skill: peaks-solo`) instead of showing a stale role name. Use the current mode and gate values; the gate may have advanced since startup. Skipping this step causes the header to display the last-known gate permanently.
 
-**Full-auto auto-proceed rule**: In the `full-auto` profile, when RD transitions to `qa-handoff`, Solo immediately invokes `peaks-qa` via the Skill tool with the same `<request-id>`. Do not pause, do not ask the user, do not summarize RD results as if they were final. The only valid reason to skip QA is when `--type` is `docs` or `chore` (no acceptance surface).
+**Full-auto auto-proceed rule**: In the `full-auto` profile, when RD transitions to `qa-handoff`, Solo immediately drives QA — by launching a `Task(subagent_type="general-purpose", ...)` sub-agent carrying the `peaks-qa` body (swarm path), or by running QA inline in the main loop (assisted/strict path). Do not pause, do not ask the user, do not summarize RD results as if they were final. The only valid reason to skip QA is when `--type` is `docs` or `chore` (no acceptance surface).
 
 A QA report with any failing, blocked, missing, or unverified acceptance item is not a pass.
 
@@ -650,9 +809,12 @@ When `peaks-qa` returns `verdict=return-to-rd`, Solo does NOT manually rewrite R
      --project <repo> --json
    ```
    `spec-locked` is the canonical "needs more RD work" state. The reason is mandatory in repair cycles so the artifact history shows the loop.
-3. Invoke `peaks-rd` via the Skill tool. Pass the request id and the path to the QA findings; peaks-rd reads `qa/test-reports/<rid>.md` and the QA `requests/<rid>.md` for the verdict.
+3. Re-launch `peaks-rd` work. Two paths, mode-driven:
+   - **Swarm / full-auto**: launch a fresh `Task(subagent_type="general-purpose", ...)` sub-agent with the same `peaks-rd` body used in the Swarm phase, plus the QA findings path so it can read the failure list. Solo restores presence after the sub-agent returns.
+   - **Assisted / strict / inline-fallback**: Solo executes the RD repair steps directly in the main loop, since there is no concurrent fan-out to coordinate.
+   In both paths, pass the QA findings path so the repair sees what failed.
 4. peaks-rd fixes the reported issues only (red-line scope: do not modify unrelated surfaces), regenerates code-review and security-review evidence if changes touched reviewed surfaces, then transitions `rd → implemented → qa-handoff` again.
-5. Solo invokes `peaks-qa` again with the same `<request-id>` (the same Skill call as before). QA re-runs gates against the new diff.
+5. Solo re-runs QA (sub-agent Task in swarm/full-auto, inline in assisted/strict) with the same `<request-id>`. QA re-runs gates against the new diff.
 6. Repeat steps 1-5 until QA returns `verdict=pass`, or the cap below fires.
    **After each repair iteration** (after peaks-rd and peaks-qa both return), Solo MUST restore presence:
    ```bash
@@ -707,14 +869,40 @@ 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 — launch UI + RD(planning) + QA(test-cases) simultaneously
-# Pass the same --type chosen for PRD so RD/QA gate matrix lines up.
-peaks request init --role ui --id <rid> --project <repo> --apply --type <type> --json
-peaks request transition <rid> --role ui --state direction-locked --project <repo> --json
-peaks request transition <rid> --role ui --state handed-off --project <repo> --json
-peaks request init --role rd --id <rid> --project <repo> --apply --type <type> --json
-peaks request transition <rid> --role rd --state spec-locked --project <repo> --json
-peaks request init --role qa --id <rid> --project <repo> --apply --type <type> --json
+# 3. Peaks-Cli Swarm parallel — sub-agent fan-out (Task tool, 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.
+#    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
+#    the Swarm phase — that's the v1.x anti-pattern.
+#
+# 3a. Pre-fan-out: Solo initialises every role's request artefact slot in the main
+#     loop so sub-agents find a stable rid <-> artefact binding. Each role's
+#     sub-agent may also call peaks request init itself (idempotent on the same rid);
+#     Solo's call here is the source of truth. Only init roles that are in the
+#     swarm plan — roles not in the plan do not get a slot yet.
+peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate swarm-fan-out
+# for each role in swarm-plan.subAgents:
+# peaks request init --role ui --id <rid> --project <repo> --apply --type <type> --json
+# peaks request init --role rd --id <rid> --project <repo> --apply --type <type> --json
+# peaks request init --role qa --id <rid> --project <repo> --apply --type <type> --json
+# 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
+#     (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):
+peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate swarm-converged
+ls .peaks/<sid>/prd/requests/<rid>.md                # PRD artefact must exist (Gate B hard)
+# feature / refactor → ls .peaks/<sid>/rd/tech-doc.md
+# bugfix             → ls .peaks/<sid>/rd/bug-analysis.md
+ls .peaks/<sid>/qa/test-cases/<rid>.md                # QA test-cases (skipped for docs|chore)
+# ui (only when in plan):
+ls .peaks/<sid>/ui/design-draft.md 2>&1               # non-blocking (Gate B info)
+# Apply the degradation rules in the main SKILL.md if any artefact is missing.
 # → Peaks-Cli Gate B convergence check. Assisted/Strict: [CONFIRM]
 
 # 4. Peaks-Cli RD planning artifact (the file required by the prerequisite gate)
@@ -762,10 +950,30 @@ peaks openspec validate <cid> --project <repo> --json
 peaks openspec archive <cid> --project <repo> --apply --json
 
 # 10. Peaks-Cli TXT handoff — invoke peaks-txt which embeds memory markers and extracts
-#     peaks-txt writes the handoff capsule to .peaks/<id>/txt/handoff.md with embedded
-#     <!-- peaks-memory:start --> blocks, then runs memory extract on it.
-#     --apply is REQUIRED to write .peaks/memory; without it the command only previews.
+#     peaks-txt writes the handoff capsule to .peaks/<id>/txt/handoff.md. Inside the
+#     capsule body, peaks-txt embeds <!-- peaks-memory:start --> blocks for every
+#     stable project fact surfaced this session.
+#
+# 10a. Skill-side scan (do this BEFORE the AskUserQuestion below):
+#      grep -n "peaks-memory:start" .peaks/<id>/txt/handoff.md
+#      Record the count. This is the skill doing the work, not a CLI command —
+#      we deliberately do not ship a `peaks memory scan` because the LLM is
+#      the only consumer and the LLM has grep.
+
+# 10b. AskUserQuestion (only if 10a returned count >= 1):
+#      "The TXT handoff has N peaks-memory:start blocks. Persist to .peaks/memory/?
+#       (a) Apply all — `peaks memory extract --project <repo>
+#                            --artifact .peaks/<id>/txt/handoff.md --apply --json`
+#       (b) Apply selectively — re-edit handoff.md first, then re-apply
+#       (c) Skip for now — blocks stay in the handoff only, no .peaks/memory/ write"
+#      If 10a returned 0 AND the session surfaced a stable project fact
+#      (decision / convention / approved refactor), STOP — peaks-txt must go
+#      back and embed at least one block before Solo can advance.
+
+# 10c. After the user picks (a) or (b), run:
 peaks memory extract --project <repo> --artifact .peaks/<id>/txt/handoff.md --apply --json
+#      --apply is REQUIRED to write .peaks/memory/; without it the command only
+#      previews. The extract regenerates index.json in the same call.
 
 # 11. Peaks-Cli Final snapshot
 peaks project dashboard --project <repo> --json
@@ -857,4 +1065,4 @@ Do not run upstream installer flows, mutate agent settings, or commit `.codegrap
 
 **MCP lifecycle**: `list → plan → apply --yes → call → rollback`. `apply` backs up settings and refuses non-peaks entries unless `--claim` is passed.
 
-Detailed rules: `references/external-skill-invocation.md`, `references/openspec-mcp-workflow.md`, `references/workflow.md`, `references/existing-system-extraction.md`.
+Detailed rules: `references/external-skill-invocation.md`, `references/openspec-mcp-workflow.md`, `references/workflow.md`, `references/existing-system-extraction.md`. For an informational mapping of peaks artefact paths to the A2A (Agent2Agent) protocol's Task / Artifact / Part / Message / AgentCard vocabulary (no A2A implementation, just a shared naming layer), see `references/a2a-artifact-mapping.md`.

package/skills/peaks-solo/references/a2a-artifact-mapping.md

@@ -0,0 +1,115 @@
+# A2A artifact mapping (informational)
+
+> Reference for `peaks-solo` and any other peaks skill that produces durable artefacts in `.peaks/<session-id>/`. Maps peaks's on-disk artefact vocabulary onto the A2A (Agent2Agent) protocol's vocabulary so a future peaks consumer (e.g. an external LLM agent or a downstream peaks-cli extension) can read peaks output without having to learn a brand-new schema. This is a **documentation mapping**, not a protocol implementation: peaks-cli does not speak A2A over HTTP, does not host an AgentCard endpoint, and does not advertise its capabilities via A2A's discovery mechanism. It only uses A2A's *concepts* as a shared naming layer.
+
+## 1. Why this reference exists
+
+The A2A protocol (https://a2acn.com) defines five core concepts: **AgentCard**, **Task**, **Artifact**, **Message**, and **Part**. peaks-cli's session workspace is a parallel vocabulary that grew up independently: `prd/requests/<rid>.md`, `rd/tech-doc.md`, `qa/test-cases/<rid>.md`, etc. The two vocabularies are *not* identical (A2A is HTTP-shaped, peaks is filesystem-shaped), but the A2A concepts are close enough that aligning peaks artefact names with A2A terms in this reference:
+
+- gives an external consumer a single translation table instead of two schemas to learn,
+- lets a peaks operator talk about "the artifact" or "the task" in mixed conversations without losing precision,
+- documents what peaks output is **not** (no SSE streaming, no remote AgentCard), so the limits are explicit.
+
+This is the kind of borrowing that costs zero code and earns some interoperability. It is **not** an integration: peaks-cli does not implement A2A, does not run an A2A server, and does not depend on the a2a-protocol package. Adopting A2A concepts here is the same as adopting any other shared nomenclature (UML, OpenTelemetry, etc.): it improves the conversation, nothing more.
+
+## 2. Concept-to-path mapping
+
+The mapping below uses peaks's own paths verbatim. Each row also notes where peaks **diverges** from A2A, so a reader does not assume parity.
+
+| A2A concept | peaks artefact | Path (under `.peaks/<session-id>/`) | Notes |
+|---|---|---|---|
+| **AgentCard** (capability advertisement) | `peaks-skill-output-style` + `.peaks/.active-skill.json` | `.peaks/.active-skill.json`, `.peaks/.session.json` | peaks is a *local* tool, not a service. The "card" is the active-skill file plus a peek at `.peaks/PROJECT.md` for human-readable history. There is no `/.well-known/agent-card.json` endpoint. |
+| **Task** (stateful unit of work) | `peaks request` state machine for a single `<rid>` | `.peaks/<sid>/{prd,rd,qa,ui,sc}/requests/<rid>.md` (the request artefact); `.peaks/<sid>/<role>/session.json` (per-session metadata) | peaks's task lifecycle is `prd:confirmed-by-user → handed-off`, then per role `draft → spec-locked → implemented → qa-handoff`, then `qa:running → verdict-issued`. The full state graph is enforced by `peaks request transition`. A2A's Task object is JSON; peaks's task is **a set of files with a `state` field per role**. |
+| **Artifact** (immutable output) | `rd/tech-doc.md`, `rd/code-review.md`, `rd/security-review.md`, `qa/test-cases/<rid>.md`, `qa/test-reports/<rid>.md`, `qa/security-findings.md`, `qa/performance-findings.md`, `sc/handoff.md` | as listed | peaks's artefacts are *append-once*, not strictly immutable: a `qa/test-reports/<rid>.md` may be re-emitted on repair cycles. The convention is "newest write wins; the file at the end of the workflow is the truth", which is close enough to A2A's immutable-Artifact semantics for translation purposes. |
+| **Message** (non-artifact communication) | `peaks skill presence` heartbeat + transition `--reason` notes | `.peaks/.active-skill.json` (`lastHeartbeat`), transition notes in `.peaks/<sid>/<role>/requests/<rid>.md` | peaks does **not** separate Messages from Artifacts at the storage layer; a "message" is anything that is not the artefact body (the `<!-- peaks-memory:start -->` markers, the `state` field, the `--reason` text on a transition). Treat these as inline metadata of the artefact, not as separate objects. |
+| **Part** (atomic content unit) | Markdown sections within an artefact, frontmatter fields | inline within the artefact | peaks's Artifacts are single Markdown files, so the "Part" concept maps to a heading or a frontmatter field. A `Part`'s `kind` in A2A terms is `text` (the prose), `file` (a `<!-- peaks-memory:start -->` block as a structured chunk), or `data` (the frontmatter). A2A's `form` / `iframe` / video `Part` kinds are not produced by peaks. |
+
+## 3. Field-level mapping (A2A Part ↔ peaks frontmatter)
+
+A2A `Part` has `kind` and `metadata` (free-form) plus `content` (typed by kind). peaks's per-artifact frontmatter carries a subset:
+
+```yaml
+---
+name: <slug>            # used in memory extraction; not a 1:1 A2A field
+description: <title>     # roughly the A2A Artifact.description
+metadata:
+  type: <kind>          # A2A Artifact.kind equivalent
+  sourceArtifact: <rel> # A2A Artifact.source / provenance equivalent
+---
+```
+
+A consumer reading a peaks artefact and translating it to A2A can populate:
+
+- `Artifact.name` ← peaks `name`
+- `Artifact.description` ← peaks `description` (or the first H1)
+- `Artifact.kind` ← peaks `metadata.type`
+- `Artifact.parts[0]` ← the body text (A2A `Part{kind: "text"}`)
+- `Artifact.metadata.sourcePath` ← peaks `metadata.sourceArtifact`
+- `Artifact.metadata.sessionId` ← from `.peaks/.session.json`
+
+The mapping is not 100% lossless: A2A's `Part` can carry structured forms or file references, peaks cannot. That is the explicit *non-goal* of this mapping; it would be over-claiming to assert parity where there is none.
+
+## 4. State-graph mapping (A2A Task ↔ peaks request)
+
+A2A's Task object has a small set of states (typically: `submitted`, `working`, `input-required`, `completed`, `failed`, `canceled`). peaks's per-role request state machine is richer and per-role:
+
+| Role | peaks states (in order) | Closest A2A Task state |
+|---|---|---|
+| `prd` | `draft` → `confirmed-by-user` → `handed-off` | `submitted` → `working` → `input-required` (for the confirm gate) |
+| `rd` | `draft` → `spec-locked` → `implemented` → `qa-handoff` | `working` |
+| `qa` | `draft` → `running` → `verdict-issued` (verdict is `pass` / `return-to-rd` / `blocked`) | `working` → `completed` (pass) / `input-required` (return-to-rd) / `failed` (blocked) |
+| `ui` | `draft` → `direction-locked` → `handed-off` | `working` → `completed` |
+| `sc` | `draft` → `recorded` | `working` → `completed` |
+
+A consumer translating peaks states to A2A should:
+
+- collapse peaks's multi-role state machine to a *single* A2A Task state by taking the most progressed of any role,
+- use the A2A `input-required` state to model **any** gate where peaks is waiting for a human (`confirmed-by-user`, `--confirm`, AskUserQuestion for a login wall, etc.),
+- emit `completed` only when QA verdict is `pass` and SC has recorded the change,
+- emit `failed` on `blocked` QA verdict or `blocked` handoff.
+
+## 5. Worked example: a feature slice from start to finish
+
+A user runs `peaks-solo` for a "add user authentication" feature. Mapping the resulting files to A2A concepts:
+
+```
+.peaks/<sid>/prd/requests/001.md      → A2A Artifact (kind=proposal)
+.peaks/<sid>/ui/requests/001.md       → A2A Artifact (kind=design-direction)
+.peaks/<sid>/ui/design-draft.md       → A2A Artifact (kind=visual-spec)
+.peaks/<sid>/rd/tech-doc.md           → A2A Artifact (kind=implementation-plan)
+.peaks/<sid>/qa/test-cases/001.md     → A2A Artifact (kind=test-cases)
+.peaks/<sid>/rd/code-review.md        → A2A Artifact (kind=review, status=fixed)
+.peaks/<sid>/rd/security-review.md    → A2A Artifact (kind=security-review)
+.peaks/<sid>/qa/test-reports/001.md    → A2A Artifact (kind=test-report, verdict=pass)
+.peaks/<sid>/qa/security-findings.md  → A2A Artifact (kind=security-findings)
+.peaks/<sid>/qa/performance-findings.md → A2A Artifact (kind=performance-findings)
+.peaks/<sid>/sc/handoff.md            → A2A Artifact (kind=change-record)
+.peaks/<sid>/txt/handoff.md           → A2A Artifact (kind=handoff-capsule)
+.peaks/<sid>/system/sub-agent-*.json  → A2A Message (sub-agent presence markers)
+.peaks/<sid>/sc/swarm-plan.json       → A2A Message (the dispatch plan)
+.peaks/memory/*.md                    → A2A Artifact (kind=project-memory, persists across sessions)
+```
+
+A consumer wanting to render a single "feature" object in A2A terms picks the `test-reports/001.md` (verdict=pass) as the terminal Artifact and the rest as supporting Parts or sibling Artifacts. The mapping is intentionally loose: peaks's value is that *all of these files exist*, not that they fit A2A's object model exactly.
+
+## 6. What peaks does NOT provide
+
+To keep the mapping honest, peaks-cli **does not** currently provide the following A2A primitives, and consumers should not expect them:
+
+- A2A **AgentCard** served over HTTP at `/.well-known/agent-card.json`. peaks-cli is a local CLI; its "card" is the on-disk `.peaks/.active-skill.json` plus `peaks skill doctor --json`.
+- A2A **streaming** responses (SSE / WebSocket). peaks commands are synchronous and return a single JSON envelope.
+- A2A **identity / auth** (OAuth, OIDC, mTLS). peaks assumes local-machine trust.
+- A2A **cross-vendor discovery**. peaks has no A2A registry entry; it has `peaks mcp list --json` for MCP-compatible capabilities.
+- A2A **Task delegation across the network**. peaks's "sub-agent" is a Claude Code `Task` tool call in the same process, not a remote A2A server.
+
+These are *deliberate* omissions. peaks-cli solves a different problem (a local workflow-gating CLI for Claude Code), and adopting A2A's networking surface would add weight without addressing peaks's actual failure modes (which are around LLM bypassing gates, not around inter-agent discovery).
+
+## 7. When to re-evaluate
+
+Re-open this mapping in any of the following cases:
+
+- a peaks user reports a real need to share workflow state with a non-peaks agent (e.g. an Autogen / LangChain agent that wants to read a peaks handoff capsule);
+- peaks-cli ships a hosted / multi-user mode where AgentCard-style discovery becomes useful;
+- the A2A protocol stabilises on a thin `Artifact` JSON schema that matches peaks's on-disk shape close enough to make translation a one-liner rather than a reference doc.
+
+Until one of those fires, this reference doc is the entire A2A surface area of peaks-cli. Adding more is over-engineering.