RalphTUI

Template Customization

Create and customize prompt templates to match your workflow and project requirements.

Why Customize Templates?

While Ralph's built-in templates work for most projects, customization lets you:

  • Add project-specific instructions or quality gates
  • Include additional context like code style guidelines
  • Modify the prompt structure for your AI agent's preferences
  • Inject custom metadata from your tracker

Quick Start: Initialize a Custom Template

The fastest way to get started is copying the built-in template:

Bash
ralph-tui template init
# or equivalently:
ralph-tui template install

This creates .ralph-tui-prompt.hbs in your project root, pre-populated with the current template for your tracker type.

INFO

The .hbs extension stands for Handlebars, the templating engine Ralph uses. You can also use .md or any other extension—Ralph just reads the file content.

Template Locations

Ralph supports a hierarchical template system with project-level and global templates.

Project Templates (Recommended)

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

your-project/
├── .ralph-tui/
│   ├── config.toml
│   └── templates/           # Project-specific templates
│       ├── beads.hbs        # Override for beads tracker
│       ├── json.hbs         # Override for json tracker
│       └── beads-bv.hbs     # Override for beads-bv tracker
└── ...

Templates are automatically detected based on your tracker type. No config changes needed!

INFO

Project templates take precedence over global templates. This lets you customize templates per-project while keeping personal defaults elsewhere.

Global Templates

For templates that apply across all your projects, use the global config directory:

~/.config/ralph-tui/
├── config.toml              # Global config
└── templates/               # Global templates
    ├── beads.hbs            # Default for Beads tracker
    ├── beads-bv.hbs         # Default for Beads-BV tracker
    ├── json.hbs             # Default for JSON tracker
    └── default.hbs          # Default for other trackers

Install global templates with:

Bash
ralph-tui template init --global

Custom Path (Explicit Override)

You can also specify an explicit template path:

TOML
# .ralph-tui/config.toml
prompt_template = "./my-custom-template.hbs"

Or via CLI:

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

Explicit paths take highest priority and override all other template sources.

Creating a Custom Template

Basic Structure

A minimal template needs the task details and completion signal:

HANDLEBARS
## Task: \{\{taskTitle\}\}
 
\{\{taskDescription\}\}
 
When finished, signal completion with:
<promise>COMPLETE</promise>

Adding Conditional Sections

Use \{\{#if\}\} blocks to include content only when data exists:

HANDLEBARS
## Task: \{\{taskTitle\}\}
 
\{\{#if taskDescription\}\}
### Description
\{\{taskDescription\}\}
\{\{/if\}\}
 
\{\{#if acceptanceCriteria\}\}
### Acceptance Criteria
\{\{acceptanceCriteria\}\}
\{\{/if\}\}
 
\{\{#if dependsOn\}\}
### Prerequisites
Complete these first: \{\{dependsOn\}\}
\{\{/if\}\}
 
When finished, signal completion with:
<promise>COMPLETE</promise>

Adding Project-Specific Instructions

Customize the instructions section for your workflow:

HANDLEBARS
## User Story
**ID**: \{\{taskId\}\}
**Title**: \{\{taskTitle\}\}
 
\{\{#if taskDescription\}\}
## Description
\{\{taskDescription\}\}
\{\{/if\}\}
 
\{\{#if acceptanceCriteria\}\}
## Acceptance Criteria
\{\{acceptanceCriteria\}\}
\{\{/if\}\}
 
## Project-Specific Instructions
 
### Code Style
- Use TypeScript with strict mode
- Follow the existing patterns in `src/`
- Add JSDoc comments for public APIs
 
### Quality Gates (REQUIRED)
Before marking complete, run:
1. `bun run typecheck` - Must pass with no errors
2. `bun run lint` - Must pass with no warnings
3. `bun run test` - All tests must pass
 
### Git Workflow
- Commit with message format: `feat(scope): description`
- Keep commits atomic and focused
 
When finished, signal completion with:
<promise>COMPLETE</promise>

Example Templates

Minimal Template

For simple, focused prompts:

HANDLEBARS
Task: \{\{taskTitle\}\}
\{\{taskDescription\}\}
 
\{\{#if acceptanceCriteria\}\}
Requirements:
\{\{acceptanceCriteria\}\}
\{\{/if\}\}
 
Signal <promise>COMPLETE</promise> when done.

Verbose Template with Full Context

This example mirrors the actual built-in templates with all features:

HANDLEBARS
\{\{!-- PRD Context (agent studies this first for the bigger picture) --\}\}
\{\{#if prdContent\}\}
We are working in a project to implement the following Product Requirements Document (PRD):
 
\{\{prdContent\}\}
 
---
\{\{/if\}\}
 
\{\{!-- Selection context for beads-bv tracker --\}\}
\{\{#if selectionReason\}\}
## Why This Task Was Selected
\{\{selectionReason\}\}
\{\{/if\}\}
 
## Your Task: \{\{taskId\}\} - \{\{taskTitle\}\}
 
\{\{#if taskDescription\}\}
### Description
\{\{taskDescription\}\}
\{\{/if\}\}
 
\{\{#if acceptanceCriteria\}\}
### Acceptance Criteria
\{\{acceptanceCriteria\}\}
\{\{/if\}\}
 
\{\{#if notes\}\}
### Notes
\{\{notes\}\}
\{\{/if\}\}
 
\{\{#if epicId\}\}
### Epic Context
- **Epic**: \{\{epicId\}\}\{\{#if epicTitle\}\} - \{\{epicTitle\}\}\{\{/if\}\}
\{\{/if\}\}
 
\{\{#if dependsOn\}\}
**Prerequisites**: \{\{dependsOn\}\}
\{\{/if\}\}
 
\{\{#if blocks\}\}
**Unblocks**: \{\{blocks\}\}
\{\{/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 task following acceptance criteria
4. Run quality checks: typecheck, lint, etc.
5. Commit with message: `feat: \{\{taskId\}\} - \{\{taskTitle\}\}`
6. Close the task (for beads): `bd close \{\{taskId\}\} --db \{\{beadsDbPath\}\} --reason "..."`
7. Document learnings (see below)
8. Signal completion
 
## Before Completing
APPEND to `.ralph-tui/progress.md`:

[Date] - {{taskId}}

  • What was implemented
  • Files changed
  • Learnings:
    • Patterns discovered
    • Gotchas encountered

If you discovered a **reusable pattern**, also add it to the `## Codebase Patterns` section at the TOP of progress.md.

## Stop Condition
**IMPORTANT**: If the work is already complete (implemented in a previous iteration or already exists), verify it meets the acceptance criteria and signal completion immediately.

When finished (or if already complete), signal completion with:
<promise>COMPLETE</promise>
INFO

This template includes compound learning - agents are instructed to study .ralph-tui/progress.md which contains learnings, patterns, and gotchas discovered in previous iterations. This makes each iteration smarter than the last.

Frontend-Focused Template

For UI development with browser verification:

HANDLEBARS
\{\{#if prdContent\}\}
We are working in a project to implement the following PRD:
 
\{\{prdContent\}\}
 
---
\{\{/if\}\}
 
## Frontend 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
2. Study `.ralph-tui/progress.md` for learnings, patterns, and gotchas
3. Implement following acceptance criteria
4. Run quality checks and verify in browser
5. Document learnings in progress.md
6. Signal completion
 
## Frontend Development Guidelines
 
### Implementation
1. Check for existing components in `src/components/`
2. Follow the design system patterns
3. Use Tailwind CSS for styling
4. Ensure responsive design (mobile-first)
 
### Browser Verification (REQUIRED)
Before marking complete:
1. Load the `dev-browser` skill
2. Navigate to the affected page(s)
3. Verify the UI renders correctly
4. Test interactive elements
5. Check responsive behavior at different viewport sizes
 
### Quality Checks
- `bun run typecheck` - No type errors
- `bun run lint` - No lint warnings
- Visual verification in browser
 
## Stop Condition
If the UI is already implemented, verify it works correctly and signal completion.
 
When finished, signal completion with:
<promise>COMPLETE</promise>

API Development Template

For backend/API work:

HANDLEBARS
\{\{#if prdContent\}\}
We are working in a project to implement the following PRD:
 
\{\{prdContent\}\}
 
---
\{\{/if\}\}
 
## API Task: \{\{taskId\}\} - \{\{taskTitle\}\}
 
\{\{#if taskDescription\}\}
### Description
\{\{taskDescription\}\}
\{\{/if\}\}
 
\{\{#if acceptanceCriteria\}\}
### Requirements
\{\{acceptanceCriteria\}\}
\{\{/if\}\}
 
\{\{#if dependsOn\}\}
**Prerequisites**: \{\{dependsOn\}\}
\{\{/if\}\}
 
\{\{#if recentProgress\}\}
## Recent Progress
\{\{recentProgress\}\}
\{\{/if\}\}
 
## Workflow
1. Study the PRD context above
2. Study `.ralph-tui/progress.md` for learnings, patterns, and gotchas
3. Implement following acceptance criteria
4. Run quality checks and tests
5. Document learnings in progress.md
6. Signal completion
 
## API Development Guidelines
 
### Implementation
1. Follow REST conventions
2. Use proper HTTP status codes
3. Validate input with Zod schemas
4. Handle errors gracefully
 
### Testing Requirements
- Write unit tests for new functions
- Add integration tests for endpoints
- Cover edge cases and error paths
 
### Documentation
- Update API docs if adding endpoints
- Add JSDoc comments for new functions
 
### Quality Checks
- `bun run typecheck`
- `bun run lint`
- `bun run test`
 
## Stop Condition
If the API endpoint already exists, verify it works correctly and signal completion.
 
When finished, signal completion with:
<promise>COMPLETE</promise>

Cross-Iteration Progress Tracking

Ralph maintains a progress file (.ralph-tui/progress.md) that summarizes work completed across iterations. Use the recentProgress variable to include this summary in your prompts:

HANDLEBARS
\{\{#if recentProgress\}\}
## Recent Progress
\{\{recentProgress\}\}
\{\{/if\}\}

Why Use recentProgress?

Reduces token burn: Instead of sending full iteration logs each time, the agent receives a concise summary of what's been done. This is especially valuable when:

  • Working through multi-iteration features
  • Agents have their own context/caching that benefits from summary over full logs
  • You want to avoid redundant file analysis between iterations

Default behavior: Ralph's built-in templates now include recentProgress to help agents understand context without receiving full iteration history.

How It Works

  1. After each iteration, Ralph extracts key information to .ralph-tui/progress.md
  2. On subsequent iterations, the content is available as the recentProgress template variable
  3. The summary includes completed tasks, key changes, and notes from previous work
INFO

The progress file is distinct from iteration logs (.ralph-tui/iterations/). Use recentProgress for context and ralph-tui logs for detailed debugging.

Customizing Progress Content

The progress file is managed by Ralph's engine. To customize what gets included:

  1. Modify task completion - Ensure tasks include helpful completion notes
  2. Use task notes - Include relevant context in tracker task notes
  3. Adjust prompt template - The recentProgress variable is read-only; customize the summary by adjusting how tasks are completed

Accessing Raw Task Data

For advanced templates, you can access the raw task and config objects:

HANDLEBARS
\{\{!-- Access nested task metadata --\}\}
\{\{#if task.metadata.customField\}\}
Custom: \{\{task.metadata.customField\}\}
\{\{/if\}\}
 
\{\{!-- Access config values --\}\}
Working directory: \{\{cwd\}\}
Model: \{\{model\}\}
INFO

The task and config objects expose internal structure that may change between versions. Prefer using the documented template variables when possible.

Testing Your Template

Preview Rendered Output

View how your template renders with a specific task:

Bash
# Show current template source
ralph-tui template show
 
# Run in dry-run mode to see prompts without executing
ralph-tui run --prd ./prd.json --iterations 1 --headless

Validate Syntax

Handlebars will error on invalid syntax. Common issues:

HANDLEBARS
\{\{!-- Wrong: unclosed block --\}\}
\{\{#if condition\}\}
Content here...
 
\{\{!-- Correct: properly closed --\}\}
\{\{#if condition\}\}
Content here...
\{\{/if\}\}

Next Steps