---

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

1. Gather intent from user
2. Analyze feature thoroughly (map user journey, identify UI touchpoints, trace data flow)
3. Break into small, testable user stories
4. Generate PRD (scripts/ralph/prd.json)
5. Initialize progress file (scripts/ralph/progress.txt)
6. Create feature branch
7. Present summary and launch
8. 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

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

2b. Identify ALL UI Touchpoints

Create a table:

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/):

Copyls 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:

Copy{
  "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

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

Step 7: Present Summary & Launch

Present structured summary:

Copy## 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:

1. Check output file for status
2. Check scripts/ralph/prd.json for story completion
3. 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

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

9b. Archive Files

Copy# 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

Copygit 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

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

File Structure

Skill Templates (this skill)

Copy.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:

Copyscripts/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:

1. Create directory: mkdir -p scripts/ralph
2. Copy templates from this skill:
   • ralph.sh -> scripts/ralph/ralph.sh
   • agent-prompt.md -> scripts/ralph/prompt.md
3. 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