sdd-workflow 1.1.0

package/templates/skills/sdd-run/SKILL.md

@@ -0,0 +1,439 @@
+---
+name: sdd-run
+description: SDD v3 全自动执行流水线 - 先需求澄清，再自主运行规划器→生成器→评估器循环，人类只验证最终结果
+invocable: true
+---
+
+# SDD Run - 全自动执行流水线
+
+> **受 Anthropic Harness 设计启发**：将规划（Planner）、生成（Generator）、评估（Evaluator）三角色合一，
+> 形成自主闭环。人类只提供初始需求，只验证最终结果。
+
+一次性自动执行完整的 SDD 流程：`specify → testcases → plan → tasks → implement → review`，
+无需人类在中间步骤确认。评审不通过自动迭代修复，最多 3 轮。
+
+## 核心原则
+
+1. **自主执行**：中间步骤不需要人类确认，自动推进
+2. **文件驱动**：各阶段通过文件产物传递上下文，不依赖人类传话
+3. **自动迭代**：评审不通过时自动修复并重新评审
+4. **人类主权**：L3 级问题（方向性错误）暂停等待人类决策
+5. **幂等恢复**：产出文件实时保存，中断后可从指定阶段继续
+
+## 前置条件
+
+- 项目宪法: `.specify/memory/constitution.md`
+- 项目配置: `CLAUDE.md`
+- 如果是已有功能迭代：已有 `.specify/specs/{feature_id}/` 目录
+
+## 输入格式
+
+```
+/sdd-run {feature_id} {功能描述或知识库链接}
+/sdd-run {feature_id} --from {stage}     # 从指定阶段恢复执行
+```
+
+**feature_id 命名规范**：
+
+- **格式**: 三位数字编号，从 `001` 开始自增（如 `001`, `002`, `003`...）
+- **目录命名**: `{feature_id}-{feature-name}/`（如 `001-user-auth/`, `002-data-export/`）
+- **自动确定编号**: 如果用户未指定 feature_id，扫描 `.specify/specs/` 下已有目录，取最大编号 + 1
+- **feature-name**: 英文小写，中划线分隔，简短概括功能
+
+**示例**：
+```
+/sdd-run 004 新增版本对比功能
+/sdd-run 004 https://知识库URL/需求文档
+/sdd-run 004 --from implement            # 从实现阶段继续
+/sdd-run 新增导出功能                    # 自动确定下一个编号
+```
+
+---
+
+## 执行流程
+
+### 总体架构
+
+```
+人类输入: "/sdd-run 004 新增XX功能"
+         │
+         ▼
+┌──────────────────────────────────────────────┐
+│  Phase 0: 需求澄清（唯一的人类交互环节）        │
+│    分析需求 → 一次性提出所有澄清问题             │
+│    → 人类回答 → 确认无误 → 进入全自动           │
+│         │                                     │
+│         ▼  ⛔ 此后全自动，不再打扰人类           │
+│  Phase A: 规划器（Planner）                    │
+│    A1. specify → A2. testcases →              │
+│    A3. plan → A4. tasks                       │
+│         │                                     │
+│         ▼                                     │
+│  Phase B: 生成器（Generator）                  │
+│    B1. implement（全自动）                     │
+│         │                                     │
+│         ▼                                     │
+│  Phase C: 评估器（MACE 多Agent竞争评审）        │
+│    C1. 并行派发 3 个评审 Agent                  │
+│    ├─ A:严苛审查员 → 功能+代码质量              │
+│    ├─ B:需求守护者 → 需求+边界处理              │
+│    └─ C:集成检查员 → 集成+架构合规              │
+│    C2. 仲裁合并 → 不通过？                      │
+│         │          │                          │
+│         │          ▼                          │
+│         │    自动修复 → 重新派发3个Agent         │
+│         │          （最多3轮）                  │
+│         ▼                                     │
+│  输出最终报告 ──→ 人类验证                      │
+└──────────────────────────────────────────────┘
+```
+
+---
+
+### Phase 0: 需求澄清（Requirement Clarification）
+
+> **全流程中唯一的人类交互环节**。澄清完成后进入全自动模式，不再打扰人类。
+
+**目标**：在动手之前，一次性把所有不确定的点问清楚，避免后期返工。
+
+**执行流程**：
+
+#### 0.1 需求预分析
+
+1. **解析输入**：提取功能名称、描述、知识库链接（如有）
+2. **获取知识库文档**（如有链接）：如果项目配置了知识库 MCP（如 Confluence），使用对应工具获取原始需求
+3. **读取项目上下文**：
+   - `.specify/memory/constitution.md`（技术栈约束）
+   - `CLAUDE.md`（项目配置）
+   - 同模块已有的 spec 文档（如有）
+4. **扫描相关代码**（如涉及现有模块）：了解当前实现状态
+
+#### 0.2 生成澄清问题
+
+基于预分析结果，列出需要确认的问题。**只问真正不确定的**，不问文档中已明确的内容。
+
+**典型问题分类**：
+
+| 分类 | 示例问题 |
+|------|----------|
+| 业务范围 | 这个功能是新增还是对现有功能的修改？影响哪些页面/接口？ |
+| 规则确认 | 对比的基准是哪个？差异判定规则是什么？ |
+| 数据来源 | 数据从哪个表/接口获取？有现成的 API 可复用吗？ |
+| 边界条件 | 最多支持多少条数据？并发场景需要考虑吗？ |
+| 排除项 | 这次不需要做 XX 功能对吧？（确认负向范围） |
+| 非功能需求 | 性能要求？权限控制？ |
+
+**输出格式**：
+
+```
+━━━ 需求澄清 ━━━
+
+我已分析你的需求「{功能描述}」，以下问题需要确认：
+
+1. {问题} — （{为什么需要确认}）
+2. {问题} — （{为什么需要确认}）
+3. ...
+
+请逐一回答，或补充你认为重要的信息。确认完毕后我将全自动执行，不再打扰。
+```
+
+#### 0.3 澄清规则
+
+- **一次性提问**：把所有问题集中在一轮提出，不要多轮追问
+- **给出默认选项**：每个问题尽量提供 2-3 个候选答案，人类可以直接选择
+- **标注优先级**：关键问题标注 [必答]，次要问题标注 [可选]
+- **已有答案不问**：文档或现有代码中已明确的信息不重复确认
+- **最少问题原则**：如果预分析后没有不确定项，直接说明"无需澄清"并进入全自动
+
+#### 0.4 澄清完成
+
+人类回答后：
+1. 整理澄清结论，保存到 `.specify/specs/{feature_id}/requirements/clarification.md`
+2. 简要复述理解，确认无误解
+3. **进入全自动模式**：此后直到最终报告输出，不再打扰人类
+
+```
+✅ 需求澄清完成，我的理解是：
+  - {要点1}
+  - {要点2}
+  - ...
+
+🚀 开始全自动执行，预计产出 spec → testcases → plan → tasks → implement → review
+过程中如有 L3 级方向性问题会暂停，否则一路到底。
+```
+
+---
+
+### Phase A: 规划器（Planner）
+
+目标：从需求到完整的开发计划，全自动生成。
+
+#### A1. 生成功能规格（specify）
+
+**读取**：
+- 用户提供的功能描述或知识库链接
+- `.specify/memory/constitution.md`
+- `CLAUDE.md`
+- 如果有知识库链接：使用已配置的知识库 MCP 工具获取原文
+
+**执行**：
+1. 解析用户输入，提取功能名称、描述、知识库链接
+2. 如有知识库链接，获取原始需求并保存到 `requirements/original.md`
+3. 读取相关现有 spec（同模块的其他 spec）
+4. 生成 spec.md，包含：
+   - 用户故事 + 验收标准（Gherkin 格式）
+   - 功能需求列表
+   - 界面需求（ASCII 示意）
+   - 边界条件
+   - **功能分组与完成定义**（SDD v2 新增）
+5. 保存到 `.specify/specs/{feature_id}/spec.md`
+
+**产物**：`spec.md`
+
+**跳过确认**：直接进入下一步。
+
+**自动拆分检查**：spec.md 保存后，检查文件行数。超过 500 行时，自动执行 `/sdd-split spec {feature_id} --auto`。
+
+#### A2. 生成测试用例（testcases）
+
+**读取**：上一步的 `spec.md`
+
+**执行**：
+1. 从 spec 提取用户故事、验收标准、边界条件
+2. 设计测试用例（UT/IT/API/FT/ST/E2E/B）
+3. 生成 testcases.md
+4. 如果发现 spec 描述模糊（无法写 Given-When-Then），按 L2 反馈补充 spec
+
+**产物**：`testcases.md`
+
+#### A3. 生成技术计划（plan）
+
+**读取**：`spec.md` + `testcases.md`
+
+**执行**：
+1. 分析现有代码结构（参考 CLAUDE.md 和 constitution.md）
+2. 设计架构方案（参考 constitution.md 中的架构模式）
+3. 生成 plan.md，包含：
+   - 数据模型设计（DDL）
+   - API 设计（URL、参数、响应格式）
+   - 前后端实现设计
+   - **阶段合约**（每个 Phase 的交付物 + 验证标准 + 质量阈值）
+4. 如果发现需求技术上不可行，按 L3 暂停等待人类
+
+**产物**：`plan.md`
+
+**自动拆分检查**：plan.md 保存后，检查文件行数。超过 1000 行时，自动执行 `/sdd-split plan {feature_id} --auto`。
+
+#### A4. 生成任务分解（tasks）
+
+**读取**：`spec.md` + `testcases.md` + `plan.md`
+
+**执行**：
+1. 基于 plan 的技术方案分解为可执行任务
+2. 建立测试-实现映射（测试任务先行）
+3. 生成 tasks.md
+4. 如果 plan 有遗漏（缺接口/组件），按 L1 自动补充
+
+**产物**：`tasks.md`
+
+**自动拆分检查**：tasks.md 保存后，检查文件行数。超过 800 行时，自动执行 `/sdd-split tasks {feature_id} --auto`。
+
+**Planner 完成标志**：四份文件均已保存到 `.specify/specs/{feature_id}/`
+
+---
+
+### Phase B: 生成器（Generator）
+
+目标：按计划自动编写代码，不逐任务确认。
+
+**读取**：`spec.md` + `testcases.md` + `plan.md` + `tasks.md`
+
+#### B1. 自动实现（implement）
+
+**执行流程**：
+
+1. **加载任务文档**：读取 tasks.md，获取所有 Phase 和任务列表
+2. **逐 Phase 执行**：
+   - Phase 1（后端）→ Phase 2（前端）→ Phase 3（测试验收）
+   - 每个 Phase 内逐任务执行
+3. **每个任务**：
+   - 读取任务描述和关联的文件路径
+   - 编写/修改代码
+   - 更新 tasks.md 中的任务状态
+4. **Phase 完成后自动合约自检**：
+   - 对照 plan.md 中的阶段合约
+   - 检查交付物是否齐全
+   - 自检失败则自动修复，最多 3 轮
+5. **反馈处理**：
+   - L1（方案调整）：自动修正 plan/tasks + 代码，记录 CR
+   - L2（需求漏洞）：自动补充 spec + 级联更新，记录 CR
+   - L3（方向性错误）：**暂停，输出影响分析，等待人类决策**
+
+**关键差异**（对比手动 sdd-implement）：
+- 跳过"每完成一个任务等待确认"
+- 跳过"每个 Phase 完成后提示用户运行 review"
+- 反馈自动处理，不等待人类指令
+- 使用 `auto` 模式的行为：遇错暂停修复后继续
+
+**产物**：已实现的代码文件 + 更新的 tasks.md
+
+---
+
+### Phase C: 评估器（MACE 多Agent竞争评审）
+
+目标：3 个独立 Agent 并行评审代码质量，仲裁合并后不通过则自动迭代。
+
+**读取**：`spec.md` + `plan.md` + `testcases.md` + `constitution.md` + 所有已实现的代码文件
+
+> **核心改变**: 评估器不再是单 Agent 自审自评，而是派发 3 个独立 Agent 并行评审。
+> 每个 Agent 拥有独立上下文窗口，看不到 Generator 的思考过程。
+
+#### C1. 并行派发评审 Agent
+
+使用 Agent 工具同时派发 3 个独立评审 Agent：
+
+| Agent | 角色 | 审查维度 | 输入上下文 |
+|-------|------|----------|------------|
+| A: 严苛审查员 | 找出所有代码问题 | 功能完整性 + 代码质量 | spec + plan + 代码 |
+| B: 需求守护者 | 代表最终用户 | 需求一致性 + 边界处理 | spec + testcases + 代码 |
+| C: 集成检查员 | 端到端验证 | 集成完整性 + 架构合规 | plan + testcases + 代码 + constitution |
+
+每个 Agent 的详细 prompt 模板和输出格式，参照 `sdd-review` skill 的「执行步骤 → 3. 并行派发 3 个评审 Agent」。
+
+**Agent 派发要点**：
+1. 将文档内容直接注入 Agent prompt（而非仅传路径），确保 Agent 独立上下文完整
+2. 3 个 Agent **必须并行派发**（单个消息中包含 3 个 Agent 工具调用）
+3. 每个 Agent 输出结构化评审结果（评分 + 问题清单 + 合约检查 + 亮点）
+
+#### C2. 仲裁合并
+
+收集 3 个 Agent 结果后执行仲裁：
+
+1. **问题去重与确认**：
+   - ≥2 个 Agent 报告的相似问题 → 确认（提升一级严重度）
+   - 仅 1 个 Agent 报告 → 待确认（保持原始严重度）
+2. **评分聚合**：每个维度取对应 Agent 的评分
+3. **合约检查合并**：取并集（任一 Agent FAIL → 该合约项 FAIL）
+
+仲裁合并的详细规则，参照 `sdd-review` skill 的「执行步骤 → 4. 仲裁合并」。
+
+#### C3. 评审结论判定
+
+```
+评审结果判定：
+  功能完整性 ≥ 4 AND 需求一致性 ≥ 4 AND 无确认的 HIGH 问题
+    → PASS → 输出最终报告
+
+  否则
+    → ITERATE → 自动修复 → 重新派发 3 个 Agent（回到 C1）
+    → 最多 3 轮，超过则暂停等待人类
+```
+
+**自动修复流程**：
+1. 从仲裁后的评审报告中提取确认问题清单
+2. 按确认人数排序：≥2 个 Agent 确认的优先修复
+3. 按严重度排序：HIGH → MEDIUM → LOW
+4. 逐一修复代码
+5. 修复完成后重新执行 C1-C2（重新派发 3 个 Agent）
+
+**评审报告格式**：参见 `sdd-review` skill 的报告格式（包含 Agent 评审详情和确认情况）。
+
+---
+
+### 最终输出
+
+全自动流水线完成后，输出执行报告：
+
+```
+━━━ SDD v3 执行报告 ━━━
+
+功能: {feature_id} - {功能名称}
+执行时间: {start} ~ {end}
+迭代轮次: {n}
+
+📋 产出文件:
+  ✅ spec.md ({版本})
+  ✅ testcases.md ({N} 个测试场景)
+  ✅ plan.md ({N} Phase, {N} 合约项)
+  ✅ tasks.md ({N} 个任务)
+
+📊 最终评审（MACE 多Agent竞争评审）:
+  功能完整性: {n}/5 (A-严苛审查员) | 需求一致性: {n}/5 (B-需求守护者)
+  代码质量: {n}/5 (A-严苛审查员) | 边界处理: {n}/5 (B-需求守护者)
+  集成完整性: {n}/5 (C-集成检查员)
+  确认问题: {N}项 | 待确认问题: {N}项
+  结论: PASS
+
+📝 变更文件:
+  后端: {N} 个文件新增, {N} 个文件修改
+  前端: {N} 个文件新增, {N} 个文件修改
+
+🔄 迭代记录:
+  Round 1: ITERATE - {问题摘要} → {修复摘要}
+  Round 2: PASS
+
+📋 CR 记录:
+  CR-001: {变更摘要} ({级别})
+
+⏸ 暂停项:
+  {无 / 列出L3暂停项}
+
+请验收以上结果。如需修改，告诉我具体问题。
+```
+
+---
+
+## 中断与恢复
+
+### `--from` 参数
+
+支持从指定阶段开始，跳过已完成的步骤：
+
+```
+/sdd-run 004 --from specify     # 从规格开始（跳过已有的前置准备）
+/sdd-run 004 --from testcases   # 已有 spec，从测试用例开始
+/sdd-run 004 --from plan        # 已有 spec + testcases
+/sdd-run 004 --from tasks       # 已有 spec + testcases + plan
+/sdd-run 004 --from implement   # 已有完整计划，只执行实现
+/sdd-run 004 --from review      # 已实现，只执行评审
+```
+
+**恢复逻辑**：
+1. 检查指定阶段的前置文件是否存在
+2. 缺少前置文件时报错并提示需要先完成的阶段
+3. 从指定阶段开始自动执行后续所有阶段
+
+### L3 暂停恢复
+
+当遇到 L3 级别问题时，流程暂停并输出：
+- 阻塞原因和影响分析
+- 建议的处理方案（可选）
+- 当前已完成阶段和产出文件
+
+人类决策后，可通过 `/sdd-run {feature_id} --from {stage}` 继续。
+
+---
+
+## 与现有 Skill 的关系
+
+| 现有 Skill | sdd-run 中的角色 | 变更 |
+|-----------|-----------------|------|
+| sdd-specify | Planner A1 | 不修改，sdd-run 内部执行等价逻辑 |
+| sdd-testcases | Planner A2 | 不修改，sdd-run 内部执行等价逻辑 |
+| sdd-plan | Planner A3 | 不修改，sdd-run 内部执行等价逻辑 |
+| sdd-tasks | Planner A4 | 不修改，sdd-run 内部执行等价逻辑 |
+| sdd-implement | Generator B1 | 不修改，sdd-run 内部执行等价逻辑 |
+| sdd-review | Evaluator C1-C2（MACE多Agent） | 不修改，sdd-run 内部执行等价逻辑（3 Agent并行派发+仲裁） |
+
+现有 6 个 skill 继续可用，支持手动逐步执行。`sdd-run` 是纯编排层。
+
+---
+
+## 注意事项
+
+1. **不跳过质量**：自动不等于降低标准，评审维度和硬阈值不变
+2. **CR 记录完整**：每次自动修正都记录 CR，保持可追溯性
+3. **宪法优先**：所有代码必须符合 `.specify/memory/constitution.md` 约束
+4. **错误处理**：代码编译/lint 错误自动修复，最多重试 3 次
+5. **不自动提交**：代码修改不自动 git commit，由人类验收后决定
+6. **大文档处理**：spec 超过 500 行、plan 超过 1000 行、tasks 超过 800 行时自动拆分（使用 `--auto` 模式）