prd

• One of the following AI coding tools installed and authenticated:

- [Amp CLI](https://ampcode.com) (default)

- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (npm install -g @anthropic-ai/claude-code)

• jq installed (brew install jq on macOS)
• A git repository for your project

Option 1: Copy to your project

Copy the ralph files into your project:

```bash

# 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

```

Option 2: Install skills globally

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

For AMP

```bash

cp -r skills/prd ~/.config/amp/skills/

cp -r skills/ralph ~/.config/amp/skills/

```

For Claude Code

```bash

cp -r skills/prd ~/.claude/skills/

cp -r skills/ralph ~/.claude/skills/

```

Configure Amp auto-handoff (recommended)

Add to ~/.config/amp/settings.json:

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

1. Create a PRD

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.

2. Convert PRD to Ralph format

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.

3. Run Ralph

```bash

# 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

| File | Purpose |

|------|---------|

| ralph.sh | The bash loop that spawns fresh AI instances (supports --tool amp or --tool claude) |

| prompt.md | Prompt template for Amp |

| CLAUDE.md | Prompt template for Claude Code |

| prd.json | User stories with passes status (the task list) |

| prd.json.example | Example PRD format for reference |

| progress.txt | Append-only learnings for future iterations |

| skills/prd/ | Skill for generating PRDs |

| skills/ralph/ | Skill for converting PRDs to JSON |

| flowchart/ | Interactive visualization of how Ralph works |

[](https://snarktank.github.io/ralph/)

[View Interactive Flowchart](https://snarktank.github.io/ralph/) - Click through to see each step with animations.

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

```bash

cd flowchart

npm install

npm run dev

```

Ea