peaks-cli 1.0.15 → 1.0.17

package/skills/peaks-solo/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: peaks-solo
-description: Full-auto orchestration facade for the Peaks skill family. Use when the user asks Peaks to handle a project workflow end-to-end, especially refactoring via `peaks-solo refactor`, coordinating peaks-prd, peaks-rd, peaks-qa, peaks-sc, and peaks-txt while preserving user confirmation gates.
+description: Full-auto orchestration facade for the Peaks skill family. Use when the user asks Peaks to handle a project workflow end-to-end (端到端/全流程/需求开发), especially from a product document (产品文档/PRD/飞书文档/Feishu doc) through implementation and validation. Coordinates peaks-prd, peaks-rd, peaks-ui, peaks-qa, peaks-sc, and peaks-txt while preserving user confirmation gates. Triggers on `/peaks-solo`, "peaks solo", "全流程开发", "端到端迭代", "根据产品文档开发", "从需求到上线".
 ---
 
 # Peaks Solo
@@ -9,12 +9,34 @@ Peaks Solo is the orchestration facade for the Peaks short skill family.
 
 Use this skill to identify the user scenario, recommend an execution mode, coordinate role skills, and produce the final handoff report. Do not collapse role responsibilities into this skill.
 
-## Skill presence (MANDATORY first action)
+## Startup sequence (MANDATORY — execute in order)
 
-Before any analysis, response, or tool call, immediately run:
+### Step 1: Mode selection (MUST run before presence:set)
+
+When the user invokes Peaks Solo without explicitly naming an execution profile, use `AskUserQuestion` BEFORE any other action. Present the recommended full-auto path as the first/default option with a practical description for each:
+
+1. **Full auto (Recommended)** — Peaks handles planning, role coordination, validation, and compact handoff end-to-end while preserving required confirmation gates for risky or shared-state actions.
+2. **Assisted** — Peaks proposes plans, artifacts, and checks, then pauses for user decisions at major workflow boundaries.
+3. **Swarm** — Peaks maximizes safe parallel role/worker execution for larger RD or QA workloads while keeping reducer validation and artifact boundaries explicit.
+4. **Strict** — Peaks uses the most conservative gates: explicit confirmations, strict slice specs, coverage evidence, QA acceptance, and commit boundaries before continuing.
+
+Map the user's selection to the `--mode` flag value:
+
+| User selects | `--mode` value |
+|---|---|
+| Full auto | `solo` |
+| Assisted | `assisted` |
+| Swarm | `swarm` |
+| Strict | `strict` |
+
+If the user already names a profile in their invocation (e.g. `/peaks-solo --full-auto`, "用全自动模式"), skip this question and use the named profile directly.
+
+### Step 2: Set skill presence
+
+Only after the mode is known (user selected or explicitly named), run:
 
 ```bash
-peaks skill presence:set peaks-solo --mode <mode> --gate startup
+peaks skill presence:set peaks-solo --mode <mode-value> --gate startup
 ```
 
 Then display the compact status header: `Peaks Skill: peaks-solo | Gate: startup | Next: <one short action>`. Display this header on EVERY turn while the skill is active.
@@ -45,45 +67,297 @@ Use the Peaks CLI for runtime side effects.
 
 ## GStack integration
 
-Use gstack as a concrete orchestration reference for the full `Think → Plan → Build → Review → Test → Ship → Reflect` loop:
+Map gstack stages to Peaks role artifacts; preserve Peaks confirmation gates. Do not delegate orchestration to gstack commands.
+
+For frontend workflows, RD and QA must use Playwright MCP for real browser E2E (`peaks mcp plan/apply --capability playwright-mcp.browser-validation --yes`). Chrome DevTools MCP is a secondary CDP surface only. Sanitize browser artifacts before retention (no login URLs, cookies, tokens, PII). See `references/browser-workflow.md`.
+
+## Local intermediate artifact workspace (MANDATORY)
+
+### Workspace initialization gate
+
+Before ANY role handoff or artifact write, Peaks Solo MUST create the workspace. The session-id uses the format `YYYY-MM-DD-<kebab-slug>` where `<kebab-slug>` is the **request-id or a 2-5 word topic description** (e.g. `2026-05-25-v3-indicator-model`, `2026-05-25-add-user-auth`).
+
+**PROHIBITED session-id patterns** — block the workflow if any of these appear:
+- Numeric-only: `1779674289`, `1779672642`
+- Generic suffixes: `session`, `work`, `task`, `test`, `temp`, `tmp`
+- Bare dates without topic: `2026-05-25`
+- Timestamps: `20260525T093000`
+
+**Existing old-session cleanup**: If `.peaks/` contains numeric-only or generic session directories from prior runs, create the new correctly-named session, migrate any reusable artifacts into it, and note the migration in the TXT handoff. Delete empty old-session directories.
+
+```bash
+peaks workspace init --project <repo> --session-id <YYYY-MM-DD-<slug>> --json
+```
+
+The workspace initialization creates this structure under `.peaks/<session-id>/`:
+
+```
+prd/source/     # PRD source documents (Feishu exports, pasted content)
+prd/requests/   # PRD request artifacts (goals, non-goals, acceptance, frontend delta)
+ui/requests/    # UI request artifacts (visual direction, taste reports)
+rd/requests/    # RD request artifacts (slice specs, coverage, CR findings)
+qa/test-cases/  # QA test cases
+qa/test-reports/ # QA test reports (regression matrices, browser evidence)
+qa/requests/    # QA request artifacts
+sc/             # SC artifacts (change-control, impact, retention, boundary)
+txt/            # TXT artifacts (handoff capsules, lessons, memory extraction)
+```
+
+Role skills create these key files at the directory levels shown above:
+- `rd/project-scan.md` (Solo step 0.6), `rd/tech-doc.md` (RD planning step 3b)
+- `ui/design-draft.md` (UI step 3a)
+- Request-scoped files under each role's `requests/` subdirectory
+
+### Root pollution prohibition (CRITICAL)
+
+**NEVER write Peaks intermediate artifacts to the project root directory.** Specifically prohibited at root level:
+
+- PRD snapshots, document extracts, or requirement notes (`feishu-doc-*.md`, `*-snapshot.md`, etc.)
+- RD tech docs, scan reports, slice specs, or architecture notes
+- QA screenshots, browser evidence, test reports, or validation logs (`.png`, `.jpg`)
+- QA test helper files, mock servers, or fixture scripts (`qa-server.js`, etc.)
+- UI design drafts, taste reports, or visual direction notes
+- TXT handoff capsules or lesson files
+
+Legitimate source files (e.g. `jest-setup.ts`, `tailwind.config.js`) belong at root — do not move them.
 
-- map gstack role reviews to Peaks PRD, RD, UI, QA, SC, and TXT artifacts;
-- map `/autoplan`-style review pipelines to Peaks mode selection and role handoffs;
-- 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.
+If you are about to Write/Edit an intermediate artifact in the project root, STOP. Create the `.peaks/<session-id>/` workspace first and write to the correct role subdirectory. If existing root-level artifacts from a prior run are discovered, move them into `.peaks/<session-id>/` and note the migration in the TXT handoff.
 
-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.
+### Git and sync policy
 
-Canonical browser workflow (URL allow-list, login handoff, tool mapping from the previous gstack/browse pattern): `references/browser-workflow.md`.
+Do not default to git-backed storage or automatic commits for intermediate artifacts. Git inclusion or sync requires explicit user confirmation or an active profile that authorizes it.
 
-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.
+## Pre-RD project scan checklist (MANDATORY)
 
-## Local intermediate artifact workspace
+Before handing off to `peaks-rd`, scan the project and record findings to `.peaks/<session-id>/rd/project-scan.md`. RD and UI roles read this before starting work.
+
+### 1. Build tool: inspect config files for the framework
+
+| Config file | Framework |
+|---|---|
+| `.umirc.ts`, `config/config.ts` | Umi (Ant Design Pro) |
+| `next.config.*` | Next.js |
+| `vite.config.*` | Vite |
+| `webpack.config.*` | Webpack |
+| `angular.json` | Angular |
+
+### 2. Component library: check `package.json` dependencies
+
+| Package | Library |
+|---|---|
+| `antd` | Ant Design |
+| `@mui/material` | Material UI |
+| `tailwindcss` + `radix-ui` | shadcn/ui |
+| `element-plus` / `element-ui` | Element UI/Plus |
+| `@arco-design/web-react` | Arco Design |
+| `tdesign-react` / `tdesign-vue-next` | TDesign |
+| `@nextui-org/react` | NextUI |
+| `@chakra-ui/react` | Chakra UI |
+
+**CRITICAL**: Never add a second component library to a project that already has one. Do not introduce shadcn/ui to an antd project or vice versa.
+
+### 3. CSS framework: check for conflicts
+
+- **antd + TailwindCSS**: High conflict risk (preflight reset overrides base styles). Resolution:
+  - Both already in `package.json` → coexist; use Tailwind for layout, antd for components.
+  - Tailwind breaks antd styles → add `corePlugins: { preflight: false }` or `important: '#root'`.
+  - Only antd, user wants Tailwind → **Block**; propose antd `ConfigProvider` tokens or CSS Modules.
+- **Less/Sass**: Standard for Umi+antd projects; compatible with CSS Modules.
+- **CSS-in-JS (@emotion, styled-components)**: Check if component library already uses one internally; don't add competing solutions.
+
+### 4. State management, routing, data fetching: detect from `package.json`
+
+State: `zustand`, `jotai`, `redux`/`@reduxjs/toolkit`, `valtio`, `mobx`, `hox`
+Routing: `react-router-dom`, `@umijs/max`, Next.js file-based, `vue-router`
+Data fetching: `@tanstack/react-query`, `swr`, `ahooks` (`useRequest`), `umi-request`
+
+### 5. Project-scan artifact template
+
+```markdown
+# Project Scan: <project-name>
+**Date:** YYYY-MM-DD
+**Session:** <session-id>
+
+## Build tool
+- Framework: <name> <version>
+- Config file: <path>
+
+## Component library
+- Library: <name> <version>
+- Design-system packages: <list>
+
+## CSS solution
+- Primary: <Less/Sass/CSS-in-JS/TailwindCSS/CSS Modules>
+- Conflicts detected: <none | description and recommendation>
+
+## State management, routing, data fetching
+- State: <name>
+- Routing: <name>
+- Data fetching: <name>
+```
+
+## Frontend-only development mode
+
+When the project is a pure frontend repository without a live backend (no swagger.json, no API server), Solo must activate frontend-only mode. This is triggered when the user says "先 mock 数据", "没有后端", "前端仓", or similar.
+
+### Mock data strategy selection
+
+Solo records the chosen mock strategy in `.peaks/<session-id>/rd/tech-doc.md` under a `## Mock Data Strategy` section. The choice depends on the project scan results:
+
+| Project data-fetching pattern | Recommended mock approach | Rationale |
+|---|---|---|
+| Umi + `umi-request` / `@umijs/plugins` request | Umi mock directory (`mock/*.ts`) | Built-in, zero-config, auto-reload on file change |
+| `@tanstack/react-query` + custom fetcher | Service-layer mock with `Promise.resolve()` stubs in the service file | Keeps query hooks unchanged; swap fetcher target later |
+| `ahooks` `useRequest` + service functions | Service-layer mock: replace HTTP call with `Promise.resolve(mockData)` | Matches existing service-function pattern |
+| MSW (Mock Service Worker) already configured | Add new handlers to existing MSW setup | Consistent with project convention |
+| No existing pattern (greenfield) | Service-layer mock with a `mock/` directory and typed fixture files | Clean separation, easy to delete later |
+
+**Mock data rules:**
+
+1. Every mock response must match the shape of the expected real API response. Define a TypeScript interface for the response type first, then create mock data that satisfies it.
+2. Mock data should be realistic (not `"test"`, `"foo"`, `123`) — use plausible Chinese/English content that resembles production data.
+3. Each mock must export its TypeScript interface so RD implementation and QA test-cases can import the same types.
+4. Mark every mock file with a header comment: `// MOCK: Replace with real API call when swagger.json is available`.
+
+### API contract placeholder pattern
+
+When no swagger.json exists, RD defines API contracts as TypeScript interfaces with a mock-then-real service layer:
+
+```
+src/services/types/<feature>-api.types.ts   ← API request/response interfaces
+src/services/<feature>-service.ts          ← Service functions (mock → real)
+mock/<feature>-mock.ts                     ← Mock data satisfying interfaces
+```
 
-Peaks Solo should establish or discover a local `.peaks/<session-id>/` workspace before role handoffs. Store PRD/RD/UI/QA/SC/TXT intermediate artifacts there by default, with role subdirectories such as `prd/`, `rd/`, `ui/`, `qa/`, `sc/`, and `txt/`.
+Each service function returns a typed mock response marked with `// MOCK: Replace with real API call when swagger.json is available`.
 
-Do not default to a git-backed local artifact repository, external artifact sync, or automatic commits for intermediate artifacts. Only include sanitized `.peaks` artifacts in git, sync them elsewhere, or create external artifact repositories after explicit user confirmation or an active profile that clearly authorizes it.
+### Mock-to-real migration path
 
-## End-to-end code workflow gates
+When swagger.json becomes available later, the migration follows this sequence:
+
+1. Generate typed API client from swagger.json (e.g. via `openapi-typescript` or manual mapping).
+2. Replace mock imports with generated API calls, one service file at a time.
+3. Remove corresponding mock files.
+4. Run QA regression to verify the real API responses match the mock interface contracts.
+
+Solo records the migration readiness in the TXT handoff capsule under a `## API Migration` section listing: mock file paths, the corresponding swagger endpoints (when known), and the migration status for each.
+
+### Feishu document access fallback
+
+When the PRD source is a Feishu/Lark document that requires authentication:
+
+1. **Primary path**: Playwright MCP headed browser → user completes login → Solo reads document content via `browser_snapshot`.
+2. **Fallback A (user cannot login)**: Ask user to copy-paste the document content or export as Markdown/PDF. Solo creates the PRD artifact from the pasted content.
+3. **Fallback B (user provides export)**: User drops a `.md` or `.pdf` export into `.peaks/<session-id>/prd/source/`. Solo reads and processes it.
+4. **Fallback C (none of the above)**: Mark PRD as `blocked` with reason `doc-inaccessible`, list the exact next steps for the user, and pause the workflow.
+
+Never silently fall back to unauthenticated `fetch` or `WebFetch` for authenticated documents.
 
 When Peaks Solo coordinates development in a code repository, keep this order explicit:
 
-1. standards preflight;
-2. PRD/RD scope and spec artifacts;
-3. OpenSpec change artifacts for non-trivial work when `openspec/` already exists or the user approves adding it;
-4. RD implementation slices;
-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 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.
+0. **Snapshot** — `peaks doctor` + `peaks project dashboard` to capture baseline state before anything else;
+0.5. **Workspace initialization** — `.peaks/<session-id>/` created, directory structure verified;
+0.6. **Project scan** — component library, CSS framework, build tool, state management, routing, data fetching detected and recorded to `.peaks/<session-id>/rd/project-scan.md`;
+1. **Standards preflight** — `peaks standards init/update --dry-run`, must reference concrete project-scan findings (never emit generic templates);
+2. **PRD phase** — capture request as canonical artifact, extract scope and acceptance criteria:
+   - Full-auto/Swarm: auto-transition to `confirmed-by-user` once the artifact is complete;
+   - Assisted/Strict: pause with `AskUserQuestion` for explicit user confirmation before proceeding;
+3. **Swarm parallel phase** — after PRD confirmed, launch UI, RD(planning), QA(test-cases) simultaneously:
+   3a. UI design draft and visual direction (MANDATORY when request is frontend/user-visible);
+   3b. RD tech-doc (architecture planning, component tree, data flow, API contracts);
+   3c. QA test-case generation (unit, integration, UI-regression test cases);
+4. **RD implementation** — consumes UI design-draft + RD tech-doc + QA test-cases + project-scan; includes unit tests for new/changed behavior (TDD);
+5. **Code review + security review** — CRITICAL/HIGH issues fixed before progression; marked-blocked issues only allow a blocked handoff;
+6. **QA validation** (auto-proceed from RD in full-auto) — execute test cases + API checks + Playwright MCP headed browser E2E for frontend + security/perf checks + test report;
+7. **RD↔QA repair loop** — if QA verdict is `return-to-rd`, loop back to step 4 (RD implementation) and re-run through QA; max 3 repair cycles, then emit blocked TXT regardless;
+8. **SC phase** — change-control evidence: impact, retention, validate, boundary;
+9. **OpenSpec archive** — exit gate: validate → archive only after QA verdict=pass (when `openspec/` exists);
+10. **TXT handoff capsule** — mode, validated decisions, artifact paths, standards deltas, open questions, next action;
+11. **Final snapshot** — `peaks project dashboard` + `peaks skill doctor` to confirm the workflow closed cleanly.
+
+### Transition verification gates (MANDATORY — run the command, see the output)
+
+You cannot declare a phase complete from memory. Each gate below is a `ls` command you **MUST run** and whose output you **MUST see** before proceeding. If any file shows "No such file", the phase is incomplete.
+
+**Gate A — After workspace init + project scan:**
+```bash
+ls .peaks/<id>/rd/project-scan.md
+# Expected output: .peaks/<id>/rd/project-scan.md
+# "No such file" → STOP, run project scan first
+```
+
+**Gate B — After swarm convergence (UI + RD planning + QA test-cases):**
+```bash
+ls .peaks/<id>/prd/requests/<rid>.md \
+   .peaks/<id>/ui/design-draft.md \
+   .peaks/<id>/rd/tech-doc.md \
+   .peaks/<id>/qa/test-cases/<rid>.md
+# Every line must be a file path.
+# Frontend: ui/design-draft.md missing → apply swarm degradation rule 1 (do not block RD, note "ui-design-missing" in TXT)
+# Pure backend: ui/design-draft.md absent → state skip reason, proceed
+```
+
+**Gate C — After RD implementation (before QA handoff):**
+```bash
+ls .peaks/<id>/rd/requests/<rid>.md \
+   .peaks/<id>/rd/tech-doc.md
+# Both must exist. Missing either → BLOCKED, do not hand off to QA
+```
+
+**Gate D — After QA validation:**
+```bash
+ls .peaks/<id>/qa/test-cases/<rid>.md \
+   .peaks/<id>/qa/test-reports/<rid>.md \
+   .peaks/<id>/qa/requests/<rid>.md
+# All three must exist. Missing any → QA incomplete
+```
+
+**Gate E — Before declaring workflow complete:**
+```bash
+find .peaks/<id>/ -type f | sort
+# Verify: files from gates A-D all appear in this list.
+# Any mandatory file missing → NOT complete. Do not emit TXT.
+```
+
+**Gate F — Root pollution check (BLOCKING before completion):**
+```bash
+# Verify no Peaks intermediate artifacts leaked to project root.
+ls feishu-doc-*.md *-snapshot.md qa-server.js 2>&1
+# Expected: "No such file or directory" for ALL patterns.
+# Any file found → ROOT POLLUTION. Move it to .peaks/<id>/prd/source/
+# (for doc snapshots) or .peaks/<id>/qa/ (for QA artifacts).
+# Note the migration in TXT handoff. Do NOT complete the workflow
+# with intermediate artifacts in the project root.
+```
+```bash
+# Extended check for common leak patterns
+find . -maxdepth 1 -name "*.png" -o -name "*.jpg" -o -name "qa-*.js" -o -name "mock-server.*" 2>&1
+# Any Peaks QA/UI intermediate files here → ROOT POLLUTION. Move and note.
+# Legitimate project files (e.g. favicon.png) are fine — only move Peaks artifacts.
+```
+
+
+## Swarm parallel phase
+
+After PRD reaches `confirmed-by-user`, Solo launches peaks-ui, peaks-rd(planning), and peaks-qa(test-cases) simultaneously using parallel Agent calls. All three derive independently from the same PRD and write to separate artifact paths. Solo waits for all three, checks convergence (Gate B), then enters RD implementation.
 
-Do not close the Solo workflow as complete if RD or QA artifacts lack required test, review, security, dry-run, OpenSpec, browser, report, or performance evidence. Do not close a workflow that changed Peaks skill behavior without a `peaks-txt` capsule capturing reusable usage lessons and artifact paths.
+### Degradation when swarm roles fail
 
-## Mandatory RD QA repair loop
+1. **UI missing**: RD continues with PRD visual descriptions; note "ui-design-missing" in TXT.
+2. **RD planning missing**: RD continues; note "tech-doc-missing" in TXT.
+3. **QA test-cases missing**: RD continues; QA must backfill test cases before issuing verdict.
+4. **Two or more missing**: Fall back to sequential mode (PRD → RD → QA); note "swarm-degraded-to-sequential".
+5. **All three missing**: Pause workflow; report to user; request confirmation to continue.
 
-After `peaks-rd` finishes any implementation, repair, or code-output slice, Peaks Solo must route the result to `peaks-qa` before completion. A QA report with any failing, blocked, missing, or unverified acceptance item is not a pass.
+**UI phase mandatory for frontend**: When the request affects user-visible behavior (pages, components, forms, modals, tables, styling, interaction, or layout), Peaks Solo MUST invoke `peaks-ui` in the swarm parallel phase alongside RD planning and QA test-case generation. UI produces design drafts that RD implementation later consumes. Skipping UI for frontend work is a blocking violation. The only valid reason to skip UI is when the request is purely backend (API, database, CLI, config, or build tooling).
+
+## Mandatory RD QA repair loop (AUTO-PROCEED)
+
+After `peaks-rd` finishes any implementation, repair, or code-output slice, Peaks Solo MUST automatically route the result to `peaks-qa` without waiting for user confirmation. This is not optional in full-auto mode. Solo must not declare the workflow complete, emit a TXT handoff, or stop at RD completion.
+
+**Full-auto auto-proceed rule**: In Solo (full-auto) profile, when RD transitions to `qa-handoff`, Solo immediately invokes `peaks-qa` with the same `<request-id>`. Do not pause, do not ask the user, do not summarize RD results as if they were final. The only valid reason to skip QA is when the request has zero code changes (documentation-only, standards-only).
+
+A QA report with any failing, blocked, missing, or unverified acceptance item is not a pass.
 
 When QA reports problems:
 
@@ -93,86 +367,75 @@ When QA reports problems:
 4. run `peaks-qa` again on the repaired output;
 5. repeat until QA reports all acceptance items passed, or emit a blocked TXT handoff.
 
-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.
+**Repair cycle cap**: After 3 repair cycles without a passing QA verdict, emit a blocked TXT handoff regardless of remaining issues. Do not loop indefinitely. If a specific issue cannot be resolved within 3 cycles, mark it as a known blocker in the TXT handoff and proceed to the SC phase.
+
+In full-auto mode, treat the RD↔QA repair loop as a built-in controller objective: loop through RD→QA until all acceptance items pass (max 3 cycles). Do not exit the loop on a non-passing QA verdict unless the TXT handoff marks the workflow as blocked.
 
 ## 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.
+> **Maintenance**: The numbered workflow list above (steps 0-11) is the canonical phase sequence. This runbook is the executable CLI transcription. When updating this skill, keep both in lockstep — a change to one must be reflected in the other.
+
+The end-to-end CLI sequence for the Solo (full-auto) profile. Assisted/Strict profiles pause at `[CONFIRM]` markers below. Full-auto and Swarm auto-proceed through all gates. See Transition Gates for artifact verification at each stage.
 
 ```bash
-# 0. snapshot the project before anything else
+# 0. Snapshot + 0.5 Workspace + 0.6 Project scan
 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
-peaks skill presence:set peaks-solo --mode solo     # show persistent skill presence every turn
-
-# 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 project dashboard --project <repo> --json
+peaks skill runbook peaks-solo --json
+peaks workspace init --project <repo> --session-id <YYYY-MM-DD-<slug>> --json
+# → write .peaks/<session-id>/rd/project-scan.md (Gate A)
+
+# 1. Standards preflight
+peaks standards init --project <repo> --dry-run --json
+# or: peaks standards update --project <repo> --dry-run --json
+
+# 2. PRD (Assisted/Strict: [CONFIRM] before confirmed-by-user)
+peaks request init --role prd --id <rid> --project <repo> --apply --json
+peaks request transition <rid> --role prd --state confirmed-by-user --project <repo> --json
+peaks request transition <rid> --role prd --state handed-off --project <repo> --json
+
+# 3. Swarm parallel — launch UI + RD(planning) + QA(test-cases) simultaneously
+peaks request init --role ui --id <rid> --project <repo> --apply --json
+peaks request transition <rid> --role ui --state direction-locked --project <repo> --json
+peaks request transition <rid> --role ui --state handed-off --project <repo> --json
+peaks request init --role rd --id <rid> --project <repo> --apply --json
+peaks request transition <rid> --role rd --state spec-locked --project <repo> --json
+peaks request init --role qa --id <rid> --project <repo> --apply --json
+# → Gate B convergence check. Assisted/Strict: [CONFIRM]
+
+# 4. RD implementation (consumes design-draft + tech-doc + test-cases + project-scan)
+peaks request transition <rid> --role rd --state implemented --project <repo> --json
+peaks request transition <rid> --role rd --state qa-handoff --project <repo> --json
+
+# 5. Code review + security review (fix CRITICAL/HIGH before proceeding)
+
+# 6. QA validation (AUTO-PROCEED from RD in full-auto)
+peaks request transition <rid> --role qa --state running --project <repo> --json
+peaks request transition <rid> --role qa --state verdict-issued --project <repo> --json
+# → Gate D check. Assisted/Strict: [CONFIRM]
+
+# 7. RD↔QA repair loop — if verdict is return-to-rd, re-run 4 through 6 until QA passes or blocked TXT
+
+# 8. SC phase
+peaks sc impact --change-id <cid> --module <module> --file <path> --json
+peaks sc retention --slice-id <rid> --prd <prd> --rd <rd> --qa <qa> --json
+peaks sc validate --slice-id <rid> --json
+peaks sc boundary --slice-id <rid> --artifact <artifact> --code <file> --json
+
+# 9. OpenSpec archive (exit gate; only after QA pass, when openspec/ exists)
+peaks openspec validate <cid> --project <repo> --json
+peaks openspec archive <cid> --project <repo> --apply --json
+
+# 10. TXT handoff
 peaks memory extract --project <repo> --artifact <qa-artifact> --dry-run --json
 
-# 8. final snapshot to confirm the workflow really closed
+# 11. Final snapshot
 peaks project dashboard --project <repo> --json
-peaks skill doctor --json                            # all 7 required skills still healthy?
-peaks skill presence:clear                          # workflow complete, remove presence indicator
+peaks skill doctor --json
+peaks skill presence:clear
 ```
 
-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.
-
-Offer these profiles unless the active command narrows the valid set:
-
-1. **Full auto (Recommended, Solo profile)** — Peaks handles planning, role coordination, validation, and compact handoff end-to-end while preserving required confirmation gates for risky or shared-state actions.
-2. **Assisted** — Peaks proposes plans, artifacts, and checks, then pauses for user decisions at major workflow boundaries.
-3. **Swarm** — Peaks maximizes safe parallel role/worker execution for larger RD or QA workloads while keeping reducer validation and artifact boundaries explicit.
-4. **Strict** — Peaks uses the most conservative gates: explicit confirmations, strict slice specs, coverage evidence, QA acceptance, and commit boundaries before continuing.
-
-If the user already names a profile, do not ask again unless the request crosses a risk boundary or the named profile conflicts with required Peaks gates.
+Repair loop details: see `## Mandatory RD QA repair loop` above for the full 5-step procedure and the 3-cycle cap. Append transition notes via `--reason` rather than rewriting artifacts during repair cycles.
 
 ## Project standards preflight
 
@@ -181,7 +444,11 @@ Before orchestrating an end-to-end code repository workflow, gather the project
 - `peaks standards init --project <path> --dry-run`
 - `peaks standards update --project <path> --dry-run`
 
-Use `standards init` for first-time creation and `standards update` for existing `CLAUDE.md` append/review behavior. Apply only when write authorization exists; otherwise keep the CLI output as the next action and continue only when the selected workflow can safely proceed without writing standards. Do not hand-write standards file mutations inside the skill.
+Use `standards init` for first-time creation and `standards update` for existing `CLAUDE.md` append/review behavior. Apply only when write authorization exists; otherwise keep the CLI output as the next action.
+
+**CRITICAL — Standards must reflect the project scan.** When generating or updating `CLAUDE.md`, the content must reference concrete findings from `.peaks/<id>/rd/project-scan.md`: the detected component library (e.g. "This project uses antd 5.x"), CSS solution (e.g. "Uses Less via Umi"), build tool, state management, and routing. Never emit a generic template that says "read .claude/rules/..." without naming the actual project stack. If the project-scan has not been run yet, run it before standards init/update.
+
+Do not hand-write standards file mutations inside the skill.
 
 For project-analysis requests such as "分析项目", the handoff must include an explicit **Standards increment** section. Report the current `CLAUDE.md` and `.claude/rules/**` status from the dry-run output as incremental deltas, not just a generic preflight note:
 
@@ -210,37 +477,18 @@ It must enforce the shared refactor red lines:
 
 ## Completion handoff
 
-After a Peaks Solo workflow reaches final validation, refresh the project-local standards from the current scan-backed evidence before the handoff closes. Route project-local `CLAUDE.md` and project-local `.claude/rules/**` writes through `peaks standards init` or `peaks standards update`; do not hand-write standards mutations. If write authorization exists, apply an incremental merge of scan-backed changes into existing project-local standards. Preserve existing hand-maintained content unless the user explicitly confirms deletion or rewrite. If write authorization or the CLI path is unavailable, keep the standards output as the next action instead of writing it.
-
-Use Peaks TXT for the final, blocked, or interrupted handoff capsule. Keep that capsule compact: current mode, validated decisions, artifact paths, standards deltas, open questions, and next action. The standards deltas must name `CLAUDE.md` and `.claude/rules/**` statuses explicitly whenever project standards preflight ran. Do not restate the full workflow log when a short handoff plus artifact links will do.
-
-## Codegraph orchestration context
-
-Codegraph is an optional project-analysis enhancement for role handoff. Solo may coordinate `peaks codegraph context --project <path> "<task>"` or `peaks codegraph affected --project <path> <changed-files...> --json` before assigning work to RD, QA, or TXT when shared project evidence would make the handoff narrower.
-
-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`.
+After final validation, refresh project-local standards via `peaks standards init/update` (never hand-write). Merge scan-backed changes incrementally; preserve hand-maintained content unless user confirms deletion.
 
-## OpenSpec and MCP lifecycle
+Use Peaks TXT for the compact handoff capsule: mode, validated decisions, artifact paths, standards deltas (`CLAUDE.md` and `.claude/rules/**` statuses), open questions, next action. Do not restate the full workflow log.
 
-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.
+## External references and lifecycle
 
-- 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.
+**Codegraph**: Optional project-analysis before RD handoff. Use `peaks codegraph affected --project <path> <changed-files...> --json` for regression-surface hints. Output as untrusted supporting evidence only; never commit `.codegraph/` artifacts.
 
-Concrete rules and integration recipes: `references/openspec-mcp-workflow.md`.
+**External skills**: All external skill references (`mattpocock/skills`, `awesome-design-md`, `taste-skill`, `shadcn/ui`, `Chrome DevTools MCP`, `Figma Context MCP`, `Context7`, etc.) follow the three-stage pattern: capability discovery before naming, reference-only (no execute/install/persist), Peaks CLI for all side effects. External skills inform, they do not approve.
 
-## Optional capabilities
+**OpenSpec lifecycle**: `render → validate → show → to-rd → validate → archive`. Solo's default runbook handles the exit gate (validate → archive after QA pass). Entry-gate validation (to-rd before slicing) is available when `openspec/` exists pre-workflow; Solo delegates it to `peaks-rd` during implementation.
 
-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.
+**MCP lifecycle**: `list → plan → apply --yes → call → rollback`. `apply` backs up settings and refuses non-peaks entries unless `--claim` is passed.
 
-Reference: `references/workflow.md`.
+Detailed rules: `references/external-skill-invocation.md`, `references/openspec-mcp-workflow.md`, `references/workflow.md`.