@gavin-hjw/sddflow 0.3.2 → 0.3.3

package/templates/brainstorming.md

@@ -1,72 +1,175 @@
 ---
 name: sddflow/brainstorming
-description: Deep design — multi-round exploration to confirm architecture and approach
+description: Deep design — multi-round exploration using Superpowers brainstorming flow, then write OpenSpec proposal
 ---
 
 # Brainstorming: 深度设计
 
 ## 目标
 
-通过多轮对话，深入探索需求、方案取舍和架构决策。产出比 proposal 更完整的需求描述和设计方向。
+通过 Superpowers brainstorming 流程深入探索需求、方案取舍和架构决策。设计确认后，将结果写入 OpenSpec 变更目录供后续 `/sddflow spec` 使用。
 
 ## 中断续接规则
 
 如果用户在本阶段被打断后继续回复、补充范围、回答确认问题、或修正边界，仍然停留在 brainstorming 阶段。继续收敛设计并更新 `openspec/changes/**/proposal.md`，不要因为用户明确了范围就直接进入实现或修改任何代码。
 
-典型错误：在确认“只改企业端？”后，用户回复“运营端也要做回显”，这只是范围修正，必须继续记录需求和方案，不得直接修改任何代码或实现文件。
+典型错误：在确认"只改企业端？"后，用户回复"运营端也要做回显"，这只是范围修正，必须继续记录需求和方案，不得直接修改任何代码或实现文件。
 
-## 流程
+---
+
+## 第一阶段：需求澄清（Superpowers Brainstorming 流程）
+
+**严格按照以下 checklist 顺序执行，不可跳步、不可合并：**
+
+<HARD-GATE>
+在完整走完下列 checklist 并获得用户对设计的明确确认之前，不得写任何代码、不得修改任何实现文件、不得进入第二阶段。
+</HARD-GATE>
+
+### Checklist
+
+**步骤 1 — 探索项目上下文**
+
+检查以下内容，为提问建立基础：
+- 近期相关 git 提交（了解最近在做什么）
+- 相关代码结构与文件
+- `openspec/project.md`（如果存在，了解项目定位）
+- `openspec/changes/` 目录（是否有关联的活跃变更）
+
+如果请求描述了多个独立子系统（如"平台要有聊天、文件存储、计费、分析"），**立即**提出拆分建议，不要继续追问单个子系统的细节。帮助用户分解后，对第一个子项目走完完整流程。
+
+---
+
+**步骤 2 — 判断是否需要可视化辅助**
+
+如果后续问题会涉及 UI 布局、架构图、方案对比等**视觉内容**，用一条单独消息提出：
 
-### 1. 理解背景
+> "接下来有些问题用图或界面来展示会更清晰。需要我在浏览器里展示 mockup / 架构图吗？（需要打开本地 URL）"
 
-先快速检查项目上下文：
-- 最近的相关 git 提交
-- 现有代码结构
-- 相关文档
+**这条消息必须单独发送，不能和任何问题合并。** 等待回复后再继续。
 
-### 2. 逐个提问
+---
+
+**步骤 3 — 逐个提问（一次只问一个）**
 
-一次只问一个问题，逐步深入。问题类型：
+每条消息只问一个问题。问题类型：
 
 - **目的** — "这个功能的核心用户场景是什么？"
-- **取舍** — "A 方案更简单但扩展性差，B 方案更灵活但复杂。你倾向哪个？"
-- **边界** — "如果 X 情况发生，期望的行为是什么？"
-- **优先级** — "这几个需求里，哪个最重要？"
+- **约束** — "有哪些已知的技术或业务限制？"
+- **取舍** — "A 更简单但扩展性差，B 更灵活但复杂，倾向哪个？"
+- **边界** — "如果 X 发生，期望的行为是什么？"
+- **成功标准** — "怎样算这个功能做完了？"
+
+尽量用选择题，选项中包含 "其他（请说明）" 兜底。
+
+---
+
+**步骤 4 — 提出 2-3 种方案**
+
+基于提问结果，提出 **2-3 种实现方案**，每个方案包含：
+- 简要描述
+- 核心取舍
+- 适合场景
+
+以你推荐的方案开头，说明推荐理由。
+
+---
+
+**步骤 5 — 逐段呈现设计，获得确认**
+
+按以下维度逐段呈现，每段呈现后问"这部分对吗？"，等确认后再呈现下一段：
 
-### 3. 提出 2-3 种方案
+1. **架构 / 整体结构**
+2. **核心组件 / 模块划分**
+3. **数据流 / 接口**
+4. **错误处理**
+5. **测试策略**（可选，视复杂度）
 
-基于讨论，提出 2-3 种实现方案，附上取舍分析。推荐一种并说明理由。
+每段篇幅视复杂度而定：简单项目几句话，复杂项目 200-300 字。
 
-### 4. 确认设计
+---
+
+**步骤 6 — 用户整体确认设计**
+
+所有段落确认后，整理并请求最终确认：
+
+> "确认的设计方向：**[方案名]**
+>
+> 核心决策：
+> 1. [决策 1]
+> 2. [决策 2]
+> 3. [决策 3]
+>
+> 确认后我会将设计记录到 OpenSpec 变更目录，以便后续生成规格。这样对吗？"
+
+**等待用户明确回复"确认"/"OK"/"对" 类似肯定后，才进入第二阶段。**
+
+---
+
+## 第二阶段：写入 OpenSpec 变更目录
 
-用户选定方案后，整理设计要点并与用户确认：
+> 用户确认设计后执行本阶段。
 
-> "确认的设计方向：[方案名]。核心决策：[2-3 条]。这样对吗？"
+### 1. 确定变更名
 
-### 5. 创建 OpenSpec 变更目录
+使用 kebab-case、动词开头的名称（如 `add-user-login`、`refactor-payment-flow`）。如果用户没有给出，根据设计内容自动生成并告知用户。
 
-用户确认后，按 OpenSpec 目录约定创建变更。`<变更名>` 使用 kebab-case、动词开头（如 `add-user-login`）：
+### 2. 创建变更目录
 
 ```bash
 mkdir -p openspec/changes/<变更名>/specs
 ```
 
-将确认的需求描述和设计方向写入 `openspec/changes/<变更名>/proposal.md`。
+### 3. 写入 proposal.md
 
-如果 OpenSpec CLI 可用，可用以下命令检查当前变更列表：
+将第一阶段中确认的内容写入 `openspec/changes/<变更名>/proposal.md`，结构如下：
 
-```bash
-openspec list
+```markdown
+# <变更名>
+
+## 背景与目标
+
+[为什么要做这个变更，解决什么问题]
+
+## 用户场景
+
+[核心用户场景，1-3 条]
+
+## 设计方向
+
+[选定的方案，简要说明架构/组件/数据流/错误处理]
+
+## 关键决策
+
+- [决策 1]
+- [决策 2]
+- [决策 3]
+
+## 范围边界
+
+**包含：**
+- [包含的内容]
+
+**不包含（本次）：**
+- [明确排除的内容]
+
+## 验收标准
+
+- [ ] [验收条件 1]
+- [ ] [验收条件 2]
 ```
 
-### 6. 提示下一步
+### 4. 提示下一步
+
+> "需求已记录至 `openspec/changes/<变更名>/proposal.md`。
+>
+> 接下来用 `/sddflow spec` 生成完整规格（specs/ + tasks.md + plan-ready.md + 实现计划；design.md 按需）。"
 
-> "需求已记录。接下来可以用 `/sddflow spec` 生成完整规格。"
+---
 
-## 注意
+## 全程约束
 
-- 不要写代码
-- 本阶段只允许写 OpenSpec 需求/设计方向文档，禁止修改任何代码或实现文件
-- 不要跳过取舍讨论直接给答案
-- 如果项目很大，建议先拆分成独立的子项目
-- 允许用户改变方向，不要过早锁定
+- 不写任何代码
+- 只允许写 `openspec/changes/**/proposal.md`，禁止修改任何代码或实现文件
+- 不跳过取舍讨论直接给答案
+- 不调用 Superpowers `writing-plans` skill（那是 `/sddflow build` 阶段的事）
+- 允许用户在任何时刻改变方向，回到步骤 3 重新提问

package/templates/build.md

@@ -1,81 +1,229 @@
----
-name: sddflow/build
-description: Call Superpowers to execute implementation, supports checkpoint recovery
----
-
-# Build: Superpowers 执行
-
-## 目标
-
-读取 plan-ready.md，调用 Superpowers 的 writing-plans 生成详细实现计划，然后按 TDD 铁律执行。
-
-## 中断续接规则
-
-如果用户在 build 阶段被打断后继续回复、说“继续”、或补充实现细节，保持 build 阶段并从实现计划/checkbox 状态恢复。不要回到 proposal、brainstorming 或 spec。
-
-如果用户明确要求修改需求、补充 spec、改变验收条件、改变功能边界或重新生成规格，停止实现并切到 `/sddflow amend`。amend 完成后再回到 `/sddflow build`。
-
-## 前置条件
-
-- `openspec/changes/<变更名>/plan-ready.md` 存在
-
-如果不满足，提示：
-> "还没生成 plan-ready.md。请先完成 /sddflow spec。"
-
-## 流程
-
-### 1. 检测状态
-
-检查以下文件确定当前状态：
-
-| 检查 | 怎么查 | 结果 |
-|------|--------|------|
-| 有活跃变更？ | `openspec/changes/` 下非 archive 子目录 | 找到变更名 |
-| 有 plan-ready.md？ | 变更目录下是否存在 | 不存在→提示先 spec |
-| 实现已开始？ | `docs/superpowers/plans/` 下是否有对应计划文件 | 已开始→断点恢复 |
-
-如果有多个活跃变更，列出并让用户选择。
-
-### 2. 断点恢复（如适用）
-
-如果检测到已有计划文件，检查其中 checkbox 状态：
-
-- 全部勾选 → 提示实现已完成，建议 /sddflow close
-- 部分勾选 → 从未完成的 task 继续执行
-- 无勾选 → 从头开始
-
-### 3. 生成详细实现计划
-
-调用 Superpowers 的 `writing-plans` skill，以 `plan-ready.md` 为输入，生成符合 Superpowers 格式的详细实现计划。
-
-每个步骤：
-- 2-5 分钟工作量
-- 包含代码、文件路径、验证命令
-- 使用 checkbox 语法 `- [ ]` 跟踪
-
-将实现计划保存到：
-```
-docs/superpowers/plans/YYYY-MM-DD-<变更名>.md
-```
-
-### 4. 执行实现
-
-按照 Superpowers 的执行流程：
-
-1. **TDD 铁律**：先写失败测试，再写实现代码
-2. **每个 task 一个 commit**
-3. 多任务可派子代理并行（参见 subagent-driven-development skill）
-4. 编译/测试不通过不让提交
-
-### 5. 执行完成
-
-所有 task 完成后，提示用户：
-
-> "所有实现任务已完成。接下来可以用 /sddflow close 验证一致性并归档。"
-
-## 关键原则
-
-- **不允许在 build 阶段修改规格文档** — 发现需求遗漏或规格错误时切到 `/sddflow amend`
-- build 是唯一默认允许修改代码或实现文件的阶段；如果上一阶段不是 build，不要因为用户确认范围而自动写代码
-- plan-ready.md 是锁定的设计决策，Superpowers 按计划展开执行，不重新理解需求
-- 断点恢复依赖文件系统状态，不依赖 AI 的会话记忆
+---
+name: sddflow/build
+description: Strict pre-flight file check, then execute with subagent-driven-development + TDD
+---
+
+# Build: 执行实现
+
+## 目标
+
+严格校验 spec 阶段产出的所有文件完整性，通过后用 `subagent-driven-development` 逐 Task 派发子代理执行，每个子代理强制遵循 `test-driven-development` 铁律。
+
+**build 阶段不生成任何计划文件。** 计划在 `/sddflow spec` 阶段已由 `writing-plans` 完成。
+
+## 中断续接规则
+
+- 被打断后继续回复、说"继续"、补充实现细节 → 保持 build 阶段，从 plan 文件的 checkbox 状态恢复
+- 用户明确要求修改需求/规格/验收条件/功能边界 → **立即切到 `/sddflow amend`**，amend 完成后再回到 build
+
+---
+
+## 阶段 1：前置文件完整性校验
+
+<HARD-GATE>
+以下必填文件必须存在且通过校验，任何一项不通过都不允许进入执行阶段。
+`design.md` 按 OpenSpec 可选规则处理，缺失不阻断 build。
+</HARD-GATE>
+
+### 1.1 确定活跃变更
+
+检查 `openspec/changes/` 下非 archive 子目录。多个时列出并让用户选择。
+
+### 1.2 文件完整性检查
+
+对找到的变更目录，逐项检查：
+
+| 检查项 | 路径 | 不通过时 |
+|--------|------|----------|
+| 提案文件 | `openspec/changes/<变更名>/proposal.md` | 提示先运行 `/sddflow brainstorming` |
+| 规格目录 | `openspec/changes/<变更名>/specs/`（非空） | 提示先运行 `/sddflow spec` |
+| 任务清单 | `openspec/changes/<变更名>/tasks.md` | 提示先运行 `/sddflow spec` |
+| 翻译计划 | `openspec/changes/<变更名>/plan-ready.md` | 提示先运行 `/sddflow spec` |
+| 详细实现计划 | `docs/superpowers/plans/` 下有 `<变更名>` 对应文件 | 提示先运行 `/sddflow spec` |
+| Checkbox 扩展 | 三份任务文档均含 `- [ ]` / `- [x]`（见 spec「三文档 Checkbox 对齐扩展」） | 提示先运行 `/sddflow spec` 补齐 checkbox |
+
+**可选参考（不阻断）：**
+
+| 检查项 | 路径 | 说明 |
+|--------|------|------|
+| 技术方案 | `openspec/changes/<变更名>/design.md` | 若存在则作为实现参考输入；不存在且符合 OpenSpec 可选规则则跳过，不得要求 spec 补空文件 |
+
+任一必填项不通过，输出完整缺失列表后终止：
+
+> "build 前置校验未通过，缺少以下文件：
+> - [缺失文件列表]
+>
+> 请先完成 `/sddflow spec` 生成全部必填文件后再执行 build。"
+
+### 1.3 Plan 文件内容校验
+
+找到 plan 文件后，验证其内容质量：
+
+| 校验项 | 规则 |
+|--------|------|
+| 包含 Task | 至少 1 个 `### Task N:` |
+| Trace / Sync | 每个 Task 都有 `> **trace:**` 与 `> **sync:**`（含 tasks.md 与 plan-ready.md 原文行） |
+| 无占位符 | 不含 "TODO"、"TBD"、"实现待定" |
+| Checkbox 语法 | plan 中每个 Step 与每个 Task 末尾 **Task complete** 均有 `- [ ]` 或 `- [x]` |
+| plan-ready / tasks | 对应变更的 plan-ready **任务完成** 行、tasks.md 任务行均为 checkbox 语法 |
+
+任一不通过，提示：
+
+> "plan 文件内容校验失败：[具体原因]。请先运行 `/sddflow spec` 重新生成计划，或用 `/sddflow amend` 修订后重新生成。"
+
+### 1.4 断点恢复判断
+
+plan 文件通过校验后，读取其 checkbox 状态：
+
+| 状态 | 处理 |
+|------|------|
+| 全部 `[x]` | 实现已完成，提示 `/sddflow close`，不再执行 |
+| 部分 `[x]` | 断点恢复 — 从第一个未勾选 Task 继续（进入阶段 2） |
+| 全部 `[ ]` | 全新执行（进入阶段 2） |
+
+---
+
+## 阶段 2：执行实现
+
+> **使用 Superpowers `subagent-driven-development` skill**
+> **每个子代理强制遵循 `test-driven-development` skill**
+
+### 2.1 启动前准备
+
+1. **完整读取** plan 文件一次，提取所有 Task（含完整文本）
+2. 用 TodoWrite 创建任务列表，每个 Task 一条，初始状态 `[ ]`（已完成的标 `[x]`）
+3. 记录变更名和相关文件路径，供子代理使用
+
+### 2.2 逐 Task 执行
+
+**连续执行，不在 Task 间停下来询问进度。** 唯一停止原因：BLOCKED 无法解决、真正的歧义阻塞执行、或全部完成。
+
+```
+对每个未完成 Task 按以下顺序执行：
+
+┌─ 派发 Implementer 子代理 ──────────────────────────────────────┐
+│  • 提供 Task 完整文本（不让子代理自己读 plan 文件）             │
+│  • 提供项目上下文（相关文件路径、架构说明、技术栈）             │
+│  • 明确要求：                                                   │
+│    - 必须遵循 test-driven-development (Red → Verify RED         │
+│      → Green → Verify GREEN → Refactor)                        │
+│    - 每完成一个 Step 立即勾选 plan 文件中对应 checkbox          │
+│    - 不允许先做完所有 Step 再批量勾选                           │
+│  • 子代理状态：DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT        │
+│    / BLOCKED                                                   │
+└────────────────────────────────────────────────────────────────┘
+         ↓ DONE 或 DONE_WITH_CONCERNS
+┌─ 派发 Spec Reviewer 子代理 ────────────────────────────────────┐
+│  • 确认代码满足 plan-ready.md 中对应需求                        │
+│  • ✅ → 进入代码质量审查                                         │
+│  • ❌ → Implementer 修复 → 重新 Spec 审查                        │
+└────────────────────────────────────────────────────────────────┘
+         ↓ ✅
+┌─ 派发 Code Quality Reviewer 子代理 ────────────────────────────┐
+│  • 审查代码质量（命名、结构、耦合、测试覆盖率）                 │
+│  • ✅ → 执行 2.5 三文档 checkbox 同步（plan Step/Task、tasks、plan-ready） │
+│  • ❌ → Implementer 修复 → 重新 Quality 审查                    │
+└────────────────────────────────────────────────────────────────┘
+```
+
+**处理子代理状态：**
+
+| 状态 | 处理方式 |
+|------|----------|
+| `DONE` | 进入 Spec 审查 |
+| `DONE_WITH_CONCERNS` | 读取 concerns；正确性/范围问题先解决再审查；观察性问题记录后继续 |
+| `NEEDS_CONTEXT` | 提供缺失上下文，重新派发 |
+| `BLOCKED` | 提供更多上下文重试；仍阻塞则升级给用户 |
+
+**绝不：**
+- 跳过 Spec Compliance 审查
+- 在 Spec 审查通过前进行 Code Quality 审查
+- 让两个 Implementer 子代理同时执行（防止冲突）
+- 接受"差不多符合"（reviewer 有问题 = 未完成）
+
+### 2.3 TDD 铁律（子代理必须遵守）
+
+每个 Step 内的代码实现按 Red-Green-Refactor 循环执行：
+
+1. **RED** — 写失败测试，运行并确认以预期原因 FAIL
+2. **GREEN** — 写最小实现代码，运行确认 PASS
+3. **REFACTOR** — 清理代码，保持测试绿色
+
+**铁律：没有先看到测试 FAIL，就没有实现代码。有代码未先写测试？删除，重来。**
+
+### 2.4 实时 checkbox 勾选
+
+<HARD-GATE>
+每完成一个 Step，立即更新 plan 文件中对应 `- [ ]` 为 `- [x]`。
+禁止等所有 Step 或所有 Task 完成后批量勾选。
+</HARD-GATE>
+
+| 时机 | 操作 |
+|------|------|
+| 每个 Step 完成后 | 立即修改 plan 文件，将该 Step 的 `- [ ]` 改为 `- [x]` |
+| 整个 Task 所有 Step `[x]` 后 | 执行三文档同步（见 2.5） |
+
+### 2.5 Task 完成后：同步 plan-ready.md、tasks.md
+
+每个 Task 全部 Step 勾选完毕后，**立即**按 plan 文件中该 Task 的 `> **sync:**` 与 `> **trace:**` 同步以下三处（顺序不限，须在同一轮完成）：
+
+**A. superpowers plan（当前文件）**
+
+1. 该 Task 下所有 Step 已为 `[x]`（应在 2.4 中逐步完成）
+2. 将该 Task 末尾 `- [ ] **Task complete**` 改为 `- [x] **Task complete**`
+
+**B. tasks.md**
+
+1. 打开 `openspec/changes/<变更名>/tasks.md`
+2. 用 `sync` 中 `tasks.md →` 后的**原文整行**定位对应 `- [ ]` 条目
+3. 改为 `- [x]`，末尾追加：`<!-- 已实现: [简短描述] -->`
+
+**C. plan-ready.md**
+
+1. 打开 `openspec/changes/<变更名>/plan-ready.md`
+2. 用 `sync` 中 `plan-ready.md →` 后的 `### Task N: ...` 标题定位对应 Task 块
+3. 将该 Task 下 `- [ ] **任务完成**` 改为 `- [x] **任务完成**`
+
+**规则：**
+
+- 整个 superpowers plan Task 完成才同步 B、C，不允许部分同步
+- `trace` 用于校验：`sync` 行与源文件不一致 → 记录警告并尝试用 `trace` 回退匹配
+- 任一文档匹配失败 → 记录警告，不阻塞执行，但阶段 3 一致性检查会暴露遗漏
+
+---
+
+## 阶段 3：完成验证
+
+所有 Task 执行完毕后，运行最终一致性检查：
+
+- [ ] `openspec/changes/<变更名>/tasks.md` 所有条目为 `[x]`
+- [ ] `openspec/changes/<变更名>/plan-ready.md` 所有 **任务完成** checkbox 为 `[x]`
+- [ ] plan 文件所有 checkbox 为 `[x]`
+- [ ] 三文档 Task 数量与 plan 中 `### Task N` 数量一致
+- [ ] superpowers plan 每个 Task 的 **Task complete** 均为 `[x]`
+
+**不一致时：**
+
+| 情况 | 处理 |
+|------|------|
+| tasks.md 有未勾选 | 回到阶段 2 执行遗漏 Task |
+| plan-ready.md 有未勾选 | 回到阶段 2 执行 2.5 同步 plan-ready |
+| plan 文件有未勾选 | 回到阶段 2 执行遗漏 Step |
+| 数量不一致 | 重新执行 2.5 后再比对 |
+
+全部通过后提示：
+
+> "所有实现任务已完成，plan 文件、plan-ready.md 与 tasks.md 已同步。
+>
+> 接下来可以用 `/sddflow close` 验证规格一致性并归档。"
+
+---
+
+## 关键原则
+
+- **build 阶段不生成任何计划文件** — 计划在 spec 阶段已完成
+- **build 阶段不修改规格文档** — 发现需求遗漏或规格错误 → `/sddflow amend`
+- **plan-ready.md 是锁定的输入** — 子代理按计划执行，不重新解读需求
+- **断点恢复依赖文件系统** — 不依赖 AI 会话记忆，任何时候重启都从 checkbox 状态恢复
+- **plan 与 plan-ready.md、tasks.md 三向同步** — 每个 Task 完成后按 `sync` 勾选三处 checkbox
+- **`design.md` 遵循 OpenSpec optional 语义** — 缺失不得阻断 build，不得要求 spec 补空 `design.md`；若存在则作为实现参考