peaks-cli 1.3.5 → 1.3.6

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/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.

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 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:
+Every Playwright screenshot tool call (the LLM invokes `browser_take_screenshot` directly when the Playwright MCP is present in its tool list) **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
@@ -61,7 +61,7 @@ What the sub-agent **MUST** still do:
 - Do NOT call `Skill(skill="...")`.
 - Do NOT call `peaks skill presence:set` — Solo owns the active-skill file.
 - Do NOT modify application code. UI is design-direction only; the actual frontend code is written in the RD implementation phase.
-- Do NOT install MCP servers. If `peaks mcp list` shows playwright-mcp missing and the headed browser is required, return `{"status":"blocked","blockedReason":"playwright-mcp-unavailable"}` and let Solo escalate to the user.
+- Do NOT install MCP servers. If the LLM tool list does not include the Playwright MCP and the headed browser is required, return `{"status":"blocked","blockedReason":"playwright-mcp-unavailable"}` and let Solo escalate to the user. (peaks-cli no longer manages MCP install — the user runs `claude mcp add playwright -- npx @playwright/mcp@latest` themselves in Claude Code, or the IDE-specific install command otherwise.)
 - 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>"}`.
 
@@ -129,14 +129,13 @@ peaks request init --role ui --id <request-id> --project <repo> --apply --json
 peaks request show <request-id> --role prd --project <repo> --json   # read linked PRD scope
 
 # 2. ensure Playwright MCP is available for the visible browser check
-peaks mcp list --json
-# if playwright-mcp.browser-validation is NOT in the list:
-peaks mcp plan  --capability playwright-mcp.browser-validation --json
-peaks mcp apply --capability playwright-mcp.browser-validation --yes --json
-# if apply fails or user denies installation:
-#   → mark browser gate as blocked with reason "playwright-mcp-unavailable"
-#   → NEVER silently downgrade to screenshots-only, manual steps, or other tools
-#   → NEVER route through chrome-devtools-mcp as a browser-launch substitute (it cannot launch)
+# Slice #016: peaks-cli no longer manages MCP install. The LLM checks
+# its own tool list for any Playwright MCP entry in the LLM tool list. If absent, the
+# LLM tells the user the install command (`claude mcp add playwright
+# -- npx @playwright/mcp@latest` in Claude Code) and reports the gate
+# as blocked. Do NOT silently downgrade to screenshots-only, manual
+# steps, or other tools. Do NOT route through chrome-devtools-mcp as a
+# browser-launch substitute (it cannot launch a browser of its own).
 
 # 3. read project-scan for component library and CSS framework context
 #    check .peaks/<session-id>/rd/project-scan.md (blocking if missing for existing projects)
@@ -151,8 +150,8 @@ peaks mcp apply --capability playwright-mcp.browser-validation --yes --json
 #    See "Prototype fidelity gate" section for the full decision tree.
 
 # 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)
-#    peaks mcp call --capability playwright-mcp.browser-validation --tool browser_navigate --args-json '{"url":"<url>"}' --json
+#    (the LLM invokes these directly from its tool list — no peaks-cli envelope)
+#    browser_navigate --args '{"url":"<url>"}'
 #    → URL (after allow-list check), launches headed browser
 #
 #    LOGIN GATE (MANDATORY checkpoint):
@@ -162,19 +161,18 @@ 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:
 #
-#    peaks mcp call --capability playwright-mcp.browser-validation --tool browser_take_screenshot --args-json '{"filename":"<abs-path>"}' --json
+#    browser_take_screenshot --args '{"filename":"<abs-path>"}'
 #    → visible-browser confirmation
-#    peaks mcp call --capability playwright-mcp.browser-validation --tool browser_snapshot --args-json '{}' --json
+#    browser_snapshot --args '{}'
 #    → accessibility tree for regression seeds
-#    peaks mcp call --capability playwright-mcp.browser-validation --tool browser_console_messages --args-json '{}' --json
+#    browser_console_messages --args '{}'
 #    → console errors
-#    peaks mcp call --capability playwright-mcp.browser-validation --tool browser_network_requests --args-json '{}' --json
+#    browser_network_requests --args '{}'
 #    → failed network
-#    peaks mcp call --capability playwright-mcp.browser-validation --tool browser_close --args-json '{}' --json
+#    browser_close --args '{}'
 #    → 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.
+# The skill body NEVER bakes in the the Playwright MCP tools prefix; the LLM's runtime
+# resolves the tool name from the registered server.
 
 # 5. write design-draft artifact to .peaks/<session-id>/ui/design-draft.md
 
@@ -238,7 +236,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 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`.
+For frontend work, especially full-auto mode, use the Playwright MCP to inspect the running page or prototype before accepting the UI direction. The LLM checks its own tool list for any Playwright MCP entry in the LLM tool list; if present, it invokes the tools by name directly (browser_navigate / browser_snapshot / browser_take_screenshot / browser_console_messages / browser_network_requests / browser_close) — there is no peaks-cli envelope. Playwright MCP launches a headed browser on demand; if the tool list is empty, the user installs via `claude mcp add playwright -- npx @playwright/mcp@latest` (Claude Code) or the IDE's own MCP install path. (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)
 
@@ -248,7 +246,7 @@ For frontend work, especially full-auto mode, use Playwright MCP to inspect the
 
 Check these sources in order:
 
-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.
+1. **Figma design file** — If the PRD links to a Figma file, the LLM checks its own tool list for any the Figma MCP entry. If present, it invokes `get_figma_data` (or similar) directly with `{"fileKey":"<key>"}`; `FIGMA_API_KEY` must be set in the user's env for the MCP to authenticate. The skill body never bakes in the Figma MCP prefix; the LLM's runtime owns the namespace. 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.
@@ -355,8 +353,8 @@ Use `peaks capabilities --source access-repo --json` and `peaks capabilities --s
 
 - In full-auto frontend mode, prefer the `awesome-design-md` + `taste-skill`/`design-taste-frontend` combination before shadcn/ui or generic component-library output (capability discovery must confirm availability first).
 - shadcn/ui, React Bits, awesome-design-md, taste-skill, and ui-ux-pro-max-skill are UI references; do not treat unreviewed generated UI as finished design.
-- Chrome DevTools MCP and Agent Browser can support runtime UI inspection only after the user approves the app target. Install or update those MCP servers through `peaks mcp plan --capability <id> --json` then `peaks mcp apply --capability <id> --yes --json` rather than hand-editing settings; invoke their tools through `peaks mcp call --capability <id> --tool <name> --args-json '{...}' --json`.
-- Figma Context MCP and Penpot require user-authorized design access and must not persist tokens or private design data in project artifacts. Same `peaks mcp plan / apply / call` installation and invocation path applies.
+- Chrome DevTools MCP and Agent Browser can support runtime UI inspection only after the user approves the app target. (Slice #016: peaks-cli no longer auto-installs these; the user runs the IDE-native MCP install command themselves, and the LLM invokes the tool by name from its tool list when present.)
+- Figma Context MCP and Penpot require user-authorized design access and must not persist tokens or private design data in project artifacts. Same rule: the LLM's tool list is the source of truth; peaks-cli is not in the install path.
 - Check license, accessibility, and performance before translating external visual references into Peaks-Cli UI constraints.
 
 ## Boundaries

package/skills/peaks-ui/references/workflow.md

@@ -11,7 +11,7 @@ Use this path before generating or accepting frontend UI:
 3. Produce a concrete visual direction, not vague “clean modern” language.
 4. Reject generic AI UI tells: centered stock hero, uniform card grids, default shadcn/library styling, purple-blue gradients, three equal feature cards, generic placeholder copy, and static-only happy states.
 5. Require meaningful loading, empty, error, hover, focus, active, and responsive states.
-6. Use Playwright MCP on the running page or prototype to inspect real browser output (install via `peaks mcp plan/apply --capability playwright-mcp.browser-validation --yes` if not yet present; open with `mcp__playwright__browser_navigate` / `navigate_page`, capture with `take_snapshot` and `take_screenshot`); visible browser confirmation is mandatory, and login/CAPTCHA/SSO/MFA requires waiting for explicit user confirmation before continuing.
+6. Use Playwright MCP on the running page or prototype to inspect real browser output (the LLM checks its tool list for `mcp__playwright__*`; if absent, the user installs via `claude mcp add playwright -- npx @playwright/mcp@latest` for Claude Code, or the IDE-native MCP install command otherwise — peaks-cli no longer auto-installs as of slice #016; open with `browser_navigate` / `navigate_page`, capture with `browser_snapshot` and `browser_take_screenshot`); visible browser confirmation is mandatory, and login/CAPTCHA/SSO/MFA requires waiting for explicit user confirmation before continuing.
 7. If the browser view looks generic, visually weak, broken, inaccessible, or has console/runtime errors, return to design/RD and iterate before handing off to QA.
 
 ## Outputs
@@ -21,7 +21,7 @@ Use this path before generating or accepting frontend UI:
 - visual direction with references;
 - design dials and rejected generic patterns;
 - interaction constraints;
-- Playwright MCP browser observations when frontend output exists (`mcp__playwright__browser_snapshot`, `take_screenshot`, `list_console_messages`, `list_network_requests`);
+- Playwright MCP browser observations when frontend output exists (`browser_snapshot`, `browser_take_screenshot`, `browser_console_messages`, `browser_network_requests`);
 - UI regression seeds;
 - accessibility notes;
 - taste report.

package/dist/src/cli/commands/mcp-commands.d.ts

@@ -1,3 +0,0 @@
-import { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
-export declare function registerMcpCommands(program: Command, io: ProgramIO): void;

package/dist/src/cli/commands/mcp-commands.js

@@ -1,144 +0,0 @@
-import { InvalidArgumentError } from 'commander';
-import { readFile } from 'node:fs/promises';
-import { scanMcpServers } from '../../services/mcp/mcp-scan-service.js';
-import { planMcpInstall } from '../../services/mcp/mcp-plan-service.js';
-import { applyMcpInstall, rollbackMcpInstall } from '../../services/mcp/mcp-apply-service.js';
-import { callMcpTool } from '../../services/mcp/mcp-call-service.js';
-import { createStdioTransportFromSpec } from '../../services/mcp/mcp-stdio-transport.js';
-import { fail, ok } from '../../shared/result.js';
-import { addJsonOption, failUnsupportedNonDryRun, getErrorMessage, printResult } from '../cli-helpers.js';
-function parsePositiveInteger(value) {
-    if (!/^\d+$/.test(value)) {
-        throw new InvalidArgumentError('must be a positive integer');
-    }
-    const parsed = Number(value);
-    if (!Number.isSafeInteger(parsed) || parsed < 1) {
-        throw new InvalidArgumentError('must be a positive integer');
-    }
-    return parsed;
-}
-async function resolveCallArgs(options) {
-    if (options.argsJson !== undefined && options.args !== undefined) {
-        throw new Error('Pass either --args-json or --args, not both');
-    }
-    const raw = options.argsJson !== undefined
-        ? options.argsJson
-        : options.args !== undefined ? await readFile(options.args, 'utf8') : '{}';
-    const parsed = JSON.parse(raw);
-    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-        throw new Error('MCP tool arguments must be a JSON object');
-    }
-    return parsed;
-}
-export function registerMcpCommands(program, io) {
-    const mcp = program.command('mcp').description('Manage Claude Code MCP servers');
-    addJsonOption(mcp
-        .command('list')
-        .alias('scan')
-        .description('Scan Claude Code settings for configured MCP servers')
-        .option('--project <path>', 'project root to also scan project-level .claude/settings.json')).action(async (options) => {
-        try {
-            const report = await scanMcpServers(options.project !== undefined ? { projectRoot: options.project } : {});
-            printResult(io, ok('mcp.list', report), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('mcp.list', 'MCP_LIST_FAILED', getErrorMessage(error), {}, ['Check Claude settings path and permissions before retrying']), options.json);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(mcp
-        .command('plan')
-        .description('Plan an MCP server install diff for a capability (dry-run only)')
-        .requiredOption('--capability <id>', 'capability id from the MCP install registry')
-        .option('--project <path>', 'project root for scoped scan')
-        .option('--dry-run', 'preview the install diff (always true)', true)
-        .option('--no-dry-run', 'unsupported: peaks mcp plan never writes settings')).action(async (options) => {
-        if (options.dryRun === false) {
-            failUnsupportedNonDryRun(io, 'mcp.plan', options.json);
-            return;
-        }
-        try {
-            const planOptions = options.project !== undefined ? { projectRoot: options.project } : {};
-            const plan = await planMcpInstall(options.capability, planOptions);
-            if (plan.action === 'unknown-capability') {
-                printResult(io, fail('mcp.plan', 'MCP_UNKNOWN_CAPABILITY', `No MCP install spec registered for capability ${options.capability}`, plan, plan.nextActions), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            printResult(io, ok('mcp.plan', plan, [], plan.nextActions), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('mcp.plan', 'MCP_PLAN_FAILED', getErrorMessage(error), { capabilityId: options.capability }, ['Check Claude settings path and the capability id before retrying']), options.json);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(mcp
-        .command('apply')
-        .description('Apply an MCP server install for a capability (writes .claude/settings.json with backup)')
-        .requiredOption('--capability <id>', 'capability id from the MCP install registry')
-        .option('--yes', 'confirm the write — required for any real side effect')
-        .option('--claim', 'take ownership of an existing non-peaks-managed server entry')
-        .option('--project <path>', 'project root for scoped scan')).action(async (options) => {
-        if (options.yes !== true) {
-            printResult(io, fail('mcp.apply', 'MCP_APPLY_REQUIRES_YES', 'Refusing to apply without --yes', { capabilityId: options.capability }, ['Re-run with --yes to confirm the write']), options.json);
-            process.exitCode = 1;
-            return;
-        }
-        try {
-            const applyOptions = {};
-            if (options.project !== undefined) {
-                applyOptions.projectRoot = options.project;
-            }
-            if (options.claim === true) {
-                applyOptions.claim = true;
-            }
-            const result = await applyMcpInstall(options.capability, applyOptions);
-            printResult(io, ok('mcp.apply', result), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('mcp.apply', 'MCP_APPLY_FAILED', getErrorMessage(error), { capabilityId: options.capability }, ['Check the plan first with peaks mcp plan, then re-run apply']), options.json);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(mcp
-        .command('rollback')
-        .description('Restore Claude Code settings.json from a peaks-managed MCP backup file')
-        .requiredOption('--backup <path>', 'path to a previously created backup settings.json')).action(async (options) => {
-        try {
-            const result = await rollbackMcpInstall({ backupPath: options.backup });
-            printResult(io, ok('mcp.rollback', result), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('mcp.rollback', 'MCP_ROLLBACK_FAILED', getErrorMessage(error), { backupPath: options.backup }, ['Verify the backup path and rerun']), options.json);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(mcp
-        .command('call')
-        .description('Invoke a tool on an installed MCP server via stdio (spawns the server, calls tools/call, closes)')
-        .requiredOption('--capability <id>', 'capability id from the MCP install registry')
-        .requiredOption('--tool <name>', 'MCP tool name to invoke')
-        .option('--args <path>', 'path to a JSON file describing the tool arguments object')
-        .option('--args-json <jsonString>', 'inline JSON object describing the tool arguments')
-        .option('--timeout <ms>', 'per-request timeout in milliseconds', parsePositiveInteger)).action(async (options) => {
-        try {
-            const args = await resolveCallArgs(options);
-            const factory = createStdioTransportFromSpec;
-            const callOptions = {
-                capabilityId: options.capability,
-                toolName: options.tool,
-                args,
-                transportFactory: factory
-            };
-            if (options.timeout !== undefined) {
-                callOptions.timeoutMs = Number(options.timeout);
-            }
-            const result = await callMcpTool(callOptions);
-            printResult(io, ok('mcp.call', result), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('mcp.call', 'MCP_CALL_FAILED', getErrorMessage(error), { capabilityId: options.capability, toolName: options.tool }, ['Check the capability id, tool name, args JSON, and required env vars before retrying']), options.json);
-            process.exitCode = 1;
-        }
-    });
-}