peaks-cli 1.3.4 → 1.3.6

package/skills/peaks-rd/SKILL.md

@@ -43,7 +43,7 @@ For frontend or UI-affecting slices, RD's self-test uses the Playwright MCP head
 
 ### Contract 1 — Self-test screenshots must land under .peaks/_runtime/<sessionId>/qa/screenshots/
 
-Even though RD runs the self-test, **the screenshot evidence is QA's** by convention (the test report under `.peaks/_runtime/<sessionId>/qa/test-reports/` cites these paths). Therefore RD's Playwright screenshot tool calls (via `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_take_screenshot --args-json '<args>' --json`) MUST pass `filename` (in the args object) whose absolute path is inside `.peaks/_runtime/<sessionId>/qa/screenshots/`, exactly the same contract QA enforces. Do not let Playwright fall back to the project root.
+Even though RD runs the self-test, **the screenshot evidence is QA's** by convention (the test report under `.peaks/_runtime/<sessionId>/qa/test-reports/` cites these paths). Therefore RD's Playwright screenshot tool calls (the LLM invokes `browser_take_screenshot` directly when the the Playwright MCP tools are present in the LLM's tool list) MUST pass `filename` (in the args object) whose absolute path is inside `.peaks/_runtime/<sessionId>/qa/screenshots/`, exactly the same contract QA enforces. Do not let Playwright fall back to the project root. If the the Playwright MCP tools are absent from the tool list, STOP and tell the user: `claude mcp add playwright -- npx @playwright/mcp@latest` (Claude Code) or consult the IDE's MCP install docs.
 
 ### Contract 2 — Login / CAPTCHA / SSO / MFA wall is a hard block, not a skip
 
@@ -119,21 +119,6 @@ On the first presence:set in a project, ensure the out-of-band status bar is ins
 peaks statusline install --project <repo>   # idempotent; skips if already installed
 ```
 
-**Auto-spawn a progress watch terminal once per slice (BLOCKING on the first phase transition).** The user opens a fresh VSCode window per slice, not per Bash call. Without a separate progress terminal the user has no live signal that the sub-agent is alive — the only signal they have is the static statusline. So at the first phase transition of every slice, fire `peaks progress start` ONCE. The CLI auto-spawns a new terminal tab running `peaks progress watch` and the user can close the new tab at any time. Do NOT re-invoke on every phase change — one per slice is the contract. The LLM-side cost of this one invocation is one Bash call plus a small JSON envelope; the watch side is a 1s file poll that does not consume LLM tokens.
-
-```bash
-# At the first phase transition of a slice (after the first
-# peaks progress step), fire the watch:
-peaks progress start --project <repo> --reason "rd-implementing for <rid>"
-
-# On every subsequent phase transition, only update the
-# progress file — the watch is already running in another tab:
-peaks progress step --project <repo> --request-id <rid> --role rd \
-  --step "running pnpm test" --phase running
-```
-
-If `peaks progress start` is unsupported on the current platform (no terminal emulator, headless container, etc.) it returns a recoverable error envelope. Surface that in the RD handoff so the user knows the auto-spawn failed; the sub-agent can still emit `peaks progress step` writes that the user reads from the on-disk file. The auto-spawn is convenience, not a gate.
-
 Read persistent project memory via CLI (durable, LLM-authored memories):
 
 ```bash
@@ -264,9 +249,11 @@ peaks codegraph affected --project <repo> <changed-files...> --json
 # NEVER write mock data inline in component files.
 # See "Mock data placement rules" section for the full framework mapping.
 
-# 5. optional library docs lookup through an installed MCP server
-peaks mcp list --json
-peaks mcp call --capability context7.docs-lookup --tool <name> --args-json '{...}' --json
+# 5. optional library docs lookup through the LLM's own tool list (Context7 MCP)
+# If the Context7 MCP is present in the tool list, invoke the
+# tool directly (resolve-library-id / query-docs / etc.). If absent, skip
+# library docs and rely on existing project knowledge — do NOT hand-edit
+# `~/.claude/settings.json` to install MCPs.
 
 # 6. record red-line scope, slice contract, coverage status into the RD artifact, then implement
 
@@ -581,7 +568,7 @@ RD cannot mark a development slice complete until all of these are true. Each ga
 1. OpenSpec change artifacts exist and are linked for non-trivial work when the target repo already has `openspec/`, or the user has approved adding it;
 2. unit tests covering the new or changed behavior have been added or updated and run successfully; **→ verified by Peaks-Cli Gate B2**
 3. if the repository is legacy and total UT coverage is below the project target, do not block on historical coverage, but require coverage evidence for newly added or changed code;
-4. for frontend or UI-affecting slices, RD self-test has launched the app and used Playwright MCP for real browser end-to-end validation with visible-browser confirmation (install via `peaks mcp plan --capability playwright-mcp.browser-validation --json` then `peaks mcp apply --capability playwright-mcp.browser-validation --yes --json` if not yet present; navigate with `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_navigate --args-json '<args>' --json`, capture with `browser_snapshot` / `browser_take_screenshot` / `browser_console_messages` / `browser_network_requests` (each via `peaks mcp call`), sanitize route/actions and observations before retention, record acceptance result, close with `browser_close` (via `peaks mcp call`)); the skill body never bakes in the `mcp__playwright__` prefix; if login, CAPTCHA, SSO, or MFA appears, the headed browser is already visible — wait for the user to complete login and explicitly confirm completion before continuing;
+4. for frontend or UI-affecting slices, RD self-test has launched the app and used the Playwright MCP for real browser end-to-end validation with visible-browser confirmation (the LLM checks its own tool list for any Playwright MCP entry in the LLM tool list; if absent, the user installs via `claude mcp add playwright -- npx @playwright/mcp@latest` — RD does NOT hand-edit `~/.claude/settings.json` or auto-install on the user's behalf); navigate with `browser_navigate`, capture with `browser_snapshot` / `browser_take_screenshot` / `browser_console_messages` / `browser_network_requests`, sanitize route/actions and observations before retention, record acceptance result, close with `browser_close`; if login, CAPTCHA, SSO, or MFA appears, the headed browser is already visible — wait for the user to complete login and explicitly confirm completion before continuing;
 5. code review has been performed with findings recorded and CRITICAL/HIGH issues fixed before progression; unresolved CRITICAL/HIGH findings only allow a blocked handoff; **→ verified by Peaks-Cli Gate B3** — evidence file must exist at `.peaks/<changeId>/rd/code-review.md`
 6. security review has been performed for the changed surface, with CRITICAL/HIGH issues fixed before progression and particular attention to user input, file system access, external calls, auth, secrets, and dependency changes; **→ verified by Peaks-Cli Gate B4** — evidence file must exist at `.peaks/<changeId>/rd/security-review.md`
 6.5. perf-baseline output is in place for any slice with a user-perceivable performance surface — `peaks perf baseline --apply` has been run and `.peaks/_runtime/<sessionId>/rd/perf-baseline.md` exists with the Results table filled in with measurements (or `N/A — no perf surface` in Notes for slices without a perf surface). For docs / chore / pure-bugfix-no-perf, the file is not required. Run the fan-out from "Parallel review fan-out" below; **→ verified by Peaks-Cli Gate B9** — evidence file must exist at `.peaks/<changeId>/rd/perf-baseline.md` and contain a non-empty Results table or the N/A marker.
@@ -816,7 +803,7 @@ Do not run upstream installer flows, mutate agent settings, or commit `.codegrap
 
 **Other external resources** (Context7, SearchCode, everything-claude-code, GitNexus, etc.): Use `peaks capabilities --source access-repo/mcp-server --json` for capability discovery before recommending. References only — do not execute upstream installers, do not install upstream resources, do not persist sensitive examples. Peaks-Cli RD gates remain authoritative.
 
-**OpenSpec and MCP CLI**: Route through Peaks-Cli CLI (`peaks openspec show/to-rd/render`, `peaks mcp list/plan/apply/call`). Do not hand-edit `openspec/changes/**` or `~/.claude/settings.json`. Recipes: `references/openspec-mcp-cli.md`.
+**OpenSpec CLI**: Route through Peaks-Cli CLI (`peaks openspec show/to-rd/render`). Do not hand-edit `openspec/changes/**`. Recipes: `references/openspec-cli.md`. (MCP CLI was retired in slice #016; the LLM's own tool list is the source of truth for which MCPs are installed.)
 
 ## Boundaries
 

package/skills/peaks-rd/references/{openspec-mcp-cli.md → openspec-cli.md}

@@ -1,6 +1,8 @@
-# OpenSpec and MCP CLI for Peaks RD
+# OpenSpec CLI for Peaks RD
 
-Peaks RD reads OpenSpec change packs and external MCP servers through the Peaks CLI rather than re-parsing markdown or spawning subprocesses by hand. The CLI returns the same stable envelope shape (`{ ok, command, data, warnings, nextActions }`) so RD can capture it as artifact JSON.
+Peaks RD reads OpenSpec change packs through the Peaks CLI rather than re-parsing markdown or spawning subprocesses by hand. The CLI returns the same stable envelope shape (`{ ok, command, data, warnings, nextActions }`) so RD can capture it as artifact JSON.
+
+> **Slice #016 (2026-06-09)**: this document used to live at `openspec-mcp-cli.md` and contained a section on the now-retired peaks-cli MCP install / call verbs. The MCP subsystem was retired in slice #016; the LLM's own tool list is now the source of truth for installed MCPs. The OpenSpec CLI recipes below are unchanged.
 
 ## Loading an existing OpenSpec change as RD input
 
@@ -43,23 +45,18 @@ The request JSON shape is:
 
 `render --apply` refuses to overwrite an existing change directory unless `--overwrite` is passed. Treat that refusal as intentional.
 
-## Calling MCP tools for research evidence
+## Library docs lookup via the LLM's own MCP tool list (slice #016)
 
-When RD needs external library or API docs, prefer a registered MCP server through Peaks instead of free-form web fetches:
+When RD needs external library or API docs, the consuming LLM checks its own tool list for an MCP entry (typically `mcp__plugin_context7_context7__*` for Context7). If present, the LLM invokes the tool by name directly (`resolve-library-id` then `query-docs` are the canonical Context7 tool names). If absent, the LLM tells the user the install command:
 
 ```bash
-peaks mcp list --json
-peaks mcp plan --capability context7.docs-lookup --json
-peaks mcp apply --capability context7.docs-lookup --yes --json   # one-time install
-peaks mcp call --capability context7.docs-lookup --tool <toolName> --args-json '{...}' --json
+# Claude Code:
+claude mcp add context7 -- npx @upstash/context7-mcp
+# Restart the IDE after install; the runtime picks up the new server only after a fresh process.
 ```
 
-Rules:
-
-- `plan` must be inspected before `apply`. `apply` is a real side effect; it backs up `~/.claude/settings.json` first.
-- Required env vars must be present before `apply` and `call`; Peaks refuses to spawn a server with missing env.
-- `call` results should be written into the RD artifact (e.g. `.peaks/<session-id>/rd/mcp-call-<ts>.json`) as the evidence link. Do not paste secrets or full network bodies into the RD handoff.
+peaks-cli does not install MCPs on the user's behalf as of slice #016; the LLM is the executor and the IDE is the dispatcher. Evidence of the lookup (sanitized query + response summary) goes into the RD artifact, not full network bodies or secrets.
 
 ## Boundary
 
-Peaks RD must not hand-edit `openspec/changes/**` or `~/.claude/settings.json` directly. All writes go through the CLI commands above with dry-run preview, explicit confirmation, and Peaks-managed source labels.
+Peaks RD must not hand-edit `openspec/changes/**` or `~/.claude/settings.json` directly. All OpenSpec writes go through the CLI commands above with dry-run preview, explicit confirmation, and Peaks-managed source labels.

package/skills/peaks-solo/SKILL.md

@@ -324,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 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`.
+For frontend workflows, RD and QA must use Playwright MCP for real browser E2E. The consuming LLM detects the MCP from its own tool list: any Playwright MCP entry in the LLM tool list means the MCP is installed; absent means the user needs to install (`claude mcp add playwright -- npx @playwright/mcp@latest` in Claude Code; other IDEs have their own MCP install path). The LLM invokes the tool directly (browser_navigate / browser_click / browser_snapshot / browser_take_screenshot / browser_console_messages / browser_network_requests / browser_close) by name — there is no peaks-cli indirection. 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)
 

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

@@ -99,7 +99,7 @@ To keep the mapping honest, peaks-cli **does not** currently provide the followi
 - 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 **cross-vendor discovery**. peaks has no A2A registry entry; MCP-compatible capabilities are discovered by the LLM via its own tool list (the LLM checks for `mcp__<server>__*` entries in its own function schema) and reported back to the user. Slice #016 retired the `peaks mcp *` indirection layer.
 - 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).

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

@@ -11,6 +11,8 @@ Peaks skills standardize on **Playwright MCP** as the controlled headed-browser
 
 > **Bug history**: an earlier version of this document recommended Chrome DevTools MCP for "open a headed browser when peaks-solo gets a product document link." Dogfood testing in 2026-05 revealed the tool requires a pre-running Chrome with remote debugging enabled — it does NOT launch its own browser. Playwright MCP is the correct tool for the "open on demand" case.
 
+> **Slice #016 (2026-06-09)**: peaks-cli no longer manages MCP install / dispatch. Skill bodies instruct the LLM to (a) check its own tool list for any Playwright MCP entry, (b) invoke the tool by name if present, (c) tell the user the install command if absent. There is no peaks-cli MCP indirection layer anymore.
+
 ## When to open the headed browser
 
 Open a controlled browser when:
@@ -21,63 +23,71 @@ Open a controlled browser when:
 
 Never open a browser to bypass authentication, run arbitrary URLs the user has not approved, or interact with payment / delete / authenticated mutation flows without explicit user confirmation.
 
-## Install the Playwright MCP server (one-time)
+## Playwright MCP — install + detect
+
+The LLM runtime exposes Playwright's tools under the `mcp__playwright__*` namespace when the user has installed the MCP. Skill bodies MUST NOT bake the prefix into a SKILL.md or reference; the prefix is owned by the LLM runtime.
+
+**Detect**: the LLM checks its own tool list for any `mcp__playwright__*` entry. If present, the MCP is installed; the LLM invokes the tool by name (e.g. `browser_navigate`, `browser_take_screenshot`).
 
-Capability discovery exposes `playwright-mcp.browser-validation`. Install through the Peaks CLI rather than hand-editing settings.json so the peaks-managed marker and backup flow apply:
+**Install (if absent)**: skill bodies surface the install command to the user. The user runs it themselves — peaks-cli does not hand-edit `~/.claude/settings.json`.
 
-```bash
-peaks mcp list --json
-peaks mcp plan   --capability playwright-mcp.browser-validation --json
-peaks mcp apply  --capability playwright-mcp.browser-validation --yes --json
-```
+- Claude Code:
+  ```bash
+  claude mcp add playwright -- npx @playwright/mcp@latest
+  ```
+  Restart Claude Code (or reload the window) so the MCP runtime picks up the new server.
 
-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.
+- Other IDEs (Trae, Cursor, Codex, Qoder, Tongyi, ...): consult the IDE's MCP install docs. The install command and the runtime prefix differ per IDE; the LLM checks the tool list rather than assuming a prefix.
 
-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.
+The skill body uses the LLM's tool list as the source of truth — never the cached `~/.claude/settings.json` (the LLM cannot read the file, and the file's contents may have drifted from runtime state).
 
-## Optional: install Chrome DevTools MCP for CDP inspection
+## Chrome DevTools MCP — optional, secondary surface
 
-When inspecting an already-running Chrome (e.g., the user's own browser session opened with `chrome --remote-debugging-port=9222`), additionally install Chrome DevTools MCP:
+When inspecting an already-running Chrome (e.g., the user's own browser session opened with `chrome --remote-debugging-port=9222`), the LLM checks its tool list for any `mcp__chrome_devtools__*` entry. If present, the LLM invokes the tool by name directly (e.g. `list_pages`, `take_screenshot`, `performance_start_trace`).
 
-```bash
-peaks mcp plan   --capability chrome-devtools-mcp.browser-debug --json
-peaks mcp apply  --capability chrome-devtools-mcp.browser-debug --yes --json
-```
+Install (if absent) is the user's responsibility:
 
-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.
+- Claude Code:
+  ```bash
+  claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
+  ```
+
+Chrome DevTools tools fail with "Could not connect to Chrome" if no Chrome is running on `:9222`; that is by design and the skill must surface it as a blocked precondition, not silently fall back.
 
 ## Tool mapping for the "open a browser on demand" path (Playwright MCP)
 
-| Verb | peaks mcp call invocation | Notes |
+The LLM invokes these tools directly from its `mcp__playwright__*` namespace. Peaks skill bodies describe the args shape; the LLM supplies them.
+
+| Verb | Direct invocation (LLM tool list) | Notes |
 |---|---|---|
-| 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. |
+| Open visible browser and navigate | `browser_navigate --args '{"url":"<url>"}'` | Spawns a headed browser if none open; navigates in the existing context otherwise. |
+| Confirm visible browser opened | `browser_take_screenshot --args '{"filename":"<abs-path>"}'` | Screenshot is the visible-browser confirmation. |
+| Read structured page (text + a11y) | `browser_snapshot --args '{}'` | Accessibility tree with element refs. |
+| Click / fill / press key | `browser_click --args '<args>'` (and `browser_type`, `browser_press_key`) | Drive the page after navigation. |
+| Inspect console errors | `browser_console_messages --args '{"level":"error"}'` | Pass `level` to filter (`error`, `warning`). |
+| Inspect network failures | `browser_network_requests --args '{"filter":"<regex>"}'` | Pass `filter` regex when the page has many requests. |
+| Resize viewport for responsive checks | `browser_resize --args '<args>'` | |
+| Capture a full-page screenshot | `browser_take_screenshot --args '{"filename":"<abs-path>","fullPage":true}'` | Sanitize before retention. |
+| Close the session cleanly | `browser_close --args '{}'` | End-of-task. |
+| **Runtime prefix (LLM-owned, do not bake into skills)** | `mcp__playwright__<toolName>` | The Claude Code / Trae / etc. runtime prefix; the LLM resolves this from the registered server. |
 
 ## Tool mapping for the "connect to running Chrome" path (Chrome DevTools MCP, optional)
 
-| Verb | peaks mcp call invocation | Notes |
+| Verb | Direct invocation (LLM tool list) | Notes |
 |---|---|---|
-| 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. |
+| List pages in user's Chrome | `list_pages --args '{}'` | Requires Chrome already running with `--remote-debugging-port=9222`. |
+| Bring a tab to front | `select_page --args '{"bringToFront":true}'` | Useful when the user navigated themselves. |
+| Screenshot the visible viewport | `take_screenshot --args '<args>'` | |
+| Read structured page | `take_snapshot --args '{}'` | |
+| Performance trace | `performance_start_trace --args '<args>'` then `performance_stop_trace` | |
+| Lighthouse audit | `lighthouse_audit --args '{"mode":"snapshot"}'` | |
+| **Runtime prefix (LLM-owned, do not bake into skills)** | `mcp__chrome_devtools__<toolName>` | The Claude Code / Trae / etc. runtime prefix; the LLM resolves this from the registered server. |
 
 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 `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_navigate --args-json '{"url":"<url>"}' --json` (or any other navigation), verify:
+Before invoking `browser_navigate --args '{"url":"<url>"}'` (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).
@@ -107,10 +117,11 @@ Redact sensitive values before retention. Store evidence as sanitized observatio
 
 ## Fallback when Playwright MCP is not installed
 
-If `peaks mcp list --json` does not include `playwright` in `mcpServers`:
+If the LLM tool list does not include `mcp__playwright__*`:
 
-1. Surface the install commands above (peaks mcp plan / apply).
+1. Surface the install command for the user's IDE (the Claude Code install is `claude mcp add playwright -- npx @playwright/mcp@latest`; other IDEs differ).
 2. Do not silently fall back to unauthenticated fetch tools, screenshots-only, or manual transcription.
 3. Frontend QA workflows that require headed browser validation mark the gate `blocked` with the install command in the next action. Manual steps or text-only fetching do not substitute for the mandatory headed browser gate.
+4. Restart the IDE after install; the runtime picks up the new server only after a fresh process / window reload.
 
 Peaks role artifacts (PRD / UI / RD / QA) remain authoritative for what evidence the role recorded; Playwright MCP is the tool, not the verdict.

package/skills/peaks-solo/references/external-skill-invocation.md

@@ -4,13 +4,15 @@ Peaks skills reference many external resources — `mattpocock/skills`, `gstack`
 
 Every reference must follow the same three-stage pattern so the Peaks gates stay authoritative and side effects stay observable.
 
+> **Slice #016 (2026-06-09)**: peaks-cli no longer manages MCP install or invocation. MCP capability detection moves from the peaks-cli CLI to the LLM's own tool list (the LLM checks for `mcp__<server>__*` entries in its own function schema). Skill bodies instruct the LLM to either invoke the tool by name (when present) or tell the user the install command (when absent).
+
 ## Stage 1 — Discovery before naming
 
-Do not name an external skill or MCP server as if it is always available. Route discovery through the Peaks CLI first:
+Do not name an external skill or MCP server as if it is always available. Route discovery through the Peaks CLI for non-MCP capabilities, and through the LLM's own tool list for MCP capabilities:
 
 - `peaks capabilities --source access-repo --json` for non-MCP capabilities (skills, agents, rules, browser tools).
-- `peaks capabilities --source mcp-server --json` for MCP servers.
-- `peaks mcp list --json` for currently configured MCP servers in `.claude/settings.json`.
+- `peaks capabilities --source mcp-server --json` for MCP catalog discovery (which MCPs are *known*, not which are *installed*).
+- For MCP install state, the LLM checks its own tool list for any `mcp__<server>__*` entry. If present, the MCP is installed. If absent, the user installs via the IDE-native MCP install command (e.g. `claude mcp add <server> -- <npx-command>` for Claude Code).
 
 A skill body may mention the capability id, but it must say or imply that the skill only applies "when capability discovery exposes …" (or equivalent phrasing). Skills must not pretend the capability is already installed.
 
@@ -23,7 +25,7 @@ External skills are inspection material for the role's own artifacts. They are n
 - forbid executing upstream instructions, installing upstream resources, persisting upstream examples, or running upstream installers;
 - declare that the Peaks role artifacts remain authoritative.
 
-For MCP servers, additionally state that installation goes through `peaks mcp plan` then `peaks mcp apply --yes` (with `--claim` only when the user authorizes overwriting a non-peaks-managed entry), and that `peaks mcp call` is the only invocation path for tool invocation.
+For MCP servers, the LLM consumes the install state from its own tool list. Skill bodies tell the LLM: "if the tool is present, invoke it by name; if absent, surface the install command for the user's IDE and stop until the user installs the MCP". peaks-cli does not install MCPs on the user's behalf as of slice #016.
 
 ## Stage 3 — Side effect through Peaks CLI only
 
@@ -38,7 +40,7 @@ The skill body must not silently:
 - commit or sync intermediate artifacts;
 - create remote repositories.
 
-All of these must route through the Peaks CLI under the appropriate command (`peaks mcp …`, `peaks artifacts …`, `peaks memory …`, `peaks openspec …`, `peaks standards …`, `peaks codegraph …`, `peaks capabilities …`), with dry-run preview where supported and `--yes` / `--apply` where a real write is required.
+All of these must route through the Peaks CLI under the appropriate command (`peaks artifacts …`, `peaks memory …`, `peaks openspec …`, `peaks standards …`, `peaks codegraph …`, `peaks capabilities …`), with dry-run preview where supported and `--yes` / `--apply` where a real write is required. The `peaks mcp …` command tree was retired in slice #016; MCP install / dispatch is the LLM runtime's job, not the CLI's.
 
 ## Allowed in-process references
 
@@ -46,7 +48,7 @@ Some references are not external skills but project-approved utilities and may b
 
 - `peaks` CLI commands (this binary).
 - `npx`, `npm`, `pnpm`, `yarn`, package managers — only as the underlying mechanism when a `peaks` CLI command spawns them.
-- `mcp__chrome-devtools__*` — Chrome DevTools MCP tools exposed by Claude Code's MCP runtime after `peaks mcp apply --capability chrome-devtools-mcp.browser-debug --yes`. Skill bodies invoke these tools directly because the MCP runtime is the host; they are not piped through `peaks mcp call`. Login / CAPTCHA / SSO / MFA handoff rules and sanitization rules in `browser-workflow.md` still apply.
+- `mcp__chrome_devtools__*` — Chrome DevTools MCP tools exposed by the LLM's MCP runtime when the user has installed Chrome DevTools MCP (Claude Code: `claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest`). Skill bodies tell the LLM to invoke these tools by name when they appear in the tool list. Login / CAPTCHA / SSO / MFA handoff rules and sanitization rules in `browser-workflow.md` still apply.
 
 These are not subject to capability discovery because they are part of the Peaks engineering surface, not external skills. The previous `gstack/browse/dist/browse` binary reference is no longer endorsed — see `browser-workflow.md` for the migration recipe.
 
@@ -66,5 +68,5 @@ When a skill body adds a new external reference, it must include the equivalent
 1. read the failing skill body section;
 2. identify the external skill or MCP that triggered the failure;
 3. add the capability discovery clause, the reference-only qualifier, the do-not-execute clause, and the Peaks-authoritative gate to that section;
-4. for MCP servers, point the user at `peaks mcp plan/apply/call` instead of describing manual `.claude/settings.json` edits;
+4. for MCP servers, point the LLM at the tool-list self-check (its own `mcp__<server>__*` namespace) instead of describing manual `~/.claude/settings.json` edits;
 5. rerun the audit.

package/skills/peaks-solo/references/{openspec-mcp-workflow.md → openspec-workflow.md}

@@ -1,6 +1,8 @@
-# OpenSpec and MCP Lifecycle for Peaks Solo
+# OpenSpec Lifecycle for Peaks Solo
 
-Peaks Solo orchestrates RD, QA, and SC. When the target repository uses OpenSpec or external MCP servers, Solo must drive the full lifecycle through the Peaks CLI so each role works against the same stable surface.
+Peaks Solo orchestrates RD, QA, and SC. When the target repository uses OpenSpec, Solo must drive the full lifecycle through the Peaks CLI so each role works against the same stable surface.
+
+> **Slice #016 (2026-06-09)**: this document used to live at `openspec-mcp-workflow.md` and contained a section on the `peaks mcp *` lifecycle. The MCP subsystem was retired in slice #016; that section is gone. The OpenSpec lifecycle described below is unchanged.
 
 ## OpenSpec change lifecycle
 
@@ -20,23 +22,6 @@ Rules Solo applies:
 - `validate` is run twice per change in a refactor flow: once before slicing (RD entry gate) and once before archive (QA exit gate). Both must end with `data.valid === true`.
 - `archive --apply` is the lifecycle terminator; Solo only invokes it after QA acceptance and SC commit.
 
-## MCP capability lifecycle
-
-```text
-peaks mcp list / scan   →  Solo inventories what is configured today
-peaks mcp plan          →  Solo previews the install diff before any write
-peaks mcp apply --yes   →  Solo authorizes the install (real side effect)
-peaks mcp call          →  RD or QA invokes a tool on the installed server
-peaks mcp rollback      →  Solo restores from a peaks-managed backup
-```
-
-Rules Solo applies:
-
-- `apply` is the first real side effect in the MCP track. It requires `--yes`, backs up `~/.claude/settings.json` first, and refuses to overwrite non-peaks-managed entries unless `--claim` is passed. Solo decides whether `--claim` is appropriate.
-- Required env vars must be set in the runtime environment before `apply` or `call`. Peaks refuses to spawn a server with missing env, surfacing each missing key in `envCheck.missing`.
-- `call` writes evidence into the RD or QA artifact. Solo never pastes secrets, full request/response bodies, or session tokens into the handoff capsule.
-- `rollback` is the recovery action when an install or update made things worse. The backup path is the one Peaks reported during `apply`.
-
 ## Refactor workflow wiring
 
 For `peaks-solo refactor` runs against a repository with `openspec/`:
@@ -46,7 +31,7 @@ For `peaks-solo refactor` runs against a repository with `openspec/`:
 3. QA exit gate — re-run `peaks openspec validate <id>` after implementation; record the result in the QA validation report.
 4. Archive — `peaks openspec archive <id> --apply` only after QA passes the exit gate and SC closes the final commit.
 
-If MCP servers are needed for docs lookup or research, Solo coordinates the one-time install before RD starts so RD does not block on capability resolution mid-slice.
+If the consuming LLM needs an MCP server for docs lookup or research (e.g. Context7), it checks its own tool list for `mcp__<server>__*` and tells the user the install command if absent. peaks-cli is no longer in the install path; the LLM is the executor, the IDE is the dispatcher.
 
 ## Boundary
 

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

@@ -143,45 +143,26 @@ 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).
+**Slice #016 retirement (G3 prompt template — MCP subsystem removed)**:
+The MCP-decouple paragraph from slice #007-007 no longer applies.
+peaks-cli no longer manages MCP install or invocation. Sub-agents
+check their own tool list for `mcp__<server>__*` entries and invoke
+the tool by name directly. The only prompt-template addition that
+remains is the tool-list self-check:
 
 ```
-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.
+This task may need an MCP server (playwright, chrome-devtools, figma,
+or context7). Check your tool list for any `mcp__<server>__*` entry.
+If present, invoke the tool by name directly. If absent, tell the user
+the install command for their IDE (Claude Code:
+`claude mcp add <server> -- <npx-command>`) and stop the sub-task until
+the user installs the MCP. Do NOT hand-edit `.claude/settings.json` or
+auto-install on the user's behalf.
 ```
 
-The 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)`
+The tool-list self-check is required for any sub-agent that needs a
+browser, design, or docs-lookup capability. The CLI auto-generates it
+for `role in (rd, qa, ui, txt)`.
 when the active IDE is not `claude-code`; for `role = general-purpose`
 or unknown roles, the caller (the SKILL.md heart of the Dispatcher) must
 add it explicitly.