ralph-prd

# Ralph PRD Skill for Claude Code

A Claude Code skill for generating Product Requirements Documents and running the Ralph autonomous implementation loop.

## What is Ralph?

Ralph is an autonomous coding workflow that:
1. Reads your PRD (Product Requirements Document)
2. Implements one task at a time
3. Runs tests to verify the implementation
4. Commits working code automatically
5. Repeats until all tasks are complete

## What's Included

| Component | Description |
|-----------|-------------|
| `SKILL.md` | The PRD generator skill for Claude Code |
| `ralph.sh` | The autonomous implementation loop script |

## Prerequisites

- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and configured
- A project directory where you want to use Ralph

## Installation

Run this command in your project directory:

```bash
curl -fsSL https://raw.githubusercontent.com/mykcryptodev/ralph-prd/master/install.sh | bash
```

This installs:
- `.claude/skills/prd/SKILL.md` - the PRD generator skill
- `ralph.sh` - the autonomous loop script

### Updating

Run the same install command to update to the latest version.

## Uninstallation

To remove Ralph from your project:

```bash
rm -rf .claude/skills/prd ralph.sh
```

Any `PRD.md` or `progress.txt` files are not affected.

## Usage

### Creating a PRD

Use the `/prd` command or just ask Claude to "create a prd":

```
/prd add user authentication
```

Or simply describe what you want to build:

```
create a prd for a REST API for managing tasks
```

The skill will:
1. Ask clarifying questions if needed
2. Generate a structured `PRD.md` in your project root
3. Create a `progress.txt` file for tracking learnings

### Running the Autonomous Loop

After the PRD is created, start Ralph:

```bash
./ralph.sh
```

Ralph will iterate through each user story in your PRD, implementing them one at a time until all tasks are marked complete.

You can optionally specify a maximum number of iterations:

```bash
./ralph.sh 25  # Run up to 25 iterations (default is 50)
```

## What Gets Created

When you use the `/prd` command, these files are created in your project:

| File | Description |
|------|-------------|
| `PRD.md` | The Product Requirements Document with user stories and acceptance criteria |
| `progress.txt` | Tracks learnings and iteration history for Ralph |
| `ralph.sh` | Executable script that runs the autonomous implementation loop |

## How Ralph Works

Each iteration of Ralph:

1. **Reads PRD.md** - Finds the first incomplete task (marked `[ ]`)
2. **Checks progress.txt** - Reviews learnings from previous iterations
3. **Implements the task** - Makes the necessary code changes
4. **Runs tests** - Verifies the implementation works
5. **On success:**
   - Marks the task complete (`[x]`) in PRD.md
   - Commits the changes
   - Logs what worked in progress.txt
6. **On failure:**
   - Does NOT mark the task complete
   - Does NOT commit broken code
   - Logs what went wrong in progress.txt

This continues until all tasks are complete or the max iteration limit is reached.

## PRD Format

PRDs generated by this skill follow this structure:

```markdown
# PRD: [Feature Name]

## Introduction
[What this feature does and why it matters]

## Goals
- [Primary and secondary goals]

## User Stories

### US-001: [Story Title]
**Description:** As a [user], I want [capability] so that [benefit].

**Acceptance Criteria:**
- [ ] [Testable criterion]
- [ ] [Another criterion]
- [ ] Typecheck passes (if applicable)

## Non-Goals
- [Things explicitly out of scope]

## Technical Considerations
- [Architecture notes, dependencies, constraints]
```

## Tips for Best Results

1. **Keep user stories small** - Each should be completable in one iteration
2. **Order stories by dependency** - Put foundational work first
3. **Make acceptance criteria testable** - Ralph uses these to verify success
4. **Review the PRD before running Ralph** - Adjust anything that seems off

## Troubleshooting

### ralph.sh: Permission denied
Make the script executable:
```bash
chmod +x ralph.sh
```

### Ralph keeps failing on the same task
Check `progress.txt` - it contains learnings from failed attempts. You may need to:
- Simplify the acceptance criteria
- Break the task into smaller steps
- Add technical context to the PRD

### Claude Code not finding the /prd command
If `/prd` is not available:
- Verify the skill is installed: check `.claude/skills/prd/SKILL.md` exists in your project
- Restart Claude Code after installation
- Reinstall if needed: run the install command again

## License

MIT