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:

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:

Subtraks capability

Gate fields

The gate field takes one of two forms.

Agentic gate (gate: true) — the agent produces an approve or reject verdict. On reject, the agent specifies which earlier stage to route back to. If the Trak is not in auto mode, a human must confirm before routing executes.

gate: true

Automated gate (gate: { command, ... }) — a shell script runs after the agent produces output:

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 trak are reserved.
• integration.on_failure must name an existing stage in the flow.
• 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: produces an implementation plan after clarifying requirements
      - name: planning
        artifact: plan
        description: Clarifies requirements and produces an implementation plan
        prompt: planner.md

      # Breakdown: 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; automated 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 produces an approve/reject verdict
      - name: review
        artifact: verdict
        description: Reviews completed work and produces an approve/reject verdict
        prompt: reviewer.md
        gate: true              # Agentic gate: agent evaluates, human confirms

      # Compound: captures learnings from the completed Trak
      - name: compound
        artifact: learnings
        description: Captures learnings to improve future Traks
        prompt: compound.md

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

  # Subtrak 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
        gate: true

    integration:
      on_failure: work