peaks-cli 1.0.11 → 1.0.13

package/skills/peaks-rd/references/artifact-per-request.md

@@ -0,0 +1,90 @@
+# RD per-request artifact contract
+
+Every RD invocation must leave one durable artifact under the workflow-local workspace so the engineering decisions and slice contracts are traceable later.
+
+## Required path
+
+```
+.peaks/<session-id>/rd/requests/<request-id>.md
+```
+
+Use the `<request-id>` PRD assigned (`YYYY-MM-DD-<kebab-slug>`). RD may also produce companion artifacts (task graph JSON, scan report, coverage evidence, slice spec, dry-run output) under the same `rd/` workspace and link to them from this file.
+
+## Required content
+
+```markdown
+# RD Request <request-id>
+
+- linked-prd: .peaks/<session-id>/prd/requests/<request-id>.md
+- linked-ui:  .peaks/<session-id>/ui/requests/<request-id>.md  (when UI involved)
+- type: feature | bug | refactor | clarification
+
+## Red-line scope
+
+- in-scope files / routes / API paths / data models
+- explicit out-of-scope surfaces (do not modify, mock, delete, or replace)
+
+## Standards preflight
+
+- `peaks standards init/update --project <path> --dry-run` output paths and status
+- planned application: apply | review-only | blocked
+
+## OpenSpec linkage (when openspec/ exists)
+
+- change-id: <openspec change id>
+- entry validate: `peaks openspec validate <change-id>` data.valid status
+- to-rd projection: `peaks openspec to-rd <change-id>` artifact path
+- exit validate (after implementation): status
+
+## Coverage status
+
+- current total UT coverage: <percent>
+- new/changed code coverage: <percent>
+- gate verdict: pass | legacy-accepted | blocked
+
+## Slice contract
+
+For each slice in this request:
+
+- slice id
+- functional boundary
+- pre-refactor behavior summary
+- target structure
+- unit-test requirements
+- acceptance checks (100% required per slice)
+- rollback plan
+- commit boundary (one per slice; aligned with OpenSpec tasks.md section when available)
+
+## Implementation evidence
+
+- diff paths
+- test commands + outputs
+- code review findings + fixes
+- security review findings + fixes
+- dry-run output
+
+## MCP usage (when external docs lookup was used)
+
+- capabilityId / tool / sanitized args
+- artifact path of stored result
+- no secrets, no full network bodies
+
+## Handoff
+
+- to peaks-qa: <link to QA request artifact>
+- to peaks-sc: <link to SC commit-boundary artifact>
+
+## Status
+
+- created: <ISO timestamp>
+- last update: <ISO timestamp>
+- state: draft | spec-locked | implemented | qa-handoff | blocked
+```
+
+## Rules
+
+- Do not skip the RD artifact for "trivial" fixes. Even a one-line bug fix needs the red-line scope and acceptance checks recorded.
+- Refactor work requires UT coverage ≥ 95% before slicing begins; record the verdict in this artifact, not just in chat.
+- Sanitize MCP/network/browser evidence before writing.
+- Do not commit unless the user or active profile authorizes durable retention.
+- Handoff to QA is blocked while state is `draft` or `spec-locked` without implementation evidence.

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

@@ -0,0 +1,65 @@
+# OpenSpec and MCP CLI for Peaks RD
+
+Peaks RD reads OpenSpec change packs and external MCP servers through the Peaks CLI rather than re-parsing markdown or spawning subprocesses by hand. The CLI returns the same stable envelope shape (`{ ok, command, data, warnings, nextActions }`) so RD can capture it as artifact JSON.
+
+## Loading an existing OpenSpec change as RD input
+
+When the target repository already has `openspec/changes/<id>/`, project the change pack into the RD input shape before slicing:
+
+```bash
+peaks openspec show <change-id> --project <repo> --json
+peaks openspec to-rd <change-id> --project <repo> --json
+```
+
+- `show` returns the parsed proposal sections, tasks progress, and detected `specs/<capability>/` capabilities.
+- `to-rd` returns `{ changeId, acceptance, whatChanges, dependencies, risks, outOfScope, commitBoundaries[] }`. RD slice acceptance must be derived from `acceptance`; out-of-scope items from `outOfScope` must remain out of scope in the slice spec.
+
+If the change does not exist, `to-rd` returns `OPENSPEC_CHANGE_NOT_FOUND`. Treat that as a blocker, not an excuse to free-form a slice spec.
+
+## Rendering a new OpenSpec change pack from RD work
+
+When RD plans a non-trivial change in a repository that already uses `openspec/`, generate the change pack first (default dry-run), inspect the rendered markdown, and only then write it:
+
+```bash
+peaks openspec render --request <jsonPath> --project <repo> --json
+peaks openspec render --request <jsonPath> --project <repo> --apply --json
+```
+
+The request JSON shape is:
+
+```json
+{
+  "changeId": "<kebab-case>",
+  "why": "...",
+  "whatChanges": ["..."],
+  "outOfScope": ["..."],
+  "dependencies": ["..."],
+  "risks": ["..."],
+  "acceptanceCriteria": ["..."],
+  "tasks": [{ "heading": "1. <section>", "todos": ["..."], "doneItems": ["..."] }],
+  "design": "<raw markdown>"
+}
+```
+
+`render --apply` refuses to overwrite an existing change directory unless `--overwrite` is passed. Treat that refusal as intentional.
+
+## Calling MCP tools for research evidence
+
+When RD needs external library or API docs, prefer a registered MCP server through Peaks instead of free-form web fetches:
+
+```bash
+peaks mcp list --json
+peaks mcp plan --capability context7.docs-lookup --json
+peaks mcp apply --capability context7.docs-lookup --yes --json   # one-time install
+peaks mcp call --capability context7.docs-lookup --tool <toolName> --args-json '{...}' --json
+```
+
+Rules:
+
+- `plan` must be inspected before `apply`. `apply` is a real side effect; it backs up `~/.claude/settings.json` first.
+- Required env vars must be present before `apply` and `call`; Peaks refuses to spawn a server with missing env.
+- `call` results should be written into the RD artifact (e.g. `.peaks/<session-id>/rd/mcp-call-<ts>.json`) as the evidence link. Do not paste secrets or full network bodies into the RD handoff.
+
+## Boundary
+
+Peaks RD must not hand-edit `openspec/changes/**` or `~/.claude/settings.json` directly. All writes go through the CLI commands above with dry-run preview, explicit confirmation, and Peaks-managed source labels.

package/skills/peaks-sc/SKILL.md

@@ -31,6 +31,50 @@ Use gstack as a concrete source-control and release workflow reference for the `
 
 Project `.claude/memory` is the primary source for durable project memory. At approved checkpoints, use `peaks memory sync --project <path> --workspace <artifact-workspace> --apply` to back up the full project memory directory into the artifact repository workspace; do not treat the artifact backup as a second writable memory source.
 
+## OpenSpec-derived commit boundaries
+
+When `openspec/changes/<id>/tasks.md` exists, derive commit boundaries from it through the Peaks CLI instead of redesigning them:
+
+- `peaks openspec to-rd <id> --project <repo> --json` returns `commitBoundaries[]`, one entry per tasks.md heading.
+- Default to one commit per heading. Each commit message references the change-id and the section heading.
+- If implementation produces diffs outside any todo, surface that as out-of-scope before closing SC.
+
+Concrete rules: `references/openspec-commit-boundaries.md`.
+
+## Default runbook
+
+Use this sequence when SC owns the change-control pass for a refactor or release slice. SC never edits code or tests; it only records boundary evidence through the Peaks CLI.
+
+```bash
+# 0. Confirm SC's own runbook integrity before recording boundary evidence
+peaks skill runbook peaks-sc --json
+
+# 1. Derive commit boundaries from OpenSpec when openspec/ exists
+peaks openspec to-rd <change-id> --project <repo> --json
+
+# 2. Inventory artifacts already produced by other roles for this session
+peaks artifacts status --project <repo> --json
+peaks artifacts workspace --workspace <session-id> --json
+
+# 3. Record change impact for the slice
+peaks sc impact --change-id <change-id> --module <module> --file <path> --json
+
+# 4. Record retention evidence linking PRD / RD / QA / coverage / review artifacts
+peaks sc retention --slice-id <slice-id> --prd <prd-path> --rd <rd-path> --qa <qa-path> --json
+
+# 5. Validate retention completeness
+peaks sc validate --slice-id <slice-id> --json
+
+# 6. Record the commit boundary for the slice
+peaks sc boundary --slice-id <slice-id> --artifact <artifact-path> --code <code-file> --json
+
+# 7. Sync memory and artifacts only when the user or active profile authorizes durable writes
+peaks memory sync --project <repo> --workspace <workspace> --apply --json
+peaks artifacts sync --workspace <workspace> --apply --json
+```
+
+The final two `--apply` calls require explicit authorization. Without it, default to `--dry-run` or omit the sync calls entirely and keep the boundary evidence local under `.peaks/<session-id>/`.
+
 ## Boundaries
 
 Do not implement code or test logic. Do not create GitHub repositories directly from the skill body. Use the Peaks CLI artifact commands.

package/skills/peaks-sc/references/openspec-commit-boundaries.md

@@ -0,0 +1,33 @@
+# OpenSpec-Derived Commit Boundaries for Peaks SC
+
+Peaks SC owns commit boundaries and artifact retention. When the change pack lives in `openspec/changes/<id>/tasks.md`, SC must derive the commit boundaries from that file via the Peaks CLI rather than reinvent them.
+
+## Pulling commit boundary candidates
+
+```bash
+peaks openspec to-rd <change-id> --project <repo> --json
+```
+
+The response includes:
+
+```json
+"commitBoundaries": [
+  { "heading": "1. Discovery", "todos": ["..."], "doneItems": ["..."] },
+  { "heading": "2. Implementation", "todos": ["..."], "doneItems": ["..."] }
+]
+```
+
+Rules SC applies:
+
+- One commit per `heading` is the default. Do not combine unrelated sections into a single commit.
+- `todos[]` items are the in-scope work for that commit. If implementation produced diffs outside any todo description, surface that as an out-of-scope finding before SC closes.
+- `doneItems[]` describes already-shipped sub-tasks; SC may close them out in the same commit only when the current diff actually touches the same surface.
+- Each commit message should reference the change-id and the section heading (e.g. `feat: M3 implement <change-id> 2. Implementation`).
+
+## Wiring with RD slice contracts
+
+When RD has split a change into multiple slices, SC must align each commit with one RD slice and one OpenSpec tasks section. The OpenSpec section heading is the canonical commit boundary name; the RD slice id is the internal reference. If they disagree, return to RD before committing.
+
+## Boundary
+
+SC must not hand-edit `openspec/changes/**` or rewrite history to match a desired boundary. If the OpenSpec tasks list is wrong, raise it as an RD/QA issue and have RD regenerate the change pack through `peaks openspec render` before SC commits.

package/skills/peaks-solo/SKILL.md

@@ -40,7 +40,9 @@ Use gstack as a concrete orchestration reference for the full `Think → Plan
 - map `/retro` to Peaks TXT final context and reusable lessons;
 - preserve Peaks confirmation gates, artifact workspace boundaries, and role separation instead of delegating orchestration to gstack commands.
 
-For frontend workflows, Peaks Solo must ensure RD self-test and QA validation use headed `gstack/browse/dist/browse` for real browser end-to-end validation. A visible browser opening is mandatory. If login, CAPTCHA, SSO, or MFA appears, wait for the user to complete login and explicitly confirm completion before continuing. If browser validation reports page, console, network, render, or visible UI errors, route the workflow back to RD for fixes before QA can pass.
+For frontend workflows, Peaks Solo must ensure RD self-test and QA validation use Playwright MCP for real browser end-to-end validation (install via `peaks mcp plan/apply --capability playwright-mcp.browser-validation --yes` if not yet present; Claude Code invokes the tools under the `mcp__playwright__*` namespace — browser_navigate, browser_snapshot, browser_take_screenshot, browser_console_messages, browser_network_requests, browser_close — and the headed browser opens on demand). Chrome DevTools MCP (`mcp__chrome-devtools__*`) is an optional secondary surface that connects to an already-running Chrome with `--remote-debugging-port=9222`; it does NOT launch a browser. A visible browser opening is mandatory. If login, CAPTCHA, SSO, or MFA appears, wait for the user to complete login and explicitly confirm completion before continuing. If browser validation reports page, console, network, render, or visible UI errors, route the workflow back to RD for fixes before QA can pass.
+
+Canonical browser workflow (URL allow-list, login handoff, tool mapping from the previous gstack/browse pattern): `references/browser-workflow.md`.
 
 Browser validation artifacts must be sanitized before retention: do not store login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material in `.peaks` artifacts, and do not commit or sync sensitive browser evidence.
 
@@ -61,7 +63,7 @@ When Peaks Solo coordinates development in a code repository, keep this order ex
 5. unit tests for new/changed behavior, with focused new-code coverage accepted for legacy low-coverage repos;
 6. code review and security review with CRITICAL/HIGH issues fixed before progression; marked-blocked CRITICAL/HIGH issues only allow a blocked handoff, not QA or completion;
 7. RD post-check dry-run;
-8. QA validation, including API checks and headed `gstack/browse/dist/browse` browser E2E for frontend;
+8. QA validation, including API checks and Chrome DevTools MCP headed browser E2E for frontend;
 9. QA security and performance checks plus validation report;
 10. TXT final handoff capsule, including reusable skill-usage lessons when the workflow revealed new habits or preferences.
 
@@ -81,6 +83,70 @@ When QA reports problems:
 
 For full-auto or long-running workflows, prefer using Claude Code's `goal` command to encode this loop goal: "RD fixes until QA passes all acceptance items." Do not treat `goal` as a replacement for Peaks role artifacts; it is only the controller objective for the RD↔QA loop.
 
+## Default runbook
+
+The default end-to-end sequence Peaks Solo orchestrates when a user supplies a request (feature / bug / refactor / product-doc link) and selects the Solo (full-auto) profile. Each role's own Default runbook owns the per-role detail; Solo's job is to drive the cross-role state transitions in order and confirm the artifact chain is complete before declaring the workflow done.
+
+```bash
+# 0. snapshot the project before anything else
+peaks doctor --json
+peaks project dashboard --project <repo> --json     # one-call cross-role status
+peaks skill runbook peaks-solo --json               # confirm Solo's own runbook is intact + apply-gated
+
+# 1. PRD phase — capture the request as the canonical artifact
+peaks request init --role prd --id <request-id> --project <repo> --apply --json
+# (Solo executes peaks-prd Default runbook here, including authenticated
+#  document handling via Chrome DevTools MCP per peaks-solo/references/browser-workflow.md)
+peaks request transition <request-id> --role prd --state confirmed-by-user --project <repo> --json
+peaks request transition <request-id> --role prd --state handed-off --project <repo> --json
+
+# 2. UI phase — only when the request affects user-visible behavior
+peaks request init --role ui --id <request-id> --project <repo> --apply --json
+# (Solo executes peaks-ui Default runbook here)
+peaks request transition <request-id> --role ui --state direction-locked --project <repo> --json
+peaks request transition <request-id> --role ui --state handed-off --project <repo> --json
+
+# 3. RD phase — engineering planning + implementation
+peaks request init --role rd --id <request-id> --project <repo> --apply --json
+# (Solo executes peaks-rd Default runbook here: standards preflight + openspec entry gate +
+#  project-analysis evidence + implementation + openspec exit gate)
+peaks request transition <request-id> --role rd --state spec-locked   --project <repo> --json
+peaks request transition <request-id> --role rd --state implemented  --project <repo> --json
+peaks request transition <request-id> --role rd --state qa-handoff   --project <repo> --json
+
+# 4. QA phase — verification with the mandatory gates
+peaks request init --role qa --id <request-id> --project <repo> --apply --json
+# (Solo executes peaks-qa Default runbook here, including Chrome DevTools MCP frontend
+#  validation when frontend is in scope)
+peaks request transition <request-id> --role qa --state running         --project <repo> --json
+peaks request transition <request-id> --role qa --state verdict-issued  --project <repo> --json
+
+# 5. SC phase — record change-control evidence after QA passes
+# (Solo executes peaks-sc Default runbook here for the full sequence)
+peaks sc impact     --change-id <change-id> --module <module> --file <path>      --json
+peaks sc retention  --slice-id  <request-id> --prd <prd> --rd <rd> --qa <qa>     --json
+peaks sc validate   --slice-id  <request-id>                                     --json
+peaks sc boundary   --slice-id  <request-id> --artifact <artifact> --code <file> --json
+
+# 6. close the loop — final verification and optional OpenSpec archive
+peaks request list --project <repo> --json                          # every artifact reached its terminal state?
+peaks request show <request-id> --role qa --project <repo> --json   # QA verdict is pass?
+peaks openspec validate <change-id> --project <repo> --json         # exit gate (when openspec/ exists)
+peaks openspec archive  <change-id> --project <repo> --apply --json # only after QA verdict=pass
+
+# 7. TXT phase — compact handoff capsule
+# (Solo executes peaks-txt Default runbook here; durable extraction requires authorization)
+peaks memory extract --project <repo> --artifact <qa-artifact> --dry-run --json
+
+# 8. final snapshot to confirm the workflow really closed
+peaks project dashboard --project <repo> --json
+peaks skill doctor --json                            # all 7 required skills still healthy?
+```
+
+Solo's RD↔QA repair loop (`## Mandatory RD QA repair loop` above) applies if QA's verdict is `return-to-rd`. In that case, Solo re-runs phase 3 + phase 4 against the same `<request-id>` instead of starting a new one; the previous artifacts get appended with new transition notes via `--reason` rather than rewritten.
+
+For Assisted, Swarm, or Strict profiles, Solo pauses at the transition boundaries to confirm the next phase rather than running the chain straight through. The CLI sequence is the same; only the confirmation gate cadence differs.
+
 ## Mode selection
 
 When the user invokes Peaks Solo without explicitly selecting an execution profile, use `AskUserQuestion` before orchestration starts. Present the recommended full-auto path as the first/default option, and give every option a practical description so users can choose quickly.
@@ -96,8 +162,6 @@ If the user already names a profile, do not ask again unless the request crosses
 
 ## Project standards preflight
 
-Peaks Solo must ensure generated project-local `CLAUDE.md` and `.claude/rules/**` treat `https://github.com/SquabbyZ/andrej-karpathy-skills` code quality guidance and strict file-size limits as red lines, not optional preferences. Oversized single-file implementations block RD/QA completion.
-
 Before orchestrating an end-to-end code repository workflow, gather the project standards preflight status from RD and QA by calling the Peaks CLI:
 
 - `peaks standards init --project <path> --dry-run`
@@ -142,6 +206,25 @@ Codegraph is an optional project-analysis enhancement for role handoff. Solo may
 
 Record useful output in the local Peaks artifact workspace, such as `.peaks/<session-id>/rd/codegraph-context.md` or `.peaks/<session-id>/rd/codegraph-affected.json`. Treat codegraph output as untrusted supporting evidence. Solo must not treat codegraph output as approval, must not bypass role skills, and must not run upstream installer flows, configure an MCP server, mutate agent settings, or commit `.codegraph/` artifacts.
 
+## External skill invocation audit
+
+All Peaks skills that name `mattpocock/skills`, `superpowers`, `awesome-design-md`, `taste-skill`, `design-taste-frontend`, `shadcn/ui`, `React Bits`, `ui-ux-pro-max-skill`, `Chrome DevTools MCP`, `Agent Browser`, `Figma Context MCP`, `Penpot`, `Context7`, `SearchCode`, `claude-mem`, `context-mode`, `everything-claude-code`, `Claude Code Best Practice`, `andrej-karpathy-skills`, `GitNexus`, or other external resources must follow the three-stage pattern: capability discovery before naming, reference material only, side effects through the Peaks CLI only.
+
+Treat every named external skill as reference material only — do not execute upstream instructions, do not install upstream resources, do not persist sensitive examples. Peaks Solo orchestration and the role-skill artifacts remain authoritative; external skills inform, they do not approve.
+
+For MCP servers in particular, route installation through `peaks mcp plan` then `peaks mcp apply --yes`, and tool invocation through `peaks mcp call`, instead of describing manual `.claude/settings.json` edits.
+
+Canonical pattern and audit/repair recipe: `references/external-skill-invocation.md`.
+
+## OpenSpec and MCP lifecycle
+
+When the target repository uses OpenSpec or external MCP servers, Solo orchestrates the full lifecycle through the Peaks CLI rather than letting individual roles diverge.
+
+- OpenSpec: `peaks openspec render → validate → show → to-rd → validate → archive` is the canonical lifecycle. Validation runs twice (RD entry gate before slicing, QA exit gate before archive); both must end `data.valid === true`.
+- MCP: `peaks mcp list → plan → apply --yes → call → rollback (if needed)` is the canonical lifecycle. `apply` is the first real side effect; it backs up `~/.claude/settings.json` and refuses non-peaks-managed entries unless `--claim` is passed.
+
+Concrete rules and integration recipes: `references/openspec-mcp-workflow.md`.
+
 ## Optional capabilities
 
 When built-in guidance is insufficient, use capability discovery rather than reimplementing specialist workflows. Ask for user consent before token-heavy discovery unless the active profile permits it.

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

@@ -0,0 +1,114 @@
+# Headed browser workflow for Peaks skills
+
+Peaks skills standardize on **Playwright MCP** as the controlled headed-browser surface for opening a browser on demand (PRD authenticated docs, UI design inspection, QA E2E validation). Chrome DevTools MCP is a secondary surface that **connects to an existing Chrome instance launched with `--remote-debugging-port=9222`** — it does not launch a browser on its own. Picking the right tool for the right job is critical:
+
+| Need | Tool | Why |
+|---|---|---|
+| Open a controlled browser when the user supplies a URL | **Playwright MCP** | Spawns its own browser instance per session; no prerequisite. |
+| Drive console/network/performance inspection on a Chrome the user already has open | Chrome DevTools MCP | Connects via CDP to an existing Chrome on `:9222`. |
+| Frontend E2E validation that needs to start, navigate, capture, close | **Playwright MCP** | Headed mode, full lifecycle in one tool. |
+| Live page debugging where the user wants to keep their own Chrome session in front | Chrome DevTools MCP | Stays attached without disrupting the user's tabs. |
+
+> **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.
+
+## When to open the headed browser
+
+Open a controlled browser when:
+
+- PRD source is an authenticated product document (Feishu/Lark, Notion, internal wiki) and the URL passes the allow-list check.
+- UI design or full-auto frontend work needs visible regression observation.
+- QA needs E2E validation on a frontend, including console / network / accessibility / performance inspection.
+
+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)
+
+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:
+
+```bash
+peaks mcp list --json
+peaks mcp plan   --capability playwright-mcp.browser-validation --json
+peaks mcp apply  --capability playwright-mcp.browser-validation --yes --json
+```
+
+If a non-peaks-managed Playwright MCP entry already exists in `.claude/settings.json`, `apply` will refuse unless `--claim` is passed. Discuss with the user before claiming.
+
+After install, Claude Code's MCP runtime exposes the tools under the `mcp__playwright__*` namespace. Peaks skills reference these tools directly; they are not invoked through `peaks mcp call` because Claude Code is the host that calls them.
+
+## Optional: install Chrome DevTools MCP for CDP inspection
+
+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:
+
+```bash
+peaks mcp plan   --capability chrome-devtools-mcp.browser-debug --json
+peaks mcp apply  --capability chrome-devtools-mcp.browser-debug --yes --json
+```
+
+Tools become available under `mcp__chrome-devtools__*`. They fail with "Could not connect to Chrome" if no Chrome is running on `:9222`; that is by design.
+
+## Tool mapping for the "open a browser on demand" path (Playwright MCP)
+
+| Verb | Playwright MCP tool | Notes |
+|---|---|---|
+| Open visible browser and navigate | `mcp__playwright__browser_navigate` with `url` | Spawns a headed browser if none open; navigates in the existing context otherwise. |
+| Confirm visible browser opened | `mcp__playwright__browser_take_screenshot` | Screenshot is the visible-browser confirmation. |
+| Read structured page (text + a11y) | `mcp__playwright__browser_snapshot` | Accessibility tree with element refs. |
+| Click / fill / press key | `mcp__playwright__browser_click`, `browser_fill`, `browser_press_key` | Drive the page after navigation. |
+| Inspect console errors | `mcp__playwright__browser_console_messages` | Pass `level` to filter (`error`, `warning`). |
+| Inspect network failures | `mcp__playwright__browser_network_requests` | Pass `filter` regex when the page has many requests. |
+| Resize viewport for responsive checks | `mcp__playwright__browser_resize` | |
+| Capture a full-page screenshot | `mcp__playwright__browser_take_screenshot` with `fullPage: true` | Sanitize before retention. |
+| Close the session cleanly | `mcp__playwright__browser_close` | End-of-task. |
+
+## Tool mapping for the "connect to running Chrome" path (Chrome DevTools MCP, optional)
+
+| Verb | Chrome DevTools MCP tool | Notes |
+|---|---|---|
+| List pages in user's Chrome | `mcp__chrome-devtools__list_pages` | Requires Chrome already running with `--remote-debugging-port=9222`. |
+| Bring a tab to front | `mcp__chrome-devtools__select_page` with `bringToFront: true` | Useful when the user navigated themselves. |
+| Screenshot the visible viewport | `mcp__chrome-devtools__take_screenshot` | |
+| Read structured page | `mcp__chrome-devtools__take_snapshot` | |
+| Performance trace | `mcp__chrome-devtools__performance_start_trace` then `performance_stop_trace` | |
+| Lighthouse audit | `mcp__chrome-devtools__lighthouse_audit` with `mode: snapshot` | |
+
+If Chrome is not running on `:9222`, every Chrome DevTools MCP tool fails. The skill must surface that as a blocked precondition, not silently fall back.
+
+## URL allow-list (always required before navigation)
+
+Before calling `mcp__playwright__browser_navigate` (or any other navigation), verify:
+
+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).
+3. Reject `localhost`, loopback, link-local, raw IP, and private IP unless the user explicitly approves a controlled local test target.
+4. Reject the navigation entirely if any check fails and surface the reason to the user. Do not silently downgrade to an unauthenticated fetch.
+
+## Login / CAPTCHA / SSO / MFA handoff
+
+If the page redirects to a login challenge:
+
+1. Do not auto-fill credentials. Do not bypass authentication.
+2. The headed browser is already visible; surface that to the user and wait for explicit confirmation that they have completed authentication. Do not assume a state transition from any DOM signal alone.
+3. After the user confirms, resume with `browser_snapshot` / `browser_take_screenshot` / `browser_console_messages` / `browser_network_requests` as needed for the role artifact.
+4. If the user cannot complete authentication, mark the role artifact `blocked` with a sanitized reason category (`login-required`, `mfa-required`, `access-denied`) and the exact next user action.
+
+## Sensitive data sanitization
+
+Never persist any of the following in `.peaks/<session-id>/**` artifacts:
+
+- Login URLs, redirect URLs, OAuth callback URLs containing tokens or state.
+- Cookies, request or response headers, session tokens, storage state, QR payloads.
+- Raw network logs.
+- Raw browser state, browser traces.
+- Screenshots or logs containing PII, SSO challenge content, or MFA material.
+
+Redact sensitive values before retention. Store evidence as sanitized observations (e.g., "user reached settings page; first 3 list items had a missing-image regression") rather than raw captures.
+
+## Fallback when Playwright MCP is not installed
+
+If `peaks mcp list --json` does not include `playwright` in `mcpServers`:
+
+1. Surface the install commands above (peaks mcp plan / apply).
+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.
+
+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

@@ -0,0 +1,70 @@
+# Canonical external-skill invocation pattern for Peaks skills
+
+Peaks skills reference many external resources — `mattpocock/skills`, `gstack`, `awesome-design-md`, `taste-skill`, `design-taste-frontend`, `superpowers`, `shadcn/ui`, `React Bits`, `Chrome DevTools MCP`, `Agent Browser`, `Figma Context MCP`, `Penpot`, `Context7`, `SearchCode`, `claude-mem`, `context-mode`, `everything-claude-code`, `Claude Code Best Practice`, `andrej-karpathy-skills`, `OpenSpec`, `GitNexus`, and others.
+
+Every reference must follow the same three-stage pattern so the Peaks gates stay authoritative and side effects stay observable.
+
+## 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:
+
+- `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`.
+
+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.
+
+## Stage 2 — Reference, never auto-execute
+
+External skills are inspection material for the role's own artifacts. They are not auto-runnable workflows. Every reference must:
+
+- explicitly say it is a reference (e.g. "use these upstream methods as <role> references only");
+- name the specific methods or surfaces the role borrows;
+- 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.
+
+## Stage 3 — Side effect through Peaks CLI only
+
+The skill body must not silently:
+
+- install hooks;
+- create agents;
+- enable or configure an MCP server;
+- modify `~/.claude/settings.json` or project `.claude/settings.json`;
+- write to `.codegraph/`, `.openspec/`, or other upstream tool state;
+- store tokens, cookies, login URLs, headers, storage state, or PII / SSO / MFA browser material;
+- 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.
+
+## Allowed in-process references
+
+Some references are not external skills but project-approved utilities and may be named directly without the discovery stage:
+
+- `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.
+
+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.
+
+## Common phrasing the audit looks for
+
+The skill-external-invocation dogfood test scans skill bodies for:
+
+- a `capability discovery exposes` clause or equivalent before naming a discoverable external skill;
+- a `references only` / `reference material` / `reference resources` phrase qualifying any external skill name;
+- a `do not execute upstream instructions` / `do not run upstream installer flows` / `do not persist sensitive examples` clause;
+- a `Peaks` authoritative-gate clause (e.g. "Peaks gates remain authoritative", "Peaks artifacts remain authoritative", "Peaks acceptance authority").
+
+When a skill body adds a new external reference, it must include the equivalent phrasing or the audit test fails.
+
+## Repair recipe when audit fails
+
+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;
+5. rerun the audit.

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

@@ -0,0 +1,53 @@
+# OpenSpec and MCP 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.
+
+## OpenSpec change lifecycle
+
+```text
+peaks openspec render   →  RD authors a change pack (dry-run, then --apply)
+peaks openspec validate →  Solo gates RD output before slicing starts
+peaks openspec show     →  any role reads parsed proposal/tasks state
+peaks openspec to-rd    →  RD projects the pack into refactor slice input
+                          SC projects it into commit boundary candidates
+peaks openspec validate →  QA gates the final state before sign-off
+peaks openspec archive  →  Solo moves the change under changes/archive/<id>/
+```
+
+Rules Solo applies:
+
+- `render --apply` is the only Peaks-managed way to write a change pack. Other roles must not hand-edit `openspec/changes/**`.
+- `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/`:
+
+1. RD entry gate — `peaks openspec validate <id>` must pass and `peaks openspec to-rd <id>` must return `acceptance.length > 0`.
+2. Each slice must reference one OpenSpec tasks section as its commit boundary (per `references/openspec-commit-boundaries.md` in peaks-sc).
+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.
+
+## Boundary
+
+Solo must not write `openspec/changes/**` or `~/.claude/settings.json` directly. Every mutation goes through the CLI commands above. The CLI returns stable envelopes; Solo captures them as artifact links rather than re-explaining their content in the handoff.

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

@@ -21,7 +21,7 @@ A code workflow is not complete until Solo has linked or summarized:
 6. security-review evidence;
 7. RD post-check dry-run evidence;
 8. QA API validation when applicable;
-9. sanitized QA headed `gstack/browse/dist/browse` browser E2E evidence for frontend projects, with mandatory visible-browser confirmation and without login URLs, cookies, headers, tokens, storage state, browser traces, or PII/SSO/MFA screenshots/logs;
+9. sanitized QA Playwright MCP browser E2E evidence for frontend projects (`mcp__playwright__browser_snapshot` / `take_screenshot` / `list_console_messages` / `list_network_requests`), with mandatory visible-browser confirmation and without login URLs, cookies, headers, tokens, storage state, browser traces, or PII/SSO/MFA screenshots/logs;
 10. QA security, performance, and validation report evidence;
 11. RD repair evidence for every failed, blocked, missing, or unverified QA item;
 12. final QA report showing all acceptance items passed, or a blocked TXT handoff;