@gavin-hjw/sddflow 0.3.2

package/templates/amend.md

@@ -0,0 +1,136 @@
+---
+name: sddflow/amend
+description: Revise active OpenSpec requirements during build, regenerate plan-ready.md, and append implementation tasks without archiving the change
+---
+
+# Amend: 需求变更修订
+
+## 目标
+
+在 active change 已经进入 spec/build 后，发现需求遗漏或规格需要改变时，受控修改 OpenSpec 文档和执行计划，然后回到 `/sddflow build` 继续实现。
+
+## 适用场景
+
+- build 过程中发现原需求漏了一个功能、边界或验收条件
+- 用户明确说“修改需求”“补充 spec”“重新生成规格”“需求变更”
+- close 前发现规格本身不完整，而不是代码没有按现有规格实现
+
+不适用：
+- 只是代码没有实现现有 spec → 继续 `/sddflow build`
+- 变更已经 close/archive → 开新的 `/sddflow proposal` 或 `/sddflow brainstorming`
+- 只是文案、注释或实现细节调整，且不改变行为 → 继续当前实现阶段
+
+## 前置条件
+
+- `openspec/changes/<变更名>/` 下存在 active change
+- 至少存在 `proposal.md`
+- 通常应已存在 `plan-ready.md`；如果没有，优先回到 `/sddflow spec`
+
+如果没有 active change，提示：
+> "还没有活跃变更。请先用 /sddflow proposal 或 /sddflow brainstorming 创建需求。"
+
+如果变更已归档，提示：
+> "该变更已经归档。归档后的需求调整应开启新的 /sddflow proposal。"
+
+## 流程
+
+### 1. 确认当前变更
+
+检查 `openspec/changes/` 下的 active change。
+
+如果有多个，列出并让用户选择：
+> "检测到多个活跃变更：[列表]。要修订哪个变更？"
+
+读取当前变更的文档：
+- `proposal.md`
+- `design.md`（如果存在）
+- `specs/**/spec.md`
+- `tasks.md`（如果存在）
+- `plan-ready.md`（如果存在）
+- `docs/superpowers/plans/` 下对应实现计划（如果存在）
+
+### 2. 判断是 amend 还是 build
+
+先判断用户描述属于哪类：
+
+| 情况 | 处理 |
+|------|------|
+| 现有 spec 已覆盖，只是代码未完成 | 回到 `/sddflow build` |
+| 新增/修改行为、验收条件、边界、非目标 | 继续 amend |
+| 技术方案受影响 | 修改 `design.md` 并追加任务 |
+| 不确定是否改变需求 | 问 1 个澄清问题 |
+
+### 3. 修改 OpenSpec 文档
+
+按影响范围更新：
+
+- `proposal.md`：追加 `## Amendments`，记录本次需求变更的日期、原因和摘要
+- `design.md`：仅当技术方案或约束变化时修改
+- `specs/<capability>/spec.md`：使用 `ADDED`、`MODIFIED`、`REMOVED` 或 `RENAMED Requirements` 表达 delta
+- `tasks.md`：追加新任务；不要重写或删除已完成任务
+
+要求：
+- 每个新增或修改的 requirement 必须至少有一个 `#### Scenario:`
+- `MODIFIED Requirements` 必须包含完整的新 requirement 文本，不只写差异片段
+- 已完成任务保留原 checkbox 状态
+
+### 4. 校验 OpenSpec
+
+如果 OpenSpec CLI 可用，运行：
+
+```bash
+openspec validate <变更名> --strict
+```
+
+校验失败时，修正文档后重新校验。
+
+### 5. 重新生成 plan-ready.md
+
+根据修订后的 OpenSpec 文档更新 `plan-ready.md`。
+
+规则：
+- 保留原 `## 来源`
+- 追加 `## Amendments`，记录本次修订来源和影响
+- 保留已完成实现步骤的历史上下文
+- 追加新的实现步骤，按执行依赖排序
+- 不删除已经完成或正在执行的步骤，除非用户明确要求废弃并说明迁移方式
+
+建议追加格式：
+
+```markdown
+## Amendments
+
+### YYYY-MM-DD: <简短标题>
+- 原因：<为什么需要改>
+- 影响规格：<spec 路径>
+- 影响任务：<tasks.md 条目>
+
+## 追加实现步骤
+
+### Task N: <任务名>
+- 目标：<做什么>
+- 改动文件：<哪些文件>
+- 验证方式：<怎么验证>
+```
+
+### 6. 同步详细实现计划
+
+如果 `docs/superpowers/plans/YYYY-MM-DD-<变更名>.md` 已存在：
+- 已勾选任务不动
+- 未完成任务可按新需求调整
+- 追加新 task，保留 checkbox
+- 记录本次 amend 来源路径
+
+如果详细实现计划还不存在：
+- 不创建代码实现计划，提示下一步用 `/sddflow build`
+
+### 7. 提示下一步
+
+> "需求变更已写入 OpenSpec，plan-ready.md 已更新。接下来继续 `/sddflow build`。"
+
+## 关键原则
+
+- amend 阶段只允许修改规格、任务、plan-ready.md 和实现计划文档，不直接修改代码
+- amend 是 close/archive 前的受控需求变更入口，不用于修代码
+- 不把 build 中的自然语言补充直接当作实现指令；只要改变需求或验收条件，先 amend
+- 已归档变更不可 amend，必须开启新 change

package/templates/brainstorming.md

@@ -0,0 +1,72 @@
+---
+name: sddflow/brainstorming
+description: Deep design — multi-round exploration to confirm architecture and approach
+---
+
+# Brainstorming: 深度设计
+
+## 目标
+
+通过多轮对话，深入探索需求、方案取舍和架构决策。产出比 proposal 更完整的需求描述和设计方向。
+
+## 中断续接规则
+
+如果用户在本阶段被打断后继续回复、补充范围、回答确认问题、或修正边界，仍然停留在 brainstorming 阶段。继续收敛设计并更新 `openspec/changes/**/proposal.md`，不要因为用户明确了范围就直接进入实现或修改任何代码。
+
+典型错误：在确认“只改企业端？”后，用户回复“运营端也要做回显”，这只是范围修正，必须继续记录需求和方案，不得直接修改任何代码或实现文件。
+
+## 流程
+
+### 1. 理解背景
+
+先快速检查项目上下文：
+- 最近的相关 git 提交
+- 现有代码结构
+- 相关文档
+
+### 2. 逐个提问
+
+一次只问一个问题，逐步深入。问题类型：
+
+- **目的** — "这个功能的核心用户场景是什么？"
+- **取舍** — "A 方案更简单但扩展性差，B 方案更灵活但复杂。你倾向哪个？"
+- **边界** — "如果 X 情况发生，期望的行为是什么？"
+- **优先级** — "这几个需求里，哪个最重要？"
+
+### 3. 提出 2-3 种方案
+
+基于讨论，提出 2-3 种实现方案，附上取舍分析。推荐一种并说明理由。
+
+### 4. 确认设计
+
+用户选定方案后，整理设计要点并与用户确认：
+
+> "确认的设计方向：[方案名]。核心决策：[2-3 条]。这样对吗？"
+
+### 5. 创建 OpenSpec 变更目录
+
+用户确认后，按 OpenSpec 目录约定创建变更。`<变更名>` 使用 kebab-case、动词开头（如 `add-user-login`）：
+
+```bash
+mkdir -p openspec/changes/<变更名>/specs
+```
+
+将确认的需求描述和设计方向写入 `openspec/changes/<变更名>/proposal.md`。
+
+如果 OpenSpec CLI 可用，可用以下命令检查当前变更列表：
+
+```bash
+openspec list
+```
+
+### 6. 提示下一步
+
+> "需求已记录。接下来可以用 `/sddflow spec` 生成完整规格。"
+
+## 注意
+
+- 不要写代码
+- 本阶段只允许写 OpenSpec 需求/设计方向文档，禁止修改任何代码或实现文件
+- 不要跳过取舍讨论直接给答案
+- 如果项目很大，建议先拆分成独立的子项目
+- 允许用户改变方向，不要过早锁定

package/templates/build.md

@@ -0,0 +1,81 @@
+---
+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 的会话记忆

package/templates/close.md

@@ -0,0 +1,91 @@
+---
+name: sddflow/close
+description: Verify implementation consistency and archive
+---
+
+# Close: 验证归档
+
+## 目标
+
+验证代码实现与设计文档一致，确认规格变更全部体现，然后归档。
+
+## 中断续接规则
+
+如果用户在 close 阶段被打断后继续回复、说“继续”、或要求完成归档，保持 close 阶段并继续验证/归档。close 阶段不允许顺手修代码；发现差异只记录到 `close-issues.md`。
+
+## 前置条件
+
+- `docs/superpowers/plans/` 下的实现计划全部 checkbox 已勾选
+- `openspec/changes/<变更名>/plan-ready.md` 存在
+
+## 流程
+
+### 1. 确认实现状态
+
+检查 `docs/superpowers/plans/` 下对应的计划文件，确认所有 checkbox 已勾选。
+
+如果有未完成的 task：
+> "还有 N 个任务未完成。请先用 /sddflow build 完成实现。"
+
+### 2. 验证设计一致性
+
+读取 `openspec/changes/<变更名>/design.md`，逐项检查代码实现：
+
+- design.md 中的技术决策是否在代码中体现？
+- 标记的架构选择是否与代码结构一致？
+
+对每一项，给出判定：✅ 一致 / ❌ 不一致（附具体差异）
+
+### 3. 验证规格完整性
+
+读取 `openspec/changes/<变更名>/specs/` 目录，检查每个规格变更：
+
+- 标记为"新增"的功能是否已实现？
+- 标记为"修改"的行为是否已更新？
+- 标记为"删除"的旧逻辑是否已移除？
+
+对每一项，给出判定：✅ 已体现 / ❌ 未体现（附具体缺失）
+
+### 4. 处理不一致
+
+如果发现不一致：
+- **不在 close 阶段改代码**
+- 将不一致项记录到 `openspec/changes/<变更名>/close-issues.md`
+- 提示用户：
+  > "发现 N 处不一致，已记录到 close-issues.md。是否需要开启新的变更来修复？"
+
+### 5. 归档
+
+全部一致（或用户接受不一致项）后，先校验变更：
+
+```bash
+openspec validate <变更名> --strict
+```
+
+校验通过后执行归档：
+
+```bash
+openspec archive <变更名> --yes
+```
+
+如果 OpenSpec CLI 不可用，手动归档：
+
+```bash
+mkdir -p openspec/changes/archive
+mv openspec/changes/<变更名> openspec/changes/archive/$(date +%Y-%m-%d)-<变更名>/
+```
+
+归档后确认：
+- 规格增量已合并到主规格库（如适用）
+- 变更记录已移到 archive 目录
+
+### 6. 完成提示
+
+> "变更 '<变更名>' 已验证并归档。可以开始下一个变更了。"
+
+## 关键原则
+
+- close 阶段不做代码修改，只做验证和归档
+- 本阶段只允许写归档、验证记录或 `close-issues.md`；禁止修改任何代码或实现文件
+- 不一致先记录，不现场修复
+- 防止边写代码边改需求的恶性循环

package/templates/proposal.md

@@ -0,0 +1,62 @@
+---
+name: sddflow/proposal
+description: Lightweight requirement capture — 3-5 questions to quickly converge on requirements
+---
+
+# Proposal: 轻量需求捕获
+
+## 目标
+
+用最少的提问，把用户脑子里的需求变成可执行的变更描述。不做深度设计，不生成代码。
+
+## 中断续接规则
+
+如果用户在本阶段被打断后继续回复、补充范围、回答确认问题、或修正边界，仍然停留在 proposal 阶段。继续更新 `openspec/changes/**/proposal.md`，不要因为用户说“就这样做”“继续”“范围改成 X”而写任何代码或实现文件。
+
+典型错误：proposal 阶段确认“只改企业端？”后，用户回复“运营端也要做回显”。这只是需求范围补充，必须继续更新 proposal，不得直接修改任何代码或实现文件。
+
+## 流程
+
+### 1. 提出关键问题
+
+一次性提出以下 3-5 个核心问题（根据上下文调整措辞）：
+
+1. **做什么** — 你想实现什么功能/变更？
+2. **为什么** — 解决什么问题？给谁用的？
+3. **成功标准** — 怎样算做完了？验收条件是什么？
+4. **边界** — 什么不在范围内？
+5. **现有约束** — 有没有技术栈、兼容性、时间上的限制？
+
+### 2. 确认需求
+
+用户回答后，整理成一段简洁的需求描述，与用户确认：
+
+> "我理解的需求是：[一句话概括]。具体来说：[2-3 条要点]。这样理解对吗？"
+
+### 3. 创建 OpenSpec 变更目录
+
+用户确认后，按 OpenSpec 目录约定创建变更。`<变更名>` 使用 kebab-case、动词开头（如 `add-user-login`）：
+
+```bash
+mkdir -p openspec/changes/<变更名>/specs
+```
+
+将确认的需求描述写入 `openspec/changes/<变更名>/proposal.md`。
+
+如果 OpenSpec CLI 可用，可用以下命令检查当前变更列表：
+
+```bash
+openspec list
+```
+
+### 4. 提示下一步
+
+> "需求已记录。接下来可以用 `/sddflow spec` 生成完整规格，或继续补充细节。"
+
+## 注意
+
+- 不要做技术设计，那是 spec 和 brainstorming 的事
+- 不要写代码
+- 本阶段只允许写 OpenSpec 需求文档，禁止修改任何代码或实现文件
+- 问题要具体，不要泛泛而谈
+- 如果用户的需求很大（跨多个独立子系统），建议拆分

package/templates/spec.md

@@ -0,0 +1,111 @@
+---
+name: sddflow/spec
+description: Call OpenSpec to generate specs, auto-translate to plan-ready.md after user confirmation
+---
+
+# Spec: 生成规格并翻译
+
+## 目标
+
+调用 OpenSpec 生成完整的规格文档（proposal.md, design.md, specs/, tasks.md），用户确认后自动翻译成 Superpowers 可执行的 plan-ready.md。
+
+## 中断续接规则
+
+如果用户在本阶段被打断后继续回复、补充范围、要求调整规格、或确认规格摘要，仍然停留在 spec 阶段。只更新 `openspec/changes/**` 与 `plan-ready.md`，不要修改任何代码或实现文件。
+
+## 前置条件
+
+- `openspec/changes/` 下存在活跃变更目录（由 proposal 或 brainstorming 阶段创建）
+- 变更目录下至少有 `proposal.md`
+
+## 流程
+
+### 1. 确认活跃变更
+
+检查 `openspec/changes/` 下是否有活跃变更（非 archive 子目录）。
+
+如果没有，提示用户：
+> "还没有活跃变更。请先用 /sddflow proposal 或 /sddflow brainstorming 创建需求。"
+
+如果有多个，列出并让用户选择：
+> "检测到多个活跃变更：[列表]。要对哪个生成规格？"
+
+### 2. 生成 OpenSpec 规格文件
+
+根据 proposal.md 的内容生成或补齐以下文件：
+
+- `openspec/changes/<变更名>/proposal.md` — 已存在，可补充
+- `openspec/changes/<变更名>/design.md` — 技术方案
+- `openspec/changes/<变更名>/specs/` — 具体规格变更（标记新增/修改/删除）
+- `openspec/changes/<变更名>/tasks.md` — 实现任务清单
+
+如果 OpenSpec CLI 可用，生成后运行校验：
+
+```bash
+openspec validate <变更名> --strict
+```
+
+如果校验失败，根据错误修正上述文件后重新校验。
+
+### 3. 与用户确认规格
+
+展示规格摘要，逐项确认：
+
+> "以下是规格摘要：
+> - **提案**：[proposal.md 核心内容]
+> - **设计**：[design.md 核心决策]
+> - **任务**：[tasks.md 任务列表]
+>
+> 有需要调整的地方吗？"
+
+用户确认后才进入翻译步骤。
+
+### 4. 自动生成 plan-ready.md（翻译层）
+
+用户确认后，自动将 OpenSpec 四文件翻译为 Superpowers 可执行的格式。
+
+**翻译规则：**
+1. 每个 OpenSpec Task 拆成 2-5 个细粒度步骤（对应 2-5 分钟工作量）
+2. 每个步骤必须指明改哪个文件
+3. 每个步骤必须有验证方式
+4. **按执行依赖排序，不是按功能模块排序**
+5. 记录来源路径，方便回溯
+
+读取以下文件作为翻译输入：
+- `openspec/changes/<变更名>/proposal.md`
+- `openspec/changes/<变更名>/design.md`
+- `openspec/changes/<变更名>/specs/` 目录下所有文件
+- `openspec/changes/<变更名>/tasks.md`
+
+生成 `openspec/changes/<变更名>/plan-ready.md`，格式如下：
+
+```markdown
+# 实现计划：<变更名>
+
+## 来源
+- 提案：openspec/changes/<变更名>/proposal.md
+- 设计：openspec/changes/<变更名>/design.md
+- 规格：openspec/changes/<变更名>/specs/
+- 任务：openspec/changes/<变更名>/tasks.md
+
+## 实现步骤
+
+### Task 1: <任务名>
+- 目标：<做什么>
+- 改动文件：<哪些文件>
+- 验证方式：<怎么验证>
+
+### Task 2: ...
+```
+
+### 5. 提示下一步
+
+> "规格已确认，plan-ready.md 已生成。接下来可以用 `/sddflow build` 开始实现。"
+
+## 关键原则
+
+- **一条代码都不许写** — spec 阶段只产出文档
+- 本阶段只允许写 `openspec/changes/**` 与 `plan-ready.md`，禁止修改任何代码或实现文件
+- 翻译必须在用户确认后自动生成，不需要用户手动触发
+- plan-ready.md 的 ## 来源 部分必须写明路径，方便 Superpowers 执行时回溯
+- 按执行依赖排序是翻译的关键步骤：先依赖后依赖方