工作流编排 · Contract-Driven Orchestrator

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

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

5 分钟快速上手 GitHub →

四阶段模型

编排器在任何子 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

TDD 红绿循环 + 子代理隔离开发，自动创建 PR。

入口：Gate 2→3 通过（user_approved = true） 退出：phase 3 状态置为 complete 流转：Gate 3→4 通过后自动进入阶段 4
  1. 工作区：记录 base_branch，worktree 固定在 .claude/worktree/<branch-name>，分支名 feat/<issue-number>-<short-description>
  2. 执行引擎：按技能来源 + 执行模式运行 SDD / executing-plans / /implement，全程 TDD RED → GREEN → REFACTOR
  3. 创建 PR：gf-pr-create，PR 正文必须包含 Closes #<issue-number> → pr_url
  4. 测试：make test / cargo test → tests_passed
  5. 更新契约：写入 branch / base_branch / worktree_path / pr_url / tests_passed
证据字段 branchbase_branchworktree_pathpr_urltests_passed

Gate 3→4 无任何模式豁免：pr_url 非空且 tests_passed 为 true 才能进入交付检查。

04

交付检查 Delivery

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

入口：Gate 3→4 通过 退出：phase 4 状态置为 complete 终态：归档契约，工作流结束
  1. 流水线分析：gf-pipeline-analyzer 生成分析报告（所有模式）→ pipeline_ok
  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 在所有模式下均为必做；按模式裁剪其中的检查步骤。

三种工作流模式

启动时自动检测模式，也可用 --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
后台代理执行 ✅ 可用 ❌（/implement 为 user-invoked）

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

三种执行模式

Gate 2→3 审批通过后进入 GO 闸门，编排器要求选择执行模式。同会话执行已移出默认菜单： 批准计划 ≠ 授权数小时无人值守的子代理扇出。

① 后台代理 默认 · superpowers only

以 isolation: worktree + run_in_background 派发独立子代理。交接物 = 契约路径 + 计划文档 + 引擎指令；执行者把证据写回契约，完成时任务通知回到原窗口。

仅 superpowers 来源可用（/implement 是用户触发，后台无法调用）

② 手动新窗口 两种来源均可用

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

superpowers 与 mattpocock 均可用

③ 同会话执行 仅显式要求

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

仅在用户显式请求时启用

质量补偿：executing-plans（轻量路径）缺少逐任务审查，由门禁补偿——PR 前 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（计划审批 + 执行模式选择），其余转换全部自动推进。

契约结构

契约文件遵循 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 + tests_passed 无豁免

跨会话恢复

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

快速开始

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

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

相关内容