Ralph

---
name: ralph
tier: companion
description: "Enforces Law 6 (Iterate Means One Thing) of the 7 Laws of AI Agent Discipline at PRD scale. Ralph is an autonomous AI agent loop that runs repeatedly until all PRD items are complete. Converts PRDs to executable JSON, implements stories iteratively with quality checks, and tracks progress."
origin: https://github.com/snarktank/ralph
disable-model-invocation: true
---

# Ralph — Autonomous Agent Loop

Ralph runs iteratively until all PRD stories are complete. Each iteration: picks highest priority story, implements, runs quality checks, commits if passing, updates progress, repeats.

## When to Use

- Large features that exceed a single context window
- Multi-story PRDs that need consistent implementation
- Tasks requiring repeated verification and commit cycles
- Long-running development that benefits from persistence across interruptions

## Do NOT Use When

- Task is a one-shot fix completable in a single edit — just edit the file
- You haven't written a PRD yet — write the PRD first, then run Ralph against it
- The work spans fewer than 3 stories — single-iteration verification is enough
- You need to explore or plan before committing to scope — use a planning skill first; Ralph is for execution, not discovery
- You want manual control over each iteration — run quality checks yourself, no need for Ralph's loop

## Prerequisites

- Git repository
- PRD document (markdown format)
- `jq` installed (`brew install jq` on macOS)

## Workflow

### 1. Create a PRD

Generate a detailed requirements document using the PRD skill:

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

Output saved to `tasks/prd-[feature-name].md`

**CRITICAL — refine generic criteria before iteration begins.** Auto-generated PRD scaffolds often produce generic acceptance criteria like `["Implementation is complete", "Code compiles without errors"]`. These are theater — Ralph cannot prove a story passes against criteria that don't actually constrain it. Replace every generic criterion with a concrete, testable statement before moving to step 2.

- Bad: `"Function is implemented correctly"`
- Good: `"Function parseUserInput(s) returns {ok: true, value} for valid s and {ok: false, error} for invalid s, asserted by tests/parse-user-input.test.ts"`
- Bad: `"Code compiles"`
- Good: `"TypeScript compiles with no errors (npm run build) AND lsp diagnostics show 0 errors on src/parse-user-input.ts"`

If you cannot write a testable criterion, the story is too big. Break it down before continuing.

**Example — refining a scaffold criterion**

Auto-generated:

```json
"acceptanceCriteria": [
  "Implementation is complete",
  "Code compiles without errors"
]
```

After refinement:

```json
"acceptanceCriteria": [
  "POST /api/users returns 201 with {id, email} for valid input, asserted by tests/api-users.test.ts",
  "POST /api/users returns 400 with {error} for missing email, asserted by tests/api-users.test.ts",
  "TypeScript compiles with 0 errors (npm run build)",
  "lsp diagnostics show 0 errors on src/api/users.ts"
]
```

### 2. Convert PRD to Ralph Format

Convert the markdown PRD to executable 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

Execute the autonomous loop:

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

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

Default: 10 iterations. Use `--tool amp` or `--tool claude` to select your AI tool.

## Ralph Loop Steps

1. **Create feature branch** — from PRD `branchName`
2. **Pick highest priority story** — where `passes: false`
3. **Implement that single story** — fresh context per iteration
4. **Run quality checks** — verify the current story's specific acceptance criteria with fresh evidence:
   - For EACH acceptance criterion, run the test/build/lint that proves it
   - Read the output, do not assume
   - If ANY criterion is not met, continue working — do NOT mark the story as `passes: true`
   - **Suite-level "all tests pass" is NOT a substitute for criterion-level proof.**

   **Example — story-by-story verification**

   Bad:

   ```
   Story US-002: "Add /api/users endpoint"
   - Ran npm test → all green → marked passes: true
   ```

   Why bad: suite-level pass doesn't prove THIS story's criteria. Other tests could be passing while the new endpoint is broken.

   Good:

   ```
   Story US-002: "Add /api/users endpoint"
   - Criterion 1: POST /api/users → 201 → ran `npx vitest tests/api-users.test.ts -t "valid input"` → PASS
   - Criterion 2: POST /api/users → 400 → ran `npx vitest tests/api-users.test.ts -t "missing email"` → PASS
   - Criterion 3: typecheck → ran `npm run build` → 0 errors
   - All criteria met with fresh evidence → marked passes: true
   ```

   Why good: each criterion proven with a targeted run; the output was read before the mark.

5. **Commit if checks pass** — atomic commits per story
6. **Update prd.json** — mark story as `passes: true`
7. **Append learnings** — to `progress.txt`
8. **Repeat** — until all stories pass or max iterations reached

## Key Concepts

### Each Iteration = Fresh Context

Every story gets a clean slate. Previous work is visible only via git history and `prd.json`, preventing context pollution.

### Small Tasks

Stories should be completable in 10-30 minutes. If a story stalls, break it down.

### AGENTS.md Updates Are Critical

Ralph updates `AGENTS.md` after each story so subsequent iterations know what's already done.

### Feedback Loops

- Build/test failures: immediate fix or rollback
- Test failures: investigate before declaring pass
- Confusion: log to `progress.txt` for human review

### Browser Verification for UI Stories

Ralph starts a dev server and uses Playwright to verify UI stories actually render.

### Stop Condition

Ralph stops when:
- All stories have `passes: true`
- Max iterations reached
- Critical failure encountered (user intervention required)

## Anti-patterns

These thoughts mean STOP — Ralph is about to slip:

| Thought | Why it's wrong |
|---|---|
| "All stories pass, time to summarise and wait for the user" mid-loop | Polite-stop. Ralph continues through commit + progress update + next pick in the same turn. |
| "Tests pass at the suite level, the story must be done" | Suite-level pass is not criterion-level proof. Verify each criterion with fresh evidence. |
| "Story is bigger than expected, I'll mark it passes: true and add a TODO" | Scope reduction. Either complete the story or break it down — never declare partial completion. |
| "The criterion is generic but obviously the test covers it" | PRD theater. Refine the criterion to something specific before proceeding. |
| "I'll skip the failing test by deleting/skipping it" | Tests are evidence. Fix the implementation, not the test. |
| "Reviewer said it looks good" — without running fresh checks | "Looks good" is not verification. Run the build, run the tests, read the output. |

## Final Checklist (Hard Gate)

Ralph cannot exit cleanly until ALL of these are true:

- [ ] Every story in `prd.json` has `passes: true` (no incomplete stories)
- [ ] Acceptance criteria are task-specific (no `"Implementation is complete"` generics)
- [ ] All requirements from the original task are met (no scope reduction)
- [ ] Fresh test run output shows all tests pass (read it, don't assume)
- [ ] Fresh build output shows success (read it, don't assume)
- [ ] No tests were deleted, skipped, or weakened to make checks green
- [ ] `progress.txt` records implementation details and learnings per iteration
- [ ] Working tree is clean (every story committed atomically)

A failing checkbox is a hard halt — do not declare done.

## Files

- `prd.json` — executable PRD with user stories
- `progress.txt` — accumulated learnings and status
- `ralph.sh` — the loop script
- `AGENTS.md` — iteration memory

## Debugging

If Ralph gets stuck:

1. Check `prd.json` for malformed stories
2. Review `progress.txt` for accumulated errors
3. Verify tests pass independently: `npm test` or equivalent
4. Check git status for uncommitted changes
5. Run single iteration manually to isolate issues

## Customizing the Prompt

Edit the prompt template in `scripts/ralph/prompt.md` (Amp) or `scripts/ralph/CLAUDE.md` (Claude Code) to adjust behavior.

## Archiving

After completion, archive `prd.json` and `progress.txt` to `tasks/archive/[date]/` for future reference.