Ralph Wiggum Loop Skill

Autonomous AI coding pattern that runs agents in iterations with clean context, working on PRD-driven features while maintaining CI green.

Commands

/ralph setup

Create all Ralph files in the current directory.

Steps:

1. Read and copy templates from this skill's templates/ folder:

   • templates/ralph-loop.sh → ./ralph-loop.sh
   • templates/prd.json → ./prd.json
   • templates/progress.txt → ./progress.txt
   • templates/README-RALPH.md → ./README-RALPH.md

2. Make script executable: chmod +x ralph-loop.sh

3. Detect project context and customize:

   • Check for package.json → determine package manager (pnpm/npm/yarn)
   • Check for tsconfig.json → TypeScript project
   • Update test commands in ralph-loop.sh accordingly

4. Show completion message with next steps

/ralph init

Guide user through creating a custom PRD interactively.

Questions to ask:

1. Project name?
2. What features do you want to build? (collect 3-5 user stories)
3. For each story:
   • Title?
   • Description?
   • Acceptance criteria? (3-5 specific, testable criteria)

Output: Generate prd.json with user's input. Offer to create other Ralph files if not present.

/ralph run

Execute the Ralph loop.

Pre-flight checks:

1. Verify ralph-loop.sh exists
2. Verify prd.json exists
3. Show summary:
   • Total user stories
   • Incomplete stories (where passes: false)
   • Max iterations configured
4. Ask for confirmation
5. Execute: ./ralph-loop.sh

/ralph (no args)

Show help menu:

Ralph Wiggum Loop - Autonomous AI Coding

Commands:
  /ralph setup  - Create Ralph infrastructure in this directory
  /ralph init   - Create a new PRD from scratch
  /ralph run    - Run the Ralph loop

What would you like to do?

Key Principles

1. Clean slate each iteration - Fresh context, no baggage
2. One feature at a time - Prevents scope creep
3. CI must stay green - Tests and types pass every commit
4. Progress tracking - Append to progress.txt each iteration
5. Clear stop condition - <promise>COMPLETE</promise> when all stories pass
6. Safety limit - Max iterations prevents infinite loops

PRD Quality Checklist

Good user stories are:

• ✅ Specific and scoped (completable in one iteration)
• ✅ Clear acceptance criteria (testable, unambiguous)
• ✅ Properly prioritized (1 = highest)
• ✅ Has "passes": false initially

Bad user stories are:

• ❌ Too vague ("build the UI")
• ❌ Too large (touches many systems)
• ❌ Unclear criteria ("make it nice")