playbooks

home / skills / kv0906 / cc-skills / ralph

ralph skill

/ralph

This skill guides automated, PRD-driven coding iterations with a clean slate, ensuring CI green while progressing features end-to-end.

npx playbooks add skill kv0906/cc-skills --skill ralph

Review the files below or copy the command above to add this skill to your agents.

Files (6)
SKILL.md
3.1 KB
---
name: ralph
description: Set up and run Ralph Wiggum loop - autonomous AI coding with clean slate iterations, PRD-driven features, and CI quality gates. Use for long-running autonomous coding tasks.
---

# 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

| Command | Action |
|---------|--------|
| `/ralph` | Show help menu |
| `/ralph setup` | Create Ralph infrastructure |
| `/ralph init` | Build custom PRD interactively |
| `/ralph run` | Execute 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:
   - [templates/ralph-loop.sh](templates/ralph-loop.sh) → `./ralph-loop.sh`
   - [templates/prd.json](templates/prd.json) → `./prd.json`
   - [templates/progress.txt](templates/progress.txt) → `./progress.txt`
   - [templates/README-RALPH.md](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")

Overview

This skill sets up and runs the Ralph Wiggum loop: an autonomous AI coding pattern that iterates on PRD-driven features with clean-slate iterations and CI quality gates. It scaffolds the loop, helps you author a testable PRD, and runs the iteration script while enforcing CI green and a clear stop condition.

How this skill works

The skill creates a local loop script and a PRD file, adapts test commands to your project (detecting package manager and TypeScript), and guides interactive PRD creation with specific user stories and acceptance criteria. When run, it performs pre-flight checks, summarizes progress and incomplete stories, asks for confirmation, and executes the loop script that runs isolated iterations, updates progress logs, and stops when all stories pass or a max iteration limit is reached.

When to use it

  • Working on multi-step features that benefit from repeated autonomous iterations.
  • You need continuous enforcement of tests and type checks across automated commits.
  • Converting high-level requirements into small, testable user stories.
  • Running long-running autonomous coding tasks that must avoid state leakage.
  • Enabling an AI agent to prioritize one feature at a time and track progress.

Best practices

  • Write PRD stories that are specific, scoped, and completable in one iteration.
  • Provide 3–5 clear, testable acceptance criteria per story to make CI decisive.
  • Keep one active story per loop run to prevent scope creep and branching complexity.
  • Ensure your project has working tests and type checks before starting the loop.
  • Set a reasonable max-iteration safety limit to prevent infinite loops.
  • Append concise, timestamped progress notes each iteration for auditability.

Example use cases

  • Add a new API endpoint with 3 precise acceptance tests and let the loop implement until tests pass.
  • Implement a single front-end component with defined behavior and CI checks in each commit.
  • Refactor a module incrementally while ensuring tests and types remain green after every change.
  • Prototype a feature by iterating on small user stories and stopping when acceptance criteria are satisfied.
  • Automate long-running feature work where the AI must repeatedly reset context to avoid carry-over errors.

FAQ

What files does the setup create?

It creates a loop script, a prd.json, and a progress log, customizing test commands to your package manager and TypeScript setup.

How does the loop decide to stop?

It stops when all stories have passes: true with an explicit COMPLETE marker or when the configured max iterations is reached as a safety cutoff.