workflow-runner

name	workflow-runner
description	十步循环轻量编排器，协调 Phase Skills 执行，支持灵活组合。 使用场景："执行 quick-fix 工作流"、"运行 [Phase B, Phase C]"、自定义 Phase 组合
argument-hint	[workflow-name]
disable-model-invocation	true
user-invocable	true
allowed-tools	Task, Read, Write, Glob, Grep

Workflow Runner v2.3 (轻量编排器)

版本: 2.3.0 | 架构: Phase-Based 更新: 2026-05-10 — wait_recoverable 错误类型 + gate_state workflow-state 扩展 (#60 D2) 类型: 编排器 (调用 Phase Skills) 更新: 2026-02-05 - 添加 A.0.5 头脑风暴步骤集成

快速开始

我应该使用这个 Skill 吗？

使用场景:

• 接收 state-scanner 的工作流推荐
• 需要执行多个 Phase 的组合工作流
• 使用预置工作流模板

不使用场景:

• 只需执行单个 Phase → 直接使用对应 Phase Skill
• 需要状态感知和推荐 → 先使用 state-scanner
• 探索性开发 → 逐步手动调用

入口选择

用户任务
    │
    ├─ 需要状态感知/推荐? ──Yes──▶ state-scanner ──▶ workflow-runner
    │
    └─ 已知要执行的工作流? ──Yes──▶ workflow-runner (直接)

---

配置 (config-loader)

执行前读取 .aria/config.json，缺失则使用默认值。参见 config-loader。

字段	默认值	说明
workflow.auto_proceed	false	Phase 间自动推进 (需用户在 config 中显式启用)

---

架构概览

v2.0 vs v1.0

特性	v1.0	v2.0
执行单元	单步骤 (A.1, B.2...)	Phase (A, B, C, D)
跳过逻辑	集中在 workflow-runner	委托给各 Phase Skill
上下文	手动传递	自动传递 context_for_next
组合方式	步骤列表	Phase 组合
复杂度	高 (管理10步)	低 (管理4个Phase)

Phase Skills 架构

workflow-runner (编排器)
     │
     ├──▶ A.0.5 brainstorm (可选) ← 新增
     │         └── problem/requirements/technical 模式
     │
     ├──▶ phase-a-planner (A.1-A.3)
     │         └── spec-drafter (内置 brainstorm), task-planner
     │
     ├──▶ phase-b-developer (B.1-B.3)
     │         └── branch-manager, test-verifier, arch-update
     │
     ├──▶ phase-c-integrator (C.1-C.2)
     │         └── commit-msg-generator, branch-manager
     │
     └──▶ phase-d-closer (D.1-D.2)
               └── progress-updater, openspec:archive

---

预置工作流

工作流	Phases	适用场景
quick-fix	B → C	简单 Bug 修复
feature-dev	A → B → C	功能开发
doc-update	B.3 → C	文档更新
full-cycle	A → B → C → D	完整开发周期
commit-only	C.1	仅提交

详见 WORKFLOWS.md

---

执行流程

输入格式

# 预置工作流
workflow: quick-fix

# 或 Phase 组合
phases: [B, C]

# 或自定义步骤
steps: [B.2, C.1]

# 可选配置
config:
  dry_run: false
  context:
    module: "mobile"
    spec_id: "add-auth-feature"

执行过程

1. 解析工作流:
   - 预置模板 → 转换为 Phase 列表
   - Phase 组合 → 直接使用
   - 步骤列表 → 映射到 Phase

2. 上下文准备:
   - 接收 state-scanner 传递的上下文
   - 或读取当前项目状态

3. A.0.5 头脑风暴检查 (v2.2.0 新增):
   - 检测工作流包含 Phase A
   - 检查 state-scanner 推荐中是否包含 brainstorm 模式
   - 如果推荐 → 在 Phase A 前执行 brainstorm
   - 传递决策记录到 spec-drafter

4. Pre-Hook 检查 (v2.1.0):
      
           
     

  
      
       
    
            
           []

   
       
       

 
    
    

---

上下文传递

自动传递机制

Phase A 输出:
  context_for_next:
    spec_id: "add-auth-feature"
    task_list: [TASK-001, ...]
    assigned_agents: {...}
           │
           ▼
Phase B 接收 + 输出:
  context_for_next:
    branch_name: "feature/add-auth"
    test_results: { passed: true, coverage: 87.5 }
           │
           ▼
Phase C 接收 + 输出:
  context_for_next:
    commit_sha: "abc1234"
    pr_url: "https://..."
           │
           ▼
Phase D 接收:
  # 使用所有上下文完成收尾

上下文合并

context_merge:
  strategy: deep_merge
  priority: later_wins  # 后续 Phase 输出覆盖前面的

---

Workflow State Persistence

工作流执行期间，通过 .aria/workflow-state.json 跟踪状态，支持中断恢复和进度可视化。

Schema 详见 references/workflow-state-schema.md

State Creation

工作流启动时，创建初始状态文件:

1. 确保 .aria/ 目录存在 (mkdir -p .aria)
2. 生成 session_id (格式: sess-YYYYMMDD-XXXXXX，X 为随机十六进制)
3. 写入初始状态:
   • session.workflow_name: 当前工作流名称
   • session.phases: 计划执行的 Phase 列表
   • session.status: "running"
   • git_context.branch, git_context.start_commit: 当前分支和 HEAD SHA
4. 原子写入: 先写到 .aria/workflow-state.json.tmp，再 rename 覆盖正式文件

State Updates

每个 Phase 完成后立即更新:

• execution.current_phase / current_step: 推进到下一 Phase
• execution.phase_results.<phase>: 记录该 Phase 输出 (status, context_for_next)
• session.last_active_at: 更新为当前时间戳
• integrity.state_hash: 重新计算 (SHA-256 of content without integrity block)

Gate State

通过质量门时记录:

• Gate 1 (Spec 审批): 设置 gates.gate1_spec_approved: true
• Gate 2 (合并主干): 设置 gates.gate2_merge_main: true

Gate 强制执行逻辑、手动/自动模式切换、失败恢复详见 references/gate-enforcement.md

Pre-Action Gate State (v2.3.0+)

新增于 v2.3.0 — 支持 wait_recoverable 错误类型 (#60 phase-c-integrator C.2.4 pre-merge gate)。

gate_state 顶级 block 跟踪当前活跃的 pre-action gate (currently only pre_merge,但 schema 通用化为未来 pre_release / pre_deploy 预留扩展):

{
  "gate_state": {
    "name": "pre_merge",
    "status": "waiting | green | fail",
    "started_at": "ISO 8601",
    "retry_count": 0,
    "next_check_at": "ISO 8601",
    "in_flight_runs": [
      {"run_id": 3161, "branch": "main", "started_at": "ISO 8601", "elapsed_seconds": 459}
    ],
    "primitive_used": "aether-ci-cli",
    "raw_message": "",
    "no_run_observations": 0
  

no_run_observations (v1.66.5+ #152): 本 episode 连续带 gate_error.kind == "no-run-for-branch" 的观测次数,含初次;某轮非该 kind → 归零。

完整 schema 见 references/workflow-state-schema.md §1.1.gate_state。Schema migration format_version 1.0 → 1.1 见 §8.3 默认 gate_state: null。

Defensive access: 所有读 gate_state 的代码必须用 state.get("gate_state") or {} 而非 state["gate_state"],防 v1.0 state 文件 KeyError。

State Cleanup

工作流结束时的清理策略:

场景	动作
正常完成	删除 .aria/workflow-state.json
用户放弃	删除 .aria/workflow-state.json
执行失败	保留文件，设置 session.status: "failed" (供恢复使用)

---

错误处理

Phase 级别

on_phase_error:
  action: stop          # stop | continue | rollback
  report: true
  suggestion: "查看 Phase X 错误详情"

可恢复策略

recovery:
  Phase_B_failed:
    - 保留已创建的分支
    - 报告测试失败详情
    - 建议: "修复测试后从 Phase B 重新开始"

  Phase_C_failed:
    - 回滚 git commit (如果已执行)
    - 建议: "检查提交消息或 hook 错误"

wait_recoverable 错误类型 (v2.3.0+)

新增于 v2.3.0 — 修复 Forgejo Issue #60 phase-c-integrator C.2.4 pre-merge gate。 "等待外部 CI 完成" 是协作正常态,不应当作 fatal error 处理。

触发场景:

• phase-c-integrator C.2.4 返回 verdict=wait (main 分支有 in-flight CI 或 PR CI pending)
• phase-c-integrator C.2.4 pr_ci_status="not_found" (远端零 run,产 gate_error.kind="no-run-for-branch") → 同样归为 verdict=wait (v1.66.5+ #152)
• 未来扩展: 任何 pre-action gate 返回 wait 状态 (eg pre_release / pre_deploy)

配置:

on_phase_error:
  wait_recoverable:
    triggered_by:
      - source: "phase-c-integrator"
        sub_step: "C.2.4"
        verdict: "wait"
    behavior:
      - log: "main 分支有 in-flight CI,等待 X 完成"  # gate_error.kind=no-run-for-branch 态改用 gate_error.message (v1.66.5+ #152)
      - persist: workflow-state.json 写 gate_state block
      - sleep: wait_check_intervals[retry_count] (默认指数退避)
      - re-invoke: phase-c-integrator C.2.4 重新检查

Exit conditions (优先级 first-match-wins, R2 patch CR-4;v1.66.5+ #152 扩为五条,新增 2.5):

1. user Ctrl-C → 转 manual mode (workflow-state 标 session.status: suspended,允许 resume) [最高]
2. retry_count > max OR elapsed > wait_timeout_seconds → user prompt (continue / abort);continue ⇒ CLI reset --retry-count --observations (两者归零,且 reset --retry-count 同时置 started_at=now — exit 2 实际只由 elapsed 触发,不重置 started_at 则 continue 后每 30s 再弹) 2.5 (v1.66.5+ #152 新增) out.gate_error.kind == "no-run-for-branch" AND record.should_prompt → no-run prompt(定义见 phase-c-integrator SKILL.md §C.2.4 步骤 6 处方段,本文只引用不复制;措辞要点: 🔴 C.2.4: <gate_error.message 原文>。已连续 <record.no_run_observations> 次观测到零 run (~<record.elapsed_seconds>s)。 处方择一由用户执行 — (a) dispatch 命令行已由 gate 渲染进 message,AI 只填 <owner>/<repo>,message 无此行则 (a) 不出现 / (b) 推一个碰 CI 触发路径的实质 commit (若 workflow 有 branches 过滤且不含本分支则无效) / (c) continue / abort);continue ⇒ CLI reset --observations 回 loop (retry_count/started_at 继续累计,exit 2 上界不变);abort ⇒ verdict=fail 语义(session failed,保留 gate_state 给 audit trail)
3. verdict=fail → 转为 stop (fatal) [不变]
4. verdict=green → 继续 merge (正常路径) [最低,不变]

时间轴: 默认阈值 3 + intervals [30,60,120,…] ⇒ 首次 gate 后 ~90s 交人 (非等满 1800s);continue 后第二次 prompt ≈810s。

实施步骤:

当 phase-c-integrator C.2.4 返回 verdict=wait:
  1. 读 .aria/config.json 加载 phase_c_integrator.pre_merge_gate.* 配置
  2. 首个 wait verdict → 创建 gate_state 也经 CLI record (同 3c' 全旗标; is_first ⇒ retry_count=0, obs=1 若带 kind)  # 非 AI 手写 JSON
     所有 CLI 调用显式传 --state-file <主仓根绝对路径>/.aria/workflow-state.json (helper 默认相对 cwd, 子模块 cwd 下会静默另起 state + 分区)
  3. 进入 polling loop:
     a. 计算本轮 sleep 时长: wait_check_intervals[min(retry_count, len-1)]
     b. polling sleep chunk 模式 (CR-5): sleep 拆分 5s 块
        - 每块结束 check `.aria/.workflow-interrupt` flag file
        - flag 存在 → 立即 break,转 suspended
     c. sleep 结束 → 重调 phase-c-integrator C.2.4 gate → 得 out
     c'. record = python3 "${CLAUDE_PLUGIN_ROOT:-aria}/skills/workflow-runner/scripts/gate_state_helper.py" record --state-file <主仓 .aria/workflow-state.json 绝对路径> --name pre_merge --verdict out.verdict --intervals <json(cfg.wait_check_intervals)> --in-flight-runs <json(out.in_flight_runs)> --raw-message <out.raw_message> --source production [--gate-error-kind out.gate_error.kind --threshold out.gate_error.prompt_after_observations]
        # 两旗标仅 out.gate_error.kind == "no-run-for-branch" 时传 (fail 类 kind 无 threshold 键); in_flight_runs / raw_message 必须透传; 先自增, 后求值
     d. 按 exit conditions 处理 (输入 = out + record); CLI 退出码 2 → surface 错误 → 直接 abort (终止分支; 不再调 reset — reset 同样会退 2), 禁止回退手写 JSON
  4. 退出 polling 后:
     - verdict=green → 调 branch-manager merge,清理 gate_state
     - verdict=fail → workflow-state.session.status=failed,保留 gate_state 给 audit trail
     - timeout → user prompt;continue → reset retry_count + 继续;abort → stop
     - Ctrl-C → workflow-state.session.status=suspended,保留 gate_state 给 resume

Ctrl-C 检测机制 (v2.3.0+)

CR-5 R2 patch — workflow-runner 现无 signal handler 设计,采用 polling sleep chunk 模式

Flag-file lifecycle (R2-CR-B inline patch):

• 创建: workflow-runner 顶层 SIGINT handler 收到中断时 atomic write .aria/.workflow-interrupt (open-O_CREAT-O_EXCL + tmp+rename)
• 检查: polling sleep chunk 每块结束后 os.path.exists(.aria/.workflow-interrupt)
• 清理时机 (3 处):
  • workflow-runner 启动入口 (resume 或 fresh): 无条件清理 stale flag
  • 进入 manual mode / suspended 状态后: 保留 flag (待 user explicit clear / resume)
  • user resume workflow 时: 清理 flag (resume 是新意图,不继承 prior interrupt)
• Ownership: flag 文件只属当前 workflow-runner pid;多 workflow-runner 并发不允许 (沿用现有 workflow-state lock 约定)

Chunk 大小 trade-off: phase_c_integrator.pre_merge_gate.poll_chunk_seconds 默认 5s;过小耗 CPU,过大 Ctrl-C 响应慢。

Resume 语义 (v2.3.0+)

CR-6 + BA-5 R2 patch — workflow 中断后 resume 时正确处理 gate_state

workflow-state.json 含 gate_state.status == waiting AND phase_results.C.2.action.pr_number != null (PR 已创建) 时:

1. resume 入口先清理 stale flag: rm -f .aria/.workflow-interrupt (R2-CR-B,resume 是新意图)
2. 判定 next_check_at 是否过期 (R2 inline patch QA-12 — clock 源):
   • next_check_at 持久化为 ISO 8601 wall clock (跨进程可读)
   • elapsed 用 time.monotonic() 防 DST/系统时钟漂移
   • 已过期 (now >= next_check_at) → 立即重新调 C.2.4 gate
   • 未过期 → 等待至 next_check_at 后再调
3. gate verdict 处理:
   • green → 跳过 C.2 push/create-PR (已完成,PR_NUMBER 已持久化),直接调 branch-manager merge call (idempotent — 若 PR 已 merged 则 branch-manager 报告 success 不重复操作)
   • wait → 增量更新 gate_state.retry_count + next_check_at(若 gate_error.kind=no-run-for-branch 则同步累计 no_run_observations),继续 polling
   • fail → workflow report 含 PR_NUMBER + 失败 verdict,转 stop
4. 不重跑 Phase C 整段,只 re-run gate + merge call (避免重复推送 / 重复创建 PR)

---

输出格式

执行报告示例:

╔══════════════════════════════════════════════════════════════╗
║              WORKFLOW EXECUTION REPORT                        ║
╚══════════════════════════════════════════════════════════════╝

Workflow: feature-dev
Duration: 2m 15s
Status: SUCCESS

───────────────────────────────────────────────────────────────
PHASE RESULTS:

  Phase A (规划) - 45s
     spec_id: add-auth-feature
     tasks: 5

  Phase B (开发) - 60s
     branch: feature/add-auth
     tests: 15/15 passed (87.5% coverage)

  Phase C (集成) - 30s
     commit: abc1234
     pr: #123
───────────────────────────────────────────────────────────────

完整输出格式（含执行计划、使用示例等）详见 references/output-formats.md

---

TDD 双保险 Pre-Hook (v2.1.0)

Phase B 执行时应用 TDD pre-hook 策略，在工作流级别自动启用 TDD 双保险机制：

• 方案 A: phase-b-developer 传递 TDD 配置给 Fresh Subagent
• 方案 B: workflow-runner 通过 Pre-Hook 启用主会话 TDD Hook

详见 references/tdd-pre-hook.md

---

与 state-scanner 的协作

推荐流程

state-scanner
    │
    │ 收集状态 + 分析 + 推荐
    │
    ▼
recommendation:
  workflow: quick-fix
  context:
    phase_cycle: "Phase4-Cycle9"
    module: "mobile"
    changed_files: [...]
    │
    │ 用户确认
    │
    ▼
workflow-runner
    │
    │ 执行工作流
    │
    ▼
result

上下文继承

# state-scanner 传递
context:
  phase_cycle: "Phase4-Cycle9"
  module: "mobile"
  changed_files: [...]

# workflow-runner 使用
→ 传递给 Phase A/B/C/D
→ 用于生成提交消息
→ 更新 UPM 进度

---

相关文档

• WORKFLOWS.md - 工作流详细定义
• MIGRATION.md - v1.0 → v2.0 迁移指南
• references/tdd-pre-hook.md - TDD 双保险详细策略
• references/output-formats.md - 完整输出格式定义
• references/workflow-state-schema.md - 工作流状态 Schema
• references/auto-proceed.md - Auto-Proceed 模式规范
• references/gate-enforcement.md - Gate 强制执行、手动回退、失败恢复
• brainstorm - 头脑风暴引擎 (新增 A.0.5)
• state-scanner - 状态感知与推荐
• phase-a-planner - Phase A
• phase-b-developer - Phase B
• phase-c-integrator - Phase C
• phase-d-closer - Phase D
• tdd-enforcer - TDD 强制执行

---

最后更新: 2026-03-16 Skill版本: 2.3.0