RFC: Workflow graph syntax compiled to step-runner IR

Primary area

Agent (Python runtime)

Related issue or feature request

• WORKFLOWS.md — linear YAML steps today
• ADR-014
• #457 (fix loops / retry_target on verify steps)
• #230 (event-driven governance — sync checkpoints for plan-before-code)

Summary

When linear YAML steps become limiting, introduce a workflow graph authoring format that compiles to the existing step-runner intermediate representation (ordered steps with explicit jump metadata). The runner execution engine stays unchanged in v1; the compiler is the new component.

Use case and motivation

Current workflows are intentionally linear with one run_agent (WORKFLOWS.md). Fix loops and human gates add control flow via fields on steps, but complex flows (parallel review, plan-revise loops, conditional skip) become awkward as YAML lists.

A graph syntax makes branching, loops, and parallelism visible in review and diffable. Compilation to IR keeps the runtime simple and testable.

Proposal

Authoring

• New workflow file with format TBD instead of steps: in YAML.
• Nodes map to step kinds; edges carry conditions (outcome=succeeded, human choice keys).
• model / stylesheet attributes on graph or nodes compile to per-step overrides.

Compilation

• CDK synth-time and agent loader invoke compiler → normalized steps + control_flow IR validated by existing JSON Schema where possible.
• Golden fixtures in contracts/workflow-graph/ (graph input → expected IR).

Execution (phased)

• v1: Compiler emits linearized steps with jump_to metadata; runner gains minimal jump support.
• v2: Parallel fan-out (explicitly out of scope for #248 / #99 today).

Out of scope

• Visual editor / web UI for graphs
• Meta-agents that generate graphs at runtime
• Replacing YAML for simple workflows — graph is opt-in
• Multi-run_agent without explicit RFC approval

Potential challenges

• Validator parity — Graph cross-field rules must match YAML rules (cedar-parity lesson).
• Resume/checkpoint — Jump targets must serialize in workflow_state.json.
• Authoring burden — learning curve; mitigate with examples in agent/workflows/.

Dependencies and integrations

• agent/src/workflow/compiler/ (new)
• agent/workflows/schema/
• cdk/ synth-time validation
• contracts/workflow-validation/ corpus extension

Alternative solutions

1. YAML-only control flow — retry_target, human gates via #230; sufficient for medium term.
2. Python DSL — More expressive but not reviewable by non-Python authors.
3. Registry-stored graphs — Phase 4 #246; local compiler still needed for dev.

---

Note: Non-triaged RFCs may not get timely review. PRs on non-triaged issues might not be accepted.

Đọc docs/design/WORKFLOWS.md và ADR-014 trước, sau đó kiểm tra các cấu trúc hiện có trong agent/workflows/schema/ và contracts/workflow-validation/. Công việc được đề xuất sẽ thêm agent/src/workflow/compiler/ và các golden fixtures bên dưới contracts/workflow-graph/; được xem là hoàn tất khi định dạng đồ thị và hành vi biên dịch được đặc tả đủ rõ để tạo ra step-runner IR đã được kiểm định, mà không thay đổi execution engine vượt quá phạm vi v1 đã nêu.