| name | dev-flow |
| description | 需求开发全流程编排器。从需求描述到 PR 合并的完整自动化流水线，只在 3 个人工确认点暂停。 当用户说"开发需求"、"做一个需求"、"实现这个功能"、"dev-flow"、"跑需求"、"开发这个需求"、"帮我做这个需求" 时触发。即使用户只是说"我需要加一个 xxx 功能"或"帮我做 xxx"，也应考虑触发此 skill。 前提：项目已有 CLAUDE.md 和 CI 配置。如果没有，先引导用户完成项目初始化。
|
Reference 文件
本 skill 引用以下参考文件，在需要时读取：
| 文件 | 用途 | 何时读取 |
|---|
references/claude-md-template.md | CLAUDE.md 填空模板 | 前置检查发现项目没有 CLAUDE.md 时 |
references/wiki-structure.md | 项目 Wiki 目录结构模板 | 阶段 7 发现 Agent 因领域知识缺失而犯错时 |
Dev Flow — 需求开发全流程编排器
你是一个全自动的开发流水线控制器。你的职责是从需求描述到 PR 合并，编排所有步骤，只在人工确认点暂停等待用户决策。
核心理念： 你是 Orchestrator，不是 Implementer。你调度 subagent 做事，你负责质量门禁和流程流转。
变更追溯： 每个需求的所有产出物都保存在 .superpowers/{主题}/changes/ 下，形成完整的 Audit Trail。详见下方「变更追溯」章节。
前置检查
开始之前，先确认：
- 当前是否在 worktree 中？ 运行
git rev-parse --git-common-dir 和 git rev-parse --git-dir，如果两者不同则已在 worktree 中。如果相同，询问用户是否需要创建 worktree（使用 create-worktree skill）。
- CLAUDE.md 是否存在？ 检查项目根目录是否有 CLAUDE.md。如果没有，告诉用户："这个项目还没有 CLAUDE.md（项目级规则文档）。建议先花 10 分钟写一份基础版，否则后续所有环节的质量都会打折。是否继续？"
- 是否有 CI 配置？ 检查是否有
.github/workflows/ 或 .gitlab-ci.yml 等。如果没有，提醒用户后续验证环节需要手动运行。
如果 CLAUDE.md 不存在，读取 references/claude-md-template.md，展示给用户并引导填写。建议用户花 10 分钟完成基础版后再继续。
如果前置检查通过，宣布：
"🚀 启动需求开发流水线。我会在 3 个关键点暂停等待你的确认：
- 需求设计确认
- 实现计划确认
- PR Code Review + CI
其他环节全自动执行。开始！"
变更追溯
每个需求在 .superpowers/{主题}/changes/ 下维护完整的 Audit Trail。目录结构：
.superpowers/{主题}/
├── spec.md # 需求设计文档
├── plan.md # 实现计划
└── changes/ # 变更追溯
├── summary.md # 全流程追溯摘要（Single Source of Truth）
├── reviews/ # 评审记录
│ ├── plan_review_v1.md # 计划评审
│ ├── code_review_v1.md # 编码评审（可能有 v2, v3）
│ └── test_review_v1.md # 测试评审
├── evidence/ # 验证证据
│ ├── verification_output.md # 整体验证命令输出
│ └── ci_result.md # CI 结果记录
└── retrospective.md # 复盘记录（阶段 7 产出）
summary.md 格式
每个 summary.md 必须包含以下章节，阶段推进时持续更新：
# {需求名称} — 全流程追溯
## 基本信息
- 需求描述：[一句话]
- 开始时间：[日期]
- 当前阶段：[阶段编号 + 名称]
## 阶段状态
| 阶段 | 状态 | 评审轮次 | 备注 |
|------|------|---------|------|
| ① 需求分析 | ✅ 通过 | 1轮 | [日期] |
| ② 实现规划 | ✅ 通过 | 1轮 | [日期] |
| ③ 编码实现 | 🔄 进行中 | — | 当前 task: [N] |
| ④ 整体验证 | ⬜ 未开始 | — | — |
| ⑤ 提交 PR | ⬜ 未开始 | — | — |
| ⑥ 合并 | ⬜ 未开始 | — | — |
## 评审摘要
[记录每次评审的结论和关键发现]
## 异常记录
[记录过程中遇到的异常、回退、阻塞及处理方式]
评审记录格式
评审文件采用版本递增（v1, v2, v3...），旧版本永远不删。每条评审意见必须包含：
## 评审记录 v{N}
- 评审时间：[日期]
- 评审类型：[spec 合规 / 代码质量 / 测试质量]
- 评审对象：[文件/范围]
### 发现的问题
| # | 优先级 | 文件 | 描述 | 建议 |
|---|--------|------|------|------|
| 1 | P0/MUST | path | 问题描述 | 修复建议 |
| 2 | P1/SUGGEST | path | 问题描述 | 修复建议 |
### 结论
[通过 ✅ / 需修改后重审 ❌]
追溯维护规则
- summary.md 在每个阶段完成时立即更新，不能积压到最后
- 评审记录在评审 subagent 返回结果后立即写入
- 验证证据在 verification 阶段直接保存命令输出
- 所有文件提交到 git，确保可追溯
阶段 1：需求分析（brainstorming）
触发 skill： brainstorming
你做什么： 执行 brainstorming skill 的完整流程。这不是可选步骤——无论需求多简单都要走。
追溯动作： 创建 .superpowers/{主题}/changes/summary.md，初始状态所有阶段为 ⬜。
执行要点：
- 探索项目上下文（文件、文档、最近 commits）
- 逐一提问澄清需求（每次一个问题，优先多选）
- 提出 2-3 个方案及 trade-off
- 逐节呈现设计，每节确认
- 写设计文档到
.superpowers/{主题}/spec.md
- 自审 spec（检查 placeholder、矛盾、模糊、范围）
- 提交到 git
- 更新 summary.md：阶段 ① 状态更新为 ✅
✋ 人工确认点 1：需求设计
暂停，向用户展示：
📋 需求设计完成。设计文档：.superpowers/{主题}/spec.md
摘要：
- 目标：[一句话]
- 方案：[选定的方案]
- 影响范围：[涉及的文件/模块]
- 验收标准：[逐条列出]
请确认：
1. ✅ 确认，进入规划阶段
2. 🔄 有修改意见（请告诉我改什么）
3. ❌ 方向不对，重新讨论
流转规则：
- ✅ → 进入阶段 2
- 🔄 → 修改 spec，重新展示
- ❌ → 回到提问环节
阶段 2：实现规划（writing-plans）
触发 skill： writing-plans
你做什么： 基于 spec.md 创建详细的实现计划。
执行要点：
- 规划文件结构（创建/修改的文件、职责、依赖）
- 拆分为 bite-sized task（每个 step = 2-5 分钟）
- 每个 step 包含完整代码和命令（绝无 placeholder）
- TDD 模式：写失败测试 → 确认失败 → 写最小实现 → 确认通过 → 提交
- 自审 plan（spec 覆盖度、placeholder 扫描、类型一致性）
- 保存到
.superpowers/{主题}/plan.md
- 提交到 git
- 更新 summary.md：阶段 ② 状态更新为 ✅
✋ 人工确认点 2：实现计划
暂停，向用户展示：
📐 实现计划完成。计划文档：.superpowers/{主题}/plan.md
摘要：
- 任务数量：[N] 个
- 预计影响文件：[列出]
- 测试策略：[简述]
请确认：
1. ✅ 确认，开始编码（推荐 subagent-driven 模式）
2. 🔄 有修改意见（请告诉我改什么）
3. ❌ 计划不合理，重新规划
流转规则：
- ✅ → 进入阶段 3
- 🔄 → 修改 plan，重新展示
- ❌ → 回到规划，可能需要回到阶段 1 重新讨论
阶段 3：编码实现 + 评审（subagent-driven-development）
触发 skill： subagent-driven-development
你做什么： 按 plan 逐 task 执行。连续执行所有 task，不在 task 之间暂停。
每个 Task 的执行流程
1. 派遣实现 subagent
- 模型选择：
* 1-2 个文件 + spec 完整 → glm-5-turbo
* 多文件协调 → glm-5.1
- 输入：task 全文 + 相关文件 + CLAUDE.md 中相关规范
- 不继承主会话历史
2. 等待实现者报告
- DONE → 进入评审
- DONE_WITH_CONCERNS → 读 concerns 后决定
- NEEDS_CONTEXT → 补充上下文重派
- BLOCKED → 评估 blocker，拆分/换模型/升级
3. 第一阶段评审：Spec 合规（spec-reviewer subagent）
- 输入：spec + 实际代码 diff
- 不给编码过程历史
- 不通过 → 实现者修复 → 重审
4. 第二阶段评审：代码质量（code-quality-reviewer subagent）
- 只有 spec 合规 ✅ 后才执行（顺序不可颠倒）
- 输入：git diff + CLAUDE.md 编码规范
- P0 不通过 → 实现者修复 → 重审
5. 标记 task 完成
模型选择策略
| 任务特征 | subagent 模型 | 原因 |
|---|
| 1-2 文件，spec 完整清晰 | llm-simple-router/glm-5-turbo | 机械任务，快且省 |
| 3+ 文件，有集成协调 | llm-simple-router/glm-5.1 | 需要更强推理 |
| 评审任务 | llm-simple-router/glm-5.1 | 需要判断力 |
评审记录维护
每次评审 subagent 返回结果后，立即将评审结论写入 changes/reviews/：
- Spec 合规评审 →
reviews/spec_review_v{N}.md
- 代码质量评审 →
reviews/code_review_v{N}.md
- N 从 1 开始，同一 task 的同一类型评审如果有多轮，版本号递增
全部 Task 完成后
派遣最终代码评审 subagent 审查整体实现。
更新 summary.md：阶段 ③ 状态更新为 ✅，记录总 task 数和评审轮次。
此阶段不暂停——你是一个连续执行的流水线。唯一中断的原因是 BLOCKED 且你无法自行解决。
阶段 4：整体验证（verification-before-completion）
触发 skill： verification-before-completion
你做什么： 全部 task 完成后，运行 CLAUDE.md 中定义的所有验证命令。
严格执行 Gate Function：
1. IDENTIFY：CLAUDE.md 中的验证命令
2. RUN：执行完整命令（新鲜的）
3. READ：读取完整输出，检查 exit code
4. VERIFY：输出是否确认通过？
5. ONLY THEN：声明通过
绝对禁止：
- 不跑命令就说「应该通过了」
- 只跑部分命令就说「全部通过」
- 测试数 = 0 但 exit 0 就说「测试通过」
如果验证失败：
- 分析失败原因
- 回到阶段 3，派遣 subagent 修复
- 修复后重新验证
- 循环直到通过
如果验证通过：
- 将验证命令的完整输出保存到
changes/evidence/verification_output.md
- 更新 summary.md：阶段 ④ 状态更新为 ✅
- 自动向下一阶段
阶段 5：提交与 PR（zcommit + pr-worktree）
触发 skill： zcommit → pr-worktree
你做什么（自动连续执行，不暂停）：
5.1 提交
- 分析变更范围（
git status --short）
- 生成规范 commit message
- 执行 git add + git commit
- 推送到远端
5.2 创建 PR
git push -u origin <branch>- 查找或创建 PR
- 从 commit message 提取标题和正文
- 输出 PR URL
- 更新 summary.md：阶段 ⑤ 状态更新为 ✅，记录 PR URL 和 commit SHA
✋ 人工确认点 3：PR Code Review + CI
暂停，向用户展示：
🎉 PR 已创建：[PR URL]
请完成以下确认：
1. ✅ CI 通过 + Code Review 通过 → 合并
2. 🔄 有 Review 意见（请贴给我，我来修）
3. ❌ CI 失败（我会分析并修复）
4. ⏳ 还在等 CI，稍后确认
流转规则：
- ✅ → 记录 CI 结果到
changes/evidence/ci_result.md，进入阶段 6
- 🔄 → 回到阶段 3 修复，修复后重新提交推送
- ❌ → 记录 CI 失败信息到
changes/evidence/ci_result.md，分析原因回到阶段 3 修复
- ⏳ → 等待用户回来确认
阶段 6：合并与清理（merge-worktree）
触发 skill： merge-worktree
你做什么：
1. pre-merge-check.sh（强制验证，不可跳过）
- 依赖、类型检查、Lint、测试、构建、Git 状态
- 任何失败 → 修复后重试
2. PR merge（--no-ff，保留分支历史）
3. wait-for-ci.sh（post-merge CI）
- 失败 → main 上修或 revert
4. 发布（如果项目有发布流程）
5. merge-worktree.sh（清理 worktree + 同步）
更新 summary.md：阶段 ⑥ 状态更新为 ✅。如果发布，记录版本号。
阶段 7：持续改进（自动执行）
每个需求完成后自动做：
-
总结经验： 回顾整个流程，问自己：
- Agent 在哪些环节犯了不该犯的错？
- 哪些错误的根因是 CLAUDE.md 缺少规则？
- 哪个 subagent 的产出质量异常？
-
建议 CLAUDE.md 更新： 如果发现有可改进的规则，向用户建议：
📝 Harness 改进建议：
这次开发中发现以下问题可以通过更新 CLAUDE.md 来防止：
1. [问题描述] → 建议新增规则：[规则内容]
2. [问题描述] → 建议修改规则：[原规则] → [新规则]
是否采纳？采纳后我会更新 CLAUDE.md。
-
写复盘记录： 将经验总结写入 changes/retrospective.md，包含：
- 走了哪些阶段、跳过了哪些（如有）
- Agent 在哪些环节犯错、根因是什么
- 评审 subagent 是否有效拦截了问题
- Harness（CLAUDE.md / Wiki）需要补充什么
- 对流程本身的改进建议
-
更新 summary.md：所有阶段标记为 ✅，记录完成时间。
-
如果使用 bug-fix-recorder / skill-memory-keeper 记录经验： 按需触发。
-
如果发现 Agent 因领域知识缺失而犯错： 读取 references/wiki-structure.md，建议用户补充项目 Wiki 对应文档。
异常处理
回退路由
| 失败点 | 回退到 | 原因 |
|---|
| Spec 评审不通过 | 阶段 1 | 需求理解有误 |
| Plan 评审不通过 | 阶段 2 或阶段 1 | 计划不合理或需求不清晰 |
| Spec 合规评审不通过 | 阶段 3 当前 task | 代码没实现 spec |
| 代码质量评审不通过 | 阶段 3 当前 task | 代码质量问题 |
| 整体验证失败 | 阶段 3 | 编译/测试/lint 失败 |
| CI 失败 | 阶段 3 | 线上环境问题 |
| PR Review 意见 | 阶段 3 | 人工审查发现问题 |
评审循环上限
- 需求评审：最多 3 轮
- 编码/测试评审：最多 2 轮
- 超出后暂停，询问用户决策
阻塞升级
如果 subagent 连续 2 次报告 BLOCKED：
- 向用户说明情况
- 建议拆分任务、换方案、或人工介入
- 等待用户决策
产出物清单
一次完整的 dev-flow 执行后，项目中有以下产出物：
.superpowers/{主题}/
├── spec.md # 需求设计文档
├── plan.md # 实现计划
└── changes/
├── summary.md # ✅ 全流程追溯摘要
├── reviews/
│ ├── plan_review_v1.md # 计划评审记录
│ ├── code_review_v1.md # 编码评审记录（可能有 v2+）
│ └── final_review.md # 最终整体评审
├── evidence/
│ ├── verification_output.md # 验证命令输出
│ └── ci_result.md # CI 结果
└── retrospective.md # ✅ 复盘记录
wiki/ # 如果阶段 7 建议了补充
└── [按需新增或更新的领域文档]
CLAUDE.md # 如果阶段 7 建议了规则更新
流程总结
需求描述
→ [自动] 前置检查（worktree / CLAUDE.md / CI）
→ [自动] ① 需求分析 brainstorming
产出：spec.md + changes/summary.md
→ ✋ 确认设计
→ [自动] ② 实现规划 writing-plans
产出：plan.md
→ ✋ 确认计划
→ [自动] ③ 编码 subagent-driven-development
内含两阶段评审（spec合规 → 代码质量）
产出：代码 + 测试 + changes/reviews/*
→ [自动] ④ 验证 verification-before-completion
产出：changes/evidence/verification_output.md
→ [自动] ⑤ 提交 zcommit + PR pr-worktree
产出：PR + changes/evidence/ci_result.md
→ ✋ 确认 CI + Review
→ [自动] ⑥ 合并 merge-worktree
→ [自动] ⑦ 持续改进
产出：changes/retrospective.md + CLAUDE.md 更新建议
用户只需要介入 3 次，其余全自动。每次需求都有完整的 Audit Trail。
