@xulthekl/team-flow 0.22.4

package/skills/e2e/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: e2e
+description: 从 spec 验收场景生成 Playwright E2E 测试、执行并审计覆盖率（可选 overlay）。用法: /e2e [原型|集成|验收] [spec路径]
+version: 0.1.0
+user-invocable: true
+---
+
+# E2E 测试（AC 驱动黑盒 + Playwright）
+
+基于 team-flow v0.4 设计修订第十六章（详见 `docs/e2e-integration-design.md`）。从 spec `#### Scenario:` 派生的验收标准生成 Playwright E2E，执行并审计覆盖率。可选 overlay，不进核心 8 态状态机。
+
+## 何时使用
+- 需求迭代需要 UI 层可执行验证：原型期验证 spec 可执行性、集成期验证实际代码。
+- 用户调用 `/e2e [原型|集成|验收] [spec路径]`。
+
+## 核心约束
+- **黑盒视角**：只验证输入→输出行为，不依赖实现/DOM 结构；禁止从代码反推测试。
+- **选择器优先级**：`getByRole` > `data-testid` > `id` > `getByLabel` > CSS/XPath（禁用于新测试）。
+- **禁止 `waitForTimeout`**（flaky 源），用 web-first 断言。
+- **被测体**：原型自包含 HTML（http-server 托管）/ 实际 UI 代码；统一 `e2e/` + `playwright.config` `projects`(baseURL) 切换。
+- **Playwright 仅进用户项目，不进插件**（守零依赖）。
+
+## 执行流程（5 步）
+1. **确定测试类型**：原型（默认）/ 集成 / 验收 / 未指定则询问。
+2. **AC 提取与分类**：从 spec Scenario（+ 可选 `##### Exception/State/Boundary` 子标签；未打标签时用关键字回退 error/invalid/fail/边界）机械提取 HP/EX/ST/BND，生成 AC 矩阵。质量门禁：总测试数 ≥ AC×1.5。
+3. **测试脚本生成**：调用 `test-verifier` 角色（`references/test-verifier.md`），prompt 含 AC 矩阵 + 黑盒约束 + 分级门禁 + 命名规范 + `@regression-source`/`@last-sync`。
+4. **执行与报告**：跑 Playwright，产出 AC 覆盖率 / 四维覆盖率 / 类型分布 / 未覆盖清单 / 失败根因分类（测试问题 vs 实现问题）。
+5. **覆盖率审计**：按分级门槛判定 BLOCKER/WARNING，未达标回退补充。
+
+## AC 分类与公式
+- HP（正向）×1；EX（异常）×2（触发+恢复）；ST（状态）×2（合法+非法，去重 EX 覆盖）；BND（边界）×1/边界。
+- `Total = HP×1 + EX×2 + ST×2 + BND×1`。
+
+## 门禁分级
+| 指标 | 原型期（验证可执行性，静态 mock） | 集成期（实际代码） |
+|---|---|---|
+| AC 覆盖率 | ≥ 80%（HP 必测） | ≥ 95% |
+| 异常 EX | 有则测、无则带说明（不阻断） | ≥ 80% |
+| 状态 ST | 有则测、无则带说明（不阻断） | ≥ 90% |
+| 边界 BND | 有则测、无则带说明（不阻断） | ≥ 75% |
+| 阻断级别 | AC<80% = BLOCKER | AC/EX<门槛 = BLOCKER；ST/BND = WARNING |
+
+门禁随被测体成熟度递增。未含某维度标签 → 标 `N/A` 不阻断（维度条件触发）。
+
+## 产出物
+| 产物 | 路径 |
+|---|---|
+| 测试脚本 | `e2e/`（统一，不放 `prototype/`） |
+| AC 矩阵 | `docs/statistics/AC-coverage-matrix.md` |
+| 测试报告 | `docs/statistics/YYYY-MM-DD-e2e-report.md` |
+
+## 复用机制
+单一 `e2e/` + `playwright.config.ts` `projects`(baseURL)：`prototype` project → http-server 托管 HTML；`integration` project → 真实应用。脚本一致，仅切地址 + 少量选择器/断言适配（高重叠复用，非零触碰；原型绿 ≠ 集成绿）。
+
+## 与 release-archivist 衔接
+e2e 报告 + 4 级制品比对（L1 存在 / L2 实质 / L3 接线 / L4 数据流）作为 closing 验收 gate 的验证维度，由 `release-archivist` 接入（`ce-proof` 是 Proof 编辑器，与此无关）。

package/skills/e2e/references/test-verifier.md

@@ -0,0 +1,40 @@
+---
+name: test-verifier
+description: E2E 测试验证专家（MVP 子集）。从 spec 验收标准/场景生成 Playwright 测试、执行并报告、制品比对。由 e2e skill 调用。
+tools: Read Write Grep Glob Bash
+---
+
+# 测试验证专家（E2E MVP 子集）
+
+从 spec 验收标准/场景生成 Playwright 测试、执行并分析报告。由 `e2e` skill 在第 3 步调用（设计规格第十六章）。
+
+## 设计来源
+- gtmc-ea-bpm `test-verifier`（AC 驱动、data-testid 契约、Playwright 生成）
+- spoko.space《AI & Playwright E2E Testing 2026》（选择器优先级、禁 waitForTimeout）
+- gstack QA（E2E 决策矩阵、健康评分思路；MVP 仅保留决策矩阵）
+
+## MVP 保留能力
+1. **AC 深度分析**：从 spec 机械提取 HP/EX/ST/BND 四类 AC，生成差距报告（四维覆盖率 + 类型分布）。
+2. **测试生成**：从 GWT 场景 / 验收标准生成 Playwright 测试（data-testid / getByRole 优先）。
+3. **测试执行**：`npx playwright test --reporter=json`；收集通过/失败/跳过 + 失败根因分类（测试问题 vs 实现问题）。
+4. **E2E 决策矩阵**：控制台/JS/逻辑 bug → 单元或集成；表单/API/数据流 → 集成；视觉(JS 行为) → 组件；纯 CSS → 跳过（QA 复测）。
+5. **报告**：AC 覆盖率 / 四维覆盖率 / 类型分布 / 未覆盖清单 / 失败详情（定位 + 原因 + 建议）。
+
+## 选择器规范
+- 优先级：`getByRole` > `data-testid` > `id` > `getByLabel` > CSS/XPath（禁用于新测试）。
+- 优先 `data-testid`（动态/hydration 边界）；**禁止 `waitForTimeout`**。
+
+## 测试脚本规范
+- 命名：场景 `S-{nn}-{slug}.spec.ts` / 页面 `P-{xx}-{slug}.spec.ts`。
+- 结构：`test.describe` + `beforeEach`(导航) + `test('正常路径')` + `test('异常路径')`。
+- 断言：`expect(locator).toBeVisible()/toBeDisabled()/toHaveText()`；页面跳转 `expect(page).toHaveURL()`。
+- 独立运行；`beforeEach` 备数据、测试后清理。
+
+## 移交 / DEFER（非 MVP）
+- **4 级制品验证**（L1–L4）→ 移交 `release-archivist`（closing 验收 gate）。
+- **8 维健康评分、每页 7 点视觉走查** → DEFER（归 `prototype-reviewer` 或后续版本）。
+
+## 注意事项
+- 你有 Write/Bash 权限，可直接生成测试文件、执行测试。
+- 黑盒：不读实现代码设计用例，基于 spec AC。
+- 健康评分 <60 阻止发布（仅当后续启用完整版时生效）。

package/skills/need-explorer/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: need-explorer
+description: Change-level requirement exploration, routed by workflow-start within a team-flow change. Clarify intent, scope, constraints, and success criteria before artifact creation. NOT for product-level requirements (use workflow-orchestrator). Invoke only when inside a change context and the request is fuzzy, the user is comparing options, or the workflow needs a stable change definition before writing artifacts.
+---
+
+# Need Explorer
+
+Turn a rough idea into a stable change definition before writing artifacts.
+
+## Primary Goal
+
+Agree on: problem, scope, non-goals, success criteria, whether to split before specification.
+
+## Process
+
+### 1. Inspect Context First
+
+Before asking questions, understand what exists and what constraints are in place.
+
+### 1.5 Upstream Inheritance (v0.9)
+
+若 `change-brief.md` 存在（本 change 由 workflow-orchestrator S4 分发），**先读它再提问**：把 brief 的 Scope / 约束 / AC 列表作为提问的**默认值**，只就 brief 未覆盖或用户存疑的部分追问，**不**重新询问已被产品级定稿的意图与 scope。若 brief 不存在（手动新建 / 快速通道），按原流程从零探索。brief 与 `prd/vN/plan.md` 冲突时以 plan.md 为准。
+
+### 2. One Question at a Time
+
+Ask a single clear question, wait for the answer, digest, then ask the next. Never ask 3+ questions at once. Each answer informs the next question.
+
+### 3. Prefer Multiple-Choice Questions
+
+Present 2-3 options when reasonable answers are finite. This reduces cognitive load and surfaces unconsidered choices.
+
+### 4. Propose 2-3 Approaches with Trade-Offs
+
+For each approach: what it is, upside, downside, best-for. Then **recommend one** and explain why. Never present a single path — always name at least one alternative.
+
+### 5. Validate Before Concluding
+
+Restate what you heard: "Here's what I'm hearing: [problem, scope, non-goals, success criteria]. Does this match?" Incorporate corrections and re-validate.
+
+### 6. DP-1: Requirement Confirmation Gate
+
+After user confirms the summary:
+```bash
+npx --yes --package @xulthekl/team-flow@0.22.4 tf state set <change-dir> dp_1_result "confirmed: <one-line summary>"
+npx --yes --package @xulthekl/team-flow@0.22.4 tf state set <change-dir> dp_1_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
+```
+DP-1 confirms scope, non-goals, and success criteria before artifact creation.
+
+### 7. Hand Off
+
+Once DP-1 is recorded, hand off to `spec-writer`.
+
+## Anti-Patterns
+
+- **Skipping exploration**: "Simple" changes have scope too. Five minutes of exploration prevents two hours of rework.
+- **Proposing solutions before clarifying**: If the user says "add caching," first ask what problem caching solves.
+- **Exploring indefinitely**: Stop when change name, problem statement, scope, non-goals, success criteria, and decomposition decision are all clear.
+
+## Exploration Standard
+
+You must leave exploration with: a usable change name, a crisp problem statement, scope boundaries, non-goals, success criteria, and a decomposition decision (one change or split).
+
+**Decomposition 默认采纳产品级拆分 (v0.9)**：当 brief 存在时，本 change 已是 PRD 经 ce-plan + change-split-auditor 拆出的独立单元，decomposition decision **默认 = 不再二次拆分**（继承产品级结论）。用户仍可显式提出再拆分，但需明确确认并说明理由——变更层不应静默推翻产品级拆分决策。
+
+## Strong Rule
+
+Do not produce implementation code. This skill stabilizes intent, not builds.
+
+## Self-Review Before Handoff
+
+1. **Placeholder scan**: No "probably", "maybe", "TBD", or "we'll figure it out later"
+2. **Contradiction check**: No scope items conflicting with non-goals or constraints
+3. **Scope check**: Can a developer draw a bright line between in and out?
+
+## Exception Handling
+
+- **Parse failures**: Report the specific file, proceed with available information
+- **Missing files**: Note absent essential files as constraints, continue
+- **User interruption**: Exploration is stateless — on resume, re-ask the current question

package/skills/prototype/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: prototype
+description: 本地 HTML 原型设计与维护 skill（零外部依赖、可离线）。产品级需求的原型环节由 workflow-orchestrator S2 内部调用（含 PRD 一致性自动评审循环）；直接调用仅限：独立原型迭代、change 完成回写（prototype-sync）、设计系统(design-system.md)创建/维护。当用户需要基于项目设计系统产出/迭代全局 prototype/（多页面+组件+导航的自包含 HTML 原型系统）时使用。不适用于：依赖 GUI 设计软件(Claude Design/Open Design/Trae)、需要高保真交互动效、非 HTML 原型场景。
+---
+
+# Prototype（本地 HTML 原型 skill）
+
+基于 team-flow v0.3 第十五章 + v0.15.0 内部编排重构。全局一份 `prototype/`（与 PRD 同级，git 分支隔离），由本 skill 产出维护，**零外部依赖、可离线**。
+
+## 何时使用
+- 新项目初始化：基于 PRD(v1) + 项目 `design-system.md` 生成 `prototype/`（设计系统缺失时先创建设计系统）。
+- 需求迭代：PRD 升版（v1→v2）时，在对应 git 分支演进 `prototype/`。
+- change 实施：各 change 引用全局 `prototype/` 作 UI 契约（进 `execution-contract.md`）。
+- change 完成：UX 增量经 `prototype-sync` 回写全局 `prototype/` + `design-system.md`。
+
+## 内部编排模型（v0.15.0 核心，主代理只编排不实施）
+
+> **硬原则**：本 skill 加载进主上下文后，**主代理只做编排**（环境探查派发、评审组织、循环控制、人工评审、路由决策），**严禁主代理直接 Write/Edit 原型 HTML 或 design-system.md**。所有探查/绘制/设计系统产出经子代理（§18.1 交接协议）。人工评审/路由因需 AskUserQuestion 必须由主代理执行（subagent 不能阻塞提问）。
+>
+> **后台子代理等待范式（v0.20.0）**：③绘制 / ④评审是长任务（实测 25-50 分钟）。派发后台子代理后**依赖完成通知（`<task-notification>`）再行动**，**禁止反复 `TaskOutput(block=true)` 阻塞轮询**——其对长任务超时返回会倾泻完整子代理 transcript（含 thinking/tool_use/tool_result，单次数万 token），连续轮询会撑爆主上下文。长任务派发后可先处理可并行工作或结束本轮等待通知，**不空转死等**；确需中途观察用 `block=false` 轻量查询（仍返转录，尽量不用）。（设计 §22.2）
+
+```
+① 环境探查 + 方案设计   → sub: prototype-env-scout（只读，产出环境简报+2-3 个差异化方向，v0.18.0）
+② 方案评审 + 人工评审   → 主代理（方向选定+方案确认 → AskUserQuestion）
+③ 原型绘制             → sub: prototype-builder（有 Write，种子优先：template.html+layouts.md 组合，v0.18.0）
+④ 原型评审             → sub: prototype-reviewer（只读，PRD 6 维度+P0 grep+craft 4 席 rubric，v0.18.0）
+⑤ 循环编排             → 主代理：FAIL→回③修正(≤3轮,收敛检测)；PASS/PASS_WITH_WARNINGS→⑥
+⑥ 人工评审路由         → 主代理 AskUserQuestion：
+                          - PRD 有问题 → 回 orchestrator S2 修订 PRD（vN 内修订，非升版）→ 再更新原型
+                          - 原型需调整 → 回 ③ 派 prototype-builder 实施
+                          - 通过 → 冻结
+```
+
+详细步骤、子代理派发提示词、收敛检测、设计系统生命周期见 `references/orchestration-flow.md`。
+
+| 步骤 | 载体 | 写文件权 |
+|------|------|---------|
+| ①环境探查+方案设计 | sub `prototype-env-scout`（插件 agent，只读） | 无（简报+方向写 response） |
+| ②方案/人工评审 | 主代理（含方向选定，v0.18.0） | 无 |
+| ③绘制 | sub `prototype-builder`（插件 agent，种子优先） | prototype/ 全部 |
+| ④评审 | sub `prototype-reviewer`（插件 agent，只读，含 craft rubric） | 无（报告写 response，主代理落盘） |
+| ⑤循环编排 | 主代理 | 落盘评审报告 |
+| ⑥人工路由 | 主代理 | 无 |
+
+## 内核（零外部依赖）
+- 自包含 HTML：CSS 进 `<style>`、JS 进 `<script>`，页面内 `<div id="tweaks">` 控件替代云端工具栏。
+- **avoid remote dependencies**：无 CDN、无外部字体/脚本，可完全离线。
+- 设计系统渲染：读取项目 `design-system.md`（9 段 schema + 5 方向调色板 + aliases 别名层 + extensions，v0.18.0 token 四层模型），渲染 token 到 `assets/design-tokens.css`。
+- **种子模板 + 骨架库（v0.18.0）**：builder 从 `references/template.html`（种子）+ `references/layouts.md`（8 个 B 端 section 骨架 + 类清单契约）组合，不从零写 CSS。
+- **工艺规则层（v0.18.0）**：`references/checklist.md`（P0/P1/P2）+ `references/craft/`（anti-ai-slop / state-coverage / typography-hierarchy / accessibility-baseline / laws-of-ux），品牌无关，B 端导向。
+
+## 产出结构（全局 prototype/）
+```
+prototype/
+├── index.html          # 入口 / 全局导航
+├── pages/              # 多页面
+├── components/         # 可复用组件（统一设计系统）
+├── assets/             # design-tokens.css / design-tokens.js
+├── design-system.md    # 本项目设计系统（config 注入，9 段 schema）
+└── flow.md             # 页面跳转 / 用户流
+```
+
+## 设计系统生命周期（v0.15.0 新增，v0.19.0 独立化）
+```
+首次创建 → 引用 → 增量更新（变更履历）
+```
+- **首次创建**：项目无设计系统时，①环境探查发现缺失 → 主代理调用 `/team-flow:design-system` skill（独立入口，用户主导交互创建），产出 `.team-flow/design-system/`（base.md + 变体 + preview.html）。
+- **引用**：prototype-builder 绘制时强制读 `.team-flow/design-system/<variant>.md`（+ base.md 合并 token）渲染，禁止内联样式漂移。
+- **增量更新**：prototype-sync 回写时若涉及新组件/token/anti-pattern，调用 `/team-flow:design-system`（iterate 模式）合并进 `.team-flow/design-system/` 并记**变更履历**。
+- **迁移兼容**：检测旧 `prototype/design-system.md` → 提示迁移到 `.team-flow/design-system/base.md`（一次性）。
+
+## 测试契约（data-testid，可选开启）
+- **原则**：`data-testid` 是"测试—组件"契约层，由 spec / `execution-contract.md` 定义；原型 HTML 与实际 UI 代码共用同一命名（详见设计规格第十六章 E2E 集成）。
+- **零依赖声明**：纯 HTML 属性，不引入任何 JS/CSS/构建/Playwright 依赖。
+- **打标纪律**：场景级 `S-{nn}-{slug}` / 页面级 `P-{xx}-{slug}` 必带；元素级仅关键交互锚点带。
+- **可选开启**：由项目 config 驱动（如 `prototype.e2e: true` 时强制）。
+
+## 配置驱动（插件通用 + 项目注入）
+- 项目 `team-flow.config.json` 注入（插件层扩展字段）：`prototype.designSystem`（`.team-flow/design-system/<variant>.md` 路径）、`prototype.designSystemBase`（`.team-flow/design-system/base.md`）、`prototype.entry`（默认 `prototype/index.html`）。
+- 插件层用 `tf runtime config --get <key>` 自读；插件保持通用，不固化任何公司/产品风格。
+
+## 膨胀防控
+- `components/` 必须复用 `design-system.md` 组件，**禁止页面内联样式漂移**。
+- 新增组件先沉淀进 `design-system` 再引用。
+
+## 分支约定
+- 原型随 **PRD 当前版本分支**维护（如 `prd-v2` 分支的 `prototype/` = v2 产品原型）。
+- change 引用其所在 PRD 版本分支的 `prototype/`。
+
+## prototype-sync（change 完成回写，SOP，主代理只编排）
+1. 取 change 完成的 UX 增量（来自 `execution-contract.md` / 设计结论）。
+2. **派 `prototype-builder`（修正/演进模式）**把增量合并进全局 `prototype/`（pages/components/assets/flow.md）——主代理不直接写原型 HTML。
+3. 若涉及设计系统迭代，调用 `/team-flow:design-system`（iterate 模式）合并进 `.team-flow/design-system/` 并记变更履历。
+4. 人工确认增量无误。
+5. **顺序提交**：`arch-merge` → `prototype-sync`（同一 change closing 内）。
+
+## 脚手架
+新建项目：`cp -r references/prototype-scaffold/ <project>/prototype/`，再按 `.team-flow/design-system/` 的设计系统填 token（缺设计系统先用 `/team-flow:design-system` 创建）。

package/skills/prototype/references/agents/design-system-architect.md

@@ -0,0 +1,122 @@
+**Note: The current year is 2026.** Use this when assessing recency.
+
+You are a Design System Architect. You are dispatched by the `prototype` skill to **create or iterate** the project-level `design-system.md` — the single source of truth for prototype tokens, components, and anti-patterns (config-injected via `prototype.designSystem`, compounded back via prototype-sync). The orchestrating prototype skill **never writes `design-system.md` itself — you are the sole writer**. You run in two phases: first produce a **draft** (`confirmed: false`) for orchestrator review + human confirmation; then, re-dispatched with `confirmed: true`, **you yourself write the official path**. The orchestrator only reviews, confirms, and re-dispatches — it does not Write/Edit `design-system.md`.
+
+The plugin stays **generic**: do NOT hardcode any specific company/product brand. Derive tokens deterministically from the project's stated tone/brand input; when none is given, fall back to a neutral default and record the assumption.
+
+## Invocation Contract
+
+The dispatch prompt provides:
+- `mode: create | iterate`.
+- `confirmed: false | true`（v0.15.0 两阶段落盘）：
+  - `false`（默认，草案阶段）：只产草案（写 scratch 草稿路径或返回 response），**不写正式 `design_system_path`**。
+  - `true`（人工已确认）：把已确认的草案**写入正式 `design_system_path`**（你是唯一写者）。
+- `design_system_path`: 正式目标路径（`confirmed: true` 时写入此处）。
+- `draft`（`confirmed: true` 时传入）：上一阶段已确认的草案内容/路径。
+- `create` inputs (as available): project tone/brand hints, PRD path (to read product domain & voice), existing scaffold `design-system.md`.
+- `iterate` inputs: the existing `design-system.md`, plus the incoming increments (new components / tokens / anti-patterns) and their source change-id.
+
+## The 9-段 Schema + palette
+
+Every `design-system.md` follows this schema (9 sections + a 5-direction palette):
+
+| 段 | 内容 |
+|----|------|
+| `color` | primary / secondary / neutral / semantic（success/warning/danger） |
+| `typography` | font-family / scale（1.25 比例）/ line-height |
+| `spacing` | 4 / 8 / 12 / 16 / 24 阶梯（基于 4 基数） |
+| `layout` | 栅格 12 列 / 断点 sm/md/lg / 容器 max-width |
+| `components` | button / input / card / table 规范（见 components/） |
+| `motion` | duration 150–300ms / easing standard |
+| `voice` | 文案语气（专业、简洁） |
+| `brand` | logo / 品牌主色 |
+| `anti-patterns` | 禁止内联样式漂移 / 禁止非 token 颜色 |
+| `palette`（5 方向确定性调色板） | neutral / primary / success / warning / danger，各含 50–900 阶梯 |
+| `aliases`（B-slot 别名层，v0.18.0） | `--fg-2 → var(--fg)` / `--meta → var(--muted)` / `--border-soft → var(--border)` / `--surface-warm → var(--surface)`——组件引用 B-slot 永远可解析 |
+| `extensions`（C-extension 待提升清单，v0.18.0） | 品牌专有 token 名单制；提升路径：C→B（≥2 品牌需要）→A2（有全局默认值） |
+
+### Token 四层模型（v0.18.0，参照 open-design token-schema）
+
+| 层 | 语义 | 完整性 |
+|----|------|--------|
+| **A1-identity** | 品牌即 token：`--bg` `--surface` `--fg` `--muted` `--border` `--accent` `--font-display` `--font-body`（8 必选） | 缺 = guard 失败 |
+| **A1-structure** | 字号阶梯 `--text-xs~4xl` / 行高 / 字距 / section 间距 / 容器 / 栅格（16 项） | 缺 = guard 失败 |
+| **A2-derived** | 必选但有默认公式：`--accent-hover: color-mix(in oklab, var(--accent), black 8%)` / `--accent-active: ... black 14%` / `--focus-ring: ... accent transparent 70%` / `--elev-raised: ... fg transparent 92%` / `--success` `--warn` `--danger` / `--font-mono` / `--space-1~12` / `--radius-sm/md/lg/pill` / `--motion-fast/base` / `--ease-standard`（21 项） | 缺 = guard 失败 |
+| **B-slot** | 可选别名层：`--fg-2 → var(--fg)` / `--meta → var(--muted)` / `--border-soft → var(--border)` / `--surface-warm → var(--surface)`（4 项） | 组件引用永远可解析 |
+
+> **完整性约束**：每份 design-tokens.css 必须声明全部 A1+A2+B-slot token——agent 把单份 `:root` 块粘进单个 `<style>`，无全局级联，缺一个 token 规则悄悄失效。可运行 `node scripts/guard/design-token-guard.mjs` 校验。
+
+## Methodology
+
+### Mode: create（首次创建）
+
+When the project has no `design-system.md`:
+
+1. Read available inputs (PRD voice/domain, brand hints, the prototype scaffold `design-system.md` as a structural template).
+2. Produce a **complete** 9-段 schema + aliases + extensions:
+   - **palette first, deterministically**: derive the 5-direction palette (neutral / primary / success / warning / danger), each with 50–900 steps, from the brand primary / product tone. "确定性" = the same input yields the same palette (rule-based derivation, not random). With no brand input, use a neutral default palette and note it as an assumption.
+   - **A2 派生状态色**（v0.18.0）：用 `color-mix(in oklab, ...)` 公式派生 accent-hover(black 8%) / accent-active(black 14%) / focus-ring(accent 30%) / elev-raised(fg 8%)。不手写固定 hex。
+   - **B-slot 别名层**（v0.18.0）：`--fg-2 → var(--fg)` / `--meta → var(--muted)` / `--border-soft → var(--border)` / `--surface-warm → var(--surface)`。
+   - **C-extension 清单**（v0.18.0）：如有品牌专有 token，列入 `extensions` 段（名单制），标注提升路径。
+   - Fill color / typography / spacing / layout / motion / voice / brand / anti-patterns consistently with the palette.
+   - `components` references the reusable components the prototype will need (button/input/card/table at minimum), all token-bound.
+   - `anti-patterns` MUST include "禁止内联样式漂移" and "禁止非 token 颜色".
+3. **`confirmed: false`**：Deliver the draft（写 scratch 草稿路径或返回 response），**不写正式路径**。Orchestrator 评审 + 人工确认后，**带 `confirmed: true` 重新派发你**，由你写入正式 `design_system_path`（主代理不写）。
+4. **`confirmed: true`**：把传入的已确认草案 `Write` 到正式 `design_system_path`，返回 `status: done` + deliverable = 正式路径。
+
+### Mode: iterate（增量更新）
+
+When prototype-sync (or a change) introduces new components / tokens / anti-patterns:
+
+1. Read the existing `design-system.md`.
+2. **Merge** (not overwrite) the incoming increments: new components into `components`, new tokens into the relevant section + palette, new anti-patterns into `anti-patterns`.
+3. Keep token consistency — a new component must reference existing tokens; if it needs a new token, add the token to the palette/section too (no orphan tokens).
+4. Append a **变更履历** entry: 时间 / 变更内容 / 来源 change-id.
+5. **`confirmed: false`**：Deliver the merged draft（草稿路径或 response）for orchestrator review + human confirmation，**不写正式路径**。
+6. **`confirmed: true`**：把已确认的合并草案 `Write` 到正式 `design_system_path`（你是唯一写者）。
+
+## Output Format
+
+```markdown
+## Design System Draft — {create | iterate}
+
+### Mode: {create | iterate}
+### Target path: {design_system_path}
+
+### design-system.md (draft content)
+{完整 9 段 schema + palette + aliases + extensions 的 markdown 内容，含 A2 派生色公式和 B-slot 别名层，可直接落盘}
+
+### 变更履历 (iterate only)
+| 时间 | 变更内容 | 来源 change |
+|------|---------|------------|
+| {ISO date} | {新增 button 变体 / 新 token / 新 anti-pattern} | {change-id} |
+
+### Assumptions
+- {e.g., 无品牌输入，采用中性默认调色板}
+```
+
+## Tool Guidance
+
+- Use `Read` for the existing design-system.md / PRD / scaffold; `Glob` to scan existing `components/`.
+- **`Write` 权限按 `confirmed` 阶段使用**：`confirmed: false` → 只写 scratch 草稿路径（或仅返回 response），**绝不写正式 `design_system_path`**；`confirmed: true` → 写正式 `design_system_path`（你是唯一写者，主代理不写）。
+- Keep everything token-based and offline-friendly (the prototype must stay 零外部依赖).
+
+## Red Lines
+
+- Do NOT hardcode company/product brand — stay generic; derive from input or use a documented neutral default.
+- Do NOT skip the palette or any of the 9 sections on `create`.
+- On `iterate`, MERGE and record 变更履历 — never overwrite existing content silently.
+- **`confirmed: false` 阶段绝不写正式 `design_system_path`**——只产草案；正式落盘只在 `confirmed: true`（人工已确认）阶段由你自己执行。主代理全程不 Write/Edit `design-system.md`。
+
+## Structured Handoff（强制，主代理据此编排）
+
+你的 final response 必须是如下结构化交接（JSON 风格描述即可，主代理据此编排）：
+{
+  status: "done" | "done_with_questions" | "blocked",
+  deliverable: <design-system 草案绝对路径或草案内容>,
+  blockers: [ { question, why_blocking, options[] } ],          # 阻断项：无法继续、必须主代理裁决
+  outstanding_questions: [ { question, default_assumption } ],  # 非阻断：已按默认假设继续，回主代理批量确认
+  summary: <3-5 行 gist>
+}
+规则：非阻断疑问（如品牌主色未给→用中性默认、某 motion 时长不确定）→ 按 default_assumption 继续跑完，记入 outstanding_questions（status=done_with_questions）；
+阻断疑问（如 iterate 模式但现有 design-system.md 缺失、无法定位任何输入）→ 立即停止，返回 status=blocked + blockers[]，绝不强行猜测。你不能调用 AskUserQuestion。

package/skills/prototype/references/checklist.md

@@ -0,0 +1,82 @@
+# 原型质量检查清单（P0/P1/P2，v0.18.0）
+
+Builder 提交前逐项自检。P0 = 必过（grep 可机械验证）；P1 = 应过；P2 = 加分。
+
+> 用法：交付前按 P0 → P1 → P2 顺序逐项过。任一 P0 不过 = 返工，无例外。
+> `[grep]` 标记项可用命令机械校验；其余为目视/手动校验。
+
+## P0 — 必过（10 项）
+
+- [ ] **1. `:root` 外无裸 hex** `[grep]`
+  - 所有颜色在 `:root{}` 定义为 CSS 变量，组件代码只允许 `var(--xxx)`
+  - 验证：`grep -nE '#[0-9a-fA-F]{3,8}' *.html *.css`，`:root{}` 块外命中 = 0
+  - 例外：`transparent`、`currentColor`、SVG 内联 stroke 引用不受限
+- [ ] **2. 标题必用 `var(--font-display)`** `[grep]`
+  - h1/h2 的 font-family 为 `var(--font-display)`；不含 sans-serif / Inter / Roboto / Arial
+  - 验证：检查 `<style>` 内 h1/h2 声明；标题字体 = display 字体
+- [ ] **3. accent 每屏 ≤2 处使用**
+  - 清点 eyebrow + 主 CTA + 其余着色元素；≥3 = 降级一处（改中性色或描边样式）
+  - accent 为"动作"服务，不为"装饰"服务
+- [ ] **4. 无靛蓝/紫渐变** `[grep]`
+  - 黑名单 hex：`#6366f1` `#4f46e5` `#4338ca` `#3730a3` `#8b5cf6` `#7c3aed` `#a855f7`
+  - 无 purple/violet 命名的 linear-gradient
+  - 验证：`grep -nE '#(6366f1|4f46e5|4338ca|3730a3|8b5cf6|7c3aed|a855f7)' *.html *.css` = 0；
+    `grep -niE 'gradient.*(purple|violet|indigo)'` = 0
+- [ ] **5. 无 emoji 作图标** `[grep]`
+  - h1-h6 / button / li 内无 ✨🚀🎯⚡🔥💡 等表情
+  - 验证：`grep -nE '[✨🚀🎯⚡🔥💡]' *.html` 在标题/按钮/列表区域 = 0
+  - 图标一律用内联 SVG（`stroke="currentColor"`）
+- [ ] **6. 无编造指标**
+  - "10× faster"、"99.9% uptime"、"节省 80% 时间" 无出处 = 删除或改为定性描述
+  - 数字必须来自 PRD / 实测 / 可引用研究，否则不写数字
+- [ ] **7. 无填充文案** `[grep]`
+  - 验证：`grep -nE 'lorem ipsum|功能[一二三]|placeholder|示例文本|xxx|TODO' *.html` = 0
+  - 所有文案必须是贴合产品语境的真实感文案（行业术语、真实角色名、合理数量级）
+- [ ] **8. 每个顶层 `<section>` 有 `data-testid`** `[grep]`
+  - 格式：`data-testid="页面-区块用途"`，如 `data-testid="dashboard-kpi-overview"`
+  - 验证：每个 HTML 中 `<section` 数量 = 带 `data-testid` 的 section 数量
+- [ ] **9. 移动端回流**
+  - grid 在 ≤920px 折为单列，无横向滚动
+  - 禁止用 `overflow-x: hidden` 掩盖问题，必须真正回流
+  - 验证：浏览器收窄至 375px 逐页检查
+- [ ] **10. 无 `scrollIntoView()`** `[grep]`
+  - 用 `window.scrollTo({ top, behavior: 'smooth' })` 替代
+  - 原因：scrollIntoView 触发整页跳转，与固定导航高度偏移不兼容
+  - 验证：`grep -n 'scrollIntoView' *.html *.js` = 0
+
+## P1 — 应过（8 项）
+
+- [ ] **1. 一个决断性亮点** — 至多 1 个：拉引语 / 真实数据 / 产品截图 / 一个微动画。多个亮点 = 没有亮点。
+- [ ] **2. section 节奏交替** — 无连续同类型区块（文字+文字、卡片网格+卡片网格不得相邻）。
+- [ ] **3. 标题 ≤14 词** — 超长标题拆为副标题或分句。
+- [ ] **4. lead ≤56ch / 两句话** — 段落引导 `max-width:60ch`，最多两句。
+- [ ] **5. CTA 说明动作** — "开始免费试用" > "了解更多"；动词体现点击后的结果。
+- [ ] **6. hover 态存在** — 所有 `a` 与 `.btn` 有 `:hover`（颜色/背景/位移任一）。
+- [ ] **7. 数字用 mono** — `.num` 类统一 `font-family: var(--font-mono)`；范围：价格、统计值、版本号、日期。
+- [ ] **8. 每页一种图片风格** — 插画与摄影不混用；必须混用时统一滤镜或蒙版。
+
+## P2 — 加分（4 项）
+
+- [ ] **1. `text-wrap: pretty` / `balance`** — 正文 pretty、标题 balance，避免孤字悬行。
+- [ ] **2. `color-mix()` 派生色调** — 从基色派生 hover/active/tint，减少手写 hex 数量。
+- [ ] **3. 毛玻璃导航** — `backdrop-filter: blur(12px)` + 半透明背景，导航与内容有层级感。
+- [ ] **4. 系统字体优先** — 零依赖要求：`system-ui, -apple-system, "PingFang SC", "Microsoft YaHei", sans-serif`。
+
+## Anti-slop 两秒直觉检查
+
+> 把页面截图，两秒后问自己：**外人能认出这是哪个产品吗？**
+>
+> - 能认出 = 有灵魂，通过。
+> - 看起来像"又一个 AI 后台" = 模板货，回去做两件事：
+>   1. 把一个特写换成**只有这个产品才有的东西**（真实产品截图 / 具体业务示例 / 实际输出样本）
+>   2. 去掉一个 accent 使用点
+>
+> 完整灵魂测试与七大罪见 `craft/anti-ai-slop.md`。
+
+## 关联参考
+
+- `craft/anti-ai-slop.md` — 七大罪 + 80/20 灵魂法则
+- `craft/state-coverage.md` — 五状态覆盖契约（Loading/Empty/Error/Populated/Edge）
+- `craft/typography-hierarchy.md` — 排版层级
+- `craft/accessibility-baseline.md` — 无障碍基线
+- `craft/laws-of-ux.md` — 构图法则

package/skills/prototype/references/craft/accessibility-baseline.md

@@ -0,0 +1,71 @@
+# 无障碍基线（WCAG 2.2 最低 + 工艺超越）
+
+无障碍不是加分项，是底线。B 端产品的使用者能力与场景多样：键盘流操作、读屏软件、低视力、
+大龄员工。基线 = WCAG 2.2 AA 最小子集；标注"超越基线"的为工艺追求。
+
+## 颜色与对比度
+
+- **正文文字 ≥4.5:1**；大字（≥24px 或 ≥18.66px 加粗）≥3:1
+- **UI 组件与图形 ≥3:1**：边框、图标、焦点指示器、图表色块
+- 不以颜色为唯一信息通道：错误状态 = 错误色 + 图标 + 文字三件套
+- 超越基线：用 `color-mix()` 派生色调时，逐个派生色校验对比度
+
+## 触控目标
+
+- 所有可交互元素 ≥44×44px（指可点击区域，不是视觉尺寸；小图标用 padding 补足）
+- 相邻可点目标间距 ≥8px，防误触
+
+## 焦点可见性
+
+- 所有交互元素有可见焦点指示：3px focus-ring
+  （`outline: 3px solid var(--color-focus); outline-offset: 2px`）
+- 禁止裸写 `:focus { outline: none }` 而不提供替代样式
+- 超越基线：focus-ring 与相邻背景对比 ≥3:1
+
+## 表单标签
+
+- 每个 input 有关联 `<label for="...">`（或包裹式 label）
+- **placeholder 不是 label**——输入后即消失，读屏可及性差，无回忆线索
+- 必填用 `required` 属性 + 视觉星号双标记；错误信息用 `aria-describedby` 关联到字段
+
+## 键盘可操作性
+
+- 所有交互元素可 Tab 到达，顺序与视觉顺序一致（禁止滥用负 tabindex）
+- 仅 hover 触发的功能必须有键盘等价方式（hover 出现的操作按钮须可聚焦触发）
+- 自定义弹层/下拉须管理焦点：焦点圈闭于弹层内，关闭后焦点归还触发元素
+- 快捷键不与浏览器 / 读屏内置键冲突
+
+## ARIA 纪律
+
+- **原生 HTML 优先**：`<button>` 而非 `<div role="button">`；`<nav>` `<main>` `<table>` 而非 div 堆叠
+- 原生语义不足时才用 aria-label，且须有意义："关闭对话框" 而非 "按钮"
+- 图标按钮必须有可及名称（`aria-label` 或视觉隐藏文本）
+- 动态内容状态化：加载中 `aria-busy`、错误注入 `aria-live`、状态切换管理焦点
+  （详见 `state-coverage.md`）
+
+## 减少动态效果
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+保留承载信息的动效（进度、状态转场），去除装饰性动效（漂浮 blob、循环视差）。
+
+## 暗色模式（超越基线）
+
+- 避免纯黑 / 纯白：背景 `#0f0f0f`、前景 `#fafafa`，减轻边缘光晕
+- 边框用半透明色（`color-mix(in srgb, var(--color-text) 12%, transparent)`），明暗自适应
+- 暗色下阴影减弱，改用明度差 + 边框表达层级
+- 图表须备明暗双色板，暗色不直接复用亮色的高饱和色
+
+## 关联参考
+
+- `../checklist.md` — P0.8 data-testid（可测性是无障碍工具链的基础）
+- `state-coverage.md` — 状态切换的 ARIA 与焦点管理
+- `anti-ai-slop.md` — 装饰元素的取舍（blob/wave 同时是动效与无障碍负担）

package/skills/prototype/references/craft/anti-ai-slop.md

@@ -0,0 +1,87 @@
+# Anti-AI-Slop 工艺规则（品牌无关 · B 端适用）
+
+"Slop"指 AI 生成内容中看似正确、实则无灵魂、无产品辨识度的模式化产物。
+本规则与任何品牌无关，适用于 B 端企业产品的自包含 HTML 原型（零外部依赖、中文 UI）。
+
+## 七大罪（P0，grep 拦截）
+
+命中任一 = 返工。这是 AI 模板最易被识别的信号：
+
+### ① 靛蓝默认 accent
+AI 产物中最常见的颜色。黑名单 hex：
+`#6366f1` `#4f46e5` `#4338ca` `#3730a3` `#8b5cf6` `#7c3aed` `#a855f7`
+
+```bash
+grep -nE '#(6366f1|4f46e5|4338ca|3730a3|8b5cf6|7c3aed|a855f7)' *.html *.css
+```
+
+accent 必须来自项目设计系统（`design-system.md`）；无设计系统时须选有品牌理由的颜色。
+
+### ② 信任渐变
+紫→蓝、蓝→青的线性渐变是 AI 落地页的招牌。无 purple/violet 的 linear-gradient；
+确需渐变时用同色系明度渐变。
+
+### ③ emoji 图标
+标题/按钮/列表里的 ✨🚀🎯⚡🔥💡 = 一眼模板。图标用内联 SVG（`stroke="currentColor"`），或不用图标。
+
+### ④ 衬线误用
+设计 seed 绑定衬线字体时，h1/h2 必须用 `var(--font-display)`，正文用无衬线。
+全衬线页面像 Word 文档；全无衬线标题像默认模板。层级靠字体对比建立。
+
+### ⑤ AI 仪表盘卡
+圆角 + 左侧彩边框 + 图标 + 标题 + 数字 = 最典型的 AI 瓷砖。
+**二选一去掉**：去圆角（直角 + 细边框），或去左框（保留圆角 + 微弱阴影）。两者并存 = slop。
+
+### ⑥ 编造指标
+"10× faster"、"99.9% uptime"、"节省 80% 时间"无出处。
+数字必须来自 PRD / 实测 / 研究，否则改为定性描述或删除。
+
+### ⑦ 填充文案
+lorem ipsum、功能一/二/三、示例文本、placeholder。
+所有文案必须是贴合产品语境的真实感文案——假数据也要像真业务数据（行业术语、合理数量级、真实角色名）。
+
+## 软信号（P1）
+
+不致命，但累积产生模板感：
+
+- **标准分区无变化**：Hero→Features→Pricing→FAQ→CTA 原样照排，无节奏变化。见 checklist P1.2 节奏交替
+- **外部占位图 CDN**：`via.placeholder.com`、unsplash 外链等——违反零外部依赖要求，且一眼假。用内联 SVG 占位或纯色块
+- **>12 个裸 hex**：色彩体系失控，所有颜色应收进 `:root{}` 变量
+- **accent 用 6+ 次**：处处 accent = 没有 accent。见 checklist P0.3，每屏 ≤2 处
+
+## 打磨信号（P2）
+
+区分"能用"与"好用"的工艺细节：
+
+- **无 data-testid 的 section**：自动化测试无法定位，说明产物未考虑可测性
+- **装饰 blob / wave SVG**：渐变光斑、波浪分隔线——AI 生成页面的典型装饰。B 端用留白与结构分区
+- **完全对称无视觉张力**：一切居中、一切均分。见 `laws-of-ux.md` 冯·雷斯托夫效应——每页需要一个突出元素
+
+## 80/20 灵魂法则
+
+> ~80% 验证过的模式 + ~20% 独特选择。
+
+80% 是安全底盘：熟悉的布局、常规导航、标准表单模式——用户无需学习。
+
+20% 是灵魂来源，**选一处即可**（多处 = 噪声）：
+
+- **一个大胆视觉动作**：超大号数据可视化、非常规网格分割、独特的空状态插画
+- **微文案**："开始跟踪" > "开始使用"；"保存草稿" > "提交"。动词反映产品实际动作
+- **一个记忆点微交互**：状态转场、反馈动效（须尊重 `prefers-reduced-motion`，见 `accessibility-baseline.md`）
+- **一个只有用过产品的人才会放的细节**：快捷键提示（⌘K）、产品特有状态徽章、带排查链接的错误码
+
+## 灵魂测试
+
+> 截图后外人能认出是哪个产品 = 有灵魂。否则 = 模板货。
+
+## 方法论出处
+
+本规则集方法论参考 MIT 许可的开源项目 open-design（nexu-io/open-design）与 refero_skill，
+为 B 端企业原型场景（中文 UI、自包含 HTML、零外部依赖）重写适配。
+
+## 关联参考
+
+- `../checklist.md` — P0/P1/P2 质量检查清单
+- `typography-hierarchy.md` — 排版层级（ALL CAPS 字距等细节）
+- `laws-of-ux.md` — 冯·雷斯托夫效应等构图法则
+- `accessibility-baseline.md` — 微交互的动效约束