Prompt Templates Overview

What Are Prompt Templates?

Prompt templates are Handlebars templates that transform task data into structured prompts for AI agents. When Ralph picks a task from your tracker, it uses a template to build the prompt that gets sent to Claude Code, OpenCode, or Factory Droid.

INFO

Handlebars is a simple templating language that uses \{\{variable\}\} syntax for variable substitution and \{\{#if condition\}\}...\{\{/if\}\} for conditional blocks.

Why Templates Matter

Templates give you control over how your AI agent receives task information:

Consistency - Every task gets the same structured format
Context injection - Include relevant metadata like dependencies, labels, and progress
Workflow customization - Tailor instructions to your project's requirements
Quality gates - Embed project-specific validation commands

How Templates Work

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐   │
│   │    TASK      │────▶│   TEMPLATE   │────▶│    PROMPT    │   │
│   │    DATA      │     │   + CONTEXT  │     │   TO AGENT   │   │
│   └──────────────┘     └──────────────┘     └──────────────┘   │
│                                                                 │
│   {                    ## User Story          Structured        │
│     id: "US-001",      **ID**: US-001   →    markdown sent      │
│     title: "Add..."    **Title**: Add...     to Claude/OpenCode/Droid │
│   }                                                             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

When Ralph executes a task:

Load Template

Ralph loads the appropriate template based on your tracker type (JSON, Beads, or custom).

Build Context

Task data is extracted and formatted as template variables: taskId, taskTitle, acceptanceCriteria, etc.

Render Prompt

Handlebars processes the template with the context, producing the final prompt string.

Execute Agent

The rendered prompt is passed to your AI agent (Claude Code, OpenCode, or Factory Droid).

Built-in Templates

Ralph includes optimized templates for each tracker type:

Tracker	Template	Optimized For
`json`	JSON Template	PRD user stories with acceptance criteria
`beads`	Beads Template	Bead workflows with epic context
`beads-bv`	Beads-BV Template	Graph-aware selection with dependency info
`default`	Default Template	Generic task structure

JSON Template Example

The JSON tracker template provides full PRD context with progress tracking:

HANDLEBARS

\{\{!-- Full PRD for project context (agent studies this first) --\}\}
\{\{#if prdContent\}\}
We are working in a project to implement the following Product Requirements Document (PRD):
 
\{\{prdContent\}\}
 
---
\{\{/if\}\}
 
\{\{!-- Task details --\}\}
## Your Task: \{\{taskId\}\} - \{\{taskTitle\}\}
 
\{\{#if taskDescription\}\}
### Description
\{\{taskDescription\}\}
\{\{/if\}\}
 
\{\{#if acceptanceCriteria\}\}
### Acceptance Criteria
\{\{acceptanceCriteria\}\}
\{\{/if\}\}
 
\{\{#if dependsOn\}\}
**Prerequisites**: \{\{dependsOn\}\}
\{\{/if\}\}
 
\{\{#if recentProgress\}\}
## Recent Progress
\{\{recentProgress\}\}
\{\{/if\}\}
 
## Workflow
1. Study the PRD context above to understand the bigger picture
2. Study `.ralph-tui/progress.md` to understand overall status, implementation progress, and learnings including codebase patterns and gotchas
3. Implement this single story following acceptance criteria
4. Run quality checks: typecheck, lint, etc.
5. Commit with message: `feat: \{\{taskId\}\} - \{\{taskTitle\}\}`
6. Document learnings in `.ralph-tui/progress.md`
7. Signal completion
 
## Stop Condition
**IMPORTANT**: If the work is already complete, verify it meets the
acceptance criteria and signal completion immediately.
 
When finished, signal completion with:
<promise>COMPLETE</promise>

Beads Template Example

The Beads template includes epic context and the bd CLI for closing issues:

HANDLEBARS

\{\{!-- Full PRD for project context (if available) --\}\}
\{\{#if prdContent\}\}
We are working in a project to implement the following Product Requirements Document (PRD):
 
\{\{prdContent\}\}
 
---
\{\{/if\}\}
 
## Bead Details
- **ID**: \{\{taskId\}\}
- **Title**: \{\{taskTitle\}\}
\{\{#if epicId\}\}
- **Epic**: \{\{epicId\}\}\{\{#if epicTitle\}\} - \{\{epicTitle\}\}\{\{/if\}\}
\{\{/if\}\}
\{\{#if taskDescription\}\}
- **Description**: \{\{taskDescription\}\}
\{\{/if\}\}
 
\{\{#if acceptanceCriteria\}\}
## Acceptance Criteria
\{\{acceptanceCriteria\}\}
\{\{/if\}\}
 
\{\{#if dependsOn\}\}
**Prerequisites**: \{\{dependsOn\}\}
\{\{/if\}\}
 
\{\{#if recentProgress\}\}
## Recent Progress
\{\{recentProgress\}\}
\{\{/if\}\}
 
## Workflow
1. Study the PRD context above (if available)
2. Study `.ralph-tui/progress.md` to understand overall status, implementation progress, and learnings including codebase patterns and gotchas
3. Implement the requirements (stay on current branch)
4. Run your project's quality checks
5. Commit: `feat: \{\{taskId\}\} - \{\{taskTitle\}\}`
6. Close the bead: `bd close \{\{taskId\}\} --db \{\{beadsDbPath\}\} --reason "..."`
7. Document learnings in `.ralph-tui/progress.md`
8. Signal completion
 
## Stop Condition
**IMPORTANT**: If the work is already complete, verify it works
correctly and signal completion immediately.
 
When finished, signal completion with:
<promise>COMPLETE</promise>

INFO

Both templates include compound learning - agents are instructed to study .ralph-tui/progress.md which contains learnings, patterns, and gotchas from previous iterations.

Template Resolution Order

Ralph uses a hierarchical resolution system, checking each level in order and using the first template found:

Custom Path (Highest Priority)

Explicit --prompt argument or prompt_template in config file.

Bash

ralph-tui run --prompt ./my-template.hbs

Project Templates

Templates in your project's .ralph-tui/templates/ folder:

.ralph-tui/templates/beads.hbs for Beads tracker
.ralph-tui/templates/beads-bv.hbs for Beads-BV tracker
.ralph-tui/templates/json.hbs for JSON tracker
.ralph-tui/templates/default.hbs for other trackers

This allows per-project customization without affecting other projects.

Global Templates

User-level templates in ~/.config/ralph-tui/templates/:

~/.config/ralph-tui/templates/beads.hbs
~/.config/ralph-tui/templates/json.hbs
etc.

These apply to all your projects unless overridden at the project level.

Tracker Bundle

Templates bundled with each tracker plugin. These are the optimized defaults for each tracker type.

Built-in Fallback (Lowest Priority)

Embedded default templates that ship with Ralph TUI.

INFO

Use project templates (.ralph-tui/templates/) for project-specific customizations and global templates (~/.config/ralph-tui/templates/) for personal preferences that apply to all projects.

Viewing Your Current Template

To see which template Ralph is using:

Bash

ralph-tui template show

This displays the resolved template source and content.

Next Steps

Customization - Create your own templates
Handlebars Reference - Complete variable and syntax reference