peaks-cli 1.3.3 → 1.3.5

package/skills/peaks-solo/SKILL.md

@@ -3,6 +3,36 @@ name: peaks-solo
 description: Full-auto orchestration facade for the Peaks-Cli skill family. Use when the user asks Peaks-Cli to handle a project workflow end-to-end (端到端/全流程/需求开发), especially from a product document (产品文档/PRD/飞书文档/Feishu doc) through implementation and validation. Coordinates peaks-prd, peaks-rd, peaks-ui, peaks-qa, peaks-sc, and peaks-txt while preserving user confirmation gates. Triggers on `/peaks-solo`, "peaks solo", "全流程开发", "端到端迭代", "根据产品文档开发", "从需求到上线".
 ---
 
+## Two-axis naming convention
+
+> **Read once at the top of this file; the rest of the skill is written against it.**
+
+The `.peaks/` workspace is partitioned by **two orthogonal axes**. Every path in this SKILL.md uses one of them; mixing them is the original `.peaks/<sid>/` / `.peaks/_runtime/<sid>/` bug class this slice corrects.
+
+| Axis | Path root | Holds | When to use |
+|---|---|---|---|
+| **change-id axis** (reviewable artifacts) | `.peaks/<changeId>/...` | PRD, RD plan, code-review, security-review, test-cases, handoff capsules, gate targets | The artifact should be reviewable on its own and survives across sessions for the same change. Change-id is the unit of work. |
+| **session-id axis** (ephemeral state) | `.peaks/_runtime/<sessionId>/...` | Session bindings (`.peaks/_runtime/session.json`), live in-flight state, the per-session project-scan and tech-doc scaffold while the session is open | The artifact is session-scoped and only meaningful while the parent session is live. |
+| **sub-agent axis** | `.peaks/_sub_agents/<sessionId>/...` | Sub-agent dispatch records, sub-agent heartbeats, per-sub-agent shared channel entries, sub-agent artifact outputs | A sub-agent ran in a parent session. The axis nests under the parent session-id; sub-agent outputs are flushed into the change-id root on commit. |
+
+**Which CLI commands operate on which axis:**
+
+- **change-id axis** (reviewable artifacts): `peaks request init`, `peaks request transition`, `peaks request show`, `peaks request lint`, `peaks request repair-status`, `peaks scan diff-vs-scope`, `peaks scan acceptance-coverage`. Inputs reference `.peaks/<changeId>/...`.
+- **session-id axis** (ephemeral state): `peaks session info`, `peaks session start`, `peaks session finish`, `peaks session list`. Reads/writes `.peaks/_runtime/<sessionId>/session.json`.
+- **sub-agent axis** (under parent session-id): `peaks sub-agent dispatch`, `peaks sub-agent heartbeat`, `peaks sub-agent share`, `peaks sub-agent shared-read`. All output paths are under `.peaks/_sub_agents/<sessionId>/...`.
+
+**Placeholder convention used in this file:**
+
+- `<changeId>` / `<change-id>` — the change-id axis. Use when describing a path that lives at `.peaks/<changeId>/...` (root-level, NOT inside `_runtime/`).
+- `<sessionId>` / `<session-id>` — the session-id axis. Use when describing a path that lives at `.peaks/_runtime/<sessionId>/...` or `.peaks/_sub_agents/<sessionId>/...`. The long form `<session-id>` is used inside bash / shell examples where `<sessionId>` would break parsing.
+- The bare `<sid>` placeholder is **forbidden** in new content — it is ambiguous between the two axes. Legacy occurrences are replaced by this convention; new content must use the right axis label.
+
+**Cross-references:**
+
+- Slice `2026-06-05-change-id-as-unit-of-work` (commits `48958fc` + `928eb53`) — established the change-id axis as the canonical root for reviewable artifacts (`src/shared/change-id.ts:131,335`, `src/services/scan/acceptance-coverage-service.ts:155`).
+- Slice `005-session-runtime-dir-regression` (commit `178a47e`) — added the `getSessionDir()` resolver at `src/services/session/getSessionDir.ts` and routed 4 stragglers that were constructing `.peaks/${sessionId}` (no `_runtime/`) through the canonical resolver. Defense-in-depth scan: `tests/unit/services/session/session-dir-canonical.test.ts`.
+- Slice `006-5th-writer-changeid-path` (this slice) — disambiguates the SKILL.md placeholders and adds the regression test `tests/unit/skills/skills-skill-md-naming.test.ts` that mechanically enforces (a) zero bare `<sid>`, (b) every `.peaks/<X>/` reference has an axis label, (c) the "Two-axis naming convention" callout is present in `peaks-solo`, `peaks-rd`, `peaks-qa`.
+
 # Peaks-Cli Solo
 
 Peaks-Cli Solo is the orchestration facade for the Peaks-Cli short skill family.
@@ -192,7 +222,7 @@ done
 **Strict quality guarantee (per user's hard rule: "严格要保证不能比当前的效果差")**:
 - If no in-flight slice is detected, this step is a no-op: zero extra commands beyond the existing Step 0 probe, zero extra token cost.
 - If an in-flight slice is detected, the cost is one `find` + one `grep` loop (sub-millisecond) + one `AskUserQuestion` (one round-trip). The savings are 3-5k tokens (the cost of manually re-reading 3-5 artifact files).
-- The dogfood test in `tests/unit/skill-resume-mode.test.ts` (8 cases, bash-fixture shim — the legacy interface used by `skills/peaks-solo-resume`) and `tests/unit/services/skill/resume-detector.test.ts` (24 cases, the canonical TypeScript classifier at `src/services/skill/resume-detector.ts`) together cover: (a) fresh / complete / resume:rd-planning / resume:qa-validation / resume:txt-handoff state-based classifications, (b) the "Other resume triggers" overrides (missing `rd/tech-doc.md` → `rd-planning`; missing `rd/code-review.md` or `rd/security-review.md` → `rd-review-fanout`; missing `qa/test-reports/<rid>.md` → `qa-execution`), (c) the mid-implementation distinction (`spec-locked` / `implemented` / `running` / `blocked` all return `in-flight:<state>`), (d) the primary-vs-abandoned filter (multiple RDs → spec-locked wins; single blocked RD stays primary; 2+ all-abandoned → fresh), (e) the legacy `.peaks/<sid>/` path fallback, and (f) determinism across two invocations on the same fixture.
+- The dogfood test in `tests/unit/skill-resume-mode.test.ts` (8 cases, bash-fixture shim — the legacy interface used by `skills/peaks-solo-resume`) and `tests/unit/services/skill/resume-detector.test.ts` (24 cases, the canonical TypeScript classifier at `src/services/skill/resume-detector.ts`) together cover: (a) fresh / complete / resume:rd-planning / resume:qa-validation / resume:txt-handoff state-based classifications, (b) the "Other resume triggers" overrides (missing `rd/tech-doc.md` → `rd-planning`; missing `rd/code-review.md` or `rd/security-review.md` → `rd-review-fanout`; missing `qa/test-reports/<rid>.md` → `qa-execution`), (c) the mid-implementation distinction (`spec-locked` / `implemented` / `running` / `blocked` all return `in-flight:<state>`), (d) the primary-vs-abandoned filter (multiple RDs → spec-locked wins; single blocked RD stays primary; 2+ all-abandoned → fresh), (e) the legacy `.peaks/_runtime/<sessionId>/` path fallback, and (f) determinism across two invocations on the same fixture.
 
 ### Peaks-Cli Step 1: Mode selection
 
@@ -294,7 +324,7 @@ Use the Peaks-Cli CLI for runtime side effects.
 
 Map gstack stages to Peaks-Cli role artifacts; preserve Peaks-Cli confirmation gates. Do not delegate orchestration to gstack commands.
 
-For frontend workflows, RD and QA must use Playwright MCP (`mcp__playwright__` tool namespace) for real browser E2E (`peaks mcp plan/apply --capability playwright-mcp.browser-validation --yes`). Chrome DevTools MCP is a secondary CDP surface only. Sanitize browser artifacts before retention (no login URLs, cookies, tokens, PII). See `references/browser-workflow.md`.
+For frontend workflows, RD and QA must use Playwright MCP for real browser E2E. The skill body never bakes in the `mcp__playwright__` prefix; it uses the peaks mcp plan/apply/call pattern (`peaks mcp plan --capability playwright-mcp.browser-validation --json` then `peaks mcp apply --capability playwright-mcp.browser-validation --yes --json` then `peaks mcp call --capability playwright-mcp.browser-validation --tool <toolName> --args-json '<args>' --json`). Chrome DevTools MCP is a secondary CDP surface only. Sanitize browser artifacts before retention (no login URLs, cookies, tokens, PII). See `references/browser-workflow.md`.
 
 ## Peaks-Cli Local intermediate artifact workspace (MANDATORY)
 
@@ -326,7 +356,7 @@ The workspace initialization creates this structure under `.peaks/`:
 
 # Per-slice artifact dirs (auto-generated, one per session). Files
 # inside ARE tracked by the 提交中间产物 convention.
-.peaks/<session-id>/
+.peaks/_runtime/<sessionId>/
 prd/source/      # PRD source documents (Feishu exports, pasted content)
 prd/requests/    # PRD request artifacts (goals, non-goals, acceptance, frontend delta)
 ui/requests/     # UI request artifacts (visual direction, taste reports)
@@ -364,7 +394,7 @@ Files written into these directories during the workflow (not pre-created — th
 
 Legitimate source files (e.g. `jest-setup.ts`, `tailwind.config.js`) belong at root — do not move them.
 
-If you are about to Write/Edit an intermediate artifact in the project root, STOP. Create the `.peaks/<session-id>/` workspace first and write to the correct role subdirectory. If existing root-level artifacts from a prior run are discovered, move them into `.peaks/<session-id>/` and note the migration in the TXT handoff.
+If you are about to Write/Edit an intermediate artifact in the project root, STOP. Create the `.peaks/_runtime/<sessionId>/` workspace first and write to the correct role subdirectory. If existing root-level artifacts from a prior run are discovered, move them into `.peaks/_runtime/<sessionId>/` and note the migration in the TXT handoff.
 
 ### Git and sync policy
 
@@ -372,7 +402,7 @@ Do not default to git-backed storage or automatic commits for intermediate artif
 
 ## Peaks-Cli Pre-RD project scan checklist (MANDATORY)
 
-Before handing off to `peaks-rd`, scan the project and record findings to `.peaks/<session-id>/rd/project-scan.md`. RD and UI roles read this before starting work. **project-scan.md is a session-scoped singleton** — check if it already exists before regenerating (e.g. via `ls .peaks/<session-id>/rd/project-scan.md`). If it exists and is complete (has `## Archetype` and `## Project mode` sections), reuse it. Only regenerate if missing or incomplete.
+Before handing off to `peaks-rd`, scan the project and record findings to `.peaks/_runtime/<sessionId>/rd/project-scan.md`. RD and UI roles read this before starting work. **project-scan.md is a session-scoped singleton** — check if it already exists before regenerating (e.g. via `ls .peaks/_runtime/<sessionId>/rd/project-scan.md`). If it exists and is complete (has `## Archetype` and `## Project mode` sections), reuse it. Only regenerate if missing or incomplete.
 
 ### 0. Project archetype detection (MANDATORY — run FIRST, deterministic CLI)
 
@@ -522,7 +552,7 @@ When there is no conflict, do not ask — the CLI value wins and the workflow pr
 
 ### Mock data strategy selection
 
-Solo records the chosen mock strategy in `.peaks/<session-id>/rd/tech-doc.md` under a `## Mock Data Strategy` section. The choice depends on the project scan results:
+Solo records the chosen mock strategy in `.peaks/_runtime/<sessionId>/rd/tech-doc.md` under a `## Mock Data Strategy` section. The choice depends on the project scan results:
 
 | Project data-fetching pattern | Recommended mock approach | Rationale |
 |---|---|---|
@@ -541,7 +571,7 @@ Solo records the chosen mock strategy in `.peaks/<session-id>/rd/tech-doc.md` un
 2. Mock data should be realistic (not `"test"`, `"foo"`, `123`) — use plausible Chinese/English content that resembles production data.
 3. Each mock must export its TypeScript interface so RD implementation and QA test-cases can import the same types.
 4. Mark every mock file with a header comment: `// MOCK: Replace with real API call when swagger.json is available`.
-5. Before producing any mock file, register the plan in `.peaks/<session-id>/rd/mock-plan.md` with: chosen strategy (from the table above), planned file paths, and a one-line rationale per file. This file is the source of truth for mock locations across runs — RD must read it before writing code, QA must read it before writing test cases.
+5. Before producing any mock file, register the plan in `.peaks/_runtime/<sessionId>/rd/mock-plan.md` with: chosen strategy (from the table above), planned file paths, and a one-line rationale per file. This file is the source of truth for mock locations across runs — RD must read it before writing code, QA must read it before writing test cases.
 
 ### API contract placeholder pattern
 
@@ -572,7 +602,7 @@ When the PRD source is a Feishu/Lark document that requires authentication:
 
 1. **Primary path**: Playwright MCP headed browser → user completes login → Solo reads document content via `browser_snapshot`.
 2. **Fallback A (user cannot login)**: Ask user to copy-paste the document content or export as Markdown/PDF. Solo creates the PRD artifact from the pasted content.
-3. **Fallback B (user provides export)**: User drops a `.md` or `.pdf` export into `.peaks/<session-id>/prd/source/`. Solo reads and processes it.
+3. **Fallback B (user provides export)**: User drops a `.md` or `.pdf` export into `.peaks/_runtime/<sessionId>/prd/source/`. Solo reads and processes it.
 4. **Fallback C (none of the above)**: Mark PRD as `blocked` with reason `doc-inaccessible`, list the exact next steps for the user, and pause the workflow.
 
 Never silently fall back to unauthenticated `fetch` or `WebFetch` for authenticated documents.
@@ -595,11 +625,11 @@ Before launching any sub-agent, Solo must compute the **swarm plan** from three
    - `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)
+   - Reading `.peaks/_runtime/<sessionId>/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.
 
-Solo records the swarm plan in `.peaks/<session-id>/sc/swarm-plan.json` so SC and TXT can audit what was launched:
+Solo records the swarm plan in `.peaks/_runtime/<sessionId>/sc/swarm-plan.json` so SC and TXT can audit what was launched:
 
 ```json
 {
@@ -633,13 +663,13 @@ 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=<sid>, request-id=<rid>, mode=<mode>,
+            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 <sid> --project <repo> --json
+  --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.
@@ -648,16 +678,16 @@ The role's required artefact paths (also see peaks-ui/rd/qa SKILL.md and `refere
 
 | 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 |
+| `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/<sid>/system/sub-agent-<role>.json` if they need to record state, but never the main presence file.
+- 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.
 - **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.
@@ -684,7 +714,7 @@ Skipping the entire swarm (when `--type` is `config|docs|chore`) is not a degrad
 
 Before computing the swarm plan, Solo runs the keyword scan deterministically:
 
-1. Read `.peaks/<session-id>/prd/requests/<rid>.md` body.
+1. Read `.peaks/_runtime/<sessionId>/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).
@@ -782,9 +812,9 @@ Before orchestrating an end-to-end code repository workflow, gather the project
 
 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/<id>/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.
+**CRITICAL — Standards must reflect the project scan.** When generating or updating `CLAUDE.md`, the content must reference concrete findings from `.peaks/<changeId>/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/<id>/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.
+**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/<changeId>/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.
 
@@ -811,7 +841,7 @@ It must enforce the shared refactor red lines:
 4. split broad refactors into minimal functional slices;
 5. require strict verifiable specs before each slice;
 6. require 100% acceptance for each slice;
-7. require code changes and sanitized intermediate artifacts to be traceable in local `.peaks/<session-id>/` storage before the next slice; commit or sync sanitized artifacts only when explicitly authorized.
+7. require code changes and sanitized intermediate artifacts to be traceable in local `.peaks/_runtime/<sessionId>/` storage before the next slice; commit or sync sanitized artifacts only when explicitly authorized.
 
 ## Peaks-Cli Quality-gate commands (CLI cheat sheet)
 
@@ -868,7 +898,7 @@ Detailed rules: `references/external-skill-invocation.md`, `references/openspec-
 
 Sub-agent artifacts (rd/tech-doc.md, qa/test-cases/&lt;rid&gt;.md, ui/design-draft.md) MUST NOT be inlined into dispatch records and fed back to the main LLM during reduce.
 
-- Sub-agent writes artifact to disk at a known path (path convention: `.peaks/_sub_agents/<sid>/artifacts/<rid>-<role>-<idx>.<ext>`).
+- Sub-agent writes artifact to disk at a known path (path convention: `.peaks/_sub_agents/<sessionId>/artifacts/<rid>-<role>-<idx>.<ext>`).
 - Sub-agent calls `peaks sub-agent dispatch --write-artifact <path>` (or via dispatch CLI flag). The CLI computes sha256 + size + writes `ArtifactMeta` to record.
 - Main LLM reduces the batch and sees ONLY the metadata view (~200 chars per sub-agent, vs ~1MB if content were inlined) — a 3000-5000× reduction.
 - Main LLM decides whether to `Read <path>` for full content (LLM tool call, NOT via peaks CLI).
@@ -892,7 +922,7 @@ If a sub-agent prompt is too large even after G7 metadata-only (e.g. 1MB artifac
 
 Sub-agent A's completion **immediately** writes a shared entry; sub-agent B (still in flight) can read shared entries from sibling sub-agents. **This is NOT peer-to-peer messaging.** The dispatcher stores, the sub-agents read/write; A and B never directly talk.
 
-- Path: `.peaks/_sub_agents/<sid>/shared/<batchId>.json`.
+- Path: `.peaks/_sub_agents/<sessionId>/shared/<batchId>.json`.
 - Two new CLI atoms (NO new top-level CLI): `peaks sub-agent share` + `peaks sub-agent shared-read`.
 - RL-23 strong constraint: when sub-agent calls `peaks sub-agent heartbeat --status done`, it MUST also call `peaks sub-agent share --key "<role>.completed" --value <artifact-meta>`.
 

package/skills/peaks-solo/references/browser-workflow.md

@@ -33,7 +33,7 @@ peaks mcp apply  --capability playwright-mcp.browser-validation --yes --json
 
 If a non-peaks-managed Playwright MCP entry already exists in `.claude/settings.json`, `apply` will refuse unless `--claim` is passed. Discuss with the user before claiming.
 
-After install, Claude Code's MCP runtime exposes the tools under the `mcp__playwright__*` namespace. Peaks skills reference these tools directly; they are not invoked through `peaks mcp call` because Claude Code is the host that calls them.
+After install, Claude Code's MCP runtime exposes the tools under the `mcp__playwright__*` namespace. Peaks skill bodies reference these tools via the `peaks mcp call` primitive (the skill body never bakes in the `mcp__playwright__` prefix; the prefix is owned by Claude Code's runtime, and `peaks mcp call` is the load-bearing fallback for sub-agents and non-Claude IDEs). The 4-step plan → apply → call pattern is the contract.
 
 ## Optional: install Chrome DevTools MCP for CDP inspection
 
@@ -44,38 +44,40 @@ peaks mcp plan   --capability chrome-devtools-mcp.browser-debug --json
 peaks mcp apply  --capability chrome-devtools-mcp.browser-debug --yes --json
 ```
 
-Tools become available under `mcp__chrome-devtools__*`. They fail with "Could not connect to Chrome" if no Chrome is running on `:9222`; that is by design.
+Tools become available under `mcp__chrome-devtools__*` in the LLM runtime. Peaks skill bodies invoke them via `peaks mcp call --capability chrome-devtools-mcp.browser-debug --tool <name> --args-json '<args>' --json` (the skill body never bakes in the `mcp__chrome-devtools__` prefix). They fail with "Could not connect to Chrome" if no Chrome is running on `:9222`; that is by design.
 
 ## Tool mapping for the "open a browser on demand" path (Playwright MCP)
 
-| Verb | Playwright MCP tool | Notes |
+| Verb | peaks mcp call invocation | Notes |
 |---|---|---|
-| Open visible browser and navigate | `mcp__playwright__browser_navigate` with `url` | Spawns a headed browser if none open; navigates in the existing context otherwise. |
-| Confirm visible browser opened | `mcp__playwright__browser_take_screenshot` | Screenshot is the visible-browser confirmation. |
-| Read structured page (text + a11y) | `mcp__playwright__browser_snapshot` | Accessibility tree with element refs. |
-| Click / fill / press key | `mcp__playwright__browser_click`, `browser_fill`, `browser_press_key` | Drive the page after navigation. |
-| Inspect console errors | `mcp__playwright__browser_console_messages` | Pass `level` to filter (`error`, `warning`). |
-| Inspect network failures | `mcp__playwright__browser_network_requests` | Pass `filter` regex when the page has many requests. |
-| Resize viewport for responsive checks | `mcp__playwright__browser_resize` | |
-| Capture a full-page screenshot | `mcp__playwright__browser_take_screenshot` with `fullPage: true` | Sanitize before retention. |
-| Close the session cleanly | `mcp__playwright__browser_close` | End-of-task. |
+| Open visible browser and navigate | `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_navigate --args-json '{"url":"<url>"}' --json` | Spawns a headed browser if none open; navigates in the existing context otherwise. |
+| Confirm visible browser opened | `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_take_screenshot --args-json '{"filename":"<abs-path>"}' --json` | Screenshot is the visible-browser confirmation. |
+| Read structured page (text + a11y) | `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_snapshot --args-json '{}' --json` | Accessibility tree with element refs. |
+| Click / fill / press key | `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_click --args-json '<args>' --json` (and `browser_fill`, `browser_press_key`) | Drive the page after navigation. |
+| Inspect console errors | `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_console_messages --args-json '{"level":"error"}' --json` | Pass `level` to filter (`error`, `warning`). |
+| Inspect network failures | `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_network_requests --args-json '{"filter":"<regex>"}' --json` | Pass `filter` regex when the page has many requests. |
+| Resize viewport for responsive checks | `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_resize --args-json '<args>' --json` | |
+| Capture a full-page screenshot | `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_take_screenshot --args-json '{"filename":"<abs-path>","fullPage":true}' --json` | Sanitize before retention. |
+| Close the session cleanly | `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_close --args-json '{}' --json` | End-of-task. |
+| **Reference (runtime prefix, do not bake into skills)** | `mcp__playwright__<toolName>` | The Claude Code runtime prefix; the LLM resolves this from the registered server. The skill body uses `peaks mcp call` exclusively. |
 
 ## Tool mapping for the "connect to running Chrome" path (Chrome DevTools MCP, optional)
 
-| Verb | Chrome DevTools MCP tool | Notes |
+| Verb | peaks mcp call invocation | Notes |
 |---|---|---|
-| List pages in user's Chrome | `mcp__chrome-devtools__list_pages` | Requires Chrome already running with `--remote-debugging-port=9222`. |
-| Bring a tab to front | `mcp__chrome-devtools__select_page` with `bringToFront: true` | Useful when the user navigated themselves. |
-| Screenshot the visible viewport | `mcp__chrome-devtools__take_screenshot` | |
-| Read structured page | `mcp__chrome-devtools__take_snapshot` | |
-| Performance trace | `mcp__chrome-devtools__performance_start_trace` then `performance_stop_trace` | |
-| Lighthouse audit | `mcp__chrome-devtools__lighthouse_audit` with `mode: snapshot` | |
+| List pages in user's Chrome | `peaks mcp call --capability chrome-devtools-mcp.browser-debug --tool list_pages --args-json '{}' --json` | Requires Chrome already running with `--remote-debugging-port=9222`. |
+| Bring a tab to front | `peaks mcp call --capability chrome-devtools-mcp.browser-debug --tool select_page --args-json '{"bringToFront":true}' --json` | Useful when the user navigated themselves. |
+| Screenshot the visible viewport | `peaks mcp call --capability chrome-devtools-mcp.browser-debug --tool take_screenshot --args-json '<args>' --json` | |
+| Read structured page | `peaks mcp call --capability chrome-devtools-mcp.browser-debug --tool take_snapshot --args-json '{}' --json` | |
+| Performance trace | `peaks mcp call --capability chrome-devtools-mcp.browser-debug --tool performance_start_trace --args-json '<args>' --json` then `performance_stop_trace` (each via `peaks mcp call`) | |
+| Lighthouse audit | `peaks mcp call --capability chrome-devtools-mcp.browser-debug --tool lighthouse_audit --args-json '{"mode":"snapshot"}' --json` | |
+| **Reference (runtime prefix, do not bake into skills)** | `mcp__chrome-devtools__<toolName>` | The Claude Code runtime prefix; the LLM resolves this from the registered server. The skill body uses `peaks mcp call` exclusively. |
 
 If Chrome is not running on `:9222`, every Chrome DevTools MCP tool fails. The skill must surface that as a blocked precondition, not silently fall back.
 
 ## URL allow-list (always required before navigation)
 
-Before calling `mcp__playwright__browser_navigate` (or any other navigation), verify:
+Before calling `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_navigate --args-json '{"url":"<url>"}' --json` (or any other navigation), verify:
 
 1. URL uses `https:` (reject `http:`, `file:`, `data:`, `javascript:`).
 2. Host belongs to an approved domain for the role (Feishu/Lark tenant for PRD product docs, the user-approved app target for UI/QA validation).

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

@@ -20,12 +20,12 @@ peaks skill runbook peaks-solo --json
 peaks workspace init --project <repo> --json
 peaks workspace reconcile --project <repo> --json
 peaks scan archetype --project <repo> --json
-# → copy archetype, frontendOnly, signals into .peaks/<session-id>/rd/project-scan.md (Peaks-Cli Gate A)
-# → copy libraries[] into .peaks/<session-id>/rd/project-scan.md under `## Library versions`
+# → copy archetype, frontendOnly, signals into .peaks/_runtime/<session-id>/rd/project-scan.md (Peaks-Cli Gate A)
+# → copy libraries[] into .peaks/_runtime/<session-id>/rd/project-scan.md under `## Library versions`
 peaks scan libraries --project <repo> --json
 # → if archetype != greenfield AND archetype != unknown:
 peaks scan existing-system --project <repo> --json
-# → copy tokens, sources, conventions, inconsistencies into .peaks/<session-id>/system/existing-system.md (Peaks-Cli Gate A.5)
+# → copy tokens, sources, conventions, inconsistencies into .peaks/_runtime/<session-id>/system/existing-system.md (Peaks-Cli Gate A.5)
 
 # 1. Peaks-Cli Standards preflight + apply
 #    Run dry-run first to inspect deltas, then APPLY. In full-auto and swarm modes,
@@ -55,7 +55,7 @@ peaks request transition <rid> --role prd --state handed-off --project <repo> --
 
 # 3. Peaks-Cli Swarm parallel — sub-agent fan-out (peaks sub-agent dispatch, NOT Skill tool)
 #    Solo computes the swarm plan from --type + frontendOnly + frontend-keyword scan,
-#    writes it to .peaks/<sid>/sc/swarm-plan.json, then launches one
+#    writes it to .peaks/_runtime/<sid>/sc/swarm-plan.json, then launches one
 #    `peaks sub-agent dispatch <role>` call per sub-agent in the same message.
 #    See "Peaks-Cli Swarm parallel phase" above for the full decision table and the
 #    prompt template; the role's required artefact paths are listed there.
@@ -80,36 +80,36 @@ peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate swarm-
 #     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)
+ls .peaks/_runtime/<sid>/prd/requests/<rid>.md                # PRD artefact must exist (Gate B hard)
+# feature / refactor → ls .peaks/_runtime/<sid>/rd/tech-doc.md
+# bugfix             → ls .peaks/_runtime/<sid>/rd/bug-analysis.md
+ls .peaks/_runtime/<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)
+ls .peaks/_runtime/<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)
-#    feature / refactor → write .peaks/<id>/rd/tech-doc.md
-#    bugfix             → write .peaks/<id>/rd/bug-analysis.md
+#    feature / refactor → write .peaks/_runtime/<id>/rd/tech-doc.md
+#    bugfix             → write .peaks/_runtime/<id>/rd/bug-analysis.md
 #    config             → no planning artifact required at this state
 #    docs / chore       → no planning artifact required
 peaks request transition <rid> --role rd --state implemented --project <repo> --json
 
 # 5. Peaks-Cli Code review + security review BEFORE qa-handoff transition.
 #    Produce the evidence files the CLI gate enforces:
-#      - .peaks/<id>/rd/code-review.md     (CRITICAL/HIGH findings + fixes; required for feature/bugfix/refactor)
-#      - .peaks/<id>/rd/security-review.md (required for feature/bugfix/refactor/config)
+#      - .peaks/_runtime/<id>/rd/code-review.md     (CRITICAL/HIGH findings + fixes; required for feature/bugfix/refactor)
+#      - .peaks/_runtime/<id>/rd/security-review.md (required for feature/bugfix/refactor/config)
 #    Then transition. If --type is docs/chore the gate is empty and the transition is unguarded.
 peaks request transition <rid> --role rd --state qa-handoff --project <repo> --json
 
 # 6. Peaks-Cli QA validation (AUTO-PROCEED from RD in full-auto)
 #    Before each QA transition, produce the evidence files the CLI gate enforces:
-#      Before qa:running        → .peaks/<id>/qa/test-cases/<rid>.md
+#      Before qa:running        → .peaks/_runtime/<id>/qa/test-cases/<rid>.md
 peaks request transition <rid> --role qa --state running --project <repo> --json
-#      Before qa:verdict-issued → .peaks/<id>/qa/test-reports/<rid>.md
-#                                 + .peaks/<id>/qa/security-findings.md
-#                                 + .peaks/<id>/qa/performance-findings.md (feature/refactor only)
+#      Before qa:verdict-issued → .peaks/_runtime/<id>/qa/test-reports/<rid>.md
+#                                 + .peaks/_runtime/<id>/qa/security-findings.md
+#                                 + .peaks/_runtime/<id>/qa/performance-findings.md (feature/refactor only)
 peaks request transition <rid> --role qa --state verdict-issued --project <repo> --json
 # → Peaks-Cli Gate D check. Assisted/Strict: [CONFIRM]
 
@@ -135,12 +135,12 @@ peaks openspec archive <cid> --project <repo> --apply --json
 peaks workspace reconcile --project <repo> --apply --older-than 7
 
 # 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. Inside the
+#     peaks-txt writes the handoff capsule to .peaks/_runtime/<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
+#      grep -n "peaks-memory:start" .peaks/_runtime/<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.
@@ -148,7 +148,7 @@ peaks workspace reconcile --project <repo> --apply --older-than 7
 # 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`
+#                            --artifact .peaks/_runtime/<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
@@ -156,7 +156,7 @@ peaks workspace reconcile --project <repo> --apply --older-than 7
 #      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
+peaks memory extract --project <repo> --artifact .peaks/_runtime/<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.
 

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

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

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

@@ -16,7 +16,7 @@ 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/<session-id>/system/sub-agent-<role>.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.
@@ -47,14 +47,14 @@ Steps:
 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/<sid>/ui/design-draft.md
-   - .peaks/<sid>/ui/requests/<rid>.md
+   - .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/<sid>/ui/design-draft.md", ".peaks/<sid>/ui/requests/<rid>.md"],
+     "artefacts": [".peaks/_runtime/<sid>/ui/design-draft.md", ".peaks/_runtime/<sid>/ui/requests/<rid>.md"],
      "warnings": [],
      "blockedReason": null
    }
@@ -80,15 +80,15 @@ Steps:
    into rd/project-scan.md.
 5. Read <existing-system-path> if archetype is legacy-*.
 6. Write the type-appropriate planning artefact:
-   - feature | refactor  → .peaks/<sid>/rd/tech-doc.md
-   - bugfix              → .peaks/<sid>/rd/bug-analysis.md
+   - 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/<sid>/rd/tech-doc.md"],   // or [] when skipped
+     "artefacts": [".peaks/_runtime/<sid>/rd/tech-doc.md"],   // or [] when skipped
      "warnings": [],
      "blockedReason": null
    }
@@ -106,14 +106,14 @@ Steps:
 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/<sid>/qa/test-cases/<rid>.md with test cases linked to PRD
+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/<sid>/qa/test-cases/<rid>.md"],
+     "artefacts": [".peaks/_runtime/<sid>/qa/test-cases/<rid>.md"],
      "warnings": [],
      "blockedReason": null
    }

package/skills/peaks-ui/SKILL.md

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