Ralph

Ralph is an autonomous AI agent loop that runs AI coding tools (Amp or Claude Code) repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context. Memory persists via git history, progress.txt, and prd.json.

Ralph includes specialized skills for the complete development lifecycle:

• PRD Generation: Create detailed product requirements with the /prd skill
• PRD Review: Validate PRDs for clarity and completeness with /prd-reviewer
• Autonomous Execution: Convert PRDs to executable format with /ralph
• Systematic Investigation: Diagnose and fix issues with hypothesis-driven investigation using /investigate

Based on Geoffrey Huntley's Ralph pattern.

Read my in-depth article on how I use Ralph

• One of the following AI coding tools installed and authenticated:
  • Amp CLI (default)
  • Claude Code (npm install -g @anthropic-ai/claude-code)
• jq installed (brew install jq on macOS)
• A git repository for your project

Copy the ralph files into your project:

# From your project root
mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/

# Copy the prompt template for your AI tool of choice:
cp /path/to/ralph/prompt.md scripts/ralph/prompt.md    # For Amp
# OR
cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md    # For Claude Code

chmod +x scripts/ralph/ralph.sh

Copy the skills to your Amp or Claude config for use across all projects:

For AMP

cp -r skills/prd ~/.config/amp/skills/
cp -r skills/prd-reviewer ~/.config/amp/skills/
cp -r skills/ralph ~/.config/amp/skills/
cp -r skills/investigate ~/.config/amp/skills/

For Claude Code

# Install skills
cp -r skills/prd ~/.claude/skills/
cp -r skills/prd-reviewer ~/.claude/skills/
cp -r skills/ralph ~/.claude/skills/
mkdir -p ~/.claude/skills/investigate && cp skills/investigate/SKILL.md ~/.claude/skills/investigate/

# Install investigate subagents (enables named subagent references)
mkdir -p ~/.claude/agents
cp skills/investigate/agents/*.md ~/.claude/agents/

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.

Use the PRD skill to generate a detailed requirements document:

Load the prd skill and create a PRD for [your feature description]

Answer the clarifying questions. The skill saves output to tasks/prd-[feature-name].md.

Use the PRD Reviewer skill to validate your PRD before conversion:

/prd-reviewer tasks/prd-[feature-name].md

This skill:

• Auto-fixes simple issues (required criteria, formatting)
• Identifies story sizing problems
• Validates dependency ordering
• Checks acceptance criteria clarity
• Generates detailed review report with actionable fixes

Iterate until the PRD gets a high readiness score (8+/10). This prevents Ralph execution failures.

Use the Ralph skill to convert the markdown PRD to JSON:

Load the ralph skill and convert tasks/prd-[feature-name].md to prd.json

This creates prd.json with user stories structured for autonomous execution.

# Using Amp (default)
./scripts/ralph/ralph.sh [max_iterations]

# Using Claude Code
./scripts/ralph/ralph.sh --tool claude [max_iterations]

Default is 10 iterations. Use --tool amp or --tool claude to select your AI coding tool.

Ralph will:

1. Create a feature branch (from PRD branchName)
2. Pick the highest priority story where passes: false
3. Implement that single story
4. Run quality checks (typecheck, tests)
5. Commit if checks pass
6. Update prd.json to mark story as passes: true
7. Append learnings to progress.txt
8. Repeat until all stories pass or max iterations reached

If you encounter bugs or unexpected behavior during development or while Ralph is running, use the investigate skill:

/investigate

The investigate skill provides systematic, hypothesis-driven investigation through orchestrated subagents. Each investigation phase runs in an isolated context to prevent context overflow.

Architecture:

• Haiku subagents (fast/cheap): Session management, instrumentation, reproduction, cleanup
• Sonnet subagents (balanced): Web research, fix verification
• Opus subagents (deep reasoning): Hypothesis generation, log analysis, fix application

Key Features:

• Structured Issue Intake: Guided collection of reproduction steps, error messages, and environment context
• Hypothesis Generation: Opus analyzes code and generates 3-5 testable hypotheses ranked by confidence
• Language-Adaptive Instrumentation: Haiku adds logging to Python, TypeScript, JavaScript, Java, Go, and other languages
• Context-Efficient: Each phase runs in isolated subagent context, preventing overflow
• Automated Workflows:
  • Issue reproduction and verification
  • Flaky test handling (configurable success count)
  • Log pattern detection and cross-file correlation
  • Web research for best practices (Sonnet)
  • Research-informed fix application (Opus)
  • Automated instrumentation cleanup
• Session Persistence: State stored in .claude/debug-sessions/ for resumption

When to use:

• Runtime errors (crashes, exceptions, null references)
• Logic bugs (incorrect behavior, wrong output)
• Intermittent/flaky issues (works sometimes, fails others)
• Performance issues (slowness, timeouts, resource leaks)
• Cross-service integration problems

Workflow:

1. Invoke /investigate
2. Answer structured intake questions (issue type, reproduction steps, expected vs actual behavior)
3. Haiku initializes session file as shared state
4. Opus generates hypotheses based on error patterns
5. Haiku instruments code with marker-based logging
6. Haiku runs tests and captures logs
7. Opus analyzes logs and confirms/rejects hypotheses
8. Sonnet researches best practices for confirmed issues
9. Opus applies research-informed fix
10. Sonnet verifies fix resolves the issue
11. Haiku cleans up all instrumentation

The investigate skill uses marker-based logging (// DEBUG_HYP_{id}_START / _END) for complete cleanup after investigation is finished, ensuring no debug code remains in your codebase.

Ralph supports per-story model selection via the reasoningLevel field in prd.json:

When using the /ralph skill to convert a PRD to prd.json, it will guide you in choosing appropriate reasoning levels for each story. The reasoningLevel field is REQUIRED for all user stories.

Cost optimization tip: Opus is ~15x more expensive than Haiku and ~3x more expensive than Sonnet. Use HIGH sparingly for genuinely complex work.

{
  "id": "US-001",
  "title": "Add status column to database",
  "description": "As a developer, I need to store task status.",
  "acceptanceCriteria": ["Add status enum column with default 'pending'"],
  "priority": 1,
  "passes": false,
  "notes": "",
  "jiraKey": null,
  "reasoningLevel": "LOW"
}

View Interactive Flowchart - Click through to see each step with animations.

The flowchart/ directory contains the source code. To run locally:

cd flowchart
npm install
npm run dev

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

• Git history (commits from previous iterations)
• progress.txt (learnings and context)
• prd.json (which stories are done)

Each PRD item should be small enough to complete in one context window. If a task is too big, the LLM runs out of context before finishing and produces poor code.

Right-sized stories:

• Add a database column and migration
• Add a UI component to an existing page
• Update a server action with new logic
• Add a filter dropdown to a list

Too big (split these):

• "Build the entire dashboard"
• "Add authentication"
• "Refactor the API"

After each iteration, Ralph updates the relevant AGENTS.md files with learnings. This is key because AI coding tools automatically read these files, so future iterations (and future human developers) benefit from discovered patterns, gotchas, and conventions.

Examples of what to add to AGENTS.md:

• Patterns discovered ("this codebase uses X for Y")
• Gotchas ("do not forget to update Z when changing W")
• Useful context ("the settings panel is in component X")

Ralph only works if there are feedback loops:

• Typecheck catches type errors
• Tests verify behavior
• CI must stay green (broken code compounds across iterations)

Frontend stories must include "Verify in browser using Selenium MCP" in acceptance criteria. Ralph will use Selenium MCP tools to navigate to the page, interact with the UI, and confirm changes work. Available Selenium MCP tools include:

• mcp__selenium__start_browser - Launch Chrome or Firefox
• mcp__selenium__navigate - Navigate to URLs
• mcp__selenium__find_element / mcp__selenium__click_element / mcp__selenium__send_keys - Interact with elements
• mcp__selenium__take_screenshot - Capture visual verification
• mcp__selenium__close_session - Clean up browser session

When all stories have passes: true, Ralph outputs <promise>COMPLETE</promise> and the loop exits.

Check current state:

# See which stories are done
cat prd.json | jq '.userStories[] | {id, title, passes}'

# See learnings from previous iterations
cat progress.txt

# Check git history
git log --oneline -10

For systematic investigation of runtime errors, logic bugs, or unexpected behavior in your codebase, use the investigate skill:

/investigate

The investigate skill uses orchestrated subagents for context-efficient investigation:

• Opus for hypothesis generation, log analysis, and fix application
• Sonnet for web research and fix verification
• Haiku for instrumentation, test execution, and cleanup

Key capabilities:

• Hypothesis-driven investigation with automated instrumentation
• Language-adaptive logging (Python, TypeScript, JavaScript, Java, Go, etc.)
• Cross-file log correlation and pattern detection
• Research-informed fix application with verification
• Session persistence in .claude/debug-sessions/

See the Investigate Issues section for detailed usage instructions.

After copying prompt.md (for Amp) or CLAUDE.md (for Claude Code) to your project, customize it for your project:

• Add project-specific quality check commands
• Include codebase conventions
• Add common gotchas for your stack

Ralph automatically archives previous runs when you start a new feature (different branchName). Archives are saved to archive/YYYY-MM-DD-feature-name/.

Ralph can optionally sync PRDs to Atlassian Jira, creating epics and tickets that update in real-time as stories are completed. This requires the Atlassian MCP server.

• Atlassian MCP Server configured
• Jira Cloud instance with API access
• Atlassian API token with required permissions

Install the Atlassian MCP server globally:

npm install -g @anthropic/mcp-server-atlassian

Add the Atlassian MCP server to your Claude Code MCP configuration at ~/.claude/mcp_servers.json:

{
  "mcpServers": {
    "atlassian": {
      "command": "mcp-server-atlassian",
      "env": {
        "ATLASSIAN_SITE_URL": "https://your-domain.atlassian.net",
        "ATLASSIAN_USER_EMAIL": "your-email@example.com",
        "ATLASSIAN_API_TOKEN": "your-api-token"
      }
    }
  }
}

Important: Credentials are stored in ~/.claude/ (your home directory), not in the repository. Never commit API tokens to version control.

1. Go to Atlassian Account Settings
2. Click "Create API token"
3. Give it a descriptive label (e.g., "Ralph Claude Code Integration")
4. Copy the token and add it to your MCP configuration

Your Atlassian account needs these permissions in the target Jira project:

Copy the example configuration and customize for your project:

# From your project root (where prd.json lives)
mkdir -p .ralph
cp /path/to/ralph/.ralph/jira.json.example .ralph/jira.json

Edit .ralph/jira.json with your project-specific values:

{
  "projectKey": "PROJ",
  "atlassianSiteUrl": "https://your-domain.atlassian.net",
  "epicIssueType": "Epic",
  "storyIssueType": "Story",
  "subtaskIssueType": "Sub-task",
  "defaultLabels": ["ralph-generated"],
  "statusMapping": {
    "start": "In Progress",
    "done": "Done",
    "fail": "In Progress"
  }
}

See .ralph/jira.json.example for all available configuration options and detailed field documentation.

Important: The .ralph/jira.json file is gitignored by default since it contains project-specific settings. Each project needs its own configuration.

After creating your prd.json, run the sync-jira skill:

/sync-jira

This creates:

• One Jira epic for the PRD
• One ticket per user story, linked to the epic
• Updates prd.json with Jira ticket references

Jira integration is completely optional. If not configured:

• Ralph operates normally without any Jira functionality
• No errors or warnings are shown
• All existing Ralph functionality works unchanged

Test the MCP server connection:

# Verify MCP server is installed
which mcp-server-atlassian

# Check Claude Code recognizes the server
claude mcp list

If the server doesn't appear, verify your ~/.claude/mcp_servers.json syntax is valid JSON.

• Geoffrey Huntley's Ralph article
• Amp documentation
• Claude Code documentation