specwf 0.2.0

package/dist/templates/artifacts/context.md

@@ -0,0 +1,151 @@
+# Phase Context: {{phase-name}}
+
+> **填表指引**：本文档在 Phase 启动时编写，记录该 Phase 的目标、关键决策和 Change 拆分。它既是实现者的工作指引，也是未来回顾时的依据。每节附填写指引。
+
+---
+
+> **讨论时间**: {{date}}
+> **决策来源**: {{会议链接 / RFC 文档 / 讨论记录链接}}
+
+---
+
+## Phase 目标
+
+<!--
+填写指引：
+1. 本 Phase 要完成什么？产出的 Changes 加起来覆盖了什么能力？
+2. 一句话概括目标，然后用 2-3 条具体说明。
+3. 本 Phase 的边界在哪里？
+
+格式示例：
+本 Phase 实现列表页滚动性能优化，具体包括：
+- 新增 OptimizedList 组件封装 FlatList
+- 新增 useScrollPerformance 滚动性能监控 hook
+- 更新 Performance Reporter 支持新数据字段
+- 不涉及后端 API 变更
+-->
+
+{{phase-goal}}
+
+---
+
+## 实现决策
+
+<!--
+填写指引：
+记录讨论中产生的关键决策。每个决策有独立编号（D1, D2, ...）。
+包含决策内容、理由、影响范围。
+
+不是所有实现细节都需要记录——只记录：
+- 有多个候选方案时做的选择
+- 影响后续 phase 或项目架构的决策
+- 与直觉相反的权衡
+-->
+
+### D1: {{决策标题}}
+
+- **决策**: {{具体的决策内容。做什么？选什么方案？}}
+- **理由**: {{为什么选这个决策？关键约束是什么？}}
+- **影响文件/模块**: {{受影响的文件或模块列表}}
+
+### D2: {{决策标题}}
+
+- **决策**: {{具体的决策内容}}
+- **理由**: {{决策理由}}
+- **影响文件/模块**: {{受影响的文件或模块列表}}
+
+### D3: {{决策标题}}
+
+- **决策**: {{具体的决策内容}}
+- **理由**: {{决策理由}}
+- **影响文件/模块**: {{受影响的文件或模块列表}}
+
+---
+
+## Decisions
+
+<!--
+填写指引：
+所有锁定决策的汇总表格。与上面的 D1/D2/... 章节保持一致。
+-->
+
+| 编号 | 决策 | 理由 | 状态 |
+|---|---|---|---|
+| D1 | {{决策摘要}} | {{理由摘要}} | <span style="color:green">✓ Locked</span> |
+| D2 | {{决策摘要}} | {{理由摘要}} | <span style="color:green">✓ Locked</span> |
+| D3 | {{决策摘要}} | {{理由摘要}} | <span style="color:green">✓ Locked</span> |
+
+> 状态说明：**Locked** = 已确定且不可逆；**Deferred** = 延迟到后续 phase；**Open** = 待进一步讨论。
+
+---
+
+## Deferred Ideas
+
+<!--
+填写指引：
+列出讨论过但决定暂不实施的想法。这是"idea parking lot"——防止好想法丢失。
+每个 idea 附：内容、暂缓原因、可能的实施时机（可选）。
+-->
+
+1. **{{idea-title-1}}**：{{idea 描述}}
+   - 暂缓原因：{{为什么现在不做}}
+   - 可能时机：{{optional: 什么条件下可以重新考虑}}
+
+2. **{{idea-title-2}}**：{{idea 描述}}
+   - 暂缓原因：{{为什么现在不做}}
+   - 可能时机：{{optional: 什么条件下可以重新考虑}}
+
+---
+
+## Claude's Discretion
+
+<!--
+填写指引：
+列出实现者在实现过程中可以自行判断而不需要额外沟通的方面。
+这给了实现者灵活性，同时避免"没问过"造成的意外。
+-->
+
+- {{实现者可自行决定的方面 1，如：错误处理方式的选择}}
+- {{实现者可自行决定的方面 2，如：次要 UI 细节的视觉调整}}
+- {{实现者可自行决定的方面 3，如：局部变量命名风格}}
+
+---
+
+## Change 拆分
+
+<!--
+填写指引：
+将 Phase 拆分为 1-3 个 Change。每个 Change 是一个独立可交付单元。
+格式：编号 + 名称 + 简短描述。
+如果 Change 之间有依赖关系，用箭头标注。
+
+格式示例：
+这个 Phase 包含 2 个 Change：
+
+1. **optimize-list-scroll** ← 核心性能优化（先做）
+   - 描述：实现 OptimizedList 组件 + getItemLayout 配置
+   - 依赖：无（基础 change）
+
+2. **add-scroll-metrics** ← 监控能力增强（后做）
+   - 描述：新增 useScrollPerformance hook + 数据上报
+   - 依赖：optimize-list-scroll（需要 OptimizedList 组件）
+-->
+
+1. **{{change-name-1}}** — {{change-description-1}}
+   - 依赖：{{dependencies}} <!-- 无则填"无" -->
+
+2. **{{change-name-2}}** — {{change-description-2}}
+   - 依赖：{{dependencies}}
+
+---
+
+## 非目标
+
+<!--
+填写指引：
+明确不属于本 Phase 的工作项。这些可能在 roadmap 上但不在本轮。
+-->
+
+- {{非目标 1：为什么不在本 phase 做}}
+- {{非目标 2：为什么不在本 phase 做}}
+- {{非目标 3：为什么不在本 phase 做}}

package/dist/templates/artifacts/design.md

@@ -0,0 +1,224 @@
+# Design: {{name}}
+
+> **填表指引**：本文档是 Change Design，在 proposal 批准后编写，描述如何实现。每节均附填写指引，请按指引填写。写完此文档后进入 tasks 拆分解段。
+
+---
+
+## 背景与目标
+
+<!--
+填写指引：
+1. 简要描述背景——什么上下文？有什么约束？
+2. 本设计的核心目标是什么？不超过 3 条。
+3. 与 proposal 中的 Intent 和 Must-haves 保持一致。
+
+示例：
+当前 FlatList 在 1000+ 条数据场景下帧率降至 20fps。
+本设计目标是：
+- 通过 getItemLayout + 固定行高将帧率恢复至 55fps+
+- 新增滚动性能监控，为后续优化提供数据依据
+- 不改变现有数据获取和渲染逻辑
+-->
+
+{{background-and-goals}}
+
+---
+
+## 技术方案
+
+### 架构图
+
+<!--
+填写指引：
+用 ASCII art 绘制模块/组件关系图，展示：
+- 新增模块与现有模块的关系
+- 数据流方向（用箭头标注）
+- 文件/模块边界
+
+示例：
+```
+┌─────────────────────────────────────────────────┐
+│                   页面层                         │
+│  ┌──────────┐    ┌──────────────────┐           │
+│  │ PageHome │───>│ OptimizedList    │           │
+│  │          │    │  (新增 wrapper)   │           │
+│  └──────────┘    └────────┬─────────┘           │
+│                           │                      │
+│                    ┌──────▼─────────┐            │
+│                    │ useScrollPerf  │            │
+│                    │ (新增 hook)     │            │
+│                    └──────┬─────────┘            │
+└───────────────────────────┼──────────────────────┘
+                            │
+                  ┌─────────▼─────────┐
+                  │   Performance     │
+                  │   Reporter        │
+                  │   (已有, 扩展)     │
+                  └───────────────────┘
+```
+
+绘图原则：
+- 方框标注模块/文件/组件
+- 箭头标注数据流或控制流
+- 标注"新增"、"修改"、"已有"区分
+-->
+
+```text
+{{architecture-diagram}}
+```
+
+### 核心数据结构
+
+<!--
+填写指引：
+列出本设计新增或修改的关键类型/接口/数据结构定义。
+用 TypeScript 接口格式展示。每个类型附简要说明。
+
+格式示例：
+```typescript
+// 列表配置接口（新增）
+interface ListOptimizationConfig {
+  /** 固定行高，单位 px。设此值启用 getItemLayout */
+  itemHeight?: number;
+  /** 可见窗口外预渲染的行数（默认 10） */
+  windowSize?: number;
+  /** 是否启用滚动性能采集 */
+  enableScrollMetrics?: boolean;
+}
+
+// 滚动性能快照（新增）
+interface ScrollPerfSnapshot {
+  avgFps: number;
+  droppedFrames: number;
+  totalFrames: number;
+  scrollDistance: number;
+  timestamp: number;
+}
+```
+-->
+
+{{data-structures}}
+
+### 数据流
+
+<!--
+填写指引：
+用步骤式描述说明数据如何流转。从触发源头到最终效果，每一步写清。
+
+格式示例：
+1. 用户下拉列表 → FlatList 触发 onScroll
+2. OptimizedList 读取 itemHeight 配置 → 启用 getItemLayout
+3. 布局引擎跳过动态测量 → 直接使用固定行高计算 offset
+4. useScrollPerformance 每 500ms 采集一次帧率
+5. 帧率数据 → Performance Reporter → 上报后端
+6. 渲染线程不再因布局计算阻塞 → 帧率恢复
+-->
+
+{{data-flow}}
+
+### 接口设计
+
+<!--
+填写指引：
+列出本设计对外暴露的 API 签名，包括：
+- 函数/方法名
+- 参数列表（名称 + 类型 + 说明）
+- 返回值类型
+- 是否 async/sync
+
+格式示例：
+
+```typescript
+// OptimizedList 组件 props
+interface OptimizedListProps<T> {
+  data: T[];
+  renderItem: (item: T, index: number) => React.ReactElement;
+  /** 固定行高（px），必填以启用 getItemLayout */
+  itemHeight: number;
+  /** 窗口外预渲染行数（可选，默认 10） */
+  windowSize?: number;
+  /** 启用滚动性能采集（可选，默认 false） */
+  enableScrollMetrics?: boolean;
+  /** 滚动性能回调（可选） */
+  onPerfSnapshot?: (snapshot: ScrollPerfSnapshot) => void;
+}
+
+// useScrollPerformance hook
+function useScrollPerformance(
+  listRef: React.RefObject<FlatList>,
+  options?: { intervalMs?: number }
+): { avgFps: number; isJanking: boolean };
+```
+-->
+
+{{api-signatures}}
+
+---
+
+## 文件清单
+
+<!--
+填写指引：
+列出所有需创建或修改的文件，用表格组织。
+-->
+
+| 文件路径 | 内容描述 | 操作 |
+|---|---|---|
+| `{{file-path-1}}` | {{description}} | 创建 |
+| `{{file-path-2}}` | {{description}} | 修改 |
+| `{{file-path-3}}` | {{description}} | 创建 |
+
+---
+
+## 测试策略
+
+<!--
+填写指引：
+按测试层次描述覆盖范围。不需要写具体用例——tasks 文件负责拆解。
+-->
+
+### 单元测试
+- <!-- 哪些模块需要单元测试？需要 mock 什么？ -->
+
+### 集成测试
+- <!-- 哪些流程需要集成测试？需要准备什么 fixture？ -->
+
+### TDD 任务
+- <!-- 列出需要走 RED→GREEN→REFACTOR 的 type:behavior 任务 -->
+
+---
+
+## 备选方案
+
+<!--
+填写指引：
+列出评估过但未选择的方案，说明为什么放弃。
+
+| 方案 | 优点 | 缺点 | 不选原因 |
+|---|---|---|---|
+| {{方案 A}} | {{优点}} | {{缺点}} | {{原因}} |
+| {{方案 B}} | {{优点}} | {{缺点}} | {{原因}} |
+-->
+
+| 方案 | 优点 | 缺点 | 不选原因 |
+|---|---|---|---|
+| {{alt-name-1}} | {{pros}} | {{cons}} | {{reason}} |
+| {{alt-name-2}} | {{pros}} | {{cons}} | {{reason}} |
+
+---
+
+## 风险点
+
+<!--
+填写指引：
+识别实现风险并评估影响。
+
+| 风险 | 概率 | 影响 | 缓解措施 |
+|---|---|---|---|
+| {{风险描述}} | 高/中/低 | 高/中/低 | {{措施}} |
+-->
+
+| 风险 | 概率 | 影响 | 缓解措施 |
+|---|---|---|---|
+| {{risk-1}} | {{probability}} | {{impact}} | {{mitigation}} |
+| {{risk-2}} | {{probability}} | {{impact}} | {{mitigation}} |

package/dist/templates/artifacts/goal-review.md

@@ -0,0 +1,95 @@
+# Goal Review: {{change-name}}
+
+> 审查时间: {{date}}
+> 审查者: {{reviewer | agent/human}}
+
+## Change 目标
+
+从 proposal.md 中提取的 must-haves（强制目标）和 nice-to-haves（非强制目标）列表。目标应以可观测、可验证的方式表述。
+
+### Must-haves（强制目标）
+
+<!-- 逐条列出 proposal.md "Scope" → "In scope" 中的条目，或 proposal.md 中标记为必须实现的目标 -->
+
+1. **目标 1**: <!-- 可观测行为描述，如"用户可以通过邮箱注册账号" -->
+2. **目标 2**: <!-- 如"未登录用户无法访问 /dashboard" -->
+3. **目标 3**: <!-- ... -->
+
+### Nice-to-haves（可选目标）
+
+<!-- 列出 proposal.md 中标记为可选的目标，或 Scope → "Out of scope" 之外的合理期望 -->
+
+1. **期望 1**: <!-- ... （如果未实现不需要 FAIL） -->
+
+**填写指引：**
+- 目标必须从 proposal.md 原文提取，不自行发明或解释
+- 目标必须以可观测行为描述——不写"模块设计好"而写"接口签名满足 X 和 Y"
+- 强制目标（must-haves）和可选目标（nice-to-haves）分开列出
+- 如果 proposal.md 没有明确定义 must-haves，则回退到 tasks.md 中的所有 task acceptance 条件
+
+## 达成情况
+
+每行对应一个目标项，检查代码实现是否实际产生了预期的可观测行为。
+
+| 目标项 | 可观测行为 | 达成状态 | 证据 | 备注 |
+|--------|------------|----------|------|------|
+| 目标 1: | <!-- 预期的可观测行为描述 --> | ✅ 达成 / ❌ 未达成 / ⚠️ 部分达成 | <!-- 测试通过、演示录屏、截图、日志等 --> | <!-- 偏离项说明 --> |
+| 目标 2: | <!-- ... --> | ✅ 达成 | <!-- test/login.test.ts:12-30 PASS --> |  |
+| API 响应时延 < 200ms | 接口 95 分位响应时间 | ❌ 未达成 | loadtest result: p95=450ms | 已在 plan 中添加性能优化任务 |
+
+**达成状态判定标准：**
+
+| 状态 | 标准 |
+|------|------|
+| ✅ 达成 | 对应的可观测行为已经实现并通过验证 |
+| ❌ 未达成 | 目标对应的行为没有实现或验证失败 |
+| ⚠️ 部分达成 | 主要行为实现但存在偏差（如缺少某些边界处理） |
+
+**证据要求：**
+- ✅ 必须附证据——通过的测试用例、截图、性能测试数据、用户验收记录等
+- 不写"代码已实现"作为证据——要证明的是"行为可观测"，而不是"代码存在"
+- ❌ 和 ⚠️ 必须在下方的"未达成项详情"中分析根因
+
+## 未达成项详情
+
+对于 ❌ 未达成 和 ⚠️ 部分达成 的目标项，逐项展开分析。
+
+### {{目标项}}: {{目标描述}}
+
+- **预期行为**: <!-- proposal.md 或 tasks.md 中定义的验收标准 -->
+- **实际行为**: <!-- 当前代码的行为 -->
+- **差距分析**: <!-- 为什么有差距 -->
+- **根因**: <!-- 是设计漏了、实现遗漏、还是需求变更了 -->
+- **修复方向**: <!-- 达成目标具体需要做啥 -->
+- **是否影响其他目标**: <!-- 修复这个会不会导致其他目标失效 -->
+
+### <!-- 下一个未达成项 -->
+
+<!-- 无 ❌/⚠️ 项时写"所有目标均已达成，无不达成项。" -->
+
+## Scope Creep 检查
+
+检查实现中是否包含了 proposal.md 范围之外的功能。
+
+| 发现的功能 | 对应代码位置 | 是否可接受 | 说明 |
+|------------|-------------|------------|------|
+| <!-- 额外实现的功能 --> | <!-- 文件+行号 --> | 可接受 / 需移除  | <!-- 理由 --> |
+
+**填写指引：**
+- 超出 proposal 范围的功能不等于坏代码，但需要在 change 上下文中评估
+- 如果 scope creep 影响了原目标的交付或增加了风险，应标记为"需移除"
+- 发现非预期的 side effect（如修改了不该改的模块）也在此记录
+
+## 结论
+
+- [ ] **PASS** — 所有 must-haves 目标达成，无 scope creep 风险
+- [ ] **FAIL** — 存在未达成的 must-haves 目标：
+  - <!-- 列出具体未达成的目标项 -->
+  - <!-- 建议：窄化 change 范围 or 增加 commit 完成剩余目标 -->
+
+**审查总结：**
+- 总目标: <!-- N --> 个 must-have, <!-- M --> 个 nice-to-have
+- 达成: <!-- 数量 --> / <!-- N --> must-haves 完成
+- 未达成: <!-- 数量 --> / <!-- N -->
+- Scope Creep: <!-- 数量 --> 处
+- 整体评估: <!-- 该 change 是否值得发布 / 需要修补 / 建议拆分 -->

package/dist/templates/artifacts/project.yml

@@ -0,0 +1,117 @@
+# specwf project configuration
+# Generated by specwf init
+# 
+# 本文件定义项目级别的工作流配置。修改后的配置在下次 specwf 命令执行时生效。
+
+# 配置文件格式版本号 —— 由 specwf 管理，不要手动修改
+version: 1
+
+# ============================================================
+# 平台配置
+# ============================================================
+# 项目运行的目标平台列表。specwf 根据平台加载对应的集成适配器。
+# 可选值:
+#   - omp         Oh My Pi 集成（默认，含 specwf CLI 完整支持）
+#   - claude      Claude Code 环境中运行
+#   - standalone  纯 CLI 模式，无平台依赖
+platform:
+  - omp
+
+# ============================================================
+# 项目配置模板
+# ============================================================
+# 项目级别设定。profile 决定默认开启哪些功能集合。
+#   可选值: standard, minimal, advanced, custom
+#   standard  — 开启所有基础功能（research/tdd/triple_review/auto_advance/spec_injection）
+#   minimal   — 只开启最基础流程，适合实验性项目
+#   advanced  — 在 standard 基础上增加 plan_check、严格校验
+#   custom    — 自行通过 workflow.* 开关配置
+profile: standard
+
+# ============================================================
+# 项目描述上下文
+# ============================================================
+# 项目描述文本，会被注入到每个 specwf agent 的系统提示中，作为项目背景知识。
+# 请填写项目名称、技术栈、测试框架等关键信息。
+# 格式: YAML 多行字符串（| 注意缩进）
+context: |
+  项目: {{name}}
+  技术栈: <!-- TypeScript, Node.js, React, PostgreSQL 等 -->
+  测试框架: <!-- vitest, jest, playwright 等 -->
+
+# ============================================================
+# 工作流开关
+# ============================================================
+# 各阶段的启用/禁用。true=启用，false=跳过。
+# 单个开关设置为 false 后，对应阶段在 specwf run 时被跳过但仍可通过 specwf run --step <name> 显式执行。
+workflow:
+  # 是否启用 Plan 前的调研阶段（research.md）
+  research: true
+  # 是否在 plan 生成后自动执行 plan_check（验证 plan 完整性）
+  plan_check: true
+  # 是否强制 TDD（type:behavior 任务必须 RED→GREEN→REFACTOR）
+  tdd: true
+  # 是否启用三重并行审查（规格审查 + 质量审查 + 目标审查）
+  triple_review: true
+  # 审查全部通过后是否自动前进到 verify 阶段
+  auto_advance: true
+  # 是否在执行 change 时注入全局 specs/conventions 到 agent 提示
+  spec_injection: true
+
+# ============================================================
+# 审查阶段配置
+# ============================================================
+review:
+  # 审查阈值模式：
+  #   all-pass          — 三重审查全部 PASS 才能进入 verify（最严格）
+  #   severity          — 没有 HIGH/CRITICAL 问题即可
+  #   report-only       — 审查结果仅供参考，不阻塞
+  #   majority-vote     — 三份报告有两份以上 PASS 即可推进
+  gate: all-pass
+  # 是否并行执行三种审查（true=同时启动三个 reviewer，false=串行）
+  parallel: true
+
+# ============================================================
+# Change 执行配置
+# ============================================================
+change:
+  # 多 Change 并发执行模式：
+  #   single            — 每次只执行一个 Change
+  #   dependency-graph  — 按依赖图调度 Change（默认，推荐的平衡模式）
+  #   concurrent        — 不做依赖检查，全部 Change 同时执行
+  parallel: dependency-graph
+  # 是否隔离 Change 的执行环境（git worktree / 临时目录等）
+  isolation: true
+
+# ============================================================
+# Git 版本管理配置
+# ============================================================
+git:
+  # 分支策略:
+  #   none        — 不自动管理分支，在当前分支上直接提交
+  #   auto        — 自动为每个 Change/Phase 创建和切换分支
+  #   per-change  — 每个 Change 创建独立分支
+  #   per-phase   — 每个 Phase 创建独立分支
+  branching: none
+  # 完成 Phase 时是否创建 git tag
+  create_tag: true
+
+# ============================================================
+# 规范注入配置
+# ============================================================
+conventions:
+  # 是否在 apply 时将全局 conventions/ 注入到 agent 提示
+  inject: true
+
+# ============================================================
+# LLM 模型配置（可选）
+# ============================================================
+# 指定不同阶段的模型。
+# 格式: <阶段名>: <模型 ID>
+# 模型 ID 取决于运行平台和本地可用的模型
+# 示例:
+#   plan: claude-sonnet-4
+#   apply: claude-haiku-3.5
+#   review: gpt-4o
+# 留空 {} 使用平台默认模型
+models: {}