/orbit

Ralph Loop Pattern (Huntley-style autonomous loop)

Purpose: load this when generating, auditing, or hardening a nexus-autoloop runner that follows the Ralph Loop lineage (Geoffrey Huntley, 2025-07). Ralph Loop is one specific implementation philosophy within Orbit's broader autonomous-loop scope. When a goal explicitly invokes Ralph (ralph, PROMPT.md, <promise>COMPLETE</promise>, ghuntley-style scripts, cat PROMPT.md | claude shapes), prefer this pattern over generic loop templates.

Contents

1. Origin and core definition
2. Nine design principles
3. Two-mode pattern (plan / build)
4. 9xx guardrail numbering
5. AGENTS.md constraints
6. Subagent constraints
7. Plan disposability rule
8. Filesystem-as-Memory model
9. Termination conditions
10. Green-field-only constraint
11. Huntley's anti-pattern warnings
12. Adjacent best practices (non-default)
13. Quick reference
14. Multi-loop orchestration (Gas Town / Weaving Loom)

1. Origin and Core Definition

• Author: Geoffrey Huntley, "Ralph Wiggum as a 'software engineer'", published 2025-07-14. [Source: https://ghuntley.com/ralph/]
• Reference implementation: ghuntley/how-to-ralph-wiggum
• Subsequent evolution: everything is a ralph loop (2026-01-17, introduces "The Weaving Loom" — evolutionary multi-loop orchestration)
• Community lineage write-up: A Brief History of Ralph — HumanLayer

Core definition: A single immutable prompt file (PROMPT.md) is piped to a coding agent inside an unbounded while loop. The prompt does not change between iterations; only the on-disk artifacts (plan, spec, AGENTS.md, code, tests) change. The agent re-reads disk every iteration, picks the single most important next task, and implements it. Determinism comes from disk state, not from prompt evolution.

Minimal canonical form:

while :; do cat PROMPT.md | claude --dangerously-skip-permissions \
  --output-format=stream-json --model opus ; done

Ralph Loop is filesystem-as-memory plus fresh-context-per-iteration. This is the structural opposite of conversation-resend loops (/loop style), which replay full chat history every call and scale token cost linearly with iteration count.

2. Nine Design Principles

3. Two-Mode Pattern (plan / build)

The loop alternates between two distinct prompt files. Mode is selected by a small dispatcher (env var, marker file, or alternating iterations).

Switching rules:

• Start in plan until fix_plan.md has ≥ 1 prioritised item.
• Stay in build while fix_plan.md has unblocked items.
• Re-enter plan on CONVERGENCE_STALL, OSCILLATION_LOOP, or when fix_plan.md is exhausted but DONE gate is unmet.

4. 9xx Guardrail Numbering Convention

Critical rules in PROMPT.md are numbered 9xx (or 99x for absolutes). Larger number = harder constraint. The numbering acts as a salience anchor for the model.

Example (canonical Huntley):

901_LOOK_FOR_EXISTING_IMPLEMENTATIONS
902_TESTS_BEFORE_IMPLEMENTATION
910_NEVER_COMMIT_SECRETS
990_DO_NOT_IMPLEMENT_PLACEHOLDERS
995_DO_NOT_ASSUME_NOT_IMPLEMENTED
999_DO_NOT_EDIT_PROMPT_MD

Orbit-generated PROMPT.md must include at minimum:

• 990_DO_NOT_IMPLEMENT_PLACEHOLDERS (covers AP-12 Validator Gap)
• 995_DO_NOT_ASSUME_NOT_IMPLEMENTED (forces grep before claiming missing)
• 999_DO_NOT_EDIT_PROMPT_MD (covers RP-1 immutability)
• 998_DO_NOT_EDIT_GOAL_MD (covers AP-16 Goal Drift)
• 997_DO_NOT_EDIT_TESTS_OR_VERIFY (covers AP-13 Reward Hacking)
• 996_DO_NOT_EDIT_SETTINGS_JSON (covers AP-20 Permission Hijack, a P0 security event)

9xx rules are prompt-level salience; the upgraded run-loop.sh backstops them with hard enforcement — a prompt-rule violation also trips a runner ABORT, not just lowered salience:

The prompt rule reduces the probability of the action; the runner pin makes it non-completable. Generate both — neither alone is sufficient.

5. AGENTS.md Constraints

AGENTS.md is the agent-facing operations file. Strict rules:

• Maximum 60 lines. Hard cap. If it grows past 60, audit for status leakage.
• Operational content only: how to build, test, run, format, lint.
• No progress notes, no decisions, no history. Those belong in IMPLEMENTATION_PLAN.md and progress.md.
• No prose explanation. Imperative form: npm test, not "we use jest to run tests".
• Pin sha256 at loop start and warn (not abort) on changes — AGENTS.md may legitimately evolve but contamination is the most common Ralph failure.

[Source: https://ghuntley.com/ralph/, https://www.humanlayer.dev/blog/brief-history-of-ralph]

6. Subagent Constraints

Never parallelise build or test in a Ralph Loop. Huntley's original warning: "unbounded parallelism collapses".

7. Plan Disposability Rule

The plan is a scratchpad, not a contract. When the agent detects any of the following, regenerate the plan instead of repairing it:

• Same top item in fix_plan.md for ≥ 3 consecutive build iterations (CONVERGENCE_STALL).
• A→B→A→B alternation in fix_plan.md (OSCILLATION_LOOP).
• An item references a file or symbol that no longer exists.
• An item depends on an assumption contradicted by current progress.md.

Runner backstop: the upgraded run-loop.sh writes a per-iteration change signature to .action-sig.log and stops the loop (CONVERGENCE_STALL) when CONVERGENCE_WINDOW (default 3) signatures are identical — a runner-level Witness even if the agent fails to self-detect plan fixation. On resume after plan regeneration, clear the counter with recover.sh --clear-stall so the fresh plan is not immediately re-flagged against stale signatures.

Regeneration steps:

1. Archive the current plan to IMPLEMENTATION_PLAN_archive_<ISO8601>.md (do not delete).
2. Re-enter plan mode.
3. Re-derive fix_plan.md from specs/ and current code state.
4. Run recover.sh --clear-stall to reset the convergence counter.
5. Continue.

8. Filesystem-as-Memory Model

[Source: https://intelligenttools.co/blog/claude-code-unsupervised-8-hours-ralph-loop, https://pageai.pro/blog/long-running-ai-coding-agents-ralph-loop, https://x.com/amaanbuilds/status/2050561260782297336 (HTTP 429 — cited via secondary aggregation)]

Rule: Orbit-generated runners must use filesystem-as-memory. Never use conversation-resend models for MAX_ITERATIONS ≥ 20.

9. Termination Conditions

Ralph Loop is unbounded by construction. Termination must be enforced externally. Acceptable terminators:

TOKEN_BUDGET is a soft alert threshold only ([COST:WARN] at 0.8×, [COST:BLOCKED] at 1.0×); it is not a hard terminator. Use USD_PER_RUN_CAP (operation-contract v1.2.0 hard cap) for guaranteed budget termination.

[Source: https://github.com/snarktank/ralph]

Hard rule: Never rely on the agent's self-assessment alone. A Ralph Loop must have at least two runner-enforced terminators active (the <promise> sentinel does not count — it is agent-emitted). The ralph subcommand satisfies this by forcing MAX_ITERATIONS plus one of LOOP_TIMEOUT > 0 / USD_PER_RUN_CAP > 0 before generation (SKILL ralph Core-Defaults override).

10. Green-field-only Constraint

Huntley's strong claim: "There's no way in heck would I use Ralph in an existing code base." [Source: https://ghuntley.com/ralph/]

Operational rule for Orbit:

• During INTAKE, check whether the target directory has prior commits, a populated src/, or non-trivial dependency manifest.
• If yes → classify as brownfield. Refuse to generate a Ralph-style loop. Recommend Orbit's standard nexus-autoloop template (scoped, branch-isolated, evidence-gated) instead, which is safer for existing code.
• If no → green-field permitted. Generate Ralph-style runner.

Detection heuristic (any one triggers brownfield):

# Thresholds: >10 commits, >20 source files, >50 dependency-manifest entries → brownfield.
[[ $(git rev-list --count HEAD 2>/dev/null || echo 0) -gt 10 ]] \
 || [[ $(git ls-files -- '*.ts' '*.js' '*.py' '*.go' '*.rs' '*.java' 2>/dev/null | wc -l) -gt 20 ]] \
 || [[ -f package-lock.json && $(jq '.packages | length' package-lock.json) -gt 50 ]] \
 || [[ -f poetry.lock && $(grep -c '^\[\[package\]\]' poetry.lock) -gt 50 ]] \
 || [[ -f go.sum && $(wc -l < go.sum) -gt 50 ]] \
 || [[ -f Cargo.lock && $(grep -c '^\[\[package\]\]' Cargo.lock) -gt 50 ]]

If a user explicitly forces Ralph in a brownfield, log a warning, require RALPH_BROWNFIELD_ACK=true, and tighten guardrails: WORKTREE_ISOLATION=true, mandatory 997_DO_NOT_EDIT_TESTS_OR_VERIFY, mandatory rollback rehearsal.

11. Huntley's Anti-Pattern Warnings

These are warnings Huntley himself documents. Orbit must surface them when generating or auditing a Ralph-style loop.

12. Adjacent Best Practices (non-default, opt-in)

These are documented practices from 2025-2026 sources that complement Ralph but are not yet default in Orbit. Enable via env var or explicit goal directive.

BP-11 note: filesystem-as-memory (RP-7) protects across iterations (fresh context at each start) and CONTEXT_OVERFLOW/memory-pointer externalizes tool outputs > 1KB — neither protects a single long iteration that exhausts context within the iteration before reaching its commit/exit. Server-side compaction (Anthropic beta header anthropic-beta: compact-2026-01-12, default trigger 150K input tokens, min 50K; supported on claude-fable-5, claude-opus-5, claude-sonnet-5 and prior Opus/Sonnet generations — verified 2026-07-25) proactively summarizes the running conversation transcript and is the recommended strategy for task-oriented prompts with heavy follow-up tool use. It is complementary to, not a substitute for, RP-7 and memory-pointer. Gotchas: compaction costs an extra sampling step that counts against rate limits and billing, and with server tools the trigger is re-checked at the start of each sampling iteration — a single request can compact more than once. Monitor usage.iterations to see when it fires. Note: with Opus 5's 1M-token default context window, a loop iteration reaching a 150K trigger is no longer the common failure mode — raise the trigger or rely on RP-7 before adding compaction. [Source: https://platform.claude.com/docs/en/build-with-claude/compaction]

Orbit's three already-promoted defaults (BP-1 cache, BP-4 critic, BP-7 worktree) appear in SKILL.md and patterns.md, not here.

13. Quick Reference

Decision checklist before generating a Ralph runner:

• Goal directory is green-field (Section 10 heuristic passes).
• PROMPT.md, PROMPT_plan.md, PROMPT_build.md are planned distinct files (RP-2).
• AGENTS.md skeleton ≤ 60 lines (RP-4).
• At least two runner-enforced terminators configured — MAX_ITERATIONS plus LOOP_TIMEOUT > 0 and/or USD_PER_RUN_CAP > 0 (Section 9; the <promise> sentinel does not count).
• <promise>COMPLETE</promise> sentinel or equivalent included (convenience exit, not one of the two required terminators).
• 9xx critical rules cover placeholders, assume-missing, prompt-immutability, tests-immutability, goal-immutability, settings-immutability — each paired with its runner sha256/grep backstop (Section 4).
• Build/test subagent count is exactly 1 (RP-5).
• WORKTREE_ISOLATION=true and USD_PER_RUN_CAP > 0 (hard cap; TOKEN_BUDGET soft-alert is not sufficient alone).
• Plan disposability triggers wired to CONVERGENCE_STALL / OSCILLATION_LOOP (RP-6).
• User has acknowledged green-field constraint if running long unattended sessions.

Detection signals for a runner claiming to be Ralph but breaking the pattern:

14. Multi-Loop Orchestration (Gas Town / Weaving Loom)

RP-5's no-parallelism rule is intra-loop only (one build/test subagent inside a single loop). Inter-loop parallelism — a fleet of isolated single-task Ralph loops — is a distinct 2026 direction, permitted only when coordinated by a shared dependency-aware queue, a single merge-serializer, and per-loop worktree isolation. Two named reference designs:

• Gas Town (Steve Yegge): an orchestration layer (~Level 8 autonomy) running many worker loops against a shared queue. [Source: https://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04]
• The Weaving Loom (Geoffrey Huntley): "infrastructure for evolutionary software" (~Level 9 autonomy). [Source: https://ghuntley.com/loop/]

Gas Town mechanisms mapped to Orbit primitives:

Generating or auditing a Ralph fleet (vs. a single runner) requires, in addition to §13:

• a git-tracked dependency-aware task queue as the single source of work — never fan multiple loops directly onto one PRD;
• exactly one task claimed and completed per iteration, then stop (RP-9);
• a single merge-serializer to main, no parallel merges (Gas Town's Refinery);
• per-loop git worktree isolation;
• a health-watcher / stuck-detector (Gas Town's Witness ≈ Orbit's convergence / oscillation guards);
• idle exponential backoff.

Start simple: a bash loop + prompt file + queue beats a clever bespoke orchestrator; add complexity only when the queue proves insufficient. [Source: https://www.chrismdp.com/your-agent-orchestrator-is-too-clever/]

Cross-reference SKILL.md §Multi-Loop Rules and patterns.md parallel-loop coordination for the generic state.env / progress.md isolation primitives, stated here in Ralph terms. Prior art: mikeyobrien/ralph-orchestrator, snwfdhmp/awesome-ralph.

Weaving Loom (Level 9): Huntley frames it as infrastructure for evolutionary software — treat as opt-in / advanced. Reuse per-loop worktree isolation and the §9 two-independent-terminators rule for each loop in the fleet. [Source: https://ghuntley.com/loop/]