Ralph Execution Skill

Autonomously implement user stories from the PRD, running quality gates and committing after each successful story. Maintains progress across sessions. Ships features while you sleep.

What is Ralph?

Ralph is an autonomous AI coding loop that ships features while you sleep. Each iteration is a fresh context window (keeping context small). Memory persists via git history, progress.txt, prd.json, and AGENTS.md.

Invocation

/ralph-execute [options]

Arguments:

• --max-iterations N - Override max iterations (default: from prd.json or 10)
• --story US-XXX - Target a specific story instead of next priority
• --dry-run - Show what would be done without making changes
• --skip-blocked - Skip blocked stories without re-attempting

Examples:

/ralph-execute                        # Continue from where we left off
/ralph-execute --max-iterations 5     # Run up to 5 stories
/ralph-execute --story US-003         # Implement specific story
/ralph-execute --dry-run              # Preview next story

Execution Flow

Phase 1: Session Initialization

Step 1.1: Load PRD

Read .ralph/prd.json. If not found:

ERROR: No PRD found at .ralph/prd.json

Run /ralph-plan first to generate a PRD with user stories.

Step 1.2: Check for Branch Change (Archival)

If current branch differs from prd.branchName, archive previous run:

mkdir -p .ralph/archive/[old-branch]-[timestamp]
mv .ralph/prd.json .ralph/archive/[old-branch]-[timestamp]/
mv .ralph/progress.txt .ralph/archive/[old-branch]-[timestamp]/

Step 1.3: Verify Branch

git branch --show-current

If not on the correct branch:

git checkout [prd.branchName]

Step 1.4: Load Progress Context

Read .ralph/progress.txt to understand:

• Previous learnings and patterns
• Files modified in past iterations
• Common gotchas discovered

CRITICAL: This context informs implementation decisions. Always read progress.txt before implementing.

Step 1.5: Load AGENTS.md

Read root-level AGENTS.md and any directory-level AGENTS.md files for:

• Module-specific patterns
• API conventions
• Known gotchas

Step 1.6: Initialize TodoWrite for UI

Sync prd.json stories to TodoWrite for visual progress tracking.

Phase 2: Story Selection

Step 2.1: Find Next Story

Select the highest-priority story where status === "pending":

const nextStory = prd.userStories
  .filter(s => s.status === 'pending')
  .sort((a, b) => a.priority - b.priority)[0];

If no pending stories:

• Check for blocked stories (offer to retry if --skip-blocked not set)
• If all passed/blocked, report completion

Step 2.2: Check Iteration Limits

if (prd.summary.iterationsRun >= prd.config.maxIterations) {
  // Report: "Max iterations reached. Run with --max-iterations N to continue."
  // Exit gracefully
}

Step 2.3: Display Story Context

STARTING ITERATION [N]
━━━━━━━━━━━━━━━━━━━━━━

Story: US-002 - Add registration form
Priority: 2 of 8
Previous Attempts: 0

Description:
As a new user, I want to register an account so that I can access the platform.
Implementation should follow the LoginForm pattern already established.

Acceptance Criteria:
□ Registration form with email, password, confirm password fields
□ Form validation using zod schema
□ Integration with existing auth context
□ TypeScript compiles without errors

Relevant Learnings from Progress:
- LoginForm pattern: src/components/auth/LoginForm.tsx
- Form validation: react-hook-form + zod
- Auth context: src/contexts/AuthContext.tsx

Phase 3: Story Implementation (Compound Engineering)

Each story follows the Plan → Work → Review → Compound cycle:

PLAN PHASE (40% of effort)

Step 3.1: Mark Story In-Progress Update prd.json: status: "in_progress" Update TodoWrite to show current task

Step 3.2: Research Codebase

• Read AGENTS.md + progress.txt "Codebase Patterns" section
• Find similar patterns in codebase using Glob/Grep
• Check commit history for related changes
• Identify existing components to reuse

Step 3.3: Create Implementation Plan Before writing code, document:

• Which files to create/modify
• Which patterns to follow
• Potential gotchas to avoid

WORK PHASE (20% of effort)

Step 3.4: Implement the Story

CRITICAL IMPLEMENTATION RULES:

1. ONE story at a time - Never implement multiple stories in one iteration
2. Follow existing patterns - Match the codebase style exactly
3. Minimal changes - Only modify what's needed for this story
4. Type safety first - Ensure TypeScript compiles before other checks

For UI Stories, Apply Frontend-Design Principles:

• Design thinking first - establish aesthetic direction before coding
• Use distinctive fonts, cohesive color schemes with CSS variables
• High-impact moments (page-load) over scattered micro-interactions
• Avoid: generic system fonts, clichéd colors, cookie-cutter patterns

Step 3.5: Run Quality Gates (Fail-Fast)

Execute in order:

1. TypeScript Check (Required)

   bashCopy

   npm run check 2>&1
   

   On failure: Parse error output, attempt fix, re-run (max 2 attempts)

2. Lint Check (Required)

   bashCopy

   npm run lint 2>&1
   

   On failure: Run npm run lint -- --fix, then re-check

3. Test Check (Optional)

   bashCopy

   npm run test 2>&1
   

   If configured in prd.json

4. Build Check (Optional)

   bashCopy

   npm run build 2>&1
   

   If enabled in prd.json config

Step 3.6: Browser Verification (UI Stories)

For stories with requiresBrowserVerification: true:

• Use visual-polish-inspector skill or Chrome extension
• Navigate to the page where UI change was made
• Take screenshot to verify rendering
• Check browser console for JavaScript errors
• Test responsive behavior if applicable
• Record pass/fail in progress.txt

Requirements:

• Chrome browser open
• Claude in Chrome extension (v1.0.36+) installed
• Dev server running (npm run dev)

REVIEW PHASE (20% of effort)

Step 3.7: Evaluate Quality Before committing, verify:

• Code quality: Clean, readable, follows patterns
• Security: No obvious vulnerabilities
• Performance: No unnecessary re-renders or expensive operations
• Testing: Adequate coverage for critical paths

Step 3.8: Handle Failures

On quality gate failure:

story.failureCount += 1;

if (story.failureCount >= prd.config.maxFailuresPerStory) {
  story.status = 'blocked';
  story.blockedReason = '[Specific error message]';
  prd.summary.blocked += 1;
  prd.summary.pending -= 1;
  // Log to progress.txt
  // Continue to next story
} else {
  // Retry this story
}

COMPOUND PHASE (20% of effort)

Step 3.9: Commit Changes

If all quality gates pass:

git add -A
git commit -m "feat: US-XXX - [Story Title]

[Brief description of implementation]

Co-Authored-By: Claude <[email protected]>"

Step 3.10: Update prd.json

story.status = 'passed';
story.completedAt = new Date().toISOString();
story.commits.push(commitHash);
prd.summary.passed += 1;
prd.summary.pending -= 1;
prd.summary.iterationsRun += 1;
prd.updatedAt = new Date().toISOString();

Step 3.11: Update AGENTS.md

If reusable patterns were discovered, add to AGENTS.md:

## Module: src/components/auth/
- Forms use react-hook-form + zod validation
- Auth state from `@clerk/nextjs`
- Follow LoginForm.tsx as pattern

Good AGENTS.md additions:

• "When modifying X, also update Y"
• "This module uses pattern Z"
• "Tests require dev server running"

Don't add to AGENTS.md:

• Story-specific details
• Temporary notes
• Info already in progress.txt

Step 3.12: Append to progress.txt

--- ITERATION [N] | US-XXX: [Title] ---
Timestamp: [ISO]
Status: PASSED

Learnings for future iterations:
- [Pattern discovered]
- [Gotcha avoided]

Files Modified:
- [file1] (created)
- [file2] (modified)

Quality Gates:
- typecheck: PASSED
- lint: PASSED (auto-fixed 2 issues)
- test: SKIPPED
- browser: VERIFIED

Commit: [hash] - feat: US-XXX - [Title]

Step 3.13: Consolidate Codebase Patterns

Update the "CODEBASE PATTERNS (Consolidated)" section at the TOP of progress.txt with any new patterns discovered.

Phase 4: Loop or Complete

Step 4.1: Check for Next Story

If pending stories remain AND iterations < max:

• Continue to next iteration (back to Phase 2)

Step 4.2: Handle Completion

If all stories passed or blocked:

RALPH EXECUTION COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━

All [N] stories processed!

Summary:
- Iterations: [N]
- Stories Passed: [N]
- Stories Blocked: [N]
- Total Commits: [N]

Branch: [branch-name]
Ready for review and merge.

Key Learnings Captured:
1. [Learning 1]
2. [Learning 2]

Next Steps:
1. Review commits: git log --oneline -n [N]
2. Push branch: git push -u origin [branch-name]
3. Create PR: gh pr create

Phase 5: Failure Handling

Blocked Story Notification

STORY BLOCKED: US-XXX
━━━━━━━━━━━━━━━━━━━━━

After 3 attempts, this story could not be completed.

Reason: [Specific blocker]

Recommended Action:
- [Suggestion based on error type]

Continuing with next priority story...

Append Failure to progress.txt

--- ITERATION [N] | US-XXX: [Title] (ATTEMPT 2/3) ---
Timestamp: [ISO]
Status: FAILED

Error:
[Error output]

Attempted Fix:
- [What was tried]

Result: Still failing. Will retry next iteration.

Session Persistence

Resuming Across Sessions

When /ralph-execute is run in a new session:

1. Read .ralph/prd.json for current state
2. Read .ralph/progress.txt for learned context
3. Read AGENTS.md for reusable patterns
4. Continue from first pending story

The loop is stateless - all state is in files, not memory.

Cross-Session Learnings

progress.txt serves as persistent memory:

• Patterns discovered in iteration 1 inform iteration 5
• Gotchas are avoided in future stories
• File locations are remembered

Always read progress.txt before implementing each story.

Critical Success Factors

1. Small Stories

Must fit in one context window.

❌ Too big: "Build entire auth system"
✅ Right size: "Add login form", "Add email validation", "Add auth server action"

2. Feedback Loops

Ralph needs fast feedback:

• npm run check (typecheck)
• npm run lint
• npm run test

Without these, broken code compounds.

3. Explicit Criteria

❌ Vague: "Users can log in"
✅ Explicit:
- Email/password fields
- Validates email format
- Shows error on failure
- typecheck passes
- Verify at localhost:3000/login

4. Learnings Compound

By story 10, Ralph knows patterns from stories 1-9.

5. CI Must Stay Green

Quality gates prevent error compounding across iterations.

Common Gotchas

Idempotent migrations:

ADD COLUMN IF NOT EXISTS email TEXT;

Interactive prompts:

echo -e "\n\n\n" | npm run db:generate

Schema changes: After editing schema, check: Server actions, UI components, API routes

Fixing related files is OK: If typecheck requires other changes, make them. Not scope creep.

Monitoring Progress

# Story status
cat .ralph/prd.json | jq '.userStories[] | {id, title, status}'

# Learnings
cat .ralph/progress.txt

# Recent commits
git log --oneline -10

When NOT to Use Ralph

• Exploratory work
• Major refactors without criteria
• Security-critical code
• Anything needing human review

Configuration Options

prd.json Config Block

"config": {
  "maxIterations": 10,        // Total iterations before stopping
  "maxFailuresPerStory": 3,   // Attempts before blocking
  "autoCommit": true          // Commit after each story
}

Quality Gate Customization

"qualityGates": {
  "typecheck": "npm run check",
  "lint": "npm run lint",
  "test": "npm run test",
  "build": null  // Set to null to skip
}

Stop Condition

If ALL stories have status: "passed" or status: "blocked", report completion.

Otherwise, continue to next pending story.