peaks-cli 1.0.16 → 1.0.18

package/skills/peaks-solo/SKILL.md

@@ -9,12 +9,36 @@ 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 (used by `peaks skill presence:set`; `presence:set --mode` accepts any string, so the name matches the user-facing label rather than overloading "solo" which is also the skill name):
+
+| User selects | `--mode` value |
+|---|---|
+| Full auto | `full-auto` |
+| Assisted | `assisted` |
+| Swarm | `swarm` |
+| Strict | `strict` |
+
+> Note: `peaks workflow route --mode solo|team` is a **different** CLI dimension (solo developer vs team flow) and is unrelated to the profile choice here. Do not conflate them.
+
+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,9 +69,9 @@ Use the Peaks CLI for runtime side effects.
 
 ## GStack integration
 
-Map gstack `Think→Plan→Build→Review→Test→Ship→Reflect` stages to Peaks role artifacts (PRD/RD/UI/QA/SC/TXT) and `/autoplan`/`/retro` patterns. Preserve Peaks confirmation gates and artifact boundaries; do not delegate orchestration to gstack commands.
+Map gstack stages to Peaks role artifacts; preserve Peaks confirmation gates. Do not delegate orchestration to gstack commands.
 
-For frontend workflows, Solo must ensure RD and QA use Playwright MCP for real browser E2E. Install via `peaks mcp plan/apply --capability playwright-mcp.browser-validation --yes`. Chrome DevTools MCP is a secondary CDP surface only — it does NOT launch a browser. If login/CAPTCHA/SSO/MFA appears, wait for user to complete login and explicitly confirm. Sanitize browser artifacts before retention (no login URLs, cookies, tokens, PII). Canonical workflow: `references/browser-workflow.md`.
+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)
 
@@ -70,14 +94,29 @@ peaks workspace init --project <repo> --session-id <YYYY-MM-DD-<slug>> --json
 The workspace initialization creates this structure under `.peaks/<session-id>/`:
 
 ```
-prd/requests/   # PRD artifacts (goals, non-goals, acceptance, frontend delta)
-ui/requests/    # UI artifacts (design drafts, visual direction, taste reports)
-rd/requests/    # RD artifacts (tech docs, scan reports, slice specs, coverage, CR findings)
-qa/requests/    # QA artifacts (test cases, test reports, regression matrices, browser evidence)
-sc/             # SC artifacts (change-control, impact, retention, boundary)
-txt/            # TXT artifacts (handoff capsules, lessons, memory extraction)
+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)
+system/          # Existing-system extraction output (visual tokens, conventions)
 ```
 
+Files written into these directories during the workflow (not pre-created — they appear as their step runs):
+
+- `rd/project-scan.md` (Solo step 0.6)
+- `rd/tech-doc.md` (feature/refactor planning; required by `rd → implemented` gate)
+- `rd/bug-analysis.md` (bugfix planning; required by `rd → implemented` gate for `--type bugfix`)
+- `rd/code-review.md`, `rd/security-review.md` (required by `rd → qa-handoff` gate for feature/bugfix/refactor; security-review only for config)
+- `rd/mock-plan.md` (frontend-only mode)
+- `ui/design-draft.md` (UI step)
+- `system/existing-system.md` (Solo step 0.7; legacy projects only)
+- `qa/test-cases/<rid>.md`, `qa/test-reports/<rid>.md`, `qa/security-findings.md`, `qa/performance-findings.md` (gated per `--type`)
+
 ### Root pollution prohibition (CRITICAL)
 
 **NEVER write Peaks intermediate artifacts to the project root directory.** Specifically prohibited at root level:
@@ -99,85 +138,120 @@ Do not default to git-backed storage or automatic commits for intermediate artif
 
 ## Pre-RD project scan checklist (MANDATORY)
 
-Before handing off to `peaks-rd` for implementation, Peaks Solo MUST scan the target project and record these findings in `.peaks/<session-id>/rd/project-scan.md`. This prevents component-library misidentification, CSS framework conflicts, and build-tool mismatches.
+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.
+
+### 0. Project archetype detection (MANDATORY — run FIRST, deterministic CLI)
+
+Run the CLI; do NOT infer the archetype from prompts. Record the JSON output as `## Archetype` and `## Project mode` in `project-scan.md`. Later gates (frontend-only mode, visual system extraction, standards generation) read these fields.
+
+```bash
+peaks scan archetype --project <repo> --json
+```
+
+The command emits a stable JSON envelope with these fields you copy verbatim into `project-scan.md`:
+
+- `archetype`: `greenfield | legacy-frontend | legacy-fullstack | frontend-monorepo | unknown`
+- `confidence`: `high | medium | low`
+- `frontendOnly`: `true | false`
+- `frontendOnlyReason`: short string explaining the decision
+- `signals[]`: each signal's name, matched flag, and detail (paste under `## Archetype → Signals matched`)
+- `detected`: raw filesystem facts (package.json presence, backend frameworks, swagger paths, monorepo configs, src file count, lockfile age)
+
+If `archetype` is `unknown`, STOP and surface to the user as an open question in the TXT handoff — do NOT guess. If `confidence` is `low`, note the uncertainty in `project-scan.md` and confirm the choice with the user before proceeding.
 
-### 1. Build tool and framework detection
+The CLI is the sole source of truth for archetype and frontend-only-mode decisions. Manual heuristics in older versions of this skill are superseded by the CLI output.
 
-Identify the project's build tool and meta-framework by inspecting config files:
+### 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 (CRA, custom) |
+| `rsbuild.config.*` | Rsbuild |
+| `rspack.config.*` | Rspack |
+| `farm.config.*` | Farm |
+| `craco.config.*` | CRA + craco |
+| `webpack.config.*` | Webpack |
+| `gulpfile.*` | Gulp (legacy) |
 | `angular.json` | Angular |
+| Custom `build/` or `scripts/build.*` only | Bespoke pipeline — record as `custom` and capture entry script path |
 
-Record the detected framework and its version from `package.json`.
+If multiple build configs coexist (e.g. `webpack.config.js` + `vite.config.ts`), record ALL of them and mark `build.mixed: true`. Mixed builds are a constraint, not an error — do not silently pick one.
 
-### 2. Component library detection
-
-Identify the UI component library in use by checking `package.json` dependencies:
+### 2. Component library: check `package.json` dependencies
 
 | Package | Library |
 |---|---|
-| `antd` | Ant Design |
-| `@mui/material`, `@emotion/*` | Material UI (MUI) |
-| `@shadcn/ui`, `tailwindcss` + `radix-ui` | shadcn/ui |
-| `element-plus`, `element-ui` | Element UI/Plus |
+| `antd` (capture major version: v3/v4/v5) | Ant Design |
+| `@ant-design/pro-components`, `@ant-design/pro-*` | Ant Design Pro suite |
+| `@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 |
+| `@douyinfe/semi-ui` | Semi Design |
 | `@nextui-org/react` | NextUI |
 | `@chakra-ui/react` | Chakra UI |
-| `tdesign-react`, `tdesign-vue-next` | TDesign |
-
-**CRITICAL**: Never assume the component library. If the project uses `antd` and `@ant-design/pro-components`, do not introduce shadcn/ui components or vice versa. Adding a second component library to a project that already has one will cause style conflicts and bloated bundles.
-
-Record the detected library, version, and any design-system packages (e.g. `@ant-design/pro-components`, `@ant-design/icons`).
+| `vant` | Vant (mobile) |
+| Workspace package (`workspace:*`) or private-registry scope matching internal design system | In-house design system — record package name and entry path |
 
-### 3. CSS framework detection and conflict prevention
+**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. For antd, ALSO record the major version — v3 / v4 / v5 have incompatible APIs and tokens; mixing component code across majors is a blocker.
 
-Check `package.json` for CSS solutions and detect conflicts:
+### 3. CSS framework: check for conflicts
 
-- **TailwindCSS** (`tailwindcss` in devDependencies) + **antd**: High conflict risk. Tailwind's preflight reset overrides antd's base styles. If TailwindCSS is not already in `package.json`, do NOT add it to a project that uses a component library with its own CSS-in-JS or Less/Sass solution.
-- **CSS Modules** (`.module.css`, `.module.less`): Compatible with most component libraries.
-- **styled-components / @emotion**: Check if the component library already uses these internally (MUI uses Emotion, antd v5 uses CSS-in-JS with `@ant-design/cssinjs`). Do not add a competing CSS-in-JS solution.
-- **Less/Sass**: Umi + antd projects typically use Less. Adding TailwindCSS on top of Less requires `postcss.config.js` and may cause selector specificity wars.
+- **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.
 
-Record the CSS solution(s), any detected conflicts, and a recommendation. If a conflict is detected (e.g. TailwindCSS added to an antd project), apply the resolution decision tree before blocking:
+### 4. State management, routing, data fetching: detect from `package.json`
 
-**CSS conflict resolution (when both TailwindCSS and a component library coexist):**
+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`
 
-| Scenario | Resolution | Priority |
-|---|---|---|
-| TailwindCSS + antd already in `package.json` (project lives with both) | Do not remove either. Record as "coexisting — project already handles specificity." RD uses Tailwind for layout/spacing utilities and antd for component styling. Add `@layer` directives if Tailwind preflight breaks antd. | Non-blocking |
-| TailwindCSS present but antd styles visibly broken | Add `corePlugins: { preflight: false }` to `tailwind.config.js` or scope Tailwind with `important: '#root'`. Record the fix in project-scan. | Fix before RD |
-| Project has only antd, user wants TailwindCSS | **Block.** Propose alternatives: CSS Modules + antd's `ConfigProvider` token system, or antd's built-in utility patterns. Only proceed with TailwindCSS if user explicitly confirms after seeing the conflict warning. | Blocking |
-
-If none of the above apply and the conflict cannot be resolved automatically, flag as a blocking pre-RD issue with the specific conflict description and proposed resolution options for user decision.
+### 5. Legacy signals (legacy-frontend / legacy-fullstack only)
 
-### 4. State management, routing, and data fetching
+Grep `src/` for outdated patterns and list them as constraints in `project-scan.md` under `## Legacy constraints`. RD must preserve these patterns for new code in the same file/module unless PRD explicitly authorizes modernization.
 
-Detect and record:
-- State management: `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
+| Signal | Detection |
+|---|---|
+| Class components | `extends React.Component` / `extends Component` in `.tsx`/`.jsx` |
+| `moment` instead of dayjs/date-fns | `package.json` dep |
+| Enzyme test suite | `package.json` dep `enzyme*` |
+| redux-saga / redux-thunk | `package.json` dep |
+| HOC-heavy patterns | `withRouter`, `connect()`, `compose(` frequency in `src/` |
+| Legacy lifecycle | `componentWillMount`/`componentWillReceiveProps` occurrences |
+| jQuery / Backbone / Vue 2 | `package.json` dep |
+| Inline styles dominant | `style={{` occurrences ≥ 50 |
 
-Write the scan result to `.peaks/<session-id>/rd/project-scan.md` with these sections:
+### 6. Project-scan artifact template
 
 ```markdown
 # Project Scan: <project-name>
 **Date:** YYYY-MM-DD
 **Session:** <session-id>
 
+## Archetype
+- Type: <greenfield | legacy-frontend | legacy-fullstack | frontend-monorepo | unknown>
+- Signals matched: <bullet list of signals that drove the decision>
+
+## Project mode
+- Frontend-only: <true | false>
+- Reason: <archetype-derived | user-stated | backend-detected>
+
 ## Build tool
 - Framework: <name> <version>
 - Config file: <path>
+- Mixed builds: <true | false; list all configs if true>
 
 ## Component library
-- Library: <name> <version>
+- Library: <name> <version (major matters for antd)>
 - Design-system packages: <list>
+- In-house design system: <package name | none>
 
 ## CSS solution
 - Primary: <Less/Sass/CSS-in-JS/TailwindCSS/CSS Modules>
@@ -187,13 +261,25 @@ Write the scan result to `.peaks/<session-id>/rd/project-scan.md` with these sec
 - State: <name>
 - Routing: <name>
 - Data fetching: <name>
-```
 
-RD and UI roles read this scan before starting work. Solo must not hand off to RD without this artifact.
+## Legacy constraints
+- <bullet list of legacy signals from section 5; empty for greenfield>
+```
 
 ## 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.
+When the project has no live backend (no swagger.json, no API server), Solo must activate frontend-only mode.
+
+### Mode determination (deterministic — CLI is the source of truth)
+
+The CLI decision is authoritative. Read `frontendOnly` and `frontendOnlyReason` directly from the `peaks scan archetype --json` output and copy both into `project-scan.md` under `## Project mode`. Do NOT re-derive the decision from user phrasing.
+
+User-stated intent is **only** consulted when it conflicts with the CLI result. The two conflict cases:
+
+- **CLI says `frontendOnly=false` but the user says "前端项目 / 没有后端 / 先 mock 数据"**: STOP and `AskUserQuestion` to confirm whether to override the scan (the repo probably contains a backend folder the user wants to ignore). Record the override decision and reason in `project-scan.md`.
+- **CLI says `frontendOnly=true` but the user says "需要做后端 / 加 API"**: STOP and `AskUserQuestion` to confirm whether the request actually targets the missing backend (the user may be confused about repo scope, or there is a separate backend repo Solo should switch to).
+
+When there is no conflict, do not ask — the CLI value wins and the workflow proceeds.
 
 ### Mock data strategy selection
 
@@ -206,6 +292,9 @@ Solo records the chosen mock strategy in `.peaks/<session-id>/rd/tech-doc.md` un
 | `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 |
+| Existing `src/services/*` but no fetcher abstraction | Inline mock inside the service file; preserve the function signature | Keeps existing call-sites unchanged |
+| Mixed data-fetching styles (e.g. react-query + raw fetch in legacy files) | Match the style of the most recently added code in the same module | Avoid introducing a third style |
+| Cannot decide from scan alone | STOP and `AskUserQuestion` | Asking once beats picking differently on every run |
 
 **Mock data rules:**
 
@@ -213,34 +302,19 @@ Solo records the chosen mock strategy in `.peaks/<session-id>/rd/tech-doc.md` un
 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`.
+5. Before producing any mock file, register the plan in `.peaks/<session-id>/rd/mock-plan.md` with: chosen strategy (from the table above), planned file paths, and a one-line rationale per file. This file is the source of truth for mock locations across runs — RD must read it before writing code, QA must read it before writing test cases.
 
 ### API contract placeholder pattern
 
-When no swagger.json exists, RD defines API contracts as TypeScript interfaces in a dedicated location:
+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
-    <feature>-service.ts        ← Service functions (mock now, real later)
-  mock/
-    <feature>-mock.ts           ← Mock data satisfying the interfaces
+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
 ```
 
-Each service function follows this migration-ready pattern:
-
-```typescript
-// src/services/knowledge-service.ts
-import type { KnowledgeListResponse, KnowledgeCreateRequest } from './types/knowledge-api.types';
-// MOCK: Replace mock import with real HTTP call when swagger.json is available
-import { mockKnowledgeList } from '@/mock/knowledge-mock';
-
-export async function fetchKnowledgeList(params: KnowledgeListParams): Promise<KnowledgeListResponse> {
-  // TODO: Replace with real API call — POST /api/v1/knowledge/list
-  return mockKnowledgeList;
-}
-```
+Each service function returns a typed mock response marked with `// MOCK: Replace with real API call when swagger.json is available`.
 
 ### Mock-to-real migration path
 
@@ -264,24 +338,45 @@ When the PRD source is a Feishu/Lark document that requires authentication:
 
 Never silently fall back to unauthenticated `fetch` or `WebFetch` for authenticated documents.
 
+## Request type classification (MANDATORY before `peaks request init`)
+
+Before initializing any role artifact, classify the request into exactly one of six types. The choice drives RD/QA gate strictness (see "Mandatory RD QA repair loop"). Pick the **primary intent** — if a request could fit two types, the higher-strictness one wins.
+
+| `--type` | Pick this when the PRD says... | Pick something else when... |
+|---|---|---|
+| `feature` | Add new capability, new page/component/route/API path, new user-facing behavior. Includes "extend X to support Y" when Y is a new code path. | The PRD is fixing an existing broken behavior → `bugfix`. The PRD is reshaping existing code without changing user-visible behavior → `refactor`. |
+| `bugfix` | Fix a specific broken behavior; PRD includes reproduction steps or a defect description; success = "the broken thing now works as it was supposed to". | The "fix" actually adds new capability (validation that didn't exist, a missing field) → `feature`. The "fix" is purely cosmetic and has zero risk → still `bugfix`; do NOT downgrade to `chore`. |
+| `refactor` | Restructure code without changing user-visible behavior. Examples: rename modules, extract shared utilities, migrate a library version with no API surface change, split a monolithic file. PRD mentions coverage targets or "no behavior change". | The refactor incidentally adds or changes user-visible behavior → split into `refactor` + `feature` or pick `feature`. The change is one-line formatting → `chore`. |
+| `config` | Modify config / infrastructure files only: `tsconfig.json`, `eslint`, CI YAML, `package.json` scripts, env defaults, CORS/CSP rules, build config, Docker, deployment manifests. No application source-code changes. | The config change is paired with code changes that consume the new config → `feature` or `refactor` (whichever the code change is). |
+| `docs` | Modify only `*.md` / docs site / inline JSDoc / README. No `.ts` / `.tsx` / `.js` / `.css` / config-file changes. | Any source code change is included → use the type matching the code change. Adding a code example to docs that requires the example to compile → still `docs` if the example is illustrative only. |
+| `chore` | Pure mechanical hygiene: formatter run, lint fix, dependency version bump with no API surface change, dead-code removal of unused files identified by tooling. | The bump changes API behavior or requires consumer migration → `refactor` (or `feature` if it adds capability). Any logic edit → `bugfix` or `refactor`. |
+
+**Self-check before locking the type**: read the PRD scope and answer "what is the smallest gate set that still protects users from regression?" — that is the right type. Picking `docs` or `chore` to skip gates when source code is actually changing is a workflow violation and the SC phase will reject it.
+
+For ambiguous cases (e.g. "improve login flow"), ask the user to clarify before initializing. The cost of one `AskUserQuestion` round is much lower than running the wrong gate matrix for the whole workflow.
+
 When Peaks Solo coordinates development in a code repository, keep this order explicit:
 
-0. workspace initialization (`.peaks/<session-id>/` created, directory structure verified);
-1. project scan (component library, CSS framework, build tool detected and recorded);
-2. standards preflight;
-3. PRD scope and spec artifacts — confirmed by user;
-4. **Swarm parallel phase** — after PRD confirmed, launch UI, RD(planning), QA(test-cases) simultaneously:
-   4a. UI design draft and visual direction (MANDATORY when request is frontend/user-visible);
-   4b. RD tech-doc (architecture planning, component tree, data flow, API contracts);
-   4c. QA test-case generation (unit, integration, UI-regression test cases);
-5. OpenSpec change artifacts for non-trivial work when `openspec/` already exists or the user approves adding it;
-6. RD implementation slices (consumes UI design-draft + RD tech-doc + QA test-cases);
-7. unit tests for new/changed behavior, with focused new-code coverage accepted for legacy low-coverage repos;
-8. 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;
-9. RD post-check dry-run;
-10. QA validation (auto-proceed from RD), executing test cases + API checks + Playwright MCP headed browser E2E for frontend;
-11. QA security and performance checks plus test report;
-12. 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** — archetype, component library, CSS framework, build tool, state management, routing, data fetching, legacy signals detected and recorded to `.peaks/<session-id>/rd/project-scan.md`;
+0.7. **Existing-system extraction** (MANDATORY when archetype ∈ {legacy-frontend, legacy-fullstack, frontend-monorepo}; SKIP for greenfield) — extract visual tokens and code conventions from the live codebase to `.peaks/<session-id>/system/existing-system.md`. The path lives under `system/` (not `ui/`) because the file also records non-UI conventions (service-layer signatures, hooks, naming) that backend-only or legacy-fullstack work consumes. See `references/existing-system-extraction.md`. UI design-draft and RD implementation MUST treat the extracted tokens and conventions as hard constraints;
+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; skipped for `--type docs|chore|config` or pure-backend requests);
+   3b. RD planning artifact — `rd/tech-doc.md` for feature/refactor, `rd/bug-analysis.md` for bugfix, skipped for docs/chore/config;
+   3c. QA test-case generation (skipped for docs/chore — no acceptance surface to validate);
+4. **RD implementation** — consumes the type-appropriate inputs: project-scan + standards + (if UI involved) UI design-draft + RD planning artifact + QA test-cases. Includes unit tests for new/changed behavior (TDD) unless `--type` is docs/chore;
+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)
 
@@ -292,32 +387,76 @@ You cannot declare a phase complete from memory. Each gate below is a `ls` comma
 ls .peaks/<id>/rd/project-scan.md
 # Expected output: .peaks/<id>/rd/project-scan.md
 # "No such file" → STOP, run project scan first
+# File present but missing `## Archetype` or `## Project mode` sections → INCOMPLETE, rerun scan
+```
+
+**Gate A.5 — Existing-system extraction (legacy projects only):**
+```bash
+# If project-scan.md `## Archetype` is greenfield → skip this gate
+# Otherwise:
+ls .peaks/<id>/system/existing-system.md
+# "No such file" → STOP, run existing-system extraction
+# (see references/existing-system-extraction.md)
 ```
 
 **Gate B — After swarm convergence (UI + RD planning + QA test-cases):**
+
+Gate B has two sub-checks: a HARD gate (blocks progression) and an INFORMATIONAL check (records degradation but does not block).
+
 ```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 → BLOCKED
-# Pure backend: ui/design-draft.md absent → state skip reason, proceed
+# B.hard — REQUIRED before continuing to RD implementation.
+#          Missing any of these → STOP, return to the role that owns the file.
+
+# Always required (every type):
+ls .peaks/<id>/prd/requests/<rid>.md
+
+# Type-specific RD planning artifact:
+#   feature / refactor → ls .peaks/<id>/rd/tech-doc.md
+#   bugfix             → ls .peaks/<id>/rd/bug-analysis.md
+#   config / docs / chore → (no RD planning artifact required)
+
+# QA test-cases (skipped for docs/chore):
+ls .peaks/<id>/qa/test-cases/<rid>.md
+```
+
+```bash
+# B.info — NON-BLOCKING. Record degradation in TXT, then proceed.
+ls .peaks/<id>/ui/design-draft.md 2>&1
+# "No such file" + request affects user-visible UI → swarm degradation rule 1 fires:
+#   note "ui-design-missing" in TXT, RD continues with PRD visual descriptions.
+# "No such file" + pure backend / docs / chore / config → state skip reason in TXT, proceed.
 ```
 
 **Gate C — After RD implementation (before QA handoff):**
+
+The CLI gate (`peaks request transition --state qa-handoff`) is the authoritative check; running this `ls` first lets you produce missing files before the CLI rejects the transition.
+
 ```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
+# Always required
+ls .peaks/<id>/rd/requests/<rid>.md
+
+# Type-specific RD evidence (must match the type recorded in the artifact body)
+#   feature / refactor → ls rd/tech-doc.md rd/code-review.md rd/security-review.md
+#   bugfix             → ls rd/bug-analysis.md rd/code-review.md rd/security-review.md
+#   config             → ls rd/security-review.md
+#   docs / chore       → (no extra evidence required)
+# Missing any required file → DO NOT attempt the qa-handoff transition; CLI will reject with PREREQUISITES_MISSING.
 ```
 
 **Gate D — After QA validation:**
+
+The CLI gate at `qa:verdict-issued` is the authoritative check; this `ls` lets you produce missing evidence before the CLI rejects the transition.
+
 ```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
+# Always required
+ls .peaks/<id>/qa/requests/<rid>.md
+
+# Type-specific QA evidence
+#   feature / refactor → ls qa/test-cases/<rid>.md qa/test-reports/<rid>.md qa/security-findings.md qa/performance-findings.md
+#   bugfix             → ls qa/test-cases/<rid>.md qa/test-reports/<rid>.md qa/security-findings.md
+#   config             → ls qa/security-findings.md
+#   docs / chore       → (no QA evidence files required)
+# Missing required file → QA incomplete; do not transition to verdict-issued.
 ```
 
 **Gate E — Before declaring workflow complete:**
@@ -345,189 +484,162 @@ find . -maxdepth 1 -name "*.png" -o -name "*.jpg" -o -name "qa-*.js" -o -name "m
 ```
 
 
-## Swarm parallel phase (PRD确认后并行蜂群)
+## Swarm parallel phase
 
-PRD 确认后，UI 设计稿、RD 技术文档、QA 测试用例三者都是从 PRD 派生出来的独立产物，互不依赖。Peaks Solo 必须并行启动这三个角色，而不是串行执行。
+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.
 
-### 并行依赖分析
+### Degradation when swarm roles fail
 
-```
-PRD (confirmed-by-user)
- │
- ├── peaks-ui  → design-draft.md   独立：只需要 PRD 知道要设计哪些页面/组件
- ├── peaks-rd  → tech-doc.md       独立：只需要 PRD 知道架构范围和数据流
- └── peaks-qa  → test-cases/*.md   独立：只需要 PRD 的验收标准来写测试用例
-                    │
-                    ↓ 三个都完成后汇合
-              peaks-rd (implementation)
-                    读取 design-draft.md + tech-doc.md + test-cases/*.md
-                    开始编码实现
-```
-
-### 为什么可以并行
-
-- **UI 不依赖 RD 技术文档**：设计稿描述"长什么样"，技术文档描述"怎么建"，两者从同一个 PRD 出发独立产出
-- **RD 技术文档不依赖 UI 设计稿**：架构决策（组件树、数据流、API 契约）可以从 PRD 的功能描述直接推导，不需要等到视觉设计完成。RD 实现阶段才需要读设计稿
-- **QA 测试用例不依赖实现代码**：TDD 原则——测试用例应该在代码之前写好。QA 根据 PRD 验收标准写用例，不依赖 RD 的输出
-
-### 并行执行规则
-
-1. PRD 状态到达 `confirmed-by-user` 后，Solo 同时启动 peaks-ui、peaks-rd(planning)、peaks-qa(test-cases)
-2. 如果在 full-auto 模式下，使用并行 Agent 调用来执行（一次发送多个 Agent tool call）
-3. 三个角色各自写入独立产物，互不冲突
-4. Solo 等待三个角色全部完成后，再进入 RD 实现阶段
-5. RD 实现阶段读取所有三个产物，综合实施
-
-### 产物汇合检查
+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.
 
-在进入 RD 实现阶段前，Solo 确认以下产物存在且非 draft：
-
-```
-.peaks/<session-id>/ui/design-draft.md          ← peaks-ui 产出
-.peaks/<session-id>/rd/tech-doc.md              ← peaks-rd 规划产出
-.peaks/<session-id>/qa/test-cases/<id>.md       ← peaks-qa 测试用例产出
-```
-
-缺任何一个都不能进入实现阶段。
+**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)
 
-当 swarm 并行阶段任一角色失败或超时时，Solo 不得无限等待或静默跳过：
+> **CLI gate enforcement**: `peaks request transition` now refuses to move RD/QA to gated states when required artifacts are missing. The required files depend on `--type` chosen at `peaks request init` (default `feature`):
+>
+> - `feature` / `refactor`: full gates (tech-doc, code-review, security-review, test-cases, test-report, security-findings, performance-findings)
+> - `bugfix`: lighter planning (`bug-analysis.md` instead of `tech-doc.md`); still requires code-review + security-review + regression test-cases + security-findings; performance-findings optional unless the bug is performance-related
+> - `config`: only security-review (RD) and security-findings (QA)
+> - `docs` / `chore`: no gates
+>
+> When PRD lands, classify the request type before running `peaks request init` for every role — pass `--type <type>` so the artifact records it and downstream transitions enforce the right gates. Misclassifying a feature as `docs` to skip gates is a workflow violation. If a transition fails with `code: PREREQUISITES_MISSING`, the response lists every missing path — produce them, then re-transition. For one-off exceptions, the escape hatch `--allow-incomplete --reason "<text>"` records the bypass in the artifact transition note.
 
-1. **UI 失败（design-draft 缺失）**: RD 实现阶段使用 PRD 的视觉描述作为参考继续编码，UI 失败不阻塞 RD 进入实现，但阻塞最终 QA 的视觉回归检查。Solo 必须在 TXT 手记中标注 "ui-design-missing" 风险
-2. **RD(planning) 失败（tech-doc 缺失）**: 不阻塞 RD 实现阶段，RD 可以在实现过程中内联补充技术决策。tech-doc 缺失必须在 TXT 手记中标注
-3. **QA(test-cases) 失败（test-cases 缺失）**: 不阻塞 RD 实现，但 QA 必须在 RD 完成实现后补充测试用例才能进入验证阶段。阻塞 QA verdict 直到测试用例补齐
-4. **两个或以上角色失败**: 回退到串行降级模式——按 PRD→RD(含内联设计+规划)→QA(含测试用例+验证) 的顺序逐步执行，跳过 UI 阶段。TXT 手记标注 "swarm-degraded-to-sequential"
-5. **全部三个角色失败**: 暂停工作流，向用户报告失败原因（大概率是 PRD 信息不足或 CLI 环境问题），请求用户确认是否继续
+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.
 
-Solo 在发起并行调用后，等待所有角色返回结果。如果某个 Agent 返回错误或超时，按上述规则降级处理，不阻塞整个工作流。
+**How Solo invokes another role skill (mechanism, not metaphor):**
 
-## Mandatory RD QA repair loop (AUTO-PROCEED)
+Solo is itself a skill running in the current session. To "invoke peaks-rd" or "peaks-qa", Solo MUST use the `Skill` tool with the role's name (e.g. `Skill(skill="peaks-rd")` or `Skill(skill="peaks-qa")`), passing the `<request-id>` and `<session-id>` as arguments so the role reads the same artifacts Solo wrote. Do NOT re-implement the role's logic inline in Solo. Do NOT use the `Agent` tool with a sub-agent — role skills are skills, not agents. After the role skill returns, Solo reads the artifacts the role wrote (via the request artifact path or `peaks request show <rid> --role <role>`) to decide the next step.
 
-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 the `full-auto` profile, when RD transitions to `qa-handoff`, Solo immediately invokes `peaks-qa` via the Skill tool 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 `--type` is `docs` or `chore` (no acceptance surface).
 
-**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.
 
-**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).
+**How Solo routes QA findings back to RD (mechanism, not metaphor):**
 
-A QA report with any failing, blocked, missing, or unverified acceptance item is not a pass.
+When `peaks-qa` returns `verdict=return-to-rd`, Solo does NOT manually rewrite RD artifacts. Instead it follows this exact sequence:
 
-When QA reports problems:
+1. Read the QA verdict and findings via `peaks request show <rid> --role qa --project <repo> --json`. The findings live in the QA artifact body (failing acceptance items, evidence paths, severity).
+2. Transition the RD artifact back from `qa-handoff` to a working state and record the QA verdict in the transition note:
+   ```bash
+   peaks request transition <rid> --role rd --state spec-locked \
+     --reason "QA return-to-rd cycle <N>: <one-line summary of failing items; full findings in qa/test-reports/<rid>.md>" \
+     --project <repo> --json
+   ```
+   `spec-locked` is the canonical "needs more RD work" state. The reason is mandatory in repair cycles so the artifact history shows the loop.
+3. Invoke `peaks-rd` via the Skill tool. Pass the request id and the path to the QA findings; peaks-rd reads `qa/test-reports/<rid>.md` and the QA `requests/<rid>.md` for the verdict.
+4. peaks-rd fixes the reported issues only (red-line scope: do not modify unrelated surfaces), regenerates code-review and security-review evidence if changes touched reviewed surfaces, then transitions `rd → implemented → qa-handoff` again.
+5. Solo invokes `peaks-qa` again with the same `<request-id>` (the same Skill call as before). QA re-runs gates against the new diff.
+6. Repeat steps 1-5 until QA returns `verdict=pass`, or the cap below fires.
 
-1. send the QA findings, evidence paths, and failing acceptance items back to `peaks-rd`;
-2. require RD to repair only the reported issues or explicitly mark a blocker;
-3. run the relevant RD checks again;
-4. run `peaks-qa` again on the repaired output;
-5. repeat until QA reports all acceptance items passed, or emit a blocked TXT handoff.
+**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.
 
-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.
+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 `full-auto` profile. `assisted` and `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 + 0.7 Existing-system extraction
 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
-
-# 0.5 workspace initialization — MANDATORY before any artifact write
+peaks project dashboard --project <repo> --json
+peaks skill runbook peaks-solo --json
 peaks workspace init --project <repo> --session-id <YYYY-MM-DD-<slug>> --json
-
-# 0.6 project scan — MANDATORY before RD handoff
-# detect: build tool, component library, CSS framework, state management, routing, data fetching
-# write result to .peaks/<session-id>/rd/project-scan.md
-
-# 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 Playwright MCP per peaks-solo/references/browser-workflow.md)
-# write artifact to .peaks/<session-id>/prd/requests/<request-id>.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. Swarm parallel phase — launch UI, RD(planning), QA(test-cases) simultaneously
-# After PRD confirmed, all three can work independently from the same PRD.
-# Use parallel Agent calls in full-auto mode.
-
-# 2a. peaks-ui (MANDATORY for frontend, skip only for pure backend)
-peaks request init --role ui --id <request-id> --project <repo> --apply --json
-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
-# output: .peaks/<session-id>/ui/design-draft.md
-
-# 2b. peaks-rd tech-doc (architecture planning — NOT implementation yet)
-peaks request init --role rd --id <request-id> --project <repo> --apply --json
-peaks request transition <request-id> --role rd --state spec-locked --project <repo> --json
-# output: .peaks/<session-id>/rd/tech-doc.md
-# scope: architecture decisions, component tree, data flow, API contracts, dependencies
-
-# 2c. peaks-qa test-case generation (before implementation — TDD)
-peaks request init --role qa --id <request-id> --project <repo> --apply --json
-# output: .peaks/<session-id>/qa/test-cases/<request-id>.md
-# scope: unit test cases, integration test cases, UI regression test cases
-
-# === Swarm convergence check ===
-# All three artifacts must be present and non-draft before RD implementation starts:
-#   .peaks/<session-id>/ui/design-draft.md
-#   .peaks/<session-id>/rd/tech-doc.md
-#   .peaks/<session-id>/qa/test-cases/<request-id>.md
-
-# 3. RD implementation phase — consumes all three swarm outputs
-# (Solo executes peaks-rd Default runbook here: standards preflight + project-scan consumption +
-#  openspec entry gate + implementation + openspec exit gate)
-# reads: design-draft.md + tech-doc.md + test-cases/<id>.md
-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 validation phase — AUTO-PROCEED from RD implementation
-# (Solo executes peaks-qa Default runbook here: execute test cases + test report +
-#  Playwright MCP frontend validation when frontend is in scope + security/perf checks)
-# writes to .peaks/<session-id>/qa/test-reports/<request-id>.md
-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 scan archetype --project <repo> --json
+# → copy archetype, frontendOnly, signals into .peaks/<session-id>/rd/project-scan.md (Gate A)
+# → if archetype != greenfield AND archetype != unknown:
+peaks scan existing-system --project <repo> --json
+# → copy tokens, sources, conventions, inconsistencies into .peaks/<session-id>/system/existing-system.md (Gate A.5)
+
+# 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)
+# Classify the request type from the PRD: feature | bugfix | refactor | docs | config | chore
+# This drives RD/QA gate strictness — see "Mandatory RD QA repair loop" for the matrix.
+peaks request init --role prd --id <rid> --project <repo> --apply --type <type> --json
+# Cross-verify the chosen --type against the current git diff (only meaningful if RD has started writing code;
+# safe to run early too, just expect "no changes" rationale until code lands).
+peaks scan request-type-sanity --project <repo> --type <type> --json
+# → consistent=false → re-classify before continuing. consistent=true → proceed.
+# Lint the PRD artifact before transitioning out of draft.
+peaks request lint <rid> --role prd --project <repo> --json
+# → ok=false → fill in <placeholders>, then re-run.
+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
+# Pass the same --type chosen for PRD so RD/QA gate matrix lines up.
+peaks request init --role ui --id <rid> --project <repo> --apply --type <type> --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 --type <type> --json
+peaks request transition <rid> --role rd --state spec-locked --project <repo> --json
+peaks request init --role qa --id <rid> --project <repo> --apply --type <type> --json
+# → Gate B convergence check. Assisted/Strict: [CONFIRM]
+
+# 4. RD planning artifact (the file required by the prerequisite gate)
+#    feature / refactor → write .peaks/<id>/rd/tech-doc.md
+#    bugfix             → write .peaks/<id>/rd/bug-analysis.md
+#    config             → no planning artifact required at this state
+#    docs / chore       → no planning artifact required
+peaks request transition <rid> --role rd --state implemented --project <repo> --json
+
+# 5. Code review + security review BEFORE qa-handoff transition.
+#    Produce the evidence files the CLI gate enforces:
+#      - .peaks/<id>/rd/code-review.md     (CRITICAL/HIGH findings + fixes; required for feature/bugfix/refactor)
+#      - .peaks/<id>/rd/security-review.md (required for feature/bugfix/refactor/config)
+#    Then transition. If --type is docs/chore the gate is empty and the transition is unguarded.
+peaks request transition <rid> --role rd --state qa-handoff --project <repo> --json
+
+# 6. QA validation (AUTO-PROCEED from RD in full-auto)
+#    Before each QA transition, produce the evidence files the CLI gate enforces:
+#      Before qa:running        → .peaks/<id>/qa/test-cases/<rid>.md
+peaks request transition <rid> --role qa --state running --project <repo> --json
+#      Before qa:verdict-issued → .peaks/<id>/qa/test-reports/<rid>.md
+#                                 + .peaks/<id>/qa/security-findings.md
+#                                 + .peaks/<id>/qa/performance-findings.md (feature/refactor only)
+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.
+#    Before invoking peaks-rd again, check the cycle count so you don't blow past the cap silently:
+peaks request repair-status <rid> --project <repo> --json
+# → atCap=true → STOP and emit a blocked TXT handoff. Do NOT enter another cycle.
+# → remaining > 0 → safe to continue. The next transition's --reason must include "QA return-to-rd cycle N: ..."
+#                   so this command keeps counting accurately.
+# After RD finishes the repair, re-check that the diff is still consistent with the declared --type:
+peaks scan request-type-sanity --project <repo> --type <type> --json
+# → consistent=false → RD scope-creeped during repair; review before re-handoff.
+
+# 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
 
@@ -540,6 +652,8 @@ Use `standards init` for first-time creation and `standards update` for existing
 
 **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.
 
+**Legacy projects additionally** — when archetype ∈ {legacy-frontend, legacy-fullstack, frontend-monorepo}, the `CLAUDE.md` Conventions section MUST extract concrete naming, directory, service-layer, and hooks conventions from `.peaks/<id>/system/existing-system.md` and record them as hard constraints for new code. It must also list the `## Legacy constraints` from `project-scan.md` (class components, moment, enzyme, etc.) and instruct that new code in the same module preserves those patterns unless PRD explicitly authorizes modernization. A `CLAUDE.md` for a legacy project that contains only generic rule pointers without naming the actual conventions is a blocking violation — regenerate it.
+
 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:
@@ -567,6 +681,18 @@ It must enforce the shared refactor red lines:
 6. require 100% acceptance for each slice;
 7. require code changes and sanitized intermediate artifacts to be traceable in local `.peaks/<session-id>/` storage before the next slice; commit or sync sanitized artifacts only when explicitly authorized.
 
+## Quality-gate commands (CLI cheat sheet)
+
+These commands harden the workflow against silent skips. Use them in the runbook at the points indicated; they all support `--json` and `--session-id`.
+
+| Command | Purpose | When to run | Non-zero exit when |
+|---|---|---|---|
+| `peaks request lint <rid> --role <role> --project <path>` | Scan artifact body for unfilled `<placeholder>`, bare `- ...` bullets, TBD/TODO markers | Before every transition out of `draft` / before role handoff | Any `error`-severity finding (unfilled placeholder, bare-dot bullet) |
+| `peaks request repair-status <rid> --project <path>` | Count RD↔QA repair cycles from `--reason` transition notes ("QA cycle N: ...") | Before every RD repair iteration in step 7 | Cycle count reached the 3-cycle cap |
+| `peaks scan request-type-sanity --project <path> --type <type>` | Cross-verify declared `--type` against the actual `git diff` file mix (catches "feature mis-declared as docs" workflow violations) | After PRD type lock-in AND after each RD repair iteration | Declared type disagrees with the file mix |
+
+Together with `peaks request transition` (which already CLI-enforces per-type artifact prerequisites), these four commands form the runtime quality net. SKILL.md prose is descriptive; the CLI is what physically blocks bad workflows.
+
 ## Completion handoff
 
 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.
@@ -579,8 +705,8 @@ Use Peaks TXT for the compact handoff capsule: mode, validated decisions, artifa
 
 **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.
 
-**OpenSpec lifecycle**: `render → validate → show → to-rd → validate → archive`. Validation at RD entry (before slicing) and QA exit (before archive); both must be `data.valid === true`.
+**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.
 
 **MCP lifecycle**: `list → plan → apply --yes → call → rollback`. `apply` backs up settings and refuses non-peaks entries unless `--claim` is passed.
 
-Detailed rules: `references/external-skill-invocation.md`, `references/openspec-mcp-workflow.md`, `references/workflow.md`.
+Detailed rules: `references/external-skill-invocation.md`, `references/openspec-mcp-workflow.md`, `references/workflow.md`, `references/existing-system-extraction.md`.