# Ralph Runner

> Run long-running autonomous AI agents using PRD-based task scoping.

- Skill: `majiayu000/ralph-runner` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/ralph-runner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/ralph-runner/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/ralph-runner

---


# Ralph Wiggum Agent Runner

Run autonomous coding agents that ship code while you sleep.

## When to Use
- Multi-story feature implementation
- Overnight autonomous coding
- Batch processing of related tasks
- When you want AI to work independently

## Quick Commands
```bash
# Run with current PRD
./scripts/ralph/ralph.sh

# Run with custom PRD
./scripts/ralph/ralph.sh scripts/ralph/my-feature.json

# Watch progress
tail -f scripts/ralph/progress.txt
```

## How It Works
1. Agent reads PRD, picks highest priority incomplete story
2. Implements ONLY that one story
3. Runs build/lint to ensure CI stays green
4. Commits work, updates PRD, appends to progress.txt
5. Repeats until all stories pass or max iterations

## PRD Structure
```json
{
  "stories": [
    {
      "id": "STORY-001",
      "title": "User can do X",
      "priority": 1,
      "passes": false,
      "acceptance_criteria": ["..."],
      "files_to_modify": ["..."]
    }
  ]
}
```

## Stop Condition
Agent emits `<promise>COMPLETE</promise>` when all stories pass.

## Files
| File | Purpose |
|------|---------|
| `scripts/ralph/ralph.sh` | Runner script |
| `scripts/ralph/prd.json` | Current PRD |
| `scripts/ralph/progress.txt` | Progress log |

## Reference Files
| Topic | File |
|-------|------|
| Full documentation | `scripts/ralph/README.md` |
| PRD template | `scripts/ralph/prd.template.json` |

## Related Skills
- `empathy-ledger-codebase` - Codebase patterns
- `deployment-workflow` - CI/CD integration