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
  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 page for the full reference.

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: "{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

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
  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:

Gump system instructions (output format, Git rules, worktree constraints, step type conventions)
Resolved template variables
Custom context (files and command outputs)
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:

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

Overview

Getting Started

Writing Workflows

Orchestration

Execution & Data

Agents

Reference

Prompts & Context

Prompts & Context

Prompt templates

Key variables

Template escaping

Custom context

File context

Command context

Combining sources

How context is materialized

Retry context injection

Prompt from a file

​Prompts & Context

​Prompt templates

​Key variables

​Template escaping

​Custom context

​File context

​Command context

​Combining sources

​How context is materialized

​Retry context injection

​Prompt from a file

Prompts & Context

Prompt templates

Key variables

Template escaping

Custom context

File context

Command context

Combining sources

How context is materialized

Retry context injection

Prompt from a file