kv0906/cc-skills/ralph

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

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

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

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

1. Ask for confirmation
2. 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")