peaks-cli 1.0.17 → 1.0.18

package/skills/peaks-solo/SKILL.md

@@ -20,15 +20,17 @@ When the user invokes Peaks Solo without explicitly naming an execution profile,
 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:
+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 | `solo` |
+| 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
@@ -92,21 +94,28 @@ 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
+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)
+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)
 ```
 
-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
+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)
 
@@ -131,6 +140,27 @@ Do not default to git-backed storage or automatic commits for intermediate artif
 
 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.
+
+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.
+
 ### 1. Build tool: inspect config files for the framework
 
 | Config file | Framework |
@@ -138,23 +168,35 @@ Before handing off to `peaks-rd`, scan the project and record findings to `.peak
 | `.umirc.ts`, `config/config.ts` | Umi (Ant Design Pro) |
 | `next.config.*` | Next.js |
 | `vite.config.*` | Vite |
+| `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 |
+
+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: check `package.json` dependencies
 
 | Package | Library |
 |---|---|
-| `antd` | Ant Design |
+| `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 |
+| `vant` | Vant (mobile) |
+| Workspace package (`workspace:*`) or private-registry scope matching internal design system | In-house design system — record package name and entry path |
 
-**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.
+**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.
 
 ### 3. CSS framework: check for conflicts
 
@@ -171,20 +213,45 @@ 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
+### 5. Legacy signals (legacy-frontend / legacy-fullstack only)
+
+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.
+
+| 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 |
+
+### 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>
@@ -194,11 +261,25 @@ Data fetching: `@tanstack/react-query`, `swr`, `ahooks` (`useRequest`), `umi-req
 - State: <name>
 - Routing: <name>
 - Data fetching: <name>
+
+## 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
 
@@ -211,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:**
 
@@ -218,6 +302,7 @@ 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
 
@@ -253,20 +338,38 @@ 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. **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`;
+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);
-   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);
+   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;
@@ -284,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 → 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
+# 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:**
@@ -353,19 +500,41 @@ After PRD reaches `confirmed-by-user`, Solo launches peaks-ui, peaks-rd(planning
 
 ## Mandatory RD QA repair loop (AUTO-PROCEED)
 
+> **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.
+
 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).
+**How Solo invokes another role skill (mechanism, not metaphor):**
+
+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.
+
+**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).
 
 A QA report with any failing, blocked, missing, or unverified acceptance item is not a pass.
 
-When QA reports problems:
+**How Solo routes QA findings back to RD (mechanism, not metaphor):**
+
+When `peaks-qa` returns `verdict=return-to-rd`, Solo does NOT manually rewrite RD artifacts. Instead it follows this exact sequence:
 
-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.
+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.
 
 **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.
 
@@ -375,46 +544,81 @@ In full-auto mode, treat the RD↔QA repair loop as a built-in controller object
 
 > **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.
+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 + 0.5 Workspace + 0.6 Project scan
+# 0. Snapshot + 0.5 Workspace + 0.6 Project scan + 0.7 Existing-system extraction
 peaks doctor --json
 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)
+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)
-peaks request init --role prd --id <rid> --project <repo> --apply --json
+# 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
-peaks request init --role ui --id <rid> --project <repo> --apply --json
+# 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 --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 --json
+peaks request init --role qa --id <rid> --project <repo> --apply --type <type> --json
 # → Gate B convergence check. Assisted/Strict: [CONFIRM]
 
-# 4. RD implementation (consumes design-draft + tech-doc + test-cases + project-scan)
+# 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
-peaks request transition <rid> --role rd --state qa-handoff --project <repo> --json
 
-# 5. Code review + security review (fix CRITICAL/HIGH before proceeding)
+# 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
+# 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
@@ -448,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:
@@ -475,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.
@@ -491,4 +709,4 @@ Use Peaks TXT for the compact handoff capsule: mode, validated decisions, artifa
 
 **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`.

package/skills/peaks-solo/references/existing-system-extraction.md

@@ -0,0 +1,78 @@
+# Existing visual & convention system extraction
+
+Run this step when `project-scan.md` archetype is `legacy-frontend`, `legacy-fullstack`, or `frontend-monorepo`. Skip for `greenfield` and `unknown`.
+
+Output: `.peaks/<session-id>/system/existing-system.md`. The path lives under `system/` (not `ui/`) because the file records both UI tokens AND code conventions (service-layer signatures, hooks, naming) that backend-only or legacy-fullstack work consumes. UI design-draft and RD implementation MUST read this file and treat extracted tokens/conventions as hard constraints. New tokens or conventions may only be introduced when PRD explicitly authorizes them.
+
+## Step 1 — Run the CLI (deterministic, source of truth)
+
+```bash
+peaks scan existing-system --project <repo> --json
+```
+
+The CLI emits stable JSON containing:
+
+- `scanned`: `true | false` (skipped for greenfield / unknown archetypes; copy `scanSkippedReason` if false)
+- `visualTokens`:
+  - `colors[]`, `spacing[]`, `typography[]`, `radii[]` — each entry is `{ name, value, source }` parsed deterministically from Less/Sass variables, CSS variables, and `tailwind.config.*` color blocks
+  - `sources[]` — every theme/style file the parser actually read (path + kind)
+- `conventions`:
+  - `componentNaming`: `PascalCase | kebab-case | mixed | unknown` (decided from real file names under the component directory)
+  - `componentDir`, `serviceDir`, `hookDir` — first matching path found
+  - `samples[]` — up to 5 most-recently-modified files per kind
+- `inconsistencies[]` — token names that have different values across sources
+
+Copy these fields VERBATIM into `existing-system.md`. Do not re-classify tokens; do not invent additional samples.
+
+## Step 2 — Render the markdown
+
+Use the template below. Every value must come from the CLI JSON; leave a section as `- (none detected)` when the CLI returned an empty array.
+
+```markdown
+# Existing visual & convention system
+**Project:** <name>
+**Date:** YYYY-MM-DD
+**CLI command:** peaks scan existing-system --project <repo> --json
+**Source files inspected:** <paste visualTokens.sources[*].path>
+
+## Color tokens
+<paste visualTokens.colors as "- {name}: {value} (source: {source})">
+
+## Typography
+<paste visualTokens.typography>
+
+## Spacing
+<paste visualTokens.spacing>
+
+## Radius
+<paste visualTokens.radii>
+
+## Component conventions
+- Naming: <conventions.componentNaming>
+- Directory: <conventions.componentDir>
+- Sample files: <conventions.samples filtered by kind=component>
+
+## Service layer convention
+- Directory: <conventions.serviceDir>
+- Sample files: <conventions.samples filtered by kind=service>
+
+## Hooks convention
+- Directory: <conventions.hookDir>
+- Sample files: <conventions.samples filtered by kind=hook>
+
+## Detected inconsistencies
+<paste inconsistencies[*] verbatim; if empty, write "- (none)">
+```
+
+## Hard rules for downstream consumers
+
+- **UI design-draft**: every color, font, radius, spacing value used in the draft MUST come from `visualTokens.*` above. New values require an explicit `## New tokens (requested)` section with PRD justification.
+- **RD implementation**: new components must match `conventions.componentNaming` and live under `conventions.componentDir`. Service and hook code must match the recorded directory.
+- **QA**: regression checks must verify that no new color/spacing values escaped the recorded token set; inconsistencies from the CLI become QA acceptance items (resolve or explicitly accept).
+
+## When the CLI returns empty results
+
+If `scanned=true` but all token arrays are empty AND `conventions.componentDir` is null, the project has no detectable token system or component convention. Record this verbatim in `existing-system.md` under `## Detected inconsistencies → no theme system; values are hard-coded across files; no canonical component dir`. Surface it in the TXT handoff as a known risk. Do NOT invent a token system.
+
+When `scanned=false` (archetype = greenfield or unknown), do not write `existing-system.md` at all — the greenfield path applies.
+