> ## 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.

# Prompts & Context

> Every agent step has a prompt that tells the agent what to do.

# Prompts & Context

Every agent step has a prompt that tells the agent what to do. Gump resolves variables in the prompt, assembles additional context, and writes everything to a context file in the worktree before launching the agent.

## Prompt templates

The `prompt` field is a template with variables in curly braces:

```yaml theme={null}
- name: impl
  type: code
  get:
    prompt: |
      Implement: {task.description}
      Files: {task.files}
```

Variables are resolved from the state before the agent launches. If a variable resolves to an empty string, the entire line is removed from the prompt (when the variable is the only content on that line).

### Key variables

| Variable                 | Available           | Description                                       |
| ------------------------ | ------------------- | ------------------------------------------------- |
| `{spec}`                 | Always              | Content of the spec file                          |
| `{task.name}`            | In an each block    | Current task name                                 |
| `{task.description}`     | In an each block    | Current task description                          |
| `{task.files}`           | In an each block    | Current task blast radius                         |
| `{impl.output}`          | After step executes | Output of a previous step                         |
| `{impl.agent}`           | After step executes | Agent that actually ran (useful after escalation) |
| `{error}`                | On retry            | Error from the previous failed attempt            |
| `{diff}`                 | On retry            | Diff from the previous failed attempt             |
| `{attempt}`              | On retry            | Current attempt number                            |
| `{gate.compile}`         | On retry            | Bool result of a specific gate                    |
| `{gate.review.comments}` | On retry            | Comments from a workflow validator                |
| `{prev.output}`          | On retry            | Output from the previous retry iteration          |

See the [State & Variables](/docs/writing-workflows/state) page for the full reference.

## Template escaping

If your prompt contains literal curly braces (e.g., a JSON example), escape them with double braces:

```yaml theme={null}
prompt: |
  Produce output in this format:
  {{
    "name": "example",
    "value": 42
  }}
```

`{{` produces a literal `{`. `}}` produces a literal `}`.

## Custom context

The `context` field injects additional information into the agent's context. Two sources are supported:

### File context

```yaml theme={null}
context:
  - file: "docs/architecture.md"
  - file: "{task.spec_path}"
```

Reads the file from the worktree and appends its content to the agent's context. The path supports variable resolution. If the file doesn't exist, it's skipped with a warning.

### Command context

```yaml theme={null}
context:
  - bash: "git log --oneline -10"
  - bash: "go test ./... -cover 2>&1 | grep coverage"
```

Runs the command in the worktree and appends stdout to the context. If the command fails, it's skipped with a warning.

### Combining sources

```yaml theme={null}
- name: audit
  type: validate
  get:
    context:
      - file: ".gump/skills/security-checklist.md"
      - bash: "gosec ./... 2>&1 || true"
    prompt: |
      Analyze the security scan results and the codebase.
  run:
    agent: claude-opus
```

Context sources are appended in order before the prompt. The agent sees: system instructions → context files → context commands → prompt.

## How context is materialized

Gump writes a context file in the worktree before launching the agent. The file name depends on the agent: `CLAUDE.md` for Claude Code, `AGENTS.md` for Codex and OpenCode, `GEMINI.md` for Gemini, `QWEN.md` for Qwen, `.cursor/rules/gump-agent.mdc` for Cursor.

The context file contains:

1. Gump system instructions (output format, Git rules, worktree constraints, step type conventions)
2. Resolved template variables
3. Custom context (files and command outputs)
4. The resolved prompt

The context file is overwritten at each step — the agent always gets fresh context.

### Retry context injection

When `attempt > 1` and the prompt is **not** overridden in the retry block, Gump automatically injects a retry section into the context — the failed diff, the error output, non-repetition instructions, and remaining attempts.

When the prompt **is** overridden in the retry block, this section is not injected — the developer controls everything.

## Prompt from a file

For long prompts, use `file:` instead of inline text:

```yaml theme={null}
- name: impl
  type: code
  get:
    prompt:
      file: ".gump/prompts/implementation.md"
```

The file is read from the worktree and variable resolution applies to its content.