Skip to main content

​
Workflow YAML Spec

Complete reference for every field in a Gump workflow file.

​
Root fields

FieldTypeRequiredDescription
namestringyesWorkflow identifier, used with --workflow
descriptionstringnoHuman-readable description
max_budgetfloatnoMaximum cost in USD for the entire run
inputsobjectnoDeclared inputs for sub-workflow composition
stepslistyesOrdered list of steps

​
Inputs (for sub-workflows)

name: security-check
inputs:
  diff: { required: true }
  agent: { default: "claude-opus" }
steps:
  - name: review
    agent: "{agent}"
    prompt: "Review: {diff}"
FieldTypeDescription
requiredboolMust be provided by the caller via with:
defaultstringUsed if the caller doesn’t provide a value

​
Agent step fields

A step with an agent field.
FieldTypeRequiredDescription
namestringyesUnique identifier within the workflow
agentstringyesAgent to use (e.g., claude-sonnet, qwen, gemini)
promptstring or objectnoPrompt template. String for inline, file: path for external
outputstringnodiff (default), plan, artifact, review
contextlistnoAdditional context: file: "path" or bash: "command"
sessionstringnofresh (default), reuse, reuse-on-retry, reuse: <step>
timeoutstringnoKill after duration (e.g., "5m", "30s")
max_budgetfloatnoCost limit in USD for this step
hitlboolnoPause for human review after execution
guardobjectnoLive breakers during execution
gatelistnoPost-execution checks
on_failureobjectnoRecovery strategy on gate/guard/review failure

​
Gate step fields

A step with gate but no agent, steps, or workflow.
FieldTypeRequiredDescription
namestringyesUnique identifier
gatelistyesChecks to run on the worktree
on_failureobjectnoRecovery strategy

​
Orchestration step fields

A step with child steps.
FieldTypeRequiredDescription
namestringyesUnique identifier
stepslistyesChild steps
foreachstringnoName of a plan step to iterate over
parallelboolnoRun items/steps concurrently
workflowstringnoSub-workflow to call for each item (in foreach)
gatelistnoPost-group check
on_failureobjectnoGroup-level recovery

​
Workflow step fields

A step with workflow but no agent or steps.
FieldTypeRequiredDescription
namestringyesUnique identifier
workflowstringyesWorkflow to call
withobjectnoInputs passed to the sub-workflow

​
Guard fields

guard:
  max_turns: 60
  max_budget: 3.00
  no_write: true
FieldTypeDescription
max_turnsintKill if turns exceed this count
max_budgetfloatKill if step cost exceeds this (USD)
no_writeboolKill if the agent writes files outside .gump/out/
no_write is implicitly true for output: plan, output: artifact, and output: review. Override with guard: { no_write: false }.

​
Gate values

gate: [compile, test, lint, "touched: *_test.*", "coverage: 80", "bash: make smoke"]
ValueDescription
compileRun the compile command (auto-detected or from config)
testRun the test command
lintRun the lint command (skipped if not available)
schemaValidate plan JSON output format
tests_foundVerify the test runner finds tests
"touched: glob"At least one file matching the glob was modified
"untouched: glob"No file matching the glob was modified
"coverage: N"Test coverage meets or exceeds N%
"bash: command"Run a custom shell command. Exit 0 = pass

​
on_failure fields

Simple form: 
on_failure:
  retry: 3
  strategy: [same, "escalate: claude-opus"]
  restart_from: tests
FieldTypeDescription
retryintMaximum additional attempts
strategylistWhat to do on each attempt
restart_fromstringStep to restart from (in the same group)
Strategy values: same, "same: N" (shorthand for N repeats), "escalate: agent-name". Conditional form: 
on_failure:
  gate_fail:
    retry: 3
    strategy: [same, "escalate: claude-opus"]
  guard_fail:
    retry: 1
    strategy: ["escalate: claude-opus"]
  review_fail:
    retry: 2
    strategy: [same]
    restart_from: impl
Each source has its own retry counter. Missing sources fall back to gate_fail. Missing gate_fail = fatal.

​
Detection rules

Gump infers step type from fields present. Invalid combinations:
CombinationResult
agent + stepsError
agent + workflow (without foreach)Error
workflow + steps (without foreach)Error
guard on a non-agent stepError
with without workflowError