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:

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

After refinement:

"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:

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