Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/snarktank/ralph/llms.txt

Use this file to discover all available pages before exploring further.

Once you have your prd.json ready, run Ralph to autonomously implement all user stories.

​
Basic Usage

./scripts/ralph/ralph.sh
Default max iterations: 10

​
Command Options

​
Specify Max Iterations

./scripts/ralph/ralph.sh 20
Runs up to 20 iterations before stopping.

​
Choose AI Tool

# Use Amp (default)
./scripts/ralph/ralph.sh --tool amp

# Use Claude Code
./scripts/ralph/ralph.sh --tool claude

​
Combined Options

./scripts/ralph/ralph.sh --tool claude 15
Runs Claude Code for up to 15 iterations.

​
What Ralph Does

1

Create Feature Branch

Ralph creates or checks out the branch specified in prd.json (branchName field).Example: ralph/task-priority
2

Pick Next Story

Ralph picks the highest priority user story where passes: false.
3

Implement Story

A fresh AI instance (Amp or Claude Code) implements that single story with clean context.
4

Run Quality Checks

Ralph runs your project’s quality checks:
  • Typecheck
  • Linter
  • Tests
  • Any custom checks in your prompt template
5

Commit If Passing

If all checks pass, Ralph commits with message:
feat: [Story ID] - [Story Title]
Example: feat: US-001 - Add priority field to database
6

Update prd.json

Ralph marks the story as passes: true in prd.json.
7

Append to progress.txt

Ralph adds learnings to progress.txt:
  • What was implemented
  • Files changed
  • Patterns discovered
  • Gotchas encountered
  • Thread URL for reference
8

Repeat or Complete

If all stories have passes: true, Ralph outputs <promise>COMPLETE</promise> and exits.Otherwise, it starts the next iteration.

​
How Iterations Work

​
Each Iteration = Fresh Context

Each iteration spawns a new AI instance (Amp or Claude Code) with clean context. The only memory between iterations is:

Persistent Memory

  • Git history - Commits from previous iterations
  • progress.txt - Learnings and context
  • prd.json - Which stories are done (passes status)
This design prevents context overflow and ensures each story gets full attention.

​
Example Ralph Run

Here’s what a Ralph execution looks like: 
$ ./scripts/ralph/ralph.sh --tool amp 10

Starting Ralph - Tool: amp - Max iterations: 10

===============================================================
  Ralph Iteration 1 of 10 (amp)
===============================================================
[Amp output: implementing US-001]
[Typecheck passes]
[Committed: feat: US-001 - Add priority field to database]
[Updated prd.json: US-001 passes=true]
Iteration 1 complete. Continuing...

===============================================================
  Ralph Iteration 2 of 10 (amp)
===============================================================
[Amp output: implementing US-002]
[Typecheck passes]
[Browser verification passes]
[Committed: feat: US-002 - Display priority indicator on task cards]
[Updated prd.json: US-002 passes=true]
Iteration 2 complete. Continuing...

===============================================================
  Ralph Iteration 3 of 10 (amp)
===============================================================
[Amp output: implementing US-003]
[All checks pass]
[Committed: feat: US-003 - Add priority selector to task edit]
[Updated prd.json: US-003 passes=true]
Iteration 3 complete. Continuing...

===============================================================
  Ralph Iteration 4 of 10 (amp)
===============================================================
[Amp output: implementing US-004]
[All checks pass]
[Committed: feat: US-004 - Filter tasks by priority]
[Updated prd.json: US-004 passes=true]
<promise>COMPLETE</promise>

Ralph completed all tasks!
Completed at iteration 4 of 10

​
Stop Conditions

​
Success: All Stories Complete

When all stories have passes: true, Ralph outputs: 
<promise>COMPLETE</promise>
And exits with code 0.

​
Timeout: Max Iterations Reached

If Ralph reaches max iterations without completing all stories: 
Ralph reached max iterations (10) without completing all tasks.
Check progress.txt for status.
Exits with code 1.

​
Automatic Archiving

When you start a new feature (different branchName), Ralph automatically archives the previous run: 
Archiving previous run: ralph/old-feature
   Archived to: archive/2026-03-11-old-feature
The archive contains:
  • Previous prd.json
  • Previous progress.txt

​
Key Files During Execution

FilePurpose
ralph.shThe bash loop that spawns fresh AI instances
prompt.mdInstructions given to each Amp instance
CLAUDE.mdInstructions given to each Claude Code instance
prd.jsonTask list with passes status
progress.txtAppend-only learnings for future iterations
.last-branchTracks current feature for archiving

​
Customizing the Prompt

After copying Ralph to your project, customize the prompt template: 
# Edit scripts/ralph/prompt.md
Add project-specific:
  • Quality check commands
  • Codebase conventions
  • Common gotchas for your stack
  • Required environment variables

​
Debugging Failed Iterations

If an iteration fails:
  1. Check the output - Scroll up to see error messages
  2. Review progress.txt - See what previous iterations learned
  3. Inspect prd.json - Check which story was being attempted
  4. Check git log - See what was committed successfully
# See which stories are done
cat prd.json | jq '.userStories[] | {id, title, passes}'

# See learnings from previous iterations
cat progress.txt

# Check recent commits
git log --oneline -10

​
Browser Verification for UI Stories

Frontend stories must include “Verify in browser using dev-browser skill” in acceptance criteria.
Ralph will:
  1. Load the dev-browser skill
  2. Navigate to the relevant page
  3. Interact with the UI
  4. Confirm changes work visually
  5. Take screenshots for the progress log
A frontend story is NOT complete until browser verification passes.

​
AGENTS.md Updates

Ralph automatically updates AGENTS.md files with discovered patterns. This is critical for future iterations!
After each iteration, Ralph checks if any learnings should be added to AGENTS.md files:
  • Patterns discovered - “This codebase uses X for Y”
  • Gotchas encountered - “Don’t forget to update Z when changing W”
  • Useful context - “The settings panel is in component X”
AI coding tools automatically read AGENTS.md files, so future iterations (and human developers) benefit immediately.

​
Feedback Loops Are Critical

Ralph only works if there are feedback loops:

Required Feedback

  • Typecheck catches type errors
  • Tests verify behavior
  • CI must stay green (broken code compounds across iterations)
  • Browser verification confirms UI changes work
Without feedback loops, Ralph cannot self-correct and will accumulate broken code. Add to ~/.config/amp/settings.json: 
{
  "amp.experimental.autoHandoff": { "context": 90 }
}
This enables automatic handoff when context fills up, allowing Ralph to handle large stories that exceed a single context window.

​
Next Steps

While Ralph is running:
  1. Monitor progress via prd.json, progress.txt, and git log
  2. Let Ralph work autonomously
  3. Review commits when complete
  4. Merge the feature branch when ready

Autonomous Execution

Ralph runs completely autonomously - no human intervention required!

Build docs developers (and LLMs) love

Get started for freeTalk to us