Ralph Orchestrator

Build structured, scaffolded prompts for Ralph loops that maximize success rates through:

• •Progress tracking: Persistent learnings that survive iterations
• •Context health: When to commit, summarize, or archive
• •TDD workflow: Test-first development patterns
• •Escape hatches: Recovery when stuck
• •Verification: Automatic and manual verification steps

Core Concept

Ralph loops succeed when Claude has:

1. •Clear completion criteria - Unambiguous signal for when to output the completion promise
2. •Progress visibility - Ability to see what worked/failed in previous iterations
3. •Incremental goals - Small, achievable steps that build momentum
4. •Recovery paths - What to do when stuck

This skill builds prompts that embed all these elements.

How Ralph Works

The official ralph-loop plugin creates a self-referential feedback loop:

1. •Your prompt is fed to Claude
2. •Claude works on the task
3. •Claude tries to exit
4. •Stop hook intercepts exit and re-feeds the SAME prompt
5. •Repeat until completion promise is detected or max iterations reached

Key insight: The prompt never changes between iterations. Claude's "memory" comes from:

• •Files on disk (progress.md, AGENTS.md, prd.json, your code)
• •Git history
• •Test results

This skill builds prompts that leverage these persistence mechanisms.

Workflow

Phase 1: Understand the Input

Determine input mode from the invocation context:

PRD Mode (if .claude/ralph/<task-name>/prd.json exists):

• •Read the prd.json file
• •Extract stories, success criteria, verification method
• •Extract integrations array (if present) for available tools
• •Identify which stories are already passing ("passes": true)
• •Determine next story to work on
• •Completion promise: <promise>ALL STORIES PASS</promise>

Plan Mode (if .claude/ralph/<task-name>/plan.json exists):

• •Read the plan.json file
• •Extract phases, goal, success criteria, verification method
• •Extract integrations array (if present) for available tools
• •Identify which phases are already complete ("complete": true)
• •Determine next phase to work on
• •Completion promise: <promise>ALL PHASES COMPLETE</promise>

Raw Freeform Mode (if neither PRD nor plan exists):

• •Parse the provided prompt text
• •Infer success criteria from the description
• •Create implicit single-phase structure
• •Completion promise: <promise>TASK COMPLETE</promise>

Phase 2: Initialize Working Files

Ensure working files exist in .claude/ralph/<task-name>/:

progress.md - Create from template if not exists:

• •Read assets/templates/progress_template.md
• •Fill in task name, timestamp, mode, first story ID
• •Write to .claude/ralph/<task-name>/progress.md

AGENTS.md - Create from template if not exists:

• •Read assets/templates/agents_template.md
• •Fill in task name, timestamp, problem statement
• •Write to .claude/ralph/<task-name>/AGENTS.md

Phase 3: Build the Master Prompt

The master prompt is fed to Claude each iteration. It must be:

• •Self-contained: All necessary context included
• •State-aware: References progress files Claude should read
• •Action-oriented: Clear next steps
• •Bounded: Knows when to stop

Load and populate the appropriate template based on mode:

For Plan Mode, also check task_type in plan.json:

• •"implementation" (default): Use TDD workflow sections
• •"documentation": Use Research/Writing workflow sections
• •"investigation": Use Investigation workflow sections

The templates use Handlebars-style placeholders ({{variable}}, {{#each}}, {{#if}}) that should be replaced with actual values from the JSON files.

Phase 4: Return the Built Prompt

Output the complete master prompt ready for the /ralph command:

Master prompt built for Ralph loop.

**Summary**:
- Task: <task-name>
- Mode: <prd|plan|freeform>
- Stories/Phases: <count> (<passing/complete> done, <blocked> blocked)
- Current focus: <first incomplete item>
- Completion promise: "<promise>"

**Working files**:
- .claude/ralph/<task-name>/progress.md
- .claude/ralph/<task-name>/AGENTS.md
- .claude/ralph/<task-name>/prd.json or plan.json
- ./CLAUDE.md (project root - for project-wide patterns)

Ready to invoke ralph-loop with this prompt.

Key Principles

1. The Prompt is the Contract

Everything Claude needs to succeed must be in the prompt. The prompt is fed fresh each iteration - Claude doesn't remember previous iterations except through:

• •Files on disk (progress.md, AGENTS.md, prd.json, code files)
• •Git history
• •Test results

2. Progress Files are Memory

Since Ralph loops re-feed the same prompt, persistent files are how Claude "remembers":

• •progress.md: Append-only learnings, current state, iteration history
• •AGENTS.md: Task-specific patterns and architectural decisions
• •CLAUDE.md: Project-wide conventions (promoted from AGENTS.md)
• •prd.json/plan.json: Story/phase completion status

3. Small Stories Beat Big Stories

Stories should be completable in 1-3 iterations. If a story takes more than 5 iterations:

• •It's too big - should have been broken down
• •There's a blocker - use escape hatch

4. Verification is Essential

Every story must have a verification method. Without it, Claude can't objectively know when it's done. Prefer automated verification (tests, type checks) over manual.

5. Escape Hatches Prevent Infinite Loops

When stuck, Claude should:

1. •Document the issue thoroughly
2. •Try an alternative approach
3. •Mark as blocked and move on
4. •NEVER lie about completion

References

Load these for detailed guidance:

• •references/prompt-patterns.md - Best practices for prompt writing
• •references/story-sizing.md - How to size user stories for Ralph
• •references/escape-hatches.md - Detailed recovery patterns

Integration with ralph-loop

This skill builds the prompt; the actual looping is handled by the official ralph-loop plugin:

/ralph-loop "<master-prompt>" --max-iterations <N> --completion-promise "<promise>"

The stop hook in ralph-loop:

• •Intercepts Claude's exit attempts
• •Re-feeds the same prompt
• •Detects completion promise to exit loop
• •Respects max-iterations limit

Our progress.md, AGENTS.md, and prd.json/plan.json provide the persistent context that makes each iteration productive.