creating-workflows

Writing Workflows

Devkit workflows are YAML files in the workflows/ directory. Each workflow defines a sequence of steps executed in order, with optional loops, branches, and parallel groups.

Schema

name: string          # Workflow display name
description: string   # What this workflow does
budget:               # Optional: token budget
  limit: number       # Max tokens (e.g., 300000)
  downgrade: string   # Model to downgrade to when approaching limit
steps:
  - id: string        # Unique step identifier
    model: string     # Model tier: "smart", "general", "fast"
    prompt: string    # Instruction (supports {{variable}} interpolation)
    command: string   # Shell command — runs directly, no LLM (mutually exclusive with prompt)
    parallel: [ids]   # Optional: run these step IDs concurrently
    loop:             # Optional: repeat this step
      max: number     # Maximum iterations
      until: string   # Stop condition (string match in output)
      gate: string    # Shell command run after each iteration — exit 0 keeps, non-zero reverts
    branch:           # Optional: conditional execution
      if: string      # Condition expression
      then: string    # Step id to jump to if true
      else: string    # Step id to jump to if false

Step Fields

• id — Must be unique. Used for branch targets and output references.
• model — Which model tier runs this step. Pick based on task complexity.
• prompt — The instruction. Use {{step-id}} to reference earlier outputs. Use {{input}} for workflow input. Mutually exclusive with command.
• command — Shell command run directly (no LLM). Output is captured and available via {{step-id}}. Costs $0. Mutually exclusive with prompt.
• expect — Only for command steps. Values: success (step fails if exit code is non-zero) or failure (step fails if exit code is 0). Omit for the default behavior where all exit codes are informational. Enables bugfix reproduction gates: repro with expect: failure must fail before fix, verify with expect: success must pass after.
• parallel — Lists step IDs to run concurrently. Results collected before next sequential step.
• loop — Repeats with max iterations. Exits early if output contains until string. Optional gate command enforces quality after each iteration.
• loop.gate — Shell command run after each loop iteration. Exit 0 = keep changes and commit. Non-zero = revert changes via git checkout. 3 consecutive gate failures trigger stuck detection and stop the loop.
• branch — Routes execution conditionally. Both then and else reference step ids.