Running Ralph

Execute ralph.sh to run autonomous AI agent iterations until all PRD items are complete

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

Basic Usage

Amp (default)

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

File	Purpose
ralph.sh	The bash loop that spawns fresh AI instances
prompt.md	Instructions given to each Amp instance
CLAUDE.md	Instructions given to each Claude Code instance
prd.json	Task list with passes status
progress.txt	Append-only learnings for future iterations
.last-branch	Tracks current feature for archiving

Customizing the Prompt

After copying Ralph to your project, customize the prompt template:

For Amp

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

Recommended Settings

Amp Auto-Handoff (Recommended)

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!