peaks-cli 1.3.5 → 1.3.7

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/micro-cycle.md

@@ -89,12 +89,14 @@ peaks slice check [--rid <rid>] [--project <path>] [--json]
 
 这个命令编排：
 1. `npx tsc --noEmit`（typecheck）
-2. `npx vitest run`（全 suite）
+2. `npx vitest run --changed`（默认；changed-only suite，只跑 git 改动相关的 test，~1-3s）。要全量请加 `--run-tests`；要彻底跳过请加 `--skip-tests`。
 3. 3-way fan-out（code-review + security-review + perf-baseline）
 4. `peaks workflow verify-pipeline --rid <rid> --project <path>`
 
 4 个 check 全绿 + verify-pipeline pass → 才进 `peaks request transition --state qa-handoff`，让 peaks-qa 接管。
 
+> **新增 run 017（2026-06-09）**：边界默认走 changed-only suite，原来的全 suite 行为移到 `--run-tests` opt-in。`peaks-solo-test` skill 仍然是手动跑全量的入口。rationale: 全量 30s+ 严重拖慢 workflow；changed-only 命中 99% 真正回归。详见 PRD `.peaks/_runtime/2026-06-07-session-84feb7/prd/requests/002-017-2026-06-09-remove-auto-full-vitest-from-slice-check.md`。
+
 ## Micro-cycle → 边界 check → QA 的串联
 
 ```
@@ -139,7 +141,7 @@ verdict=return-to-rd → RD 修 (new slice 内部走 micro-cycle)
 ## 为什么这套比当前 peaks-solo 的设计合理
 
 - **快**：micro-cycle ~100ms（vs 30s 全 suite），改 10 个 bug 从 5 分钟降到 30 秒
-- **稳**：边界 check 不省，4 项检查（tsc + vitest + 3-way + verify-pipeline）一次全跑
+- **稳**：边界 check 不省，4 项检查（tsc + vitest run --changed + 3-way + verify-pipeline）一次全跑；changed-only 模式 1-3s 内出结果，全量用 `--run-tests` opt-in
 - **清晰**：LLM 看到一个 explicit "禁止" 列表 + 强制 sequence，比"建议"更不容易越界
 - **可观测**：micro-cycle 走单测 → 边界跑 verify-pipeline，每步都有 JSON envelope 验证
 

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;
-        }
-    });
-}

package/dist/src/services/mcp/mcp-apply-service.d.ts

@@ -1,31 +0,0 @@
-import { type PlanMcpInstallOptions, type McpInstallEnvCheck } from './mcp-plan-service.js';
-export type McpApplyAction = 'add' | 'update' | 'claimed' | 'noop';
-export type McpApplyBackupInfo = {
-    path: string | null;
-    skipped: boolean;
-};
-export type McpApplyResult = {
-    capabilityId: string;
-    action: McpApplyAction;
-    backup: McpApplyBackupInfo;
-    written: {
-        settingsPath: string;
-        managedMarkerPath: string;
-    };
-    envCheck: McpInstallEnvCheck;
-};
-export type McpApplyOptions = PlanMcpInstallOptions & {
-    claim?: boolean;
-    backupRoot?: string;
-    clock?: () => string;
-};
-export type McpRollbackOptions = {
-    backupPath: string;
-    globalSettingsPath?: string;
-};
-export type McpRollbackResult = {
-    restoredFrom: string;
-    restoredTo: string;
-};
-export declare function applyMcpInstall(capabilityId: string, options?: McpApplyOptions): Promise<McpApplyResult>;
-export declare function rollbackMcpInstall(options: McpRollbackOptions): Promise<McpRollbackResult>;

package/dist/src/services/mcp/mcp-apply-service.js

@@ -1,112 +0,0 @@
-import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
-import { mkdir, writeFile } from 'node:fs/promises';
-import { pathExists, readText } from '../../shared/fs.js';
-import { planMcpInstall } from './mcp-plan-service.js';
-function defaultGlobalSettingsPath() {
-    return join(homedir(), '.claude', 'settings.json');
-}
-function defaultManagedMarkerPath() {
-    return join(homedir(), '.peaks', 'mcp-managed.json');
-}
-function defaultBackupRoot() {
-    return join(homedir(), '.peaks-artifacts', 'mcp-backups');
-}
-function defaultClock() {
-    return new Date().toISOString().replace(/[:.]/g, '-');
-}
-async function readJsonFile(path) {
-    if (!(await pathExists(path))) {
-        return {};
-    }
-    const raw = await readText(path);
-    if (raw.length === 0) {
-        return {};
-    }
-    const parsed = JSON.parse(raw);
-    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-        return {};
-    }
-    return parsed;
-}
-async function writeJsonFile(path, data) {
-    await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
-}
-function buildServerConfig(spec) {
-    const env = {};
-    for (const key of spec.envKeys) {
-        env[key] = `\${${key}}`;
-    }
-    return { command: spec.command, args: [...spec.args], env };
-}
-async function createBackup(settingsPath, backupRoot, timestamp) {
-    if (!(await pathExists(settingsPath))) {
-        return null;
-    }
-    const backupPath = join(backupRoot, timestamp, 'settings.json');
-    await mkdir(dirname(backupPath), { recursive: true });
-    await writeFile(backupPath, await readText(settingsPath), 'utf8');
-    return backupPath;
-}
-async function updateManagedMarker(markerPath, name) {
-    const marker = await readJsonFile(markerPath);
-    const existing = Array.isArray(marker.servers)
-        ? marker.servers.filter((entry) => typeof entry === 'string')
-        : [];
-    if (!existing.includes(name)) {
-        existing.push(name);
-    }
-    await writeJsonFile(markerPath, { ...marker, servers: existing });
-}
-export async function applyMcpInstall(capabilityId, options = {}) {
-    const plan = await planMcpInstall(capabilityId, options);
-    if (plan.action === 'unknown-capability' || plan.spec === null) {
-        throw new Error(`No MCP install spec registered for capability ${capabilityId} (unknown-capability)`);
-    }
-    if (plan.envCheck.missing.length > 0) {
-        throw new Error(`Refusing to apply: missing required env vars: ${plan.envCheck.missing.join(', ')}`);
-    }
-    if (plan.action === 'conflict' && options.claim !== true) {
-        throw new Error(`Refusing to apply: server ${plan.spec.name} exists but is not peaks-managed (conflict). Re-run with --claim to take ownership.`);
-    }
-    const settingsPath = options.globalSettingsPath ?? defaultGlobalSettingsPath();
-    const markerPath = options.managedMarkerPath ?? defaultManagedMarkerPath();
-    const backupRoot = options.backupRoot ?? defaultBackupRoot();
-    const clock = options.clock ?? defaultClock;
-    if (plan.action === 'noop') {
-        return {
-            capabilityId,
-            action: 'noop',
-            backup: { path: null, skipped: true },
-            written: { settingsPath, managedMarkerPath: markerPath },
-            envCheck: plan.envCheck
-        };
-    }
-    const backupPath = await createBackup(settingsPath, backupRoot, clock());
-    const settings = await readJsonFile(settingsPath);
-    const existingServers = settings.mcpServers !== null && typeof settings.mcpServers === 'object' && !Array.isArray(settings.mcpServers)
-        ? settings.mcpServers
-        : {};
-    const nextServers = { ...existingServers, [plan.spec.name]: buildServerConfig(plan.spec) };
-    await writeJsonFile(settingsPath, { ...settings, mcpServers: nextServers });
-    await updateManagedMarker(markerPath, plan.spec.name);
-    const action = plan.action === 'conflict' ? 'claimed' : plan.action;
-    return {
-        capabilityId,
-        action,
-        backup: { path: backupPath, skipped: false },
-        written: { settingsPath, managedMarkerPath: markerPath },
-        envCheck: plan.envCheck
-    };
-}
-export async function rollbackMcpInstall(options) {
-    if (!(await pathExists(options.backupPath))) {
-        throw new Error(`Refusing to rollback: backup file not found at ${options.backupPath}`);
-    }
-    const target = options.globalSettingsPath ?? defaultGlobalSettingsPath();
-    const content = await readText(options.backupPath);
-    await mkdir(dirname(target), { recursive: true });
-    await writeFile(target, content, 'utf8');
-    return { restoredFrom: options.backupPath, restoredTo: target };
-}