Ralph: Autonomous AI Development Loop

Execute the complete Ralph workflow: generate a PRD with user stories, then autonomously implement them one at a time with quality gates, commits, and learning persistence.

Invocation

/ralph <requirements> [options]

Arguments:

• <requirements> - Feature description (inline text, file path, or URL)
• --branch NAME - Branch name (default: auto-generated with ralph/ prefix)
• --max-stories N - Maximum stories to generate (default: 10)
• --max-iterations N - Maximum iterations to run (default: from prd.json or 10)

Examples:

/ralph "Build a user authentication system with login and registration"
/ralph ./requirements.md --branch ralph/auth-system
/ralph "Add dark mode toggle" --max-stories 5 --max-iterations 10

Execution Flow

This skill orchestrates two phases sequentially:

Phase 1: Planning (via /ralph-plan)

1. Gather Requirements - Parse input (file, URL, or inline text)
2. Analyze Codebase - Understand existing patterns and structure
3. Ask Clarifying Questions - 3-5 questions to refine scope
4. Generate PRD - Create atomic, testable user stories
5. Initialize Tracking - Create .ralph/prd.json and .ralph/progress.txt
6. Create Branch - Set up feature branch

Phase 2: Execution (via /ralph-execute)

1. Load Context - Read PRD, progress, and AGENTS.md
2. Select Story - Pick highest-priority pending story
3. Implement - Code the story following existing patterns
4. Quality Gates - Run typecheck, lint, test, build
5. Commit - Git commit on success
6. Learn - Update progress.txt with learnings
7. Loop - Continue until all stories complete or blocked

How It Works

┌─────────────────────────────────────────────────────────────┐
│                        /ralph                                │
│                                                              │
│  ┌──────────────┐          ┌──────────────────────────────┐ │
│  │  /ralph-plan │ ───────▶ │       /ralph-execute         │ │
│  │              │          │                              │ │
│  │ • Questions  │          │ ┌──────────────────────────┐ │ │
│  │ • PRD gen    │          │ │ Story 1 → Gates → Commit │ │ │
│  │ • Branch     │          │ │ Story 2 → Gates → Commit │ │ │
│  └──────────────┘          │ │ Story 3 → Gates → Commit │ │ │
│                            │ │ ...                      │ │ │
│                            │ └──────────────────────────┘ │ │
│                            └──────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Detailed Steps

Step 1: Invoke /ralph-plan

First, use the Skill tool to invoke /ralph-plan with the user's requirements:

Skill: ralph-plan
Args: <requirements> [--branch NAME] [--max-stories N]

This will:

• Ask clarifying questions
• Generate .ralph/prd.json with user stories
• Initialize .ralph/progress.txt
• Create/switch to feature branch

Wait for planning to complete before proceeding.

Step 2: Confirm with User

After planning completes, present the summary:

RALPH PLANNING COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━

Project: [Name]
Branch: [branch-name]
Stories: [N] user stories

Ready to begin autonomous implementation.

Proceed with /ralph-execute?

Use AskUserQuestion with options:

• Yes, start execution - Continue to Phase 2
• Review PRD first - Show story details
• Stop here - Exit without executing

Step 3: Invoke /ralph-execute

If user confirms, use the Skill tool to invoke /ralph-execute:

Skill: ralph-execute
Args: [--max-iterations N]

This will autonomously:

• Implement stories one at a time
• Run quality gates
• Commit on success
• Log learnings
• Continue until done

Step 4: Report Completion

After execution completes, summarize:

RALPH COMPLETE
━━━━━━━━━━━━━━

All [N] stories processed!

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

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

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

Error Handling

When to Use /ralph vs Individual Skills

Output Files

After successful execution:

1. .ralph/prd.json - PRD with story status
2. .ralph/progress.txt - Learnings and history
3. AGENTS.md - Updated with reusable patterns
4. Git commits for each completed story

Credits

Original Ralph by @GeoffreyHuntley