Skip to main content

Reference

workflow.yaml Reference

The canonical schema for workflow configuration. All examples in the documentation follow this structure.

Full schema

# workflow.yaml -- canonical schema

# Phase definitions
phases:
  plan:
    template: prompts/plan.md
    tools: [read, search]
  build:
    template: prompts/build.md
    tools: [read, search, execute, write]
  test:
    template: prompts/test.md
    tools: [read, search, execute, write]
  review:
    template: prompts/review.md
    tools: [read, search]
  document:
    template: prompts/document.md
    tools: [read, search, write]
  deploy:
    template: prompts/deploy.md
    tools: [read, search, execute]
  monitor:
    template: prompts/monitor.md
    tools: [read, search, execute]

# Quality gates
gates:
  test:
    all_pass: true
    coverage_min: 80          # 0-100, percentage
    new_code_covered: true
  review:
    max_blockers: 0
    max_critical: 2
    tech_debt_logged: true

# Self-healing loops
loops:
  test_retry:
    max: 3                    # 1-10
    trigger: test_failure
    on_exhaust: escalate
    cost_ceiling: 5.00        # USD, optional
  review_patch:
    max: 3
    trigger: blocker
    ignore: [tech_debt, skippable]
    on_exhaust: escalate
    cost_ceiling: 5.00
  full_rebuild:
    max: 1
    trigger: architectural_issue
    on_exhaust: escalate

# Escalation
escalation:
  target: human
  notify: [slack, email]      # optional
  include: [plan, build_report, test_results, review_issues]

# Autonomy level
autonomy: assisted            # assisted | supervised | autonomous | ase
checkpoints:                  # only for supervised
  after_plan: { require: human_approval, timeout: 24h }
  after_test: { require: human_approval, timeout: 24h }
  after_review: { require: human_approval, timeout: 24h }

# Auto-merge (L4 only)
auto_merge:
  enabled: false
  delay: 5m

# Monitoring
monitor:
  anomaly_detection: false
  rollback_on: []             # e.g., [error_rate_spike, latency_increase]
  auto_create_issue: false

# Issue-type routing (optional)
routing:
  feature:
    phases: [plan, build, test, review, document, deploy, monitor]
  bug:
    phases: [plan, build, test, review, document, deploy]
  patch:
    phases: [build, test, deploy]
  hotfix:
    phases: [build, test, deploy]
    loops: { test_retry: { max: 1 } }

# Team overrides (optional, enterprise)
teams:
  frontend:
    override_dir: teams/frontend
    merge_strategy: { prompts: replace, gates: additive }

Key names

Concept Canonical Key NOT This
Test retry limit loops.test_retry.max feedback_loops.test_retry.max_attempts, loops.test.max_retries
Review patch limit loops.review_patch.max review_patch.max_attempts
Coverage threshold gates.test.coverage_min test.coverage_threshold, criteria.min_coverage
Max blockers gates.review.max_blockers criteria.max_blocker_count
Max critical issues gates.review.max_critical criteria.max_critical_count
Escalation target escalation.target escalation.notify (notify is for channels)
Autonomy level autonomy autonomy_level
Loop trigger loops.<name>.trigger trigger_on
Loop exhaustion loops.<name>.on_exhaust on_fail, on_exhaust at gate level

Minimal example

The smallest valid workflow.yaml (3 phases, 1 gate, 1 loop):

phases:
  plan:
    template: prompts/plan.md
    tools: [read, search]
  build:
    template: prompts/build.md
    tools: [read, search, execute, write]
    gates:
      all_pass: true
  review:
    template: prompts/review.md
    tools: [read, search]
    gates:
      max_blockers: 0

loops:
  test_retry: { max: 3 }
  review_patch: { max: 3 }

escalation:
  target: human
  include: [plan, build_report, test_results, review_issues]
Glossary Prerequisites