Skip to main content

​
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: 
- name: impl
  prompt: |
    Implement: {item.description}
    Files: {item.files}
Variables are resolved from the state bag before the agent launches. If a variable resolves to an empty string, the entire line is removed from the prompt.

​
Available variables

VariableAvailableDescription
{spec}AlwaysContent of the spec file
{item.name}In a foreachCurrent item name
{item.description}In a foreachCurrent item description
{item.files}In a foreachCurrent item blast radius
{steps.<n>.output}After step executesOutput of a previous step
{error}On retryError from the previous failed attempt
{diff}On retryDiff from the previous failed attempt
{run.cost}AlwaysRunning cost total
See the State Bag page for the full list of variables.

​
Template escaping

If your prompt contains literal curly braces (e.g., a JSON example), escape them with double braces: 
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

context:
  - file: "docs/architecture.md"
  - file: "{item.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

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

- name: audit
  agent: claude-opus
  output: plan
  context:
    - file: ".gump/skills/security-checklist.md"
    - bash: "gosec ./... 2>&1 || true"
  prompt: |
    Analyze the security scan results and the codebase.
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 and Cursor, AGENTS.md for Codex and OpenCode, GEMINI.md for Gemini, QWEN.md for Qwen. The context file contains:
  1. Gump system instructions (output format, Git rules, worktree constraints)
  2. Custom context (files and command outputs)
  3. Validation commands (so the agent knows what checks will run)
  4. The resolved prompt
The context file is overwritten at each step — the agent always gets fresh context.

​
Prompt from a file

For long prompts, use file: instead of inline text: 
- name: impl
  prompt:
    file: ".gump/prompts/implementation.md"
The file is read from the worktree and variable resolution applies to its content.