specwf 0.2.0

package/dist/templates/artifacts/summary.md

@@ -0,0 +1,129 @@
+# Phase Summary: {{phase-name}}
+
+> **Phase 起止**: {{start-date}} → {{end-date}}
+> **完成度**: {{percentage}}%（基于 completion checklist）
+
+---
+
+## 完成状态
+
+<!--
+填写指引：
+基于验证结果给出最终完成状态。
+从以下状态中选择一个：
+- **Phase shipped**：所有 task 完成，验证全部通过
+- **Phase shipped with gaps**：核心功能完成，但标记了 gapped items
+- **Phase deferred**：本轮未完成已回滚，推迟到后续 phase
+-->
+
+✅ **Phase shipped**。
+
+所有 Wave 的 task 已完成，验证项全部通过。本 phase 目标已达成。
+
+---
+
+## Change 产出明细
+
+<!--
+填写指引：
+按 change 分列产出。每个 change 列出：
+- 产出文件清单（具体文件路径，不要泛泛说"若干文件"）
+- 关键实现决策（实现中做的关键决定）
+- 验证结果（测试 + 类型检查结果）
+-->
+
+### Change: {{change-name-1}}
+
+**产出文件：**
+
+| 文件路径 | 说明 |
+|---|---|
+| `{{file-path-1}}` | {{说明}} |
+| `{{file-path-2}}` | {{说明}} |
+| `{{file-path-3}}` | {{说明}} |
+
+**关键实现决策：**
+- {{决策 1：如"选择在组件内部实现 getItemLayout 而非通过 props 传入"}}
+- {{决策 2：如"useScrollPerformance 用 RAF 而非 setInterval 采集帧率"}}
+
+**验证结果：**
+- `tsc --noEmit`：✅ 通过（0 error）
+- `vitest run`：✅ 通过（{{N}} tests, {{N}} passed）
+- lint：✅ 通过（0 warning）
+
+---
+
+### Change: {{change-name-2}}
+
+**产出文件：**
+
+| 文件路径 | 说明 |
+|---|---|
+| `{{file-path-1}}` | {{说明}} |
+| `{{file-path-2}}` | {{说明}} |
+
+**关键实现决策：**
+- {{决策 1}}
+
+**验证结果：**
+- `tsc --noEmit`：✅ 通过
+- `vitest run`：✅ 通过
+- lint：✅ 通过
+
+---
+
+## 验证结果
+
+<!--
+填写指引：
+填写验证汇总表。证据列可以是 CI 链接、截图、或命令执行结果摘要。
+-->
+
+| 验证项 | 结果 | 证据 |
+|---|---|---|
+| 类型检查 (`tsc --noEmit`) | ✅ 通过 / ❌ 失败 | {{无错误/错误数及原因}} |
+| 单元测试 (`vitest run`) | ✅ 通过 / ❌ 失败 | {{N tests, N passed, N failed}} |
+| 集成测试 | ✅ 通过 / ❌ 失败 / N/A | {{测试范围说明}} |
+| lint 检查 | ✅ 通过 / ❌ 失败 | {{eslint / prettier 结果}} |
+| {{自定义验证项 1}} | ✅ / ❌ / N/A | {{证据}} |
+| {{自定义验证项 2}} | ✅ / ❌ / N/A | {{证据}} |
+
+---
+
+## 偏差记录
+
+<!--
+填写指引：
+记录实现过程中与计划（proposal / design 文档）相比的偏差。
+每项偏差说明：原计划 vs 实际结果 + 原因 + 是否可接受。
+
+如果没有偏差，写：无偏差，实现完全符合设计文档。
+-->
+
+| 原计划 | 实际结果 | 偏差原因 | 可接受？ |
+|---|---|---|---|
+| {{原计划描述}} | {{实际结果描述}} | {{为什么发生偏差}} | ✅ 是 / ❌ 否 / ⚠️ 有风险 |
+| {{原计划描述}} | {{实际结果描述}} | {{为什么发生偏差}} | ✅ 是 / ❌ 否 / ⚠️ 有风险 |
+| {{原计划描述}} | {{实际结果描述}} | {{为什么发生偏差}} | ✅ 是 / ❌ 否 / ⚠️ 有风险 |
+
+---
+
+## 下一步
+
+<!--
+填写指引：
+基于本 phase 的完成情况和发现，建议下一 phase 或后续 action item。
+每个建议说明：做什么 + 为什么做 + 建议时机。
+-->
+
+1. **{{下一步 action 1}}**：{{描述。如"在 Android 端进行列表滚动性能验证，确保 getItemLayout 效果一致"}}
+   - 原因：{{为什么需要做}}
+   - 建议时机：{{下个 sprint / 下个 phase 开始后两周内}}
+
+2. **{{下一步 action 2}}**：{{描述}}
+   - 原因：{{为什么需要做}}
+   - 建议时机：{{建议时机}}
+
+3. **{{下一步 action 3}}**：{{描述}}
+   - 原因：{{为什么需要做}}
+   - 建议时机：{{建议时机}}

package/dist/templates/artifacts/tasks.md

@@ -0,0 +1,109 @@
+# Tasks: {{name}}
+
+> **填表指引**：本文档将 design 拆解为按 wave 分组的可执行 task。每个 task 需包含 description、files、acceptance、可选的 depends_on 和 spec_ref。type:behavior 的 task 必须编写 RED 测试描述（GIVEN/WHEN/THEN 格式）。
+
+---
+
+## TDD type 标注规则
+
+<!--
+每种 task 的 type 定义其 TDD 协议。
+type:behavior 必须走 RED→GREEN→REFACTOR，其余 type 直接实现。
+-->
+
+| type | 含义 | TDD 协议 |
+|---|---|---|
+| `behavior` | 业务行为——实现一个具体的、可观测/可断言的业务功能 | **RED→GREEN→REFACTOR**（强制 TDD：先写测试 → 实现 → 重构） |
+| `config` | 配置文件——环境变量、CI/CD、lint、tsconfig 等 | 直接实现，无需 TDD |
+| `refactor` | 重构——不改变外部行为只改善内部结构 | 先验证已有测试通过 → 重构 → 再次验证 |
+| `docs` | 文档——README、API 文档、注释 | 直接实现，无需 TDD |
+| `scaffolding` | 骨架代码——新建模块的空壳、目录结构、模板文件 | 直接实现，无需 TDD |
+
+> **规则**：如果 task 的核心产出是"某个行为"（用户可感知或测试可断言），使用 `behavior`。如果只是"文件存在"或"配置生效"，使用 `config`/`scaffolding`。
+
+---
+
+## Wave 1: {{wave-1-theme}}
+
+<!--
+Wave 是独立可验证的工作单元。一个 wave 内的 task 可能有依赖关系但整体封闭。
+每个 wave 完成后可执行验证（tsc + test pass）。
+-->
+
+- [ ] task-{{id-1}}: [type:{{type}}] {{title}}
+  - **description**: {{详细描述：具体做什么、用什么方法、参考哪些文件/API}}
+  - **files**: {{文件路径列表，逗号分隔}}
+  - **acceptance**: {{可观测可断言的验收标准}}
+  - **depends_on**: [task-{{id-x}}] <!-- 可选：前置依赖 -->
+  - **spec_ref**: specs/{{domain}}/spec.md <!-- 可选：关联的规格文件 -->
+  {{if behavior}}
+  - ***RED 测试***:
+    ```
+    GIVEN {{前置条件}}
+    WHEN {{操作触发}}
+    THEN {{预期结果}}
+    ```
+  {{/if}}
+
+- [ ] task-{{id-2}}: [type:{{type}}] {{title}}
+  - **description**: {{详细描述}}
+  - **files**: {{文件路径列表}}
+  - **acceptance**: {{验收标准}}
+  {{if behavior}}
+  - ***RED 测试***:
+    ```
+    GIVEN {{前置条件}}
+    WHEN {{操作触发}}
+    THEN {{预期结果}}
+    ```
+  {{/if}}
+
+---
+
+## Wave 2: {{wave-2-theme}}
+
+<!--
+如果设计超过一个 wave，在此添加。Wave 2 依赖 Wave 1 的产出。
+-->
+
+- [ ] task-{{id-3}}: [type:{{type}}] {{title}}
+  - **description**: {{详细描述}}
+  - **files**: {{文件路径列表}}
+  - **acceptance**: {{验收标准}}
+  - **depends_on**: [task-{{id-1}}] <!-- 可选 -->
+  {{if behavior}}
+  - ***RED 测试***:
+    ```
+    GIVEN {{前置条件}}
+    WHEN {{操作触发}}
+    THEN {{预期结果}}
+    ```
+  {{/if}}
+
+- [ ] task-{{id-4}}: [type:{{type}}] {{title}}
+  - **description**: {{详细描述}}
+  - **files**: {{文件路径列表}}
+  - **acceptance**: {{验收标准}}
+  {{if behavior}}
+  - ***RED 测试***:
+    ```
+    GIVEN {{前置条件}}
+    WHEN {{操作触发}}
+    THEN {{预期结果}}
+    ```
+  {{/if}}
+
+---
+
+## 验证
+
+<!--
+填写指引：
+所有 task 实现完毕后，在此 checklist 中逐项确认。
+-->
+
+- [ ] `tsc --noEmit` 通过（或对应语言的类型检查）
+- [ ] `vitest run` 测试套件全部通过
+- [ ] 每个 wave 的验收标准已通过人工或自动化确认
+- [ ] 新增代码的 lint 检查通过
+- [ ] 未引入新的类型错误或告警

package/dist/templates/artifacts/verification.md

@@ -0,0 +1,113 @@
+# Verification: {{change-name}}
+
+> 验证时间: {{date}}
+
+## 测试结果
+
+列出所有执行过的测试及其结果。优先引用自动化测试结果（vitest、tsc 等），手工测试单独标注。
+
+| 测试名 | 类型 | 结果 | 耗时 | 备注 |
+|--------|------|------|------|------|
+| <!-- vitest run 等测试套件名 --> | <!-- unit / integration / e2e / manual / typecheck --> | ✅ 通过 / ❌ 失败 / ⏭ 跳过 | <!-- 如 "12s" --> | <!-- 特殊观察、不稳定测试等 --> |
+| tsc --noEmit | typecheck | ✅ | 5s | 无类型错误 |
+
+**填写指引：**
+- "类型"字段：`unit`（单元测试）、`integration`（集成测试）、`e2e`（端到端）、`manual`（手工验证）、`typecheck`（类型检查）
+- "结果"字段使用符号标记以便快速扫描：✅ = 通过、❌ = 失败、⏭ = 跳过、⚠ = 有警告但通过
+- "耗时"统一单位为秒（加 `s` 后缀）
+- 跳过或失败须在"备注"中说明原因
+
+## 需求覆盖检查
+
+对照 delta-specs 中的 Requirement 列表，逐项检查实现覆盖情况。
+
+| 需求 ID | 需求描述 | 覆盖状态 | 证据 |
+|---------|----------|----------|------|
+| <!-- REQ-001 等编号，按 proposal 或 spec 文档编号 --> | <!-- 需求原文摘要 --> | ✅ 已覆盖 / ❌ 未覆盖 / ⚠️ 部分覆盖 | <!-- 通过的测试名、代码链接、截图等 --> |
+
+**填写指引：**
+- 需求 ID 遵循 `REQ-{NNN}` 格式，与 delta-specs 中的编号一致
+- "覆盖状态"必须基于实际测试结果，而非代码审查印象
+- "证据"链接到具体的通过测试用例（如 `test/xxx.test.ts:12`）或手工验证记录
+- ⚠️ 部分覆盖须在备注或下方根因中说明未覆盖的边界
+
+## 决策覆盖检查
+
+对照 design.md 和 context.md 中的决策记录（D1、D2...），检查决策的落地情况。
+
+| 决策 ID | 决策内容 | 实现状态 | 证据 |
+|---------|----------|----------|------|
+| <!-- D1、D2 等编号 --> | <!-- 决策摘要 --> | ✅ 已实现 / ❌ 未实现 / ⚠️ 偏离 | <!-- 代码位置、文件名+行号等 --> |
+
+**填写指引：**
+- 决策 ID 与 design.md / context.md 中的编号一致
+- "实现状态"检查的是决策意图是否在代码中得到体现，不只是代码中是否包含关键字
+- ⚠️ 偏离须在下方根因诊断中分析原因
+
+## 目标达成检查
+
+对照 proposal.md 中的目标定义，逐项检查达成情况。
+
+| 目标项 | 达成状态 | 证据 |
+|--------|----------|------|
+| <!-- 从 proposal.md 提取的 must-haves 目标 --> | ✅ 达成 / ❌ 未达成 / ⚠️ 部分达成 | <!-- 测试结果、用户验证等 --> |
+
+## 根因诊断
+
+对于所有 ❌ 或 ⚠️ 的失败项（测试失败、未覆盖的需求、未实现的决策、未达成的目标），按照以下分类进行根因分析。
+
+### 失败项分类
+
+| 分类 | 含义 | 对应路由 |
+|------|------|----------|
+| 计划缺陷 | 设计错了或漏了 — 方案设计时不满足需求 | → replan（回 plan 重设计） |
+| 实现缺陷 | 代码写错了 — 设计正确但编码有误 | → reapply（回 apply 重实现） |
+| 规格缺陷 | spec 本身错了 — 需求描述错误或不完整 | → 标记 spec 待修，回 plan 修 spec |
+
+### 逐项根因分析
+
+<!-- 每列格式 -->
+#### 失败项 1: <测试名/需求ID/决策ID/目标项>
+
+- **现象**: <!-- 具体失败表现 -->
+- **根因分类**: <!-- 计划缺陷 / 实现缺陷 / 规格缺陷 -->
+- **根因分析**: <!-- 为什么错了，深层原因 -->
+- **影响范围**: <!-- 影响哪些模块、测试 -->
+- **修复建议**: <!-- 具体修复方向 -->
+
+#### 失败项 2: ...
+
+<!-- 每发现一个失败项，都按此格式记录。无失败项时写"所有项通过，无需根因分析。" -->
+
+## 路由建议
+
+根据根因诊断分类，勾选对应的处理路径：
+
+- [ ] **计划缺陷 → replan**: <!-- 具体列出哪些项需要回 plan 重新设计，以及重新设计的内容 -->
+- [ ] **实现缺陷 → reapply**: <!-- 具体列出哪些项需要回 apply 重写代码，以及修复方向 -->
+- [ ] **规格缺陷 → 标记 spec 待修，回 plan 修 spec**: <!-- 具体列出哪些 specs 需要修正 -->
+
+**路由原则：**
+- 一个失败项只能路由到一个路径（主路由），但可以影响其他路径（次影响）
+- 计划缺陷全部回 plan 重设计后重新 apply
+- 实现缺陷在 apply 修复后回到 review 重新审查对应项
+- 规格缺陷标为 spec-debt，在修 spec 后回 plan → apply 重新实现
+
+## 回环记录
+
+每次从 verify 返回到 plan/apply 的回环，在此记录。用于追踪迭代质量和效率。
+
+| 回环 # | 问题 | 路由 | 修复内容 | 验证结果 |
+|--------|------|------|----------|----------|
+| <!-- 1, 2, 3... --> | <!-- 触发回环的问题描述 --> | <!-- replan / reapply / spec-fix --> | <!-- 修改了哪些文件、改了什么 --> | ✅ 通过 / ❌ 仍需修复 |
+| | | | | |
+
+**填写指引：**
+- 每次回环递增编号（1、2、3...）
+- "路由"字段填写具体路径（如 `replan: D1 决策边界重新定义`）
+- "修复内容"要具体到文件和关键变更，方便后续审查
+- 回环超过 3 次时，应考虑简化 change 范围或重新评估方案可行性
+
+---
+
+*Verification 报告由 specwf verify 阶段自动生成。每次验证结果覆盖前次。*

package/dist/templates/commands/adhoc.md

@@ -0,0 +1,38 @@
+# 临时 Change
+
+## 创建
+
+```bash
+specwf change new <change-name>
+```
+
+CLI 自动创建目录结构并生成模板文件。
+
+## 上下文
+
+```bash
+specwf context adhoc
+specwf state
+```
+
+## 推进
+
+完成 proposal 后：
+
+```bash
+specwf continue change <change-name>
+```
+
+`continue change <name>` 会读取该 change 的当前状态（proposal/planning/applying/reviewing/verifying/archived），输出下一步建议和 slash command。
+
+## 查看状态
+
+```bash
+specwf continue change <change-name>
+```
+
+## 归档
+
+```bash
+specwf archive specwf/changes/<change-name>
+```

package/dist/templates/commands/apply.md

@@ -0,0 +1,20 @@
+# 代码实现
+
+按 tasks.md 执行实现。使用 specwf-executor agent，分组并发。
+
+## TDD 协议
+
+type:behavior 任务走 RED→GREEN→REFACTOR。
+
+## 上下文
+
+```bash
+specwf context apply
+specwf state
+```
+
+## 下一步
+
+```bash
+specwf continue
+```

package/dist/templates/commands/archive.md

@@ -0,0 +1,21 @@
+# 归档
+
+Delta-spec 合并 + 代码认知回灌。
+
+## 执行
+
+```bash
+specwf archive <change-path>
+```
+
+## 上下文
+
+```bash
+specwf state
+```
+
+## 下一步
+
+```bash
+specwf continue
+```

package/dist/templates/commands/continue.md

@@ -0,0 +1,27 @@
+# 自动推进
+
+读 @specwf/state.md → 状态机确定下一步 → 自动执行。
+
+## 用法
+
+```bash
+# 从当前 active_context 推断下一步
+specwf continue
+
+# 查询指定 change 的下一步
+specwf continue change <name>
+```
+
+CLI 自动输出：
+- 当前位置
+- 当前步骤
+- 推荐下一步命令
+- Slash 命令（如有）
+- 是否需要子代理
+- 无下一步时的引导提示
+
+## 上下文
+
+```bash
+specwf state
+```

package/dist/templates/commands/discuss.md

@@ -0,0 +1,24 @@
+# Phase 讨论
+
+捕获实现决策，产出 CONTEXT.md。
+
+## 上下文
+
+```bash
+specwf context discuss
+specwf state
+```
+
+可参考：
+@specwf/roadmap.md
+@specwf/project.yml
+
+## 产出
+
+写入当前 phase 目录下的 context.md。
+
+## 下一步
+
+```bash
+specwf continue
+```

package/dist/templates/commands/grill.md

@@ -0,0 +1,24 @@
+# 需求探讨
+
+逐条向用户提问，直到所有需求细节达成共识。
+
+## 上下文
+
+```bash
+specwf context grill
+specwf state
+```
+
+可参考：
+@specwf/project.md
+@specwf/requirements.md
+
+## 产出
+
+更新 @specwf/requirements.md。
+
+## 下一步
+
+```bash
+specwf continue
+```

package/dist/templates/commands/init.md

@@ -0,0 +1,20 @@
+# 初始化项目
+
+执行 `specwf init` 创建 specwf 目录结构。
+
+## 存量项目
+
+如果已有代码，执行 `specwf init --brownfield`，CLI 自动完成 codebase mapping + spec bootstrap。
+
+## 上下文
+
+```bash
+specwf context init
+specwf state
+```
+
+## 下一步
+
+```bash
+specwf continue
+```

package/dist/templates/commands/milestone.md

@@ -0,0 +1,27 @@
+# 里程碑管理
+
+切换或创建 Milestone。
+
+## 上下文
+
+```bash
+specwf state
+```
+
+## 操作
+
+```bash
+# 切换到指定 milestone
+specwf state set-milestone <id>
+
+# 切换到指定 phase
+specwf state set-phase <id>
+```
+
+可参考 @specwf/roadmap.md 查看 milestone 列表。
+
+## 下一步
+
+```bash
+specwf continue
+```

package/dist/templates/commands/plan.md

@@ -0,0 +1,22 @@
+# Change 设计
+
+使用 specwf-planner agent 设计技术方案、拆分任务、预写 delta-specs。
+
+## 上下文
+
+```bash
+specwf context plan
+specwf state
+```
+
+## 产出
+
+- design.md（技术方案）
+- tasks.md（任务清单，标注 TDD type）
+- specs/<domain>/spec.md（delta-specs）
+
+## 下一步
+
+```bash
+specwf continue
+```

package/dist/templates/commands/research-phase.md

@@ -0,0 +1,20 @@
+# Phase 调研
+
+对当前 phase 的实现路径进行调研。使用 specwf-researcher agent。
+
+## 上下文
+
+```bash
+specwf context research-phase
+specwf state
+```
+
+## 产出
+
+写入当前 phase 目录下的 research.md。
+
+## 下一步
+
+```bash
+specwf continue
+```

package/dist/templates/commands/research.md

@@ -0,0 +1,24 @@
+# 项目技术调研
+
+并行调研多个技术方向。使用 task 工具 fan-out specwf-researcher agent。
+
+## 上下文
+
+```bash
+specwf context research
+specwf state
+```
+
+## 产出
+
+写入 @specwf/research/ 目录：
+- @specwf/research/stack.md
+- @specwf/research/architecture.md
+- @specwf/research/pitfalls.md
+- @specwf/research/summary.md
+
+## 下一步
+
+```bash
+specwf continue
+```

package/dist/templates/commands/review.md

@@ -0,0 +1,20 @@
+# 三重审查
+
+规格审查 + 质量审查 + 目标审查，batch tasks[3] 并行。
+
+## 上下文
+
+```bash
+specwf context review
+specwf state
+```
+
+## 门控
+
+全部通过才进 verify。
+
+## 下一步
+
+```bash
+specwf continue
+```

package/dist/templates/commands/roadmap.md

@@ -0,0 +1,23 @@
+# 路线图拆分
+
+将项目拆分为 Milestone × Phase。
+
+## 上下文
+
+```bash
+specwf context roadmap
+specwf state
+```
+
+可参考 @specwf/requirements.md。
+
+## 产出
+
+更新 @specwf/roadmap.md。
+
+## 下一步
+
+```bash
+specwf state set-milestone <第一个 milestone id>
+specwf continue
+```