$ show ClaytonFarr/ralph-playbook
This repository is a comprehensive operational playbook for 'Ralph', Geoff Huntley's methodology for running Claude Code in an autonomous loop to build software. The core deliverable is a detailed guide (README.md plus a styled index.html mirror) explaining the three-phase workflow: define requirements as JTBD-aligned specs, generate an implementation plan via a planning loop, then run a building loop where Claude picks tasks from the plan, implements them, validates against tests, and commits — with a fresh context window per iteration. The guide is unusually well-structured, covering context management, backpressure via tests, sandbox security, and tuning strategies. Beyond documentation, the repo ships functional artifacts: two bash loop scripts (files/loop.sh, files/loop_streamed.sh) that orchestrate the Claude CLI, a dependency-free Node.js stream parser (files/parse_stream.js) for readable terminal output, and five prompt templates (PROMPT_build.md, PROMPT_plan.md, PROMPT_specs.md, PROMPT_reverse_engineer_specs.md) encoding the methodology's guardrails. It also documents sandbox environment options (E2B, Fly Sprites, Modal, Cloudflare, Docker) for safely running autonomous agents with --dangerously-skip-permissions. The prompt templates are the real product — they encode hard-won operational knowledge about context efficiency, subagent fan-out, and steering LLM behavior. Notable patterns include escalating 9s-numbered guardrails, explicit subagent limits (500 for search, 1 for build/tests), the 'one sentence without and' topic scoping test, and a two-phase reverse-engineering prompt that produces implementation-free behavioral specs. This is a documentation-first repo with a small but functional code footprint.
The LLM identified 4 files worth highlighting for reuse:
Dependency-free Node.js utility that parses Claude Code's stream-json output into readable, color-coded terminal output. Handles stream events, tool calls, results, errors, and final execution stats (duration, cost, tokens). Uses only Node.js built-ins (readline) and gracefully degrades on malformed input — could be extracted into any project using the Claude CLI with zero modification.
Production-grade prompt template for autonomous LLM coding loops. Demonstrates a notable guardrail pattern: escalating 9s numbering for critical invariants, explicit subagent fan-out limits (500 for search/read, 1 for build/tests), and backpressure-driven task completion ('run tests before commit'). Reusable as a template for any Claude Code autonomous build loop — copy into a project, adjust the spec paths, and it works.
Sophisticated prompt for reverse-engineering existing codebases into implementation-free behavioral specs. The two-phase process (Phase 1: exhaustive investigation with full code access; Phase 2: output with zero implementation details — no function names, file paths, or framework references) and the exhaustive pre-finalization checklist are genuinely reusable patterns for documenting brownfield systems. The 'bugs are features' rule (document reality, not intent) is a sharp insight for spec generation.
Minimal but effective orchestration script for the Ralph loop: pipes a prompt file to Claude CLI headless mode, pushes changes after each iteration, and supports plan/build modes with iteration limits. Demonstrates the file-based shared state pattern — IMPLEMENTATION_PLAN.md persists on disk between isolated context windows, acting as the coordination mechanism between otherwise stateless LLM sessions. Simple enough to fork and adapt to any CLI-based agent.