--- title: "The Ralph Playbook" description: "December 2025 boiled [Ralph's](https://ghuntley.com/ralph/) powerful yet dumb little face to the top of most AI-related timelines." type: skill canonical_url: https://claudary.paisolsolutions.com/skills/readme-584 source: "Claudary" difficulty: intermediate author: "Claude Code Knowledge Pack" date: 2026-07-10T11:36:42.116Z license: CC-BY-4.0 attribution: "The Ralph Playbook β€” Claudary (https://claudary.paisolsolutions.com/skills/readme-584)" --- # The Ralph Playbook December 2025 boiled [Ralph's](https://ghuntley.com/ralph/) powerful yet dumb little face to the top of most AI-related timelines. ## Overview # The Ralph Playbook December 2025 boiled [Ralph's](https://ghuntley.com/ralph/) powerful yet dumb little face to the top of most AI-related timelines. I try to pay attention to the crazy-smart insights [@GeoffreyHuntley](https://x.com/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](https://x.com/mattpocockuk/status/2008200878633931247) and [@ryancarson](https://x.com/ryancarson/status/2008548371712135632)'s overviews helped a lot - right until Geoff came in and [said 'nah'](https://x.com/GeoffreyHuntley/status/2008731415312236984). nah ## 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](https://www.youtube.com/watch?v=O2bBWDoxO4s) and Geoff's [original post](https://ghuntley.com/ralph/) 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](#enhancements) to the core approach that aim to stay aligned with the guidelines that make Ralph work so well. > [!TIP] > View as [πŸ“– Formatted Guide β†’](https://ClaytonFarr.github.io/ralph-playbook/) Hope this helps you out - [@ClaytonFarr](https://x.com/ClaytonFarr) --- ## Table of Contents - [Workflow](#workflow) - [Key Principles](#key-principles) - [Loop Mechanics](#loop-mechanics) - [License](#license) - [Files](#files) - [Enhancements?](#enhancements) --- ## Workflow A picture is worth a thousand tweets and an hour-long video. Geoff's [overview here](https://ghuntley.com/ralph/) (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. ![ralph-diagram.png](references/ralph-diagram.png) ### πŸ—˜ 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: | Mode | When to use | Prompt focus | | ---------- | -------------------------------------- | ------------------------------------------------------- | | _PLANNING_ | No plan exists, or plan is stale/wrong | Generate/update `IMPLEMENTATION_PLAN.md` only | | _BUILDING_ | Plan exists | Implement from plan, commit, update plan as side effect | _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 | Term | Definition | | ----------------------- | --------------------------------------------------------------- | | _Job to be Done (JTBD)_ | High-level user need or outcome | | _Topic of Concern_ | A distinct aspect/component within a JTBD | | _Spec_ | Requirements doc for one topic of concern (`specs/FILENAME.md`) | | _Task_ | Unit of work derived from comparing specs to code | _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](#non-deterministic-backpressure) 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](references/sandbox-environments.md) - 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](https://x.com/ClaytonFarr/status/2010780371542241508)) > 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: ```bash 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) ```bash #!/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 --- Source: [Claudary](https://claudary.paisolsolutions.com/skills/readme-584) Β· https://claudary.paisolsolutions.com