mcpField
R
ralph

ralph

github.com/kv0906Agent workflows1843 installsUpdated 3w ago
Repository

About ralph

ralph is a skill for running AI coding agents through repeated, PRD-driven iterations. It creates project files, tracks story progress, and uses iteration limits and passing checks to guide completion.

Key features

  1. 01Scaffold loop, PRD, and progress files
  2. 02Create a custom PRD interactively
  3. 03Run the coding loop from a command
  4. 04Track stories and iteration progress
  5. 05Enforce iteration limits and passing checks

Use cases

  1. 01Set up an iterative coding project
  2. 02Break a feature plan into testable stories
  3. 03Run an agent through prioritized stories
  4. 04Monitor progress toward a completed PRD

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/kv0906/cc-skills --skill ralph

After installing, type/ralphin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

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

Details

From the project README

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

CommandAction
/ralphShow help menu
/ralph setupCreate Ralph infrastructure
/ralph initBuild custom PRD interactively
/ralph runExecute the autonomous loop

/ralph setup

Create all Ralph files in the current directory.

Steps:

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

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

Comments

Markdown supported