> ## Documentation Index
> Fetch the complete documentation index at: https://gump.build/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow YAML Spec

> Complete reference for every field in a Gump workflow file.

# Workflow YAML Spec

Complete reference for every field in a Gump workflow file.

## Root fields

| Field         | Type   | Required | Description                                 |
| ------------- | ------ | -------- | ------------------------------------------- |
| `name`        | string | yes      | Workflow identifier                         |
| `max_budget`  | float  | no       | Maximum cost in USD for the entire run      |
| `max_timeout` | string | no       | Maximum wall-clock duration (e.g., `"30m"`) |
| `max_tokens`  | int    | no       | Maximum tokens consumed for the entire run  |
| `steps`       | list   | yes      | Ordered list of steps                       |

`description` and `inputs` from v0.0.3 have been removed. Inputs are deduced automatically.

## Step fields

### GET phase

| Field      | Type          | Description                                      | Default                    |
| ---------- | ------------- | ------------------------------------------------ | -------------------------- |
| `prompt`   | string        | Instructions for the agent (inline or file path) | Required if agent declared |
| `context`  | list          | Files and commands injected into context         | `[]`                       |
| `worktree` | string        | `read-write`, `read-only`, `none`                | Derived from type          |
| `session`  | string/object | `new` or `from: <step_name>`                     | `new`                      |

### RUN phase

| Field   | Type   | Description                                    | Default  |
| ------- | ------ | ---------------------------------------------- | -------- |
| `agent` | string | Agent to use, or `pass` to skip RUN            | Required |
| `guard` | object | Circuit breakers during execution              | `{}`     |
| `hitl`  | string | `before_gate`, `after_gate`, or `true` (alias) | —        |

### GATE phase

| Field  | Type | Description                                      |
| ------ | ---- | ------------------------------------------------ |
| `gate` | list | Ordered list of checks, each producing pass/fail |

### RETRY

| Field          | Type | Description                                           |
| -------------- | ---- | ----------------------------------------------------- |
| `retry`        | list | Ordered list of entries with conditions and overrides |
| `retry[].exit` | int  | Stop retrying (required — no exit = dry-run error)    |

### Composition

| Field      | Type   | Description                                 |
| ---------- | ------ | ------------------------------------------- |
| `type`     | string | `code`, `split`, `validate` (required)      |
| `each`     | list   | Mini-workflow per task (split only)         |
| `parallel` | bool   | Parallelize tasks (on split) or group steps |
| `steps`    | list   | Sub-steps of a parallel group               |
| `workflow` | string | Path to a sub-workflow                      |
| `with`     | object | Inputs for a sub-workflow                   |

## Guard fields

| Field        | Type   | Description                                     |
| ------------ | ------ | ----------------------------------------------- |
| `max_turns`  | int    | Kill if turns exceed this count                 |
| `max_budget` | float  | Kill if step cost exceeds this (USD)            |
| `max_tokens` | int    | Kill if tokens consumed exceed this             |
| `max_time`   | string | Kill if duration exceeds this. Alias: `timeout` |
| `no_write`   | bool   | Kill if agent writes outside `.gump/out/`       |

## Gate values

| Value               | Description                                        |
| ------------------- | -------------------------------------------------- |
| `compile`           | Run the compile command (auto-detected or config)  |
| `test`              | Run the test command                               |
| `lint`              | Run the lint command (skipped if not available)    |
| `schema`            | Validate split output JSON format                  |
| `tests_found`       | Verify the test runner finds tests                 |
| `touched: "glob"`   | At least one file matching glob modified           |
| `untouched: "glob"` | No file matching glob modified                     |
| `coverage: N`       | Test coverage ≥ N% (optional)                      |
| `bash: "command"`   | Custom shell command. Exit 0 = pass                |
| `validate: <path>`  | Workflow validator (type: validate, output = bool) |

## Retry entry fields

| Field                  | Type   | Description                       |
| ---------------------- | ------ | --------------------------------- |
| `attempt: N`           | int    | Apply from attempt N (sticky)     |
| `not: <gate>`          | string | Apply if the named gate failed    |
| `validate: <workflow>` | string | Invoke a validator; apply if true |
| `exit: N`              | int    | Stop at attempt N → FATAL         |
| `agent`                | string | Override agent                    |
| `session`              | string | Override session (e.g., `new`)    |
| `worktree`             | string | Override worktree (e.g., `reset`) |
| `prompt`               | string | Override entire prompt            |
| `with`                 | object | Inputs for a validate condition   |