工作流编排 · Contract-Driven Orchestrator

gf-workflow — 四阶段 AI 编程工程工作流编排

gf-workflow 是一个契约驱动的四阶段闸门编排器: 需求澄清 → 计划制定 → 执行 → 交付检查。 每个阶段之间由 JSON 契约与质量门禁把关;状态可跨会话、跨代理恢复,闸门从不被跳过。

四阶段模型

编排器在任何子 skill 之前先建立契约,然后驱动四个阶段依次执行。每个阶段完成即更新契约, 再校验门禁条件后进入下一阶段。

01

需求澄清 Clarification

契约先行,先搞清楚要做什么。

入口:契约必须已存在 退出:phase 1 状态置为 complete 流转:Gate 1→2 通过后自动进入阶段 2
  1. Bootstrap:创建契约 .cache/workflows/active/<workflow_id>.json,写入 mode / title / current_phase
  2. 读取 open issues:gf issue list --state open,并读取评论 gf issue comments <number> 补充上下文
  3. 澄清 skill:按技能来源调用 brainstorming / grilling / inline 自访谈,产出设计文档 → design_doc_path
  4. issue-create(必做):gf-issue-create 创建或复用 Issue,正文引用设计文档 → issue_url
  5. issue-review(必做):gf-issue-review 审查 Issue 质量并添加审查评论 → comment_id
  6. 更新契约:写入证据字段,标记 Phase 1 complete
证据字段 issue_urlcomment_iddesign_doc_path

fast 模式豁免 comment_id 与 design_doc_path;issue-create 在两种技能来源下均为必做。

02

计划制定 Planning

产出完整实施计划,质量门禁层层把关。

入口:Gate 1→2 通过 退出:phase 2 状态置为 complete 暂停:Gate 2→3(唯一人工审批闸门)
  1. 计划 skill:按技能来源调用 writing-plans / /to-tickets,产出计划文档 → spec_path
  2. quality 门禁:gf-quality 运行 build / test / coverage / fmt / static / pre-commit 全部检查
  3. 更新契约:写入 spec_path,user_approved: false
  4. 人工审批(暂停):approved → 进入执行模式选择;changes → 修改计划;rejected → 终止
证据字段 spec_pathuser_approvedticket_refs(mattpocock)

任一质量检查失败都会阻塞闸门,全部通过才允许继续。

03

执行 Execution

worktree 隔离开发,完成验证后选择本地合并或创建 PR。

入口:Gate 2→3 通过(user_approved = true) 退出:phase 3 状态置为 complete 流转:Gate 3→4 通过后自动进入阶段 4
  1. 工作区:先分类未提交内容并记录 base_branch,worktree 固定在 .worktree/<branch-name>,分支名 feat/<issue-number>-<short-description>
  2. 执行引擎:按技能来源 + 执行模式运行 SDD / executing-plans / /implement,全程 TDD RED → GREEN → REFACTOR
  3. 风险检查:按改动面触发 gf-security-check / gf-regression,失败会阻断交付
  4. 交付选择:本地合并写入 merge_commit;推送并创建 PR 则写入 pr_url,PR 正文必须包含 Closes #<issue-number>
  5. 测试:make test / cargo test → tests_passed
  6. 更新契约:写入工作区、风险检查、交付方式与测试证据
证据字段 branchworktree_pathdelivery_modepr_url / merge_committests_passed

Gate 3→4 无模式豁免:交付证据与 delivery_mode 对应、tests_passed 为 true,且安全/回归检查不能处于 failed。

04

交付检查 Delivery

流水线分析、Issue 分流、代码审查与 dogfooding。

入口:Gate 3→4 通过 退出:phase 4 状态置为 complete 终态:归档契约,工作流结束
  1. 流水线分析:进入阶段时询问是否运行,默认运行 gf-pipeline-analyzer;跳过该项不等于跳过 Phase 4
  2. Issue 分流:gf-issue-triage 产出分流报告(full 模式)
  3. 代码审查:gf-review 生成审查报告(full + standard)→ review_report_path
  4. Dogfooding:dogfooding 清单检查(full 模式)→ dogfooding_passed
  5. Branch Finish:检测 PR 合并状态,用户确认后清理分支与 worktree
  6. 归档契约:移动到 .cache/workflows/archive/YYYY-MM/
证据字段 pipeline_okreview_report_pathdogfooding_passedbranch_cleaned

阶段 4 在所有模式下均为必做;流水线分析可由用户跳过,其余检查按模式裁剪,Branch Finish 始终执行。

三种工作流模式

启动时自动检测模式,也可用 --mode <mode> 手动覆盖。优先级:显式覆盖 > Issue 标签 > Issue 标题前缀(conventional commits)> 默认 standard。

维度full(完整)standard(标准)fast(快速)
适用场景 feat / 大型重构 / 破坏性变更 fix / 小型重构 / 单文件模块 typo / docs / hotfix / chore
阶段 1 需求澄清 brainstorming + issue-create + issue-review brainstorming + issue-create + issue-review issue-create 必做,brainstorming 可选
阶段 2 计划制定 writing-plans + quality 门禁 writing-plans + quality 门禁 可跳过
阶段 3 执行 subagent-driven-development(TDD + 代码审查) subagent-driven-development(TDD + 代码审查) 必做(TDD + 审查不可跳过)
阶段 4 交付检查 可选 pipeline + triage + review + dogfooding 可选 pipeline + review 可选 pipeline + branch-finish
自动检测流程:
检测到 `feat:` 前缀 → 建议 full 模式
自动检测结果:full
是否确认?[Y/n/override]

技能来源:superpowers / mattpocock

gf-workflow 运行在一个外部技能来源之上:superpowers 或 mattpocock/skills。启动时检测 会话内可用 skills;两源同时在时询问用户,两源皆无时询问继续 inline 或中止。 Skill 名称通过 references.md 中的映射表解析(单一维护点)。

能力superpowersmattpocock/skills
澄清 Clarification brainstorming(模型调用) grilling(模型调用)
规格 Spec 合并进设计文档 /to-spec(本地文件,用户触发)
计划 Planning writing-plans(模型调用) /to-tickets(用户触发)
执行引擎 Execution subagent-driven-development / executing-plans /implement(按 ticket,内部 /tdd 强制)
Issue 创建 gf-issue-create gf-issue-create(权威统一)
Issue 审查 gf-issue-review gf-issue-review
质量门禁 gf-quality gf-quality
交付审查 gf-review gf-review

mattpocock 路径中 /to-spec、/to-tickets、/implement 均为 disable-model-invocation——编排器必须暂停并等待用户手动执行。

两种执行模式

Gate 2→3 审批通过后进入 GO 闸门。默认在手动新窗口继续;只有用户显式要求时,才在同会话执行。 已移除的后台代理模式不再出现在菜单中。

① 手动新窗口 默认 · 两种来源均可用

打印开启指引:worktree 路径(或创建命令)+ 契约恢复命令(gf workflow status &lt;id&gt; 与计划文档路径)。新窗口自行创建分支/worktree 并运行执行引擎;用户回报后编排器校验证据。

superpowers 与 mattpocock 均可用

② 同会话执行 仅显式要求

编排器在当前会话创建 worktree 并内联驱动执行引擎。SDD 一旦启动会接管对话,因此同会话执行只在用户明确要求时启用。

仅在用户显式请求时启用

质量补偿:executing-plans(轻量路径)缺少逐任务审查,由门禁补偿:交付前 make test + 阶段 4 的 gf-review;SDD 自带内置逐任务审查。

契约机制

契约是工作流的单一事实来源。核心规则:任何子 skill 执行之前,契约必须已存在; 没有契约就没有子 skill。状态保存在 JSON 中,闸门从不跳过。

gf workflow — contract
❯ gf workflow create --title "feat: 双技能来源" --mode full
✔ Workflow 已创建: wf-2026-08-09-001
合同: .cache/workflows/active/wf-2026-08-09-001.json
❯ gf workflow status wf-2026-08-09-001
current_phase: 1 · mode: full · skill_source: superpowers
需求澄清 → 计划制定 → 执行 → 交付检查
❯
.cache/workflows/
├── active/ AI
│ ├── wf-2026-08-09-001.json
│ └── wf-2026-08-08-002.json
└── archive/
└── 2026-08/
└── wf-2026-08-07-001.json

状态机

[Start] → Bootstrap → Phase 1 → [Gate 1→2] AUTO → Phase 2
         → [Gate 2→3] PAUSE → Phase 3 → [Gate 3→4] AUTO → Phase 4 → [Archive] → [Complete]

Gate 2→3 是唯一的阶段间强制暂停点。执行中的脏工作区、安全检查选择、交付方式与 Branch Finish 仍可能按场景请求确认。

契约结构

契约文件遵循 contract.schema.json(v1.1), 顶层字段:version、 workflow_id(wf-YYYY-MM-DD-NNN,由 CLI 原子分配)、 title、 mode、 skill_source、 current_phase 与四个 phases。每个阶段记录 name / status / started_at / completed_at / executor / evidence。

闸门证据

进入阶段必填证据fast 模式豁免
2 · 计划制定 issue_url + comment_id + design_doc_path comment_id 可选
3 · 执行 spec_path + user_approved 可跳过(计划可跳过)
4 · 交付检查 pr_url 或 merge_commit + tests_passed + 风险检查状态 无豁免

跨会话恢复

工作流可随时被打断。新会话读取 .cache/workflows/active/ 下状态不为 complete 的契约,按 current_phase 加载上下文并继续,无需从头开始。契约是代理无关的—— 任何 Agent 都能从 current_phase + evidence 恢复。

快速开始

  1. 安装 gf:
    ❯cargo install gitflow-cli
  2. 安装 skills:
    ❯gf skills install
  3. 触发工作流:在项目根目录对 Claude Code 输入 /gf-workflow
  4. 确认模式与来源:确认自动检测出的 full / standard / fast 模式与技能来源
  5. 跟随编排器:走完需求澄清 → 计划制定 → 执行 → 交付检查,Gate 2→3 等待人工审批

所有状态自动写入契约,可随时中断、跨会话恢复。

相关内容