Ralph Loop Patterns

Python hat-based execution loops — Ralph orchestrator pattern reference.

Live site: withagents.dev/posts/post-08-ralph-loop Field journal entry: withagents.dev/posts/post-08-ralph-loop

---

Single-responsibility hat rotation patterns for builder, writer, and reviewer agent loops. Each agent wears exactly one hat per iteration, with quality gates between rotations and convergence detection.

Quick Start

pip install -e .
ralph-loop patterns
ralph-loop simulate "Build REST API for blog posts" --pattern builder-writer-reviewer
ralph-loop simulate "Implement auth" --pattern full-cycle --max-iterations 5

Architecture

graph TD
    A[Task] --> B[Iteration 1]
    B --> C[Builder Hat]
    C --> D[Writer Hat]
    D --> E[Reviewer Hat]
    E --> F{Issues Found?}
    F -->|Yes| G[Iteration 2]
    G --> C
    F -->|No| H[Converged]

Loading

Usage

from ralph_loop_patterns.core import RalphLoop, Hat, HatOutput, BUILDER_WRITER_REVIEWER

loop = RalphLoop(pattern=BUILDER_WRITER_REVIEWER, task_description="Build API")
loop.start_iteration()

for hat in [Hat.BUILDER, Hat.WRITER, Hat.REVIEWER]:
    prompt = loop.get_hat_prompt(hat)
    # ... agent executes with prompt ...
    loop.submit_hat_output(HatOutput(hat=hat, content="..."))

Available Patterns

Pattern	Hats
builder-writer-reviewer	Builder -> Writer -> Reviewer
plan-build-review	Planner -> Builder -> Reviewer
build-review-refactor	Builder -> Reviewer -> Refactorer
full-cycle	Planner -> Builder -> Writer -> Reviewer -> Verifier

Part of Agentic Development Series

Post 56 of "Agentic Development: 21 Lessons from 8,481 AI Coding Sessions" by Nick Krzemienski.