The Ralph Playbook

December 2025 boiled Ralph's powerful yet dumb little face to the top of most AI-related timelines.

I try to pay attention to the crazy-smart insights @GeoffreyHuntley shares, but I can't say Ralph really clicked for me this summer. Now, all of the recent hubbub has made it hard to ignore.

@mattpocockuk and @ryancarson's overviews helped a lot - right until Geoff came in and said 'nah'.

<img src="references/nah.png" alt="nah" width="500" />

So what is the optimal way to Ralph?

Many folks seem to be getting good results with various shapes - but I wanted to read the tea leaves as closely as possible from the person who not only captured this approach but also has had the most ass-time in the seat putting it through its paces.

So I dug in to really RTFM on recent videos and Geoff's original post to try and untangle for myself what works best.

Below is the result - a (likely OCD-fueled) Ralph Playbook that organizes the miscellaneous details for putting this all into practice w/o hopefully neutering it in the process.

Digging into all of this has also brought to mind some possibly valuable additional enhancements to the core approach that aim to stay aligned with the guidelines that make Ralph work so well.

[!TIP] View as 📖 Formatted Guide →

Hope this helps you out - @ClaytonFarr

---

Table of Contents

• Workflow
• Key Principles
• Loop Mechanics
• License
• Files
• Enhancements?

---

Workflow

A picture is worth a thousand tweets and an hour-long video. Geoff's overview here (sign up to his newsletter to see full article) really helped clarify the workflow details for moving from 1) idea → 2) individual JTBD-aligned specs → 3) comprehensive implementation plan → 4) Ralph work loops.

🗘 Three Phases, Two Prompts, One Loop

This diagram clarified for me that Ralph isn't just "a loop that codes." It's a funnel with 3 Phases, 2 Prompts, and 1 Loop.

Phase 1. Define Requirements (LLM conversation)

• Discuss project ideas → identify Jobs to Be Done (JTBD)
• Break individual JTBD into topic(s) of concern
• Use subagents to load info from URLs into context
• LLM understands JTBD topic of concern: subagent writes specs/FILENAME.md for each topic

Phase 2 / 3. Run Ralph Loop (two modes, swap PROMPT.md as needed)

Same loop mechanism, different prompts for different objectives:

Prompt differences per mode:

• 'PLANNING' prompt does gap analysis (specs vs code) and outputs a prioritized TODO list—no implementation, no commits.
• 'BUILDING' prompt assumes plan exists, picks tasks from it, implements, runs tests (backpressure), commits.

Why use the loop for both modes?

• BUILDING requires it: inherently iterative (many tasks × fresh context = isolation)
• PLANNING uses it for consistency: same execution model, though often completes in 1-2 iterations
• Flexibility: if plan needs refinement, loop allows multiple passes reading its own output
• Simplicity: one mechanism for everything; clean file I/O; easy stop/restart

Context loaded each iteration: PROMPT.md + AGENTS.md

PLANNING mode loop lifecycle:

1. Subagents study specs/* and existing /src
2. Compare specs against code (gap analysis)
3. Create/update IMPLEMENTATION_PLAN.md with prioritized tasks
4. No implementation

BUILDING mode loop lifecycle:

1. Orient – subagents study specs/* (requirements)
2. Read plan – study IMPLEMENTATION_PLAN.md
3. Select – pick the most important task
4. Investigate – subagents study relevant /src ("don't assume not implemented")
5. Implement – N subagents for file operations
6. Validate – 1 subagent for build/tests (backpressure)
7. Update IMPLEMENTATION_PLAN.md – mark task done, note discoveries/bugs
8. Update AGENTS.md – if operational learnings
9. Commit
10. Loop ends → context cleared → next iteration starts fresh

Concepts

Relationships:

• 1 JTBD → multiple topics of concern
• 1 topic of concern → 1 spec
• 1 spec → multiple tasks (specs are larger than tasks)

Example:

• JTBD: "Help designers create mood boards"
• Topics: image collection, color extraction, layout, sharing
• Each topic → one spec file
• Each spec → many tasks in implementation plan

Topic Scope Test: "One Sentence Without 'And'"

• Can you describe the topic of concern in one sentence without conjoining unrelated capabilities?
  • ✓ "The color extraction system analyzes images to identify dominant colors"
  • ✗ "The user system handles authentication, profiles, and billing" → 3 topics
• If you need "and" to describe what it does, it's probably multiple topics

---

Key Principles

⏳ Context Is Everything

• When 200K+ tokens advertised = ~176K truly usable
• And 40-60% context utilization for "smart zone"
• Tight tasks + 1 task per loop = 100% smart zone context utilization

This informs and drives everything else:

• Use the main agent/context as a scheduler
  • Don't allocate expensive work to main context; spawn subagents whenever possible instead
• Use subagents as memory extension
  • Each subagent gets ~156kb that's garbage collected
  • Fan out to avoid polluting main context
• Simplicity and brevity win
  • Applies to number of parts in system, loop config, and content
  • Verbose inputs degrade determinism
• Prefer Markdown over JSON
  • To define and track work, for better token efficiency

🧭 Steering Ralph: Patterns + Backpressure

Creating the right signals & gates to steer Ralph's successful output is critical. You can steer from two directions:

• Steer upstream
  • Ensure deterministic setup:
    • Allocate first ~5,000 tokens for specs
    • Every loop's context is allocated with the same files so model starts from known state (PROMPT.md + AGENTS.md)
  • Your existing code shapes what gets used and generated
  • If Ralph is generating wrong patterns, add/update utilities and existing code patterns to steer it toward correct ones
• Steer downstream
  • Create backpressure via tests, typechecks, lints, builds, etc. that will reject invalid/unacceptable work
  • Prompt says "run tests" generically. AGENTS.md specifies actual commands to make backpressure project-specific
  • Backpressure can extend beyond code validation: some acceptance criteria resist programmatic checks - creative quality, aesthetics, UX feel. LLM-as-judge tests can provide backpressure for subjective criteria with binary pass/fail. (More detailed thoughts below on how to approach this with Ralph.)
• Remind Ralph to create/use backpressure
  • Remind Ralph to use backpressure when implementing: "Important: When authoring documentation, capture the why — tests and implementation importance."

🙏 Let Ralph Ralph

Ralph's effectiveness comes from how much you trust it do the right thing (eventually) and engender its ability to do so.

• Let Ralph Ralph
  • Lean into LLM's ability to self-identify, self-correct and self-improve
  • Applies to implementation plan, task definition and prioritization
  • Eventual consistency achieved through iteration
• Use protection
  • To operate autonomously, Ralph requires --dangerously-skip-permissions - asking for approval on every tool call would break the loop. This bypasses Claude's permission system entirely - so a sandbox becomes your only security boundary.
  • Philosophy: "It's not if it gets popped, it's when. And what is the blast radius?"
  • Running without a sandbox exposes credentials, browser cookies, SSH keys, and access tokens on your machine
  • Run in isolated environments with minimum viable access:
    • Only the API keys and deploy keys needed for the task
    • No access to private data beyond requirements
    • Restrict network connectivity where possible
  • Options: Docker sandboxes (local), Fly Sprites/E2B/etc. (remote/production) - additional notes
  • Additional escape hatches: Ctrl+C stops the loop; git reset --hard reverts uncommitted changes; regenerate plan if trajectory goes wrong

🚦 Move Outside the Loop

To get the most out of Ralph, you need to get out of his way. Ralph should be doing all of the work, including decided which planned work to implement next and how to implement it. Your job is now to sit on the loop, not in it - to engineer the setup and environment that will allow Ralph to succeed.

Observe and course correct – especially early on, sit and watch. What patterns emerge? Where does Ralph go wrong? What signs does he need? The prompts you start with won't be the prompts you end with - they evolve through observed failure patterns.

Tune it like a guitar – instead of prescribing everything upfront, observe and adjust reactively. When Ralph fails a specific way, add a sign to help him next time.

But signs aren't just prompt text. They're anything Ralph can discover:

• Prompt guardrails - explicit instructions like "don't assume not implemented"
• AGENTS.md - operational learnings about how to build/test
• Utilities in your codebase - when you add a pattern, Ralph discovers it and follows it
• Other discoverable, relevant inputs…

[!TIP]

1. try starting with nothing in AGENTS.md (empty file; no best practices, etc.)
2. spot-test desired actions, find missteps (walkthrough example from Geoff)
3. watch initial loops, see where gaps occur
4. tune behavior only as needed, via AGENTS updates and/or code patterns (shared utilities, etc.)

And remember, the plan is disposable:

• If it's wrong, throw it out, and start over
• Regeneration cost is one Planning loop; cheap compared to Ralph going in circles
• Regenerate when:
  • Ralph is going off track (implementing wrong things, duplicating work)
  • Plan feels stale or doesn't match current state
  • Too much clutter from completed items
  • You've made significant spec changes
  • You're confused about what's actually done

---

Loop Mechanics

I. Task Selection

loop.sh acts in effect as an 'outer loop' where each loop = a single task (in separate sessions). When the task is completed, loop.sh kicks off a fresh session to select the next task, if any remaining tasks are available.

Geoff's initial minimal form of loop.sh script:

while :; do cat PROMPT.md | claude ; done

Note: The same approach can be used with other CLIs; e.g. amp, codex, opencode, etc.

What controls task continuation?

The continuation mechanism is elegantly simple:

1. Bash loop runs → feeds PROMPT.md to claude
2. PROMPT.md instructs → "Study IMPLEMENTATION_PLAN.md and choose the most important thing..."
3. Agent completes one task → updates IMPLEMENTATION_PLAN.md on disk, commits, exits
4. Bash loop restarts immediately → fresh context window
5. Agent reads updated plan → picks next most important thing...

Key insight: The IMPLEMENTATION_PLAN.md file persists on disk between iterations and acts as shared state between otherwise isolated loop executions. Each iteration deterministically loads the same files (PROMPT.md + AGENTS.md + specs/*) and reads the current state from disk.

No sophisticated orchestration needed - just a dumb bash loop that keeps restarting the agent, and the agent figures out what to do next by reading the plan file each time.

II. Task Execution

Each task is prompted to keep doing its work against backpressure (tests, etc) until it passes - creating a pseudo inner 'loop' (in single session).

This inner loop is just internal self-correction / iterative reasoning within one long model response, powered by backpressure prompts, tool use, and subagents. It's not a loop in the programming sense.

A single task execution has no hard technical limit. Control relies on:

• Scope discipline - PROMPT.md instructs "one task" and "commit when tests pass"
• Backpressure - tests/build failures force the agent to fix issues before committing
• Natural completion - agent exits after successful commit

Ralph can go in circles, ignore instructions, or take wrong directions - this is expected and part of the tuning process. When Ralph "tests you" by failing in specific ways, you add guardrails to the prompt or adjust backpressure mechanisms. The nondeterminism is manageable through observation and iteration.

Enhanced loop.sh Example

Wraps core loop with mode selection (plan/build), with max-iterations for max number of tasks to complete, and git push after each iteration.

This enhancement uses two saved prompt files:

• PROMPT_plan.md - Planning mode (gap analysis, generates/updates plan)
• PROMPT_build.md - Building mode (implements from plan)

#!/bin/bash
# Usage: ./loop.sh [plan|build] [max_iterations]
# Examples:
#   ./loop.sh              # Build mode, unlimited tasks
#   ./loop.sh 20           # Build mode, max 20 tasks
#   ./loop.sh build 20     # Build mode, max 20 tasks
#   ./loop.sh plan         # Plan mode, unlimited tasks
#   ./loop.sh plan 5       # Plan mode, max 5 tasks

# Parse arguments
if [ "$1" = "plan" ]; then
    # Plan mode
    MODE="plan"
    PROMPT_FILE="PROMPT_plan.md"
    MAX_ITERATIONS=${2:-0}
elif [ "$1" = "build" ]; then
    # Explicit build mode (with optional max iterations)
    MODE="build"
    PROMPT_FILE="PROMPT_build.md"
    MAX_ITERATIO