@pzy560117/codex-harness 0.1.0 → 0.1.1

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/skills-index.md

@@ -0,0 +1,112 @@
+---
+description: Index of active skills under .agents/skills
+---
+
+# Skills 索引
+
+所有 active skill package 都位于 `.agents/skills/`。
+
+说明:
+
+- `skills/` 是当前主入口。
+- `workflows/` 只保留独立 workflow 文档。
+- 与 `skills/` 重复的 workflow 平铺副本已移到 `archive/workflows/skill-mirrors/`。
+
+## 核心开发
+
+| Skill | 目录 | 描述 |
+|-------|------|------|
+| **planner** | `planner/` | 复杂功能规划与实施步骤拆解（Opus 模型） |
+| **architect** | `architect/` | 系统架构设计与技术选型（Opus 模型） |
+| **Glue Coding** | `glue-coding/` | 胶水编程开发方法 - 通过组合现有成熟库快速实现功能 |
+| **coding-standards** | `coding-standards/` | TypeScript/JavaScript/React/Node.js 通用编码标准与最佳实践 |
+| **backend-patterns** | `backend-patterns/` | 后端架构模式、API 设计、数据库优化 |
+| **frontend-patterns** | `frontend-patterns/` | React/Next.js 前端开发模式、状态管理、性能优化 |
+
+## 测试与质量
+
+| Skill | 目录 | 描述 |
+|-------|------|------|
+| **tdd-guide** | `tdd-guide/` | TDD 专家，强制 write-tests-first，确保 80%+ 覆盖率（Opus 模型） |
+| **tdd-workflow** | `tdd-workflow/` | TDD 工作流，包含 unit/integration/E2E 测试，80%+ 覆盖率 |
+| **e2e-runner** | `e2e-runner/` | Playwright E2E 测试专家 - 测试创建/维护/Flaky 管理/制品上传 |
+| **browser-e2e-testing** | `browser-e2e-testing/` | 使用 browser_subagent (devtools MCP) 进行全量前端 E2E 测试 |
+| **code-reviewer** | `code-reviewer/` | 代码审查专家 - 质量/安全/可维护性检查 |
+| **Allure Report** | `allure-report/` | 生成和查看 Allure 测试报告 |
+
+## 安全
+
+| Skill | 目录 | 描述 |
+|-------|------|------|
+| **security-reviewer** | `security-reviewer/` | 安全漏洞检测与修复专家 - OWASP Top 10 / Secrets / SSRF / 注入（Opus 模型） |
+| **security-review** | `security-review/` | 安全检查清单与模式 - 认证/输入验证/API 端点/敏感数据 |
+
+## 构建与维护
+
+| Skill | 目录 | 描述 |
+|-------|------|------|
+| **build-error-resolver** | `build-error-resolver/` | 构建/TypeScript 错误修复专家，最小 diff 快速变绿 |
+| **refactor-cleaner** | `refactor-cleaner/` | 死代码清理与重构专家 - knip/depcheck/ts-prune 分析（Opus 模型） |
+| **doc-updater** | `doc-updater/` | 文档与 Codemap 更新专家 |
+| **harness-surface-sync** | `harness-surface-sync/` | 一次性审计并同步 harness runtime、docs/testing、templates、workflows、config、skills 与 package-assets 镜像 |
+
+## Git 与自动化
+
+| Skill | 目录 | 描述 |
+|-------|------|------|
+| **Auto Review and Commit** | `auto-commit/` | 检查当前工作区、补齐必要同步、生成提交并推送；缺少远程仓库时可用 GitHub CLI 自动建仓 |
+| **ai-config-git-sync** | `ai-config-git-sync/` | 审计、更新并 fan-out 共享 AI workflow/config 到多个 Git 项目，支持 drift 检查、同步分支、push 和 PR |
+| **git-xianyu-analyzer** | `git-xianyu-analyzer/` | 克隆 Git 仓库→清理→分析→生成咸鱼销售文案 |
+
+## 设计与 UI/UX
+
+| Skill | 目录 | 描述 |
+|-------|------|------|
+| **ui-ux-pro-max** | `ui-ux-pro-max/` | UI/UX 设计智能 - 67 种风格/96 色板/57 字体搭配/99 UX 指南 |
+| **frontend-design** | `frontend-design/` | 前端界面设计原则，定义生产级视觉方向和差异化美学 |
+| **impeccable** | `impeccable/` | 上游 Impeccable 前端设计 skill：设计语言、视觉层级、排版、布局、色彩、动效、响应式与 polish |
+| **Taste Skill** | `taste-skill/` | 上游 Leonxlnx Taste Skill 主 skill，内部 name 为 `design-taste-frontend`，用于审美判断和抗 AI 默认 UI |
+| **brand-design-md** | `brand-design-md/` | 根据 Apple/Stripe/Notion/Linear/Claude 等品牌名称拉取 getdesign.md/awesome-design-md 的 DESIGN.md |
+| **baseline-ui** | `baseline-ui/` | UI Skills 子 skill：Tailwind、组件结构、状态、可访问 primitive 和 UI 工程基线 |
+| **fixing-accessibility** | `fixing-accessibility/` | UI Skills 子 skill：键盘、焦点、ARIA、语义和表单可访问性修复 |
+| **fixing-metadata** | `fixing-metadata/` | UI Skills 子 skill：页面 title/meta/OG/social card/favicon |
+| **fixing-motion-performance** | `fixing-motion-performance/` | UI Skills 子 skill：动画性能、reduced motion、layout thrashing 检查 |
+| **better-icons** | `better-icons/` | 通过 better-icons/Iconify 搜索并获取 SVG 图标 |
+| **ai-ui-prompts** | `ai-ui-prompts/` | AI 生图/编辑提示词模板，按需求矩阵、CSS/token 和状态生成界面图 |
+| **frontend-first-workflow** | `frontend-first-workflow/` | 前端先行流程：需求映射→难点研究→AI 生图→图片评审→图转规格→前端实现 |
+
+说明：`motion-ai-kit` 是 Motion 官方 Motion+ AI Kit，需要 Motion+ token 通过官方 installer 安装；公开 GitHub 未提供可直接复制的 skill 包，当前未列为 active skill。
+
+## 产品与 PRD
+
+| Skill | 目录 | 描述 |
+|-------|------|------|
+| **prd-writer-skill** | `prd-writer-skill/` | PRD 写作工作流：需求采集→Feature List→PRD 文档→可交互原型（集成 UI/UX 设计系统） |
+| **requirements-design-template** | `requirements-design-template/` | 需求与设计文档模板，覆盖目标/非目标、业务流程、状态、权限、数据字典、验收和设计方案 |
+| **page-spec-template** | `page-spec-template/` | 页面规格模板，覆盖页面状态、交互状态、字段规格、操作反馈和权限视图 |
+| **business-rule-spec** | `business-rule-spec/` | 业务规则规格模板，覆盖前置条件、后置动作、批量操作、导入导出和敏感操作确认 |
+| **interaction-detail-spec** | `interaction-detail-spec/` | 交互细节规格模板，覆盖键盘、快捷键、手势、拖拽、动效、防抖节流和焦点管理 |
+| **data-flow-spec** | `data-flow-spec/` | 数据流转规格模板，覆盖数据依赖、联动、缓存、更新、冲突和同步机制 |
+
+## 规格与评审
+
+| Skill | 目录 | 描述 |
+|-------|------|------|
+| **OpenSpec Architecture Review** | `openspec-architecture-review/` | OpenSpec 规格架构深度评审与完善工作流 |
+| **Eval Harness** | `eval-harness/` | AI 会话评估框架 (Eval-Driven Development) |
+
+## 数据库
+
+| Skill | 目录 | 描述 |
+|-------|------|------|
+| **clickhouse-io** | `clickhouse-io/` | ClickHouse 数据库模式、查询优化、分析与数据工程最佳实践 |
+
+## 工具与辅助
+
+| Skill | 目录 | 描述 |
+|-------|------|------|
+| **strategic-compact** | `strategic-compact/` | 在逻辑边界建议手动 compact 以保留上下文 |
+| **continuous-learning** | `continuous-learning/` | 从 Claude Code 会话中自动提取可复用模式并保存为 skill |
+| **skill-creator** | `skill-creator/` | 创建和打包新 skill 的工作流与脚本 |
+| **Example Skill** | `example-skill/` | 示例技能，展示如何创建和使用技能文件 |
+| **Project Guidelines (Example)** | `project-guidelines-example/` | 项目指南示例模板（基于 Zenith 项目） |

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/spec-based-review/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: spec-based-review
+description: 以 spec.md 为基准评审 design.md 和 tasks.md 的一致性与最佳实践
+---
+
+# Spec-Based Review（基于规格的反向评审）
+
+> 目标：以 spec.md 为 **唯一真相来源**，验证 design.md 与 tasks.md 是否完整覆盖、表述一致、符合最佳实践
+
+---
+
+## 工作流程
+
+```mermaid
+flowchart LR
+    A[读取 spec.md] --> B[提取 Requirements/Scenarios]
+    B --> C[比对 design.md]
+    C --> D[比对 tasks.md]
+    D --> E[输出评审报告]
+```
+
+---
+
+## 适用场景
+
+- spec.md 已完成或更新后，需验证 design/tasks 是否同步
+- 发现 design/tasks 与实际实现不一致时，回溯到 spec 重新对齐
+- 确保文档体系遵循最佳实践
+
+---
+
+## 评审步骤
+
+### 步骤 1：读取 spec.md
+
+**提取清单**：
+
+| 类型 | 提取项 |
+|------|--------|
+| 术语定义 | 所有 `> **术语**` 定义块 |
+| Requirements | 所有 `### Requirement:` 章节 |
+| Scenarios | 每个 Requirement 下的 `#### Scenario:` |
+| 附录 | 配置示例、关键词集合等 |
+
+### 步骤 2：对齐 design.md
+
+| 检查项 | 验证方法 | 预期结果 |
+|--------|----------|----------|
+| **Decisions 覆盖** | 每个 spec Requirement 是否有对应 Decision | 1:1 或 N:1 映射 |
+| **术语一致** | design 中使用的术语是否与 spec 定义一致 | 无偏差 |
+| **Goals 对齐** | design Goals 是否覆盖 spec 中的核心 Requirements | 无遗漏 |
+| **Non-Goals 合理** | Non-Goals 是否与 spec 范围冲突 | 无冲突 |
+| **Compatibility 完整** | 每个 spec 中涉及现有组件的 Requirement 是否有兼容性说明 | 有对应条目 |
+| **Open Questions 状态** | 所有问题是否已关闭或有明确待办 | 无悬而未决 |
+
+### 步骤 3：对齐 tasks.md
+
+| 检查项 | 验证方法 | 预期结果 |
+|--------|----------|----------|
+| **任务覆盖** | 每个 spec Requirement 是否有对应任务 | 1:N 映射 |
+| **追溯标注** | 任务是否有 `_Requirements: X.Y_` 标注 | 全部有标注 |
+| **场景对应** | spec Scenarios 是否有对应测试任务 | 有 Validation 任务 |
+| **依赖顺序** | 任务顺序是否符合 spec 中定义的逻辑依赖 | 无循环、顺序合理 |
+| **验证任务** | 每个可测试 Scenario 是否有测试任务 | 有 `_Validates:_` 标注 |
+
+### 步骤 4：最佳实践检查
+
+#### design.md 最佳实践
+
+- [ ] 有 Context 章节说明背景
+- [ ] Goals/Non-Goals 明确边界
+- [ ] Decisions 使用主动语态
+- [ ] Compatibility 覆盖五维度（入口/配置/行为/日志/依赖）
+- [ ] Risks/Trade-offs 有缓解措施
+- [ ] Migration Plan 分步骤渐进
+
+#### tasks.md 最佳实践
+
+- [ ] Implementation 与 Validation 分组
+- [ ] 任务编号连续（1, 1.1, 1.2, 2...）
+- [ ] 每个任务有 `_Requirements:_` 追溯
+- [ ] 验证任务有 `_Validates:_` 标注
+- [ ] 高风险任务有 Checkpoint（确保测试通过）
+- [ ] 可选任务标记 `*`
+
+---
+
+## 评审报告模板
+
+```markdown
+# Spec-Based Review: [change-name]
+
+## 1. 快速摘要
+
+| 维度 | 状态 | 问题数 |
+|------|------|--------|
+| design.md 覆盖度 | ✅/⚠️/❌ | N/M Requirements |
+| tasks.md 覆盖度 | ✅/⚠️/❌ | N/M Requirements |
+| 术语一致性 | ✅/⚠️/❌ | N |
+| 最佳实践 design | ✅/⚠️/❌ | N/M 项 |
+| 最佳实践 tasks | ✅/⚠️/❌ | N/M 项 |
+
+## 2. 覆盖度矩阵
+
+| spec Requirement | design Decision | tasks 任务 | 状态 |
+|------------------|-----------------|------------|------|
+| [Requirement 1] | [Decision X] | 1.1, 1.2 | ✅ |
+| [Requirement 2] | ❌ 缺失 | 1.3 | ⚠️ |
+
+## 3. 术语偏差
+
+| 术语 | spec 定义 | design/tasks 用法 | 建议 |
+|------|-----------|-------------------|------|
+| [术语 A] | [定义] | [实际用法] | [修正建议] |
+
+## 4. 最佳实践差距
+
+### design.md
+- ⚠️ [缺失项]
+
+### tasks.md
+- ⚠️ [缺失项]
+
+## 5. 改进建议
+
+- [ ] 建议 1
+- [ ] 建议 2
+
+## 6. 下一步
+
+- 若无问题：文档体系一致，可进入 EXECUTION
+- 若有问题：按建议更新后重新 review
+```
+
+---
+
+## 严重级别定义
+
+| 级别 | 标记 | 定义 | 处理要求 |
+|------|------|------|----------|
+| Critical | 🔴 | spec 有 Requirement 但 design/tasks 无覆盖 | 必须补齐 |
+| Warning | 🟡 | 术语不一致或追溯标注缺失 | 建议修复 |
+| Info | 🟢 | 最佳实践建议 | 可选优化 |
+
+---
+
+## 快速检查清单
+
+### spec.md → design.md
+
+- [ ] 每个 Requirement 有 Decision 覆盖
+- [ ] 术语定义被正确引用
+- [ ] Goals 覆盖核心 Requirements
+- [ ] Compatibility 覆盖涉及现有组件的 Requirements
+
+### spec.md → tasks.md
+
+- [ ] 每个 Requirement 有实现任务
+- [ ] 每个可测试 Scenario 有验证任务
+- [ ] 任务有 `_Requirements:_` 追溯标注
+- [ ] 验证任务有 `_Validates:_` 标注
+
+---
+
+## 与其他工作流的关系
+
+```mermaid
+graph TB
+    A[spec.md 创建/更新] --> B[spec-based-review]
+    B --> C{一致?}
+    C -->|否| D[更新 design/tasks]
+    D --> B
+    C -->|是| E[spec-review 整体评审]
+    E --> F[开始实现]
+```
+
+- **前置**：spec.md 已完成或更新
+- **后续**：通过后可直接实现或再做 `/spec-review` 整体评审

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/spec-review/SKILL.md

@@ -0,0 +1,395 @@
+---
+name: spec-review
+description: 规格评审与 reviewspec 工作流，通过 #spec-review 引用；用于 .kiro/specs 下 requirements/design/tasks 与代码对齐审查
+---
+
+# Spec Review（规格评审）
+
+> 目标：对需求/设计/任务进行一致性审查，并与现有代码、测试入口和约束对齐
+
+---
+
+## 工作流程
+
+```mermaid
+flowchart LR
+    A[读取规格] --> B[提取关键点]
+    B --> C[追溯矩阵构建]
+    C --> D[代码对齐检查]
+    D --> E[输出评审报告]
+```
+
+---
+
+## 输入范围
+
+- 规格路径：`.kiro/specs/<spec-name>/`
+- 必读文件：
+  - `requirements.md` - 需求文档
+  - `design.md` - 设计文档
+  - `tasks.md` - 任务清单
+
+---
+
+## 评审步骤
+
+### 步骤 1：读取规格文档
+
+**提取内容清单**：
+
+| 文档 | 提取项 |
+|------|--------|
+| requirements.md | 用户故事、验收标准（EARS 格式）、术语表、非功能需求 |
+| design.md | 架构图、组件接口、数据模型、正确性属性、错误处理、测试策略 |
+| tasks.md | 任务层级、依赖关系、属性测试标注、可选任务标记 |
+
+### 步骤 2：构建追溯矩阵
+
+建立 Requirements → Design → Tasks 的映射关系：
+
+```markdown
+| 需求ID | 验收标准 | 设计章节 | 正确性属性 | 任务编号 | 状态 |
+|--------|----------|----------|------------|----------|------|
+| 1.1 | WHEN... | 组件A | Property 1 | 1.1, 1.2 | ✅ |
+| 1.2 | WHILE... | 组件A | Property 2 | 1.3 | ⚠️ 缺失 |
+```
+
+**检查项**：
+- [ ] 每个验收标准都有对应的设计章节
+- [ ] 可测试的验收标准都有对应的正确性属性
+- [ ] 每个正确性属性都有对应的任务
+- [ ] 任务的 `_Requirements: X.Y_` 标注与需求对应
+
+### 步骤 3：EARS 格式合规检查
+
+验证验收标准是否符合 EARS 模式：
+
+| 模式 | 格式 | 检查点 |
+|------|------|--------|
+| Ubiquitous | THE [系统] SHALL [响应] | 无条件触发 |
+| Event-driven | WHEN [事件], THE [系统] SHALL [响应] | 有明确触发事件 |
+| State-driven | WHILE [状态], THE [系统] SHALL [响应] | 有持续状态 |
+| Unwanted | IF [异常], THEN THE [系统] SHALL [响应] | 异常处理 |
+| Optional | WHERE [条件], THE [系统] SHALL [响应] | 可选功能 |
+
+**常见问题**：
+- ❌ 使用模糊词汇（"快速"、"合理"、"适当"）
+- ❌ 使用代词（"它"、"这个"）
+- ❌ 缺少可测试的量化指标
+- ❌ 负面陈述（应改为正面陈述）
+
+### 步骤 4：正确性属性检查
+
+验证 design.md 中的 Correctness Properties：
+
+**必须包含**：
+- [ ] 属性编号（Property 1, 2, ...）
+- [ ] 全称量化语句（"For any..."）
+- [ ] 需求追溯（"Validates: Requirements X.Y"）
+
+**属性类型覆盖检查**：
+
+| 类型 | 适用场景 | 示例 |
+|------|----------|------|
+| Round-trip | 序列化/解析 | `parse(format(x)) == x` |
+| Invariant | 状态转换 | 操作后保持某属性不变 |
+| Idempotence | 重复操作 | `f(f(x)) == f(x)` |
+| Metamorphic | 关系验证 | `len(filter(x)) <= len(x)` |
+
+### 步骤 5：代码与测试入口对齐
+
+**搜索现有代码**：
+```bash
+# 搜索涉及的模块
+rg -l "模块名" src/
+
+# 搜索测试入口
+rg -l "describe|test|it" tests/
+
+# 搜索全局 setup
+rg "globalSetup|setupFiles" vitest*.config.ts
+```
+
+**检查项**：
+- [ ] 设计中的组件路径与现有代码结构一致
+- [ ] 测试策略与现有测试框架配置兼容
+- [ ] 环境变量与 `.env.example` 对齐
+- [ ] 导出路径与 `src/index.ts` 一致
+
+### 步骤 6：任务拆解审查
+
+**任务结构检查**：
+- [ ] 任务编号连续（1, 1.1, 1.2, 2, 2.1...）
+- [ ] 子任务在父任务下方
+- [ ] 可选任务标记 `*`（如 `[ ]* 1.2 编写属性测试`）
+- [ ] 每个任务有 `_Requirements: X.Y_` 标注
+
+**测试覆盖检查**：
+- [ ] 属性测试任务引用了 design.md 中的 Property
+- [ ] 属性测试使用 fast-check，最少 100 次迭代
+- [ ] 有 Checkpoint 任务（确保测试通过）
+
+**依赖顺序检查**：
+- [ ] 核心实现在测试之前
+- [ ] 集成任务在单元任务之后
+- [ ] 无循环依赖
+
+---
+
+## 输出格式
+
+### 评审报告模板
+
+```markdown
+# Spec Review Report: [spec-name]
+
+## 评审概要
+
+| 维度 | 状态 | 问题数 |
+|------|------|--------|
+| 追溯完整性 | ✅/⚠️/❌ | N |
+| EARS 合规性 | ✅/⚠️/❌ | N |
+| 属性覆盖 | ✅/⚠️/❌ | N |
+| 代码对齐 | ✅/⚠️/❌ | N |
+| 任务结构 | ✅/⚠️/❌ | N |
+
+## 问题清单
+
+| 严重级别 | 来源 | 问题描述 | 建议修复 |
+|----------|------|----------|----------|
+| 🔴 Critical | requirements.md#1.2 | 验收标准不可测试 | 添加量化指标 |
+| 🟡 Warning | design.md#Property3 | 缺少需求追溯 | 添加 Validates |
+| 🟢 Info | tasks.md#2.1 | 建议拆分子任务 | 可选优化 |
+
+## 追溯矩阵
+
+[完整的追溯矩阵表格]
+
+## 风险清单
+
+| 风险类型 | 描述 | 影响 | 缓解措施 |
+|----------|------|------|----------|
+| 实现风险 | [描述] | [影响] | [措施] |
+| 测试风险 | [描述] | [影响] | [措施] |
+| 兼容性风险 | [描述] | [影响] | [措施] |
+
+## 最小修订建议
+
+1. [必须修改项 1]
+2. [必须修改项 2]
+```
+
+---
+
+## 严重级别定义
+
+| 级别 | 标记 | 定义 | 处理要求 |
+|------|------|------|----------|
+| Critical | 🔴 | 阻塞实现或导致错误 | 必须修复后才能开始实现 |
+| Warning | 🟡 | 影响质量或可维护性 | 建议修复，可带风险实现 |
+| Info | 🟢 | 优化建议 | 可选修复 |
+
+---
+
+## 快速检查清单
+
+### requirements.md 检查
+
+- [ ] 有 Introduction 和 Glossary
+- [ ] 每个 Requirement 有 User Story
+- [ ] 验收标准使用 EARS 格式
+- [ ] 无模糊词汇和代词
+- [ ] 术语表定义了所有系统名称
+
+### design.md 检查
+
+- [ ] 有架构图（Mermaid）
+- [ ] 有组件接口定义（TypeScript）
+- [ ] 有数据模型
+- [ ] 有 Correctness Properties 章节
+- [ ] 每个 Property 有全称量化和需求追溯
+- [ ] 有 Error Handling 章节
+- [ ] 有 Testing Strategy 章节
+
+### tasks.md 检查
+
+- [ ] 有 Overview
+- [ ] 任务编号连续
+- [ ] 有 `_Requirements: X.Y_` 标注
+- [ ] 属性测试任务引用 Property
+- [ ] 有 Checkpoint 任务
+- [ ] 可选任务标记 `*`
+
+---
+
+## 注意事项
+
+1. **只做评审与对齐**，不直接实现代码
+2. **如规格缺少必需文档**，先补齐缺口再评审
+3. **输出内容保持简洁**，聚焦可执行的修复建议
+4. **优先处理 Critical 问题**，Warning 和 Info 可延后
+5. **评审结果记录到 MCP/记忆系统**，便于后续追踪
+
+---
+
+## 与其他工作流的关系
+
+```mermaid
+graph TB
+    A[requirements-design-template] --> B[spec-review]
+    B --> C{问题?}
+    C -->|有| D[修订规格]
+    D --> B
+    C -->|无| E[开始实现]
+    E --> F[project-planning]
+```
+
+- **前置**：使用 `requirements-design-template` 创建规格
+- **后续**：评审通过后使用 `project-planning` 细化计划
+
+---
+
+## OpenSpec 变更评审（扩展）
+
+> 适用于 `openspec/changes/<change-name>/` 结构的规格评审。
+
+### OpenSpec 结构
+
+```
+openspec/changes/<change-name>/
+├── proposal.md      # 变更背景与影响
+├── design.md        # 设计决策与迁移计划
+├── tasks.md         # 实现与验证任务
+└── specs/
+    └── <spec-name>/
+        └── spec.md  # 规格详情 (Requirements + Scenarios)
+```
+
+### OpenSpec 评审步骤
+
+#### 步骤 O1：结构检查
+1. 验证必要文件存在：`proposal.md` / `design.md` / `tasks.md` / `specs/*/spec.md`
+2. 检查 `design.md` 中 Open Questions 是否已解决
+
+#### 步骤 O2：覆盖度分析
+1. 提取 `design.md` 中的 Decisions 列表
+2. 提取 `spec.md` 中的 Requirements 列表
+3. 验证每个 Decision 有对应的 Requirement 覆盖
+
+#### 步骤 O3：代码扫描
+1. 从 spec.md 提取涉及的组件/接口名称（类名、函数名、配置文件名）
+2. 使用 `grep_search` 在项目中搜索现有实现
+3. 记录：存在性、实现位置、接口签名
+
+#### 步骤 O4：兼容性分析
+
+| 兼容维度 | 分析要点 | 评估输出 |
+|----------|----------|----------|
+| **入口兼容** | 现有 API 签名是否保持？调用方是否需改动？ | 风险等级 + 迁移成本 |
+| **配置兼容** | 现有配置结构是否保持？新字段是否向后兼容？ | 配置迁移方案 |
+| **行为兼容** | 默认模式下行为是否与当前一致？（无感知升级） | 回归测试范围 |
+| **日志兼容** | 现有日志语义是否保留？新字段是否破坏解析？ | 日志消费方影响 |
+| **依赖兼容** | 是否引入新依赖？是否影响现有版本？ | 依赖变更清单 |
+
+#### 步骤 O5：设计质量评估
+
+| 评估项 | 评估问题 | 评分标准 |
+|--------|----------|----------|
+| **问题解决度** | 设计是否真正解决 proposal 描述的问题？ | 根因解决 / 表象缓解 / 未解决 |
+| **过度设计** | 是否引入超出当前需求的复杂度？ | 恰好 / 轻微 / 严重 |
+| **可扩展性** | 未来类似需求是否可复用此设计？ | 可复用 / 需改造 / 不可复用 |
+| **可测试性** | 每个 Requirement 是否可直接编写测试用例？ | 全部可测 / 部分抽象 / 难以验证 |
+| **职责单一** | 变更是否聚焦单一关注点？ | 单一 / 轻微耦合 / 严重耦合 |
+
+#### 步骤 O6：改进建议生成
+
+| 问题类型 | 改进建议 |
+|----------|----------|
+| 术语模糊 | 补充术语定义章节 |
+| 场景抽象 | 细化为具体 hook/参数/输入输出 |
+| 缺少示例 | 补充配置/代码片段 |
+| 兼容风险 | 补充 Compatibility 章节到 design.md |
+| 覆盖遗漏 | 新增对应 Requirement |
+| Open Questions 未关闭 | 提供结论建议 |
+
+### OpenSpec 评审报告模板
+
+```markdown
+# Spec Review: <change-name>
+
+## 1. 快速摘要
+
+| 维度 | 状态 |
+|------|------|
+| 结构完整性 | ✅ / ⚠️ / ❌ |
+| 覆盖度 | X / Y Decisions 已覆盖 |
+| 兼容性风险 | 低 / 中 / 高 |
+| 设计质量 | 良好 / 需改进 / 需重设计 |
+
+## 2. 兼容性分析
+
+| 兼容维度 | 风险 | 迁移成本 | 建议 |
+|----------|------|----------|------|
+| 入口兼容 | | | |
+| 配置兼容 | | | |
+| 行为兼容 | | | |
+| 日志兼容 | | | |
+| 依赖兼容 | | | |
+
+## 3. 设计质量
+
+| 评估项 | 评分 | 说明 |
+|--------|------|------|
+| 问题解决度 | | |
+| 过度设计 | | |
+| 可扩展性 | | |
+| 可测试性 | | |
+| 职责单一 | | |
+
+## 4. 代码对齐
+
+| spec 组件 | 现有实现 | 差距 | 实现难度 |
+|-----------|----------|------|----------|
+
+## 5. 改进建议
+
+- [ ] 建议 1
+- [ ] 建议 2
+
+## 6. 下一步
+
+- 若改进建议为空：可进入 EXECUTION
+- 若有改进建议：先更新 spec，再重新 review
+```
+
+### OpenSpec 快速检查清单
+
+#### 结构
+- [ ] proposal.md 存在
+- [ ] design.md 存在
+- [ ] tasks.md 存在
+- [ ] specs/*/spec.md 存在
+
+#### 覆盖度
+- [ ] 所有 Decisions 有对应 Requirement
+- [ ] Open Questions 已关闭或有明确待办
+
+#### 兼容性
+- [ ] 入口 API 签名不变
+- [ ] 配置向后兼容
+- [ ] 默认行为无感知升级
+- [ ] 日志语义保留
+- [ ] 无新外部依赖（或已评估）
+
+#### 设计质量
+- [ ] 解决 proposal 描述的根本问题
+- [ ] 无过度设计
+- [ ] 可扩展复用
+- [ ] 场景可直接测试
+- [ ] 职责单一
+
+#### 规格内容
+- [ ] 抽象术语有定义
+- [ ] 场景有具体输入/输出
+- [ ] 提供配置示例
+- [ ] 字段说明完整