Skip to main content

​
Anatomy of a Workflow

A workflow is a YAML file with a name and a list of steps. Here’s a minimal example: 
name: simple
description: Single agent, one step
max_budget: 3.00

steps:
  - name: implement
    agent: claude-sonnet
    output: diff
    prompt: "{spec}"
    gate: [compile]

​
Root fields

Every workflow has these top-level fields:
  • name — identifier, used with --workflow.
  • description — human-readable description.
  • max_budget — maximum cost in dollars for the entire run. If the run exceeds this, Gump stops.
  • steps — ordered list of steps to execute.

​
Steps are sequential

Steps execute in order, top to bottom. Each step can read the outputs of previous steps via the state bag. A step doesn’t start until the previous one has completed and passed its gate.

​
Where workflows live

Gump looks for workflows in three places, in order:
  1. Project — .gump/workflows/my-workflow.yaml
  2. User — ~/.gump/workflows/my-workflow.yaml
  3. Built-in — shipped with Gump
The first match wins. A project workflow with the same name as a built-in overrides it.

​
A real workflow

Here’s what a typical workflow looks like with decomposition, retries, and a quality gate: 
name: my-workflow
description: Decompose, implement, verify
max_budget: 8.00

steps:
  - name: decompose
    agent: claude-opus
    output: plan
    prompt: |
      Decompose {spec} into independent items.
      Each item must be implementable and testable in isolation.
    gate: [schema]

  - name: build
    foreach: decompose
    steps:
      - name: impl
        agent: claude-sonnet
        output: diff
        prompt: |
          Implement: {item.description}
          Files: {item.files}
        gate: [compile, test]
        on_failure:
          retry: 3
          strategy: [same, "escalate: claude-opus"]

  - name: quality
    gate: [compile, lint, test]
The following pages explain each building block in detail — steps, output modes, gates, guards, prompts, and the state bag.