peaks-cli 1.0.14 → 1.0.16

package/skills/peaks-solo/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: peaks-solo
-description: Full-auto orchestration facade for the Peaks skill family. Use when the user asks Peaks to handle a project workflow end-to-end, especially refactoring via `peaks-solo refactor`, coordinating peaks-prd, peaks-rd, peaks-qa, peaks-sc, and peaks-txt while preserving user confirmation gates.
+description: Full-auto orchestration facade for the Peaks skill family. Use when the user asks Peaks to handle a project workflow end-to-end (端到端/全流程/需求开发), especially from a product document (产品文档/PRD/飞书文档/Feishu doc) through implementation and validation. Coordinates peaks-prd, peaks-rd, peaks-ui, peaks-qa, peaks-sc, and peaks-txt while preserving user confirmation gates. Triggers on `/peaks-solo`, "peaks solo", "全流程开发", "端到端迭代", "根据产品文档开发", "从需求到上线".
 ---
 
 # Peaks Solo
@@ -9,6 +9,18 @@ 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)
+
+Before any analysis, response, or tool call, immediately run:
+
+```bash
+peaks skill presence:set peaks-solo --mode <mode> --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.
+
+Update with `peaks skill presence:set peaks-solo --mode <mode> --gate <gate>` when gates change. When the workflow ends, run `peaks skill presence:clear`.
+
 ## Boundaries
 
 Peaks Solo may:
@@ -33,45 +45,372 @@ Use the Peaks CLI for runtime side effects.
 
 ## GStack integration
 
-Use gstack as a concrete orchestration reference for the full `Think → Plan → Build → Review → Test → Ship → Reflect` loop:
+Map gstack `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.
+
+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`.
+
+## Local intermediate artifact workspace (MANDATORY)
+
+### Workspace initialization gate
+
+Before ANY role handoff or artifact write, Peaks Solo MUST create the workspace. The session-id uses the format `YYYY-MM-DD-<kebab-slug>` where `<kebab-slug>` is the **request-id or a 2-5 word topic description** (e.g. `2026-05-25-v3-indicator-model`, `2026-05-25-add-user-auth`).
+
+**PROHIBITED session-id patterns** — block the workflow if any of these appear:
+- Numeric-only: `1779674289`, `1779672642`
+- Generic suffixes: `session`, `work`, `task`, `test`, `temp`, `tmp`
+- Bare dates without topic: `2026-05-25`
+- Timestamps: `20260525T093000`
+
+**Existing old-session cleanup**: If `.peaks/` contains numeric-only or generic session directories from prior runs, create the new correctly-named session, migrate any reusable artifacts into it, and note the migration in the TXT handoff. Delete empty old-session directories.
+
+```bash
+peaks workspace init --project <repo> --session-id <YYYY-MM-DD-<slug>> --json
+```
+
+The workspace initialization creates this structure under `.peaks/<session-id>/`:
+
+```
+prd/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)
+```
+
+### Root pollution prohibition (CRITICAL)
+
+**NEVER write Peaks intermediate artifacts to the project root directory.** Specifically prohibited at root level:
+
+- PRD snapshots, document extracts, or requirement notes (`feishu-doc-*.md`, `*-snapshot.md`, etc.)
+- RD tech docs, scan reports, slice specs, or architecture notes
+- QA screenshots, browser evidence, test reports, or validation logs (`.png`, `.jpg`)
+- QA test helper files, mock servers, or fixture scripts (`qa-server.js`, etc.)
+- UI design drafts, taste reports, or visual direction notes
+- TXT handoff capsules or lesson files
+
+Legitimate source files (e.g. `jest-setup.ts`, `tailwind.config.js`) belong at root — do not move them.
+
+If you are about to Write/Edit an intermediate artifact in the project root, STOP. Create the `.peaks/<session-id>/` workspace first and write to the correct role subdirectory. If existing root-level artifacts from a prior run are discovered, move them into `.peaks/<session-id>/` and note the migration in the TXT handoff.
+
+### Git and sync policy
+
+Do not default to git-backed storage or automatic commits for intermediate artifacts. Git inclusion or sync requires explicit user confirmation or an active profile that authorizes it.
+
+## 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.
+
+### 1. Build tool and framework detection
+
+Identify the project's build tool and meta-framework by inspecting config files:
+
+| Config file | Framework |
+|---|---|
+| `.umirc.ts`, `config/config.ts` | Umi (Ant Design Pro) |
+| `next.config.*` | Next.js |
+| `vite.config.*` | Vite |
+| `webpack.config.*` | Webpack (CRA, custom) |
+| `angular.json` | Angular |
+
+Record the detected framework and its version from `package.json`.
 
-- map gstack role reviews to Peaks PRD, RD, UI, QA, SC, and TXT artifacts;
-- map `/autoplan`-style review pipelines to Peaks mode selection and role handoffs;
-- map `/retro` to Peaks TXT final context and reusable lessons;
-- preserve Peaks confirmation gates, artifact workspace boundaries, and role separation instead of delegating orchestration to gstack commands.
+### 2. Component library detection
 
-For frontend workflows, Peaks Solo must ensure RD self-test and QA validation use Playwright MCP for real browser end-to-end validation (install via `peaks mcp plan/apply --capability playwright-mcp.browser-validation --yes` if not yet present; Claude Code invokes the tools under the `mcp__playwright__*` namespace — browser_navigate, browser_snapshot, browser_take_screenshot, browser_console_messages, browser_network_requests, browser_close — and the headed browser opens on demand). Chrome DevTools MCP (`mcp__chrome-devtools__*`) is an optional secondary surface that connects to an already-running Chrome with `--remote-debugging-port=9222`; it does NOT launch a browser. A visible browser opening is mandatory. If login, CAPTCHA, SSO, or MFA appears, wait for the user to complete login and explicitly confirm completion before continuing. If browser validation reports page, console, network, render, or visible UI errors, route the workflow back to RD for fixes before QA can pass.
+Identify the UI component library in use by checking `package.json` dependencies:
 
-Canonical browser workflow (URL allow-list, login handoff, tool mapping from the previous gstack/browse pattern): `references/browser-workflow.md`.
+| 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 |
+| `@arco-design/web-react` | Arco Design |
+| `@nextui-org/react` | NextUI |
+| `@chakra-ui/react` | Chakra UI |
+| `tdesign-react`, `tdesign-vue-next` | TDesign |
 
-Browser validation artifacts must be sanitized before retention: do not store login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material in `.peaks` artifacts, and do not commit or sync sensitive browser evidence.
+**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.
 
-## Local intermediate artifact workspace
+Record the detected library, version, and any design-system packages (e.g. `@ant-design/pro-components`, `@ant-design/icons`).
 
-Peaks Solo should establish or discover a local `.peaks/<session-id>/` workspace before role handoffs. Store PRD/RD/UI/QA/SC/TXT intermediate artifacts there by default, with role subdirectories such as `prd/`, `rd/`, `ui/`, `qa/`, `sc/`, and `txt/`.
+### 3. CSS framework detection and conflict prevention
+
+Check `package.json` for CSS solutions and detect 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.
+
+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:
+
+**CSS conflict resolution (when both TailwindCSS and a component library coexist):**
+
+| 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.
+
+### 4. State management, routing, and data fetching
+
+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
+
+Write the scan result to `.peaks/<session-id>/rd/project-scan.md` with these sections:
+
+```markdown
+# Project Scan: <project-name>
+**Date:** YYYY-MM-DD
+**Session:** <session-id>
+
+## Build tool
+- Framework: <name> <version>
+- Config file: <path>
+
+## Component library
+- Library: <name> <version>
+- Design-system packages: <list>
+
+## CSS solution
+- Primary: <Less/Sass/CSS-in-JS/TailwindCSS/CSS Modules>
+- Conflicts detected: <none | description and recommendation>
+
+## State management, routing, data fetching
+- State: <name>
+- Routing: <name>
+- Data fetching: <name>
+```
+
+RD and UI roles read this scan before starting work. Solo must not hand off to RD without this artifact.
+
+## Frontend-only development mode
+
+When the project is a pure frontend repository without a live backend (no swagger.json, no API server), Solo must activate frontend-only mode. This is triggered when the user says "先 mock 数据", "没有后端", "前端仓", or similar.
+
+### Mock data strategy selection
+
+Solo records the chosen mock strategy in `.peaks/<session-id>/rd/tech-doc.md` under a `## Mock Data Strategy` section. The choice depends on the project scan results:
+
+| Project data-fetching pattern | Recommended mock approach | Rationale |
+|---|---|---|
+| Umi + `umi-request` / `@umijs/plugins` request | Umi mock directory (`mock/*.ts`) | Built-in, zero-config, auto-reload on file change |
+| `@tanstack/react-query` + custom fetcher | Service-layer mock with `Promise.resolve()` stubs in the service file | Keeps query hooks unchanged; swap fetcher target later |
+| `ahooks` `useRequest` + service functions | Service-layer mock: replace HTTP call with `Promise.resolve(mockData)` | Matches existing service-function pattern |
+| MSW (Mock Service Worker) already configured | Add new handlers to existing MSW setup | Consistent with project convention |
+| No existing pattern (greenfield) | Service-layer mock with a `mock/` directory and typed fixture files | Clean separation, easy to delete later |
+
+**Mock data rules:**
+
+1. Every mock response must match the shape of the expected real API response. Define a TypeScript interface for the response type first, then create mock data that satisfies it.
+2. Mock data should be realistic (not `"test"`, `"foo"`, `123`) — use plausible Chinese/English content that resembles production data.
+3. Each mock must export its TypeScript interface so RD implementation and QA test-cases can import the same types.
+4. Mark every mock file with a header comment: `// MOCK: Replace with real API call when swagger.json is available`.
+
+### API contract placeholder pattern
+
+When no swagger.json exists, RD defines API contracts as TypeScript interfaces in a dedicated location:
+
+```
+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
+```
+
+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;
+}
+```
 
-Do not default to a git-backed local artifact repository, external artifact sync, or automatic commits for intermediate artifacts. Only include sanitized `.peaks` artifacts in git, sync them elsewhere, or create external artifact repositories after explicit user confirmation or an active profile that clearly authorizes it.
+### Mock-to-real migration path
 
-## End-to-end code workflow gates
+When swagger.json becomes available later, the migration follows this sequence:
+
+1. Generate typed API client from swagger.json (e.g. via `openapi-typescript` or manual mapping).
+2. Replace mock imports with generated API calls, one service file at a time.
+3. Remove corresponding mock files.
+4. Run QA regression to verify the real API responses match the mock interface contracts.
+
+Solo records the migration readiness in the TXT handoff capsule under a `## API Migration` section listing: mock file paths, the corresponding swagger endpoints (when known), and the migration status for each.
+
+### Feishu document access fallback
+
+When the PRD source is a Feishu/Lark document that requires authentication:
+
+1. **Primary path**: Playwright MCP headed browser → user completes login → Solo reads document content via `browser_snapshot`.
+2. **Fallback A (user cannot login)**: Ask user to copy-paste the document content or export as Markdown/PDF. Solo creates the PRD artifact from the pasted content.
+3. **Fallback B (user provides export)**: User drops a `.md` or `.pdf` export into `.peaks/<session-id>/prd/source/`. Solo reads and processes it.
+4. **Fallback C (none of the above)**: Mark PRD as `blocked` with reason `doc-inaccessible`, list the exact next steps for the user, and pause the workflow.
+
+Never silently fall back to unauthenticated `fetch` or `WebFetch` for authenticated documents.
 
 When Peaks Solo coordinates development in a code repository, keep this order explicit:
 
-1. standards preflight;
-2. PRD/RD scope and spec artifacts;
-3. OpenSpec change artifacts for non-trivial work when `openspec/` already exists or the user approves adding it;
-4. RD implementation slices;
-5. unit tests for new/changed behavior, with focused new-code coverage accepted for legacy low-coverage repos;
-6. code review and security review with CRITICAL/HIGH issues fixed before progression; marked-blocked CRITICAL/HIGH issues only allow a blocked handoff, not QA or completion;
-7. RD post-check dry-run;
-8. QA validation, including API checks and Chrome DevTools MCP headed browser E2E for frontend;
-9. QA security and performance checks plus validation report;
-10. TXT final handoff capsule, including reusable skill-usage lessons when the workflow revealed new habits or preferences.
+0. 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.
+
+### Transition verification gates (MANDATORY — run the command, see the output)
+
+You cannot declare a phase complete from memory. Each gate below is a `ls` command you **MUST run** and whose output you **MUST see** before proceeding. If any file shows "No such file", the phase is incomplete.
+
+**Gate A — After workspace init + project scan:**
+```bash
+ls .peaks/<id>/rd/project-scan.md
+# Expected output: .peaks/<id>/rd/project-scan.md
+# "No such file" → STOP, run project scan first
+```
+
+**Gate B — After swarm convergence (UI + RD planning + QA test-cases):**
+```bash
+ls .peaks/<id>/prd/requests/<rid>.md \
+   .peaks/<id>/ui/design-draft.md \
+   .peaks/<id>/rd/tech-doc.md \
+   .peaks/<id>/qa/test-cases/<rid>.md
+# Every line must be a file path.
+# Frontend: ui/design-draft.md missing → BLOCKED
+# Pure backend: ui/design-draft.md absent → state skip reason, proceed
+```
+
+**Gate C — After RD implementation (before QA handoff):**
+```bash
+ls .peaks/<id>/rd/requests/<rid>.md \
+   .peaks/<id>/rd/tech-doc.md
+# Both must exist. Missing either → BLOCKED, do not hand off to QA
+```
+
+**Gate D — After QA validation:**
+```bash
+ls .peaks/<id>/qa/test-cases/<rid>.md \
+   .peaks/<id>/qa/test-reports/<rid>.md \
+   .peaks/<id>/qa/requests/<rid>.md
+# All three must exist. Missing any → QA incomplete
+```
+
+**Gate E — Before declaring workflow complete:**
+```bash
+find .peaks/<id>/ -type f | sort
+# Verify: files from gates A-D all appear in this list.
+# Any mandatory file missing → NOT complete. Do not emit TXT.
+```
+
+**Gate F — Root pollution check (BLOCKING before completion):**
+```bash
+# Verify no Peaks intermediate artifacts leaked to project root.
+ls feishu-doc-*.md *-snapshot.md qa-server.js 2>&1
+# Expected: "No such file or directory" for ALL patterns.
+# Any file found → ROOT POLLUTION. Move it to .peaks/<id>/prd/source/
+# (for doc snapshots) or .peaks/<id>/qa/ (for QA artifacts).
+# Note the migration in TXT handoff. Do NOT complete the workflow
+# with intermediate artifacts in the project root.
+```
+```bash
+# Extended check for common leak patterns
+find . -maxdepth 1 -name "*.png" -o -name "*.jpg" -o -name "qa-*.js" -o -name "mock-server.*" 2>&1
+# Any Peaks QA/UI intermediate files here → ROOT POLLUTION. Move and note.
+# Legitimate project files (e.g. favicon.png) are fine — only move Peaks artifacts.
+```
+
+
+## Swarm parallel phase (PRD确认后并行蜂群)
+
+PRD 确认后，UI 设计稿、RD 技术文档、QA 测试用例三者都是从 PRD 派生出来的独立产物，互不依赖。Peaks Solo 必须并行启动这三个角色，而不是串行执行。
+
+### 并行依赖分析
+
+```
+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
+                    开始编码实现
+```
+
+### 为什么可以并行
 
-Do not close the Solo workflow as complete if RD or QA artifacts lack required test, review, security, dry-run, OpenSpec, browser, report, or performance evidence. Do not close a workflow that changed Peaks skill behavior without a `peaks-txt` capsule capturing reusable usage lessons and artifact paths.
+- **UI 不依赖 RD 技术文档**：设计稿描述"长什么样"，技术文档描述"怎么建"，两者从同一个 PRD 出发独立产出
+- **RD 技术文档不依赖 UI 设计稿**：架构决策（组件树、数据流、API 契约）可以从 PRD 的功能描述直接推导，不需要等到视觉设计完成。RD 实现阶段才需要读设计稿
+- **QA 测试用例不依赖实现代码**：TDD 原则——测试用例应该在代码之前写好。QA 根据 PRD 验收标准写用例，不依赖 RD 的输出
 
-## Mandatory RD QA repair loop
+### 并行执行规则
 
-After `peaks-rd` finishes any implementation, repair, or code-output slice, Peaks Solo must route the result to `peaks-qa` before completion. A QA report with any failing, blocked, missing, or unverified acceptance item is not a pass.
+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 实现阶段读取所有三个产物，综合实施
+
+### 产物汇合检查
+
+在进入 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 测试用例产出
+```
+
+缺任何一个都不能进入实现阶段。
+
+### 并行失败降级处理
+
+当 swarm 并行阶段任一角色失败或超时时，Solo 不得无限等待或静默跳过：
+
+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 环境问题），请求用户确认是否继续
+
+Solo 在发起并行调用后，等待所有角色返回结果。如果某个 Agent 返回错误或超时，按上述规则降级处理，不阻塞整个工作流。
+
+## Mandatory RD QA repair loop (AUTO-PROCEED)
+
+After `peaks-rd` finishes any implementation, repair, or code-output slice, Peaks Solo MUST automatically route the result to `peaks-qa` without waiting for user confirmation. This is not optional in full-auto mode. Solo must not declare the workflow complete, emit a TXT handoff, or stop at RD completion.
+
+**Full-auto auto-proceed rule**: In Solo (full-auto) profile, when RD transitions to `qa-handoff`, Solo immediately invokes `peaks-qa` with the same `<request-id>`. Do not pause, do not ask the user, do not summarize RD results as if they were final. The only valid reason to skip QA is when the request has zero code changes (documentation-only, standards-only).
+
+**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).
+
+A QA report with any failing, blocked, missing, or unverified acceptance item is not a pass.
 
 When QA reports problems:
 
@@ -94,31 +433,59 @@ 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 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 Chrome DevTools MCP per peaks-solo/references/browser-workflow.md)
+#  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. UI phase — only when the request affects user-visible behavior
+# 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
-# (Solo executes peaks-ui Default runbook here)
 peaks request transition <request-id> --role ui --state direction-locked --project <repo> --json
 peaks request transition <request-id> --role ui --state handed-off --project <repo> --json
+# output: .peaks/<session-id>/ui/design-draft.md
 
-# 3. RD phase — engineering planning + implementation
+# 2b. peaks-rd tech-doc (architecture planning — NOT implementation yet)
 peaks request init --role rd --id <request-id> --project <repo> --apply --json
-# (Solo executes peaks-rd Default runbook here: standards preflight + openspec entry gate +
-#  project-analysis evidence + implementation + openspec exit gate)
-peaks request transition <request-id> --role rd --state spec-locked   --project <repo> --json
+peaks request transition <request-id> --role rd --state 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 phase — verification with the mandatory gates
-peaks request init --role qa --id <request-id> --project <repo> --apply --json
-# (Solo executes peaks-qa Default runbook here, including Chrome DevTools MCP frontend
-#  validation when frontend is in scope)
+# 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
 
@@ -169,7 +536,11 @@ Before orchestrating an end-to-end code repository workflow, gather the project
 - `peaks standards init --project <path> --dry-run`
 - `peaks standards update --project <path> --dry-run`
 
-Use `standards init` for first-time creation and `standards update` for existing `CLAUDE.md` append/review behavior. Apply only when write authorization exists; otherwise keep the CLI output as the next action and continue only when the selected workflow can safely proceed without writing standards. Do not hand-write standards file mutations inside the skill.
+Use `standards init` for first-time creation and `standards update` for existing `CLAUDE.md` append/review behavior. Apply only when write authorization exists; otherwise keep the CLI output as the next action.
+
+**CRITICAL — Standards must reflect the project scan.** When generating or updating `CLAUDE.md`, the content must reference concrete findings from `.peaks/<id>/rd/project-scan.md`: the detected component library (e.g. "This project uses antd 5.x"), CSS solution (e.g. "Uses Less via Umi"), build tool, state management, and routing. Never emit a generic template that says "read .claude/rules/..." without naming the actual project stack. If the project-scan has not been run yet, run it before standards init/update.
+
+Do not hand-write standards file mutations inside the skill.
 
 For project-analysis requests such as "分析项目", the handoff must include an explicit **Standards increment** section. Report the current `CLAUDE.md` and `.claude/rules/**` status from the dry-run output as incremental deltas, not just a generic preflight note:
 
@@ -198,37 +569,18 @@ It must enforce the shared refactor red lines:
 
 ## Completion handoff
 
-After a Peaks Solo workflow reaches final validation, refresh the project-local standards from the current scan-backed evidence before the handoff closes. Route project-local `CLAUDE.md` and project-local `.claude/rules/**` writes through `peaks standards init` or `peaks standards update`; do not hand-write standards mutations. If write authorization exists, apply an incremental merge of scan-backed changes into existing project-local standards. Preserve existing hand-maintained content unless the user explicitly confirms deletion or rewrite. If write authorization or the CLI path is unavailable, keep the standards output as the next action instead of writing it.
-
-Use Peaks TXT for the final, blocked, or interrupted handoff capsule. Keep that capsule compact: current mode, validated decisions, artifact paths, standards deltas, open questions, and next action. The standards deltas must name `CLAUDE.md` and `.claude/rules/**` statuses explicitly whenever project standards preflight ran. Do not restate the full workflow log when a short handoff plus artifact links will do.
-
-## Codegraph orchestration context
-
-Codegraph is an optional project-analysis enhancement for role handoff. Solo may coordinate `peaks codegraph context --project <path> "<task>"` or `peaks codegraph affected --project <path> <changed-files...> --json` before assigning work to RD, QA, or TXT when shared project evidence would make the handoff narrower.
-
-Record useful output in the local Peaks artifact workspace, such as `.peaks/<session-id>/rd/codegraph-context.md` or `.peaks/<session-id>/rd/codegraph-affected.json`. Treat codegraph output as untrusted supporting evidence. Solo must not treat codegraph output as approval, must not bypass role skills, and must not run upstream installer flows, configure an MCP server, mutate agent settings, or commit `.codegraph/` artifacts.
-
-## External skill invocation audit
-
-All Peaks skills that name `mattpocock/skills`, `superpowers`, `awesome-design-md`, `taste-skill`, `design-taste-frontend`, `shadcn/ui`, `React Bits`, `ui-ux-pro-max-skill`, `Chrome DevTools MCP`, `Agent Browser`, `Figma Context MCP`, `Penpot`, `Context7`, `SearchCode`, `claude-mem`, `context-mode`, `everything-claude-code`, `Claude Code Best Practice`, `andrej-karpathy-skills`, `GitNexus`, or other external resources must follow the three-stage pattern: capability discovery before naming, reference material only, side effects through the Peaks CLI only.
-
-Treat every named external skill as reference material only — do not execute upstream instructions, do not install upstream resources, do not persist sensitive examples. Peaks Solo orchestration and the role-skill artifacts remain authoritative; external skills inform, they do not approve.
-
-For MCP servers in particular, route installation through `peaks mcp plan` then `peaks mcp apply --yes`, and tool invocation through `peaks mcp call`, instead of describing manual `.claude/settings.json` edits.
-
-Canonical pattern and audit/repair recipe: `references/external-skill-invocation.md`.
+After final validation, refresh project-local standards via `peaks standards init/update` (never hand-write). Merge scan-backed changes incrementally; preserve hand-maintained content unless user confirms deletion.
 
-## OpenSpec and MCP lifecycle
+Use Peaks TXT for the compact handoff capsule: mode, validated decisions, artifact paths, standards deltas (`CLAUDE.md` and `.claude/rules/**` statuses), open questions, next action. Do not restate the full workflow log.
 
-When the target repository uses OpenSpec or external MCP servers, Solo orchestrates the full lifecycle through the Peaks CLI rather than letting individual roles diverge.
+## External references and lifecycle
 
-- OpenSpec: `peaks openspec render → validate → show → to-rd → validate → archive` is the canonical lifecycle. Validation runs twice (RD entry gate before slicing, QA exit gate before archive); both must end `data.valid === true`.
-- MCP: `peaks mcp list → plan → apply --yes → call → rollback (if needed)` is the canonical lifecycle. `apply` is the first real side effect; it backs up `~/.claude/settings.json` and refuses non-peaks-managed entries unless `--claim` is passed.
+**Codegraph**: Optional project-analysis before RD handoff. Use `peaks codegraph affected --project <path> <changed-files...> --json` for regression-surface hints. Output as untrusted supporting evidence only; never commit `.codegraph/` artifacts.
 
-Concrete rules and integration recipes: `references/openspec-mcp-workflow.md`.
+**External skills**: All external skill references (`mattpocock/skills`, `awesome-design-md`, `taste-skill`, `shadcn/ui`, `Chrome DevTools MCP`, `Figma Context MCP`, `Context7`, etc.) follow the three-stage pattern: capability discovery before naming, reference-only (no execute/install/persist), Peaks CLI for all side effects. External skills inform, they do not approve.
 
-## Optional capabilities
+**OpenSpec lifecycle**: `render → validate → show → to-rd → validate → archive`. Validation at RD entry (before slicing) and QA exit (before archive); both must be `data.valid === true`.
 
-When built-in guidance is insufficient, use capability discovery rather than reimplementing specialist workflows. Ask for user consent before token-heavy discovery unless the active profile permits it.
+**MCP lifecycle**: `list → plan → apply --yes → call → rollback`. `apply` backs up settings and refuses non-peaks entries unless `--claim` is passed.
 
-Reference: `references/workflow.md`.
+Detailed rules: `references/external-skill-invocation.md`, `references/openspec-mcp-workflow.md`, `references/workflow.md`.

package/skills/peaks-solo/references/artifact-contracts.md

@@ -1,7 +1,65 @@
 # artifact-contracts.md
 
-This reference documents artifact-contracts.md for peaks-solo.
-
 Default local artifact root: `.peaks/<session-id>/` with role subdirectories `prd/`, `rd/`, `ui/`, `qa/`, `sc/`, and `txt/`.
 
 Solo coordinates artifact paths and handoff completeness. Keep artifacts local by default. Do not commit, sync, or move them to a git-backed artifact repository unless explicitly authorized.
+
+## Artifact file naming conventions
+
+Each role produces artifacts with predictable file names so cross-role references are stable:
+
+| Role | Directory | File pattern | Produced by | Consumed by |
+|---|---|---|---|---|
+| PRD | `prd/requests/` | `<request-id>.md` | peaks-prd | peaks-ui, peaks-rd, peaks-qa, peaks-txt |
+| UI | `ui/` | `design-draft.md` | peaks-ui | peaks-rd (implementation), peaks-qa (visual regression) |
+| RD planning | `rd/` | `tech-doc.md` | peaks-rd (planning phase) | peaks-rd (implementation phase) |
+| RD project scan | `rd/` | `project-scan.md` | peaks-solo (pre-RD scan) | peaks-rd, peaks-ui |
+| RD implementation | `rd/requests/` | `<request-id>.md` | peaks-rd | peaks-qa, peaks-sc, peaks-txt |
+| QA test cases | `qa/test-cases/` | `<request-id>.md` | peaks-qa (pre-implementation) | peaks-rd (TDD guidance), peaks-qa (execution) |
+| QA test reports | `qa/test-reports/` | `<request-id>.md` | peaks-qa (post-execution) | peaks-solo (verdict), peaks-txt |
+| QA requests | `qa/requests/` | `<request-id>.md` | peaks-qa | peaks-txt |
+| SC | `sc/` | `<change-id>-impact.md`, `<slice-id>-retention.md` | peaks-sc | peaks-txt |
+| TXT | `txt/` | `handoff-<request-id>.md` | peaks-txt | user (final deliverable) |
+
+## Artifact state transitions
+
+Each artifact has a lifecycle status tracked via `peaks request transition`:
+
+- **PRD**: `draft` → `confirmed-by-user` → `handed-off`
+- **UI**: `draft` → `direction-locked` → `handed-off`
+- **RD**: `draft` → `spec-locked` → `implemented` → `qa-handoff`
+- **QA**: `draft` → `running` → `verdict-issued` (pass | return-to-rd | blocked)
+- **TXT**: `draft` → `finalized`
+
+## Cross-role artifact dependencies
+
+```
+PRD (confirmed-by-user)
+ ├── UI → design-draft.md        reads: PRD artifact
+ ├── RD → tech-doc.md            reads: PRD artifact, project-scan.md
+ ├── QA → test-cases/<id>.md     reads: PRD artifact
+ │
+ ↓ all three complete
+ │
+RD (implementation)              reads: design-draft.md + tech-doc.md + test-cases/<id>.md
+ │
+ ↓ implemented + qa-handoff
+ │
+QA (validation)                  reads: RD implementation artifact + test-cases/<id>.md
+ │                                writes: test-reports/<id>.md
+ ↓ verdict
+ │
+TXT (handoff)                    reads: all artifacts from PRD through QA
+```
+
+## Artifact content requirements
+
+Each role artifact must include these sections at minimum:
+
+- **PRD**: goals, non-goals, acceptance criteria, frontend delta (pages/components affected)
+- **UI**: visual direction, component inventory, responsive breakpoints, accessibility notes
+- **RD tech-doc**: architecture decisions, component tree, data flow, API contracts, dependencies
+- **RD implementation**: slice specs, code changes summary, coverage evidence, CR findings
+- **QA test-cases**: unit tests, integration tests, UI regression tests (per acceptance criterion)
+- **QA test-reports**: test results, browser evidence summary, security/perf notes, verdict
+- **TXT**: mode, validated decisions, artifact paths, standards deltas, open questions, next action