name: ralph-loop description: Launch an autonomous coding loop that implements features through small, incremental user stories. Use when implementing new features that can be broken into small stories, working on tasks that benefit from iterative refinement, or letting Claude work autonomously on greenfield features with clear acceptance criteria. Not for quick fixes, debugging, or unclear requirements.

Ralph Loop

Autonomous coding loop that implements features through incremental user stories.

Workflow Overview

Gather intent from user
Analyze feature thoroughly (map user journey, identify UI touchpoints, trace data flow)
Break into small, testable user stories
Generate PRD (scripts/ralph/prd.json)
Initialize progress file (scripts/ralph/progress.txt)
Create feature branch
Present summary and launch
Monitor and notify on completion

Step 1: Gather Intent

Ask the user:

What feature/goal?
Specific requirements or constraints?
Any existing spec or documentation?

Step 2: Feature Analysis (CRITICAL)

Before writing ANY stories, analyze comprehensively. Most failures come from implementing only the "happy path."

2a. Map Complete User Journey

Entry points: How does user discover/access this?
Primary flow: Main action
Feedback loops: How does user know it worked?
Persistent indicators: What shows state across app?
Reverse actions: Undo/modify?
Edge cases: Empty, error, loading states

2b. Identify ALL UI Touchpoints

Create a table:

Location	What Changes	Data Needed
...	...	...

Ask: "After this ships, how will user know [X]?"

2c. Trace Data Flow

For each touchpoint, identify:

New API endpoints needed?
Modified existing endpoints?
New/modified hooks?
Cache invalidation strategy?

If spec doesn't specify data flow, ASK before assuming.

2d. Find Gaps

Check for unspecified:

Loading states
Error states
Empty states
Permissions
Validation rules
Integration with existing features

When gaps found, ASK before assuming.

2e. Document Assumptions

List assumptions explicitly and get user confirmation.

Step 3: Break Into Stories

Only after Step 2, create small testable stories.

Size constraints:

Fit in ONE context window
Completable in ONE iteration
Touch minimal files (ideally 1-3)

Bad: "Build entire X system" Good: "Add X component", "Add X API endpoint", "Wire X to Y"

Acceptance criteria must be explicit:

Specific expected behavior
Typecheck/test commands pass
Reference existing patterns

See references/story-patterns.md for detailed guidance.

Step 4: Generate PRD

4a. Check for Existing Plan

Before generating, check if a plan exists (e.g., in docs/plans/):

ls docs/plans/  # Look for related feature folder

If plan exists:

Read task plan and findings for context
Link them in planFiles field
Reference implementation patterns from plan

4b. Write PRD

Write scripts/ralph/prd.json:

{
  "featureName": "[Feature Name]",
  "branchName": "ralph/[feature-slug]",
  "baseBranch": "main",
  "description": "[What this accomplishes]",
  "planFiles": [
    "docs/plans/[feature]/task_plan.md",
    "docs/plans/[feature]/findings.md"
  ],
  "userStories": [
    {
      "id": "US-001",
      "title": "[Short title]",
      "description": "[What this accomplishes]",
      "acceptanceCriteria": ["[Specific criterion]", "[Test commands pass]"],
      "priority": 1,
      "passes": false,
      "notes": "[Pattern references]"
    }
  ]
}

Fields:

planFiles: Optional. Links to existing plan docs (for archival and context)
baseBranch: Branch to create feature branch from (default: main)
Priority: Lower = higher priority. Dependencies first (schema -> API -> hooks -> UI).

Step 5: Initialize Progress

Create scripts/ralph/progress.txt with codebase patterns from project's CLAUDE.md. Add feature-specific context to Key Files section.

Step 6: Create Branch

git checkout [base-branch] && git pull && git checkout -b ralph/[feature-slug]

Step 7: Present Summary & Launch

Present structured summary:

## Ralph Loop Ready

### Feature: [Name]
[1-2 sentence description]

### User Stories ([N] total)
| # | Story | Description |
|---|-------|-------------|
| 1 | US-001: [Title] | [Brief] |

### Branch
`ralph/[feature-slug]`

### Estimated Cost
- Stories: [N]
- Iterations: [N + 5 buffer]
- Cost: $[X]-$[Y] (~$2-5/iteration)

Then ask user:

"Yes, run in background" -> Run with run_in_background: true
"No, I'll run manually" -> Provide command: bash ./scripts/ralph/ralph.sh [iterations]

Step 8: Monitor & Notify

When background task completes:

Check output file for status
Check scripts/ralph/prd.json for story completion
Report: "Ralph finished! PR at [URL]" or "Completed [X/Y] stories. Continue?"

Step 9: Archive PRD

After PR is created/merged, archive the PRD for historical reference:

9a. Find Destination

Check if prd.json has a planFiles field pointing to a plan folder
If plan folder exists -> archive there
If no plan folder -> archive to docs/ralph-history/

9b. Archive Files

# If plan exists
PLAN_DIR="docs/plans/[feature-name]"
cp scripts/ralph/prd.json "$PLAN_DIR/prd.json"
cp scripts/ralph/progress.txt "$PLAN_DIR/ralph-progress.txt"

# If no plan exists
ARCHIVE_DIR="docs/ralph-history/[feature-slug]-$(date +%Y%m%d)"
mkdir -p "$ARCHIVE_DIR"
cp scripts/ralph/prd.json "$ARCHIVE_DIR/prd.json"
cp scripts/ralph/progress.txt "$ARCHIVE_DIR/progress.txt"

9c. Commit Archive

git add docs/plans/ docs/ralph-history/
git commit -m "docs: archive ralph PRD for [feature-name]"

Step 10: Finalize

PR created automatically targeting base branch. Review and merge.

Resume Failed/Incomplete Loop

cat scripts/ralph/prd.json  # Check status
bash ./scripts/ralph/ralph.sh [remaining + 5]

File Structure

Skill Templates (this skill)

.claude/skills/ralph-loop/
├── SKILL.md                      # This file
├── scripts/
│   ├── ralph.sh                  # Loop runner template
│   └── agent-prompt.md           # Agent instructions template
└── references/
    └── story-patterns.md         # Story breakdown guidance

Project Runtime Files

Ralph reads/writes these files in the project root:

scripts/ralph/
├── ralph.sh          # Loop runner (copy from skill template)
├── prompt.md         # Agent instructions (copy from skill template)
├── prd.json          # Task list (GENERATED per feature)
└── progress.txt      # Context/learnings (GENERATED per feature)

Setup for New Projects

If scripts/ralph/ doesn't exist in the project:

Create directory: mkdir -p scripts/ralph
Copy templates from this skill:
- ralph.sh -> scripts/ralph/ralph.sh
- agent-prompt.md -> scripts/ralph/prompt.md
Customize prompt.md with project-specific test commands if needed

Where Ralph Logs Progress

IMPORTANT: Ralph always reads/writes to project's scripts/ralph/:

scripts/ralph/prd.json - Story status (update passes: true when done)
scripts/ralph/progress.txt - Learnings and patterns (append after each story)
.claude/CLAUDE.md - Permanent codebase patterns (update sparingly)

Checklist Before Running

scripts/ralph/ exists with ralph.sh and prompt.md
Read relevant specs if they exist
Read project's CLAUDE.md for patterns
Stories are small (1 context window each)
Each story has explicit, testable criteria
Dependencies ordered by priority
Typecheck/test commands in criteria
Summary presented to user
User confirmed launch

ralph-loop

SKILL.md