用途
dev-flow 是一个不依赖 keel 文档体系的通用开发执行器,用于在非 keel 项目中按任务、Issue 或已有计划实现功能与修复问题。它的输入形态包括:计划文档路径(如 superpowers writing-plans 产出的 Markdown checklist)、任务 prompt、issue 文本,以及代码上下文提示(仅作 scope hint)。用户给出计划文档要求逐项实施、给出任务描述或 issue 文本要求直接开发且项目无 keel 文档体系、或要求“轻量/通用/独立的开发流程”时,均可触发本 skill。
路由判定:项目存在 docs/devdocs/ 且任务有 T-XX 编号 → 用 /dev-workflow;否则用本 skill。
主要能力与五阶段流程
dev-flow 将开发过程划分为五个阶段:
- 输入定位:读取输入,扫描代码上下文,产出目标、范围、风险、候选测试命令。
- 执行契约:协商 Execution Contract,产出契约 yaml,通过 Contract Gate。
- 测试先行:写最小测试,确认红验,产出红验记录与测试冻结点,通过 Red-Green Gate。
- 实现与重构:只实现契约内行为,跑到绿验,产出代码变更与绿验结果。
- 证据与交付:执行质量地板检查、fresh-context 契约审查与可选提交,产出交付报告,通过 Verify Gate。
只识别 Markdown checklist 和自然语言任务,不解析任何框架专有计划语法,也不引入新编号体系(契约只用本轮局部 checklist,不生成 DF-XX / AC-XX)。
三硬门控
Gate 1:Contract Gate(唯一默认人工批准点) 进入实现前必须形成可执行验收契约。交互模式下契约以一次 AskUserQuestion 请用户确认(确认 / 修改范围 / 终止);headless 或任务明确时自动通过并在交付报告记录理由。后续仍可临时询问(疑似测试缺陷、范围冲突、危险操作),但禁止逐阶段批准,人工控制集中在契约这一个高杠杆时刻。
Gate 2:Red-Green Gate 行为变更且自动测试可行时,必须先红后绿:新测试先全部失败(且不破坏既有测试基线),实现后全部通过。红验通过即测试冻结,实现阶段不得修改测试文件,完成时以 diff 机械校验,有变更即为 Blocker;疑似测试缺陷时应停止实现并请求确认,不得静默改测试。自动测试不可行时(无测试框架 / 纯配置 / 探索任务)不伪造 TDD,必须在契约 evidence_plan 中声明降级证据(命令 / 截图 / 手动验证)及不可行原因。
Gate 3:Verify Gate(一个门、两个独立 verdict,均必过)
- 3a. Evidence Check(质量地板,不可降):绿验通过且 skipped/todo = 0;测试冻结 diff 校验通过;声称 vs 实际 diff 一致;每个契约行为至少 1 条独立证据;受影响测试后置运行通过。自动测试不可行(已在契约声明降级)时,绿验/冻结/后置测试三项记 N/A,由降级证据与原因替代,其余两项不可豁免。
- 3b. Fresh-Context Contract Review:派一个新上下文子 Agent(Task tool),只校验 diff ↔ Execution Contract ↔ evidence 合规。contract-critical 发现阻断修复后重审。审查即分诊:契约内 critical 发现阻断修复;契约外发现不阻断、不顺手改,列入交付报告 deferred 清单。这是“写码者不自评”的最低保障,不可跳过;完整对抗审查用 --audit。
使用方式
Execution Contract 模板
execution_contract: source: "<plan path | prompt | issue text>" goal: "<一句话目标>" in_scope: ["<本次会做什么>"] out_of_scope: ["<明确不做什么>"] expected_behavior: ["<用户或系统可观察结果>"] evidence_plan: - kind: "test | command | screenshot | manual" command_or_path: "<验证方式;非 test 时附自动测试不可行原因>" risk_flags: ["<public-api | schema | auth | data-loss | ui | low-risk>"] stop_conditions: ["<遇到什么必须暂停确认>"]
模糊任务处理:可推导单一可验证目标时写明“推导契约”继续执行;多个合理方向必须确认;完全无验收标准(如“优化一下”)不进实现,降级为契约澄清;显式 --explore 时允许 spike / 方案 / 可回滚实验,但不得声称“已完成”。
执行模型
默认单 Agent 两 Pass(语义屏障):Test Pass 基于契约写接口骨架 + 测试断言(断言值来自契约 expected_behavior)→ 红验;Impl Pass 只实现契约内行为 → 绿验 → 重构(保持绿)。--strict-tdd 或 risk_flags 含 auth/data-loss/schema/public-api 时,升级为物理双子 Agent(Task tool):Test Agent 不读已有实现,Impl Agent 不读契约推导过程、不可改测试。编码纪律恒定遵循 /code-quality 与 /testing-guide。
批量模式
仅可独立执行、可验收的 checklist 项进入批量,叙事型条目先转任务队列(与用户确认)。逐项执行,每项 fresh context;每项独立走完三硬门控,不做批末统一审查;每项完成后勾选计划文档对应项并原子提交(--no-commit 时仅勾选不提交)。断点恢复无检查点文件、无状态机,每项启动前重读计划文档勾选状态,未勾选即未完成。
Flags
- --strict-tdd:强制物理双子 Agent + 信息屏障(核心逻辑 / 高风险)
- --audit:Verify Gate 后追加完整独立审查(调用 /adversarial-review)
- --no-commit:只改代码 + 输出证据,不提交
- --explore:模糊/调研任务,spike 模式,产出方案或可回滚实验
提交规范
workspace_context.mode 不是 inline 时(代码不在本仓),“一项一 commit”展开为 N+1 仓,协议见 workspace-topology/references/protocol.md。mode 为 linked 时代码根不归本仓所有,各仓各自提交、不 bump 指针。用户要求提交或批量模式逐项提交时:原子提交,一项一 commit,遵循 /commit-convention;文件移动/删除遵循 /git-safety(git mv/rm);绝不推送远程;Verify Gate 未过不提交。
交付报告
dev-flow 交付报告
任务: <goal> | 来源: <source> | 结果: 完成 / 部分完成 / 阻塞 契约批准: 用户确认 / 自动通过(理由)
证据
| 契约行为 | 证据 | 位置 |
|---|
Verify
- Evidence Check: ✅/❌ | Fresh-Context Review: ✅/❌(轮次 N)
Deferred(契约外发现,未处理)
- <发现 + 位置>
建议沉淀项(可选,仅确有可复用惯例/踩坑时输出)
- <一行;用户可自行 /agent-memory 或忽略>
适用场景
- 计划文档 / 普通 issue / CE·superpowers·BMAD 松散计划驱动的开发
- 非 keel 项目中的功能实现与问题修复
- 需要轻量、通用、独立开发流程的任务
限制与约束
- 三硬门控不可跳过:Contract / Red-Green(测试可行时)/ Verify(两 verdict 均必过)
- Fresh-Context Review 必须是新上下文子 Agent,不得由实现者自评
- 契约外发现不顺手改,进 deferred 清单
- 无自动测试不伪造 TDD,降级证据须声明原因
- 不生成编号体系、不写 traceability、不做文档同步
- 提交前排除构建/缓存生成物(pycache/dist 等)
- 绝不推送远程
生态边界与协作
keel 项目 T-XX 任务执行 / 追溯 / 04-dev-tasks 状态推进 / review-drain 用 /dev-workflow;任务拆分用 superpowers writing-plans 或 /dev-tasks(keel);项目转文档驱动用 /retrofit。superpowers 衔接:writing-plans 产出可直接作输入;executing-plans 可作上层计划执行器,单项开发由本 skill 接管门控。协作 skill:写业务代码用 /code-quality,写测试用 /testing-guide,完整审查用 /adversarial-review(仅 --audit 或用户显式要求),提交用 /commit-convention + /git-safety,UI 任务可选协作 /ui-orchestrator(非硬依赖)。
Language:接受中英文提问,始终用中文回应。