Every stage in a Trak’s pipeline — what agent runs, what gates check the output, what capabilities it has, and what happens on failure — is configured in .orkestra/workflow.yaml.

File structure

A workflow.yaml file contains one or more named flows. A Trak is assigned to a flow at creation time and runs the flow’s stages in order.

version: 2

flows:
  default:
    stages:
      - name: work
        artifact: summary
        prompt: worker.md
    integration:
      on_failure: work

Root fields

Flow fields

Each entry under flows is a named flow:

Integration fields

Stage fields

Each item in stages configures one stage in the flow:

name and artifact must be unique within a flow. The names activity_log and task are reserved and cannot be used as artifact values.

Model values

The model field selects both the AI provider and the model. The provider is inferred from the model name.

Capabilities

The capabilities object extends what a stage can do:

subtasks and approval cannot coexist on the same stage. ask_questions and approval can coexist. ask_questions and subtasks can coexist.

Subtasks capability

Approval capability

Gate fields

See Gates for gate behavior and environment variables.

Tool restrictions

Each item in disallowed_tools restricts the agent from using a specific tool:

Available tool patterns include: Bash, Bash(<pattern>), Edit, Write, Read, Glob, Grep. Any Claude Code tool name is a valid pattern.

Validation

Orkestra validates workflow.yaml at startup and reports errors immediately:

• Stage name must be unique within a flow.
• Stage artifact must be unique within a flow. activity_log and task are reserved.
• integration.on_failure must name an existing stage in the flow.
• approval.rejection_stage must name an existing stage in the flow (if specified).
• subtasks.completion_stage must name an existing stage in the parent flow (if specified).
• subtasks.flow must name an existing flow (if specified).
• gate.timeout_seconds must be greater than 0.
• disallowed_tools[].pattern cannot be empty.

Full example

The default workflow.yaml created by Orkestra on first run:

version: 2

flows:
  # Default pipeline — used for most Traks
  default:
    stages:
      # Planning: agent asks questions, then produces a plan
      - name: planning
        artifact: plan
        description: Clarifies requirements and produces an implementation plan
        prompt: planner.md
        capabilities:
          ask_questions: true   # Agent can ask clarifying questions before outputting

      # Breakdown: agent researches the codebase and proposes Subtraks
      - name: breakdown
        artifact: breakdown
        description: Breaks the plan into parallel implementation Subtraks
        prompt: breakdown.md
        capabilities:
          subtasks:
            flow: subtask       # Subtraks use the subtask flow below

      # Work: agent implements the changes; gate verifies quality
      - name: work
        artifact: summary
        description: Implements code changes and produces a summary
        prompt: worker.md
        gate:
          command: "$ORKESTRA_PROJECT_ROOT/.orkestra/scripts/checks.sh"
          timeout_seconds: 600  # 10 minutes; adjust for your project's test suite

      # Review: agentic gate — agent approves or rejects the work
      - name: review
        artifact: verdict
        description: Reviews completed work and produces an approve/reject verdict
        prompt: reviewer.md
        capabilities:
          approval:
            rejection_stage: work  # On reject, route back to the work stage

      # Compound: captures learnings; automated — no human review step
      - name: compound
        artifact: learnings
        description: Captures learnings to improve future Traks
        prompt: compound.md
        is_automated: true

    integration:
      on_failure: work  # If merge fails, route back to the work stage

  # Subtask pipeline — simpler flow for child Traks
  subtask:
    stages:
      - name: work
        artifact: summary
        prompt: worker.md
        gate:
          command: "$ORKESTRA_PROJECT_ROOT/.orkestra/scripts/checks.sh"
          timeout_seconds: 600

      - name: review
        artifact: verdict
        prompt: reviewer.md
        capabilities:
          approval:
            rejection_stage: work

    integration:
      on_failure: work