A design framework for AI agent loops built on three questions — when should it run (schedule), what does done mean (goal), and who does the isolated pieces (subagents) — with worked examples in Claude Code and Codex.
Design framework: choose schedule (when), goal (what done means), subagents (who does isolated pieces) — with worked examples in Claude Code and Codex.
Guardrails: Stop when the goal is verifiably met, or stop after 15 iterations, whichever comes first. Verify each pass by running the relevant tests or checks — self-reported success does not count. Keep changes minimal and never touch files outside the task’s scope.
claude-code
Implementation note
When to use: before building any nontrivial loop — this is a design framework, not a runnable loop, and it exists because most loop failures are design failures: fuzzy done conditions, wrong triggers, monolithic tasks. How it works: three questions structure the design. When should it run — that is the schedule. What does done mean — that is the goal, which must be concrete and checkable. Who does the isolated pieces — those are subagents, each taking a bounded slice of the work with its own context. The framework ships with worked examples in both Claude Code and Codex showing the questions applied to real automations. Safety: the discipline itself is the safety value — a loop with an explicit machine-checkable done condition and decomposed responsibilities is far less likely to run away than a vibes-based one. Whatever design emerges, still add the runtime rails: iteration caps, budgets, and review gates on anything that mutates.
Hardened 2026-07-27: explicit stop/cap/verification guardrails appended; regraded D→A.
Run a multi-stage software factory pipeline where each agent handles one task in a fresh context, anchored to mechanical gates and held-out test suites.
# AGENTS.md — read this first This is Software Bodega , a software factory: a pipeline that turns an idea into verified code with one human touch per stage. Where state lives — on disk, never in chat history: - factory/STATE.md — current stage + pointer. Single source of truth. - factory/BRIEF.md BLUEPRINT.md CONTRACT.md HANDOFF.md REVIEW.md GUIDE.md - factory/.planning/{spec,decompose,plan}.json — machine-checked artifacts - factory/.planning/gate-results/ — <gate>-<sha>.json verdicts - factory/tasks/ .md — one file per task - factory/progress.md factory/log.md — append-only diaries. Never rewrite. Rules that do not bend: 1. One agent per station. One task per fresh context window. No multi-agent chat. 2. Every gate anchors to something mechanical. LLM judges are fallbacks and must be a different model FAMILY than the author. 3. factory/tests/heldout/ is held out . Never read it, never reference it, never write to it. If you can see it, that is a bug — report it. 4. Repair loops cap at 2. Then resample N=3. Then PARK. Never loop forever. 5. Never weaken a test to make it pass. Never edit CONTRACT.md — it is signed. 6. git add
A graduated path to unattended Ralph runs: start with a single bounded task, add a PROMPT.md spec file, add verification, and only then remove the human from the loop for overnight builds.
Staged path from basic prompt → PROMPT.md spec → overnight Ralph run: start with a single bounded task, add a spec file, add verification, only then remove the human from the loop. Cap the run at 25 iterations; leave remaining work for the next session.
Turn the open issue backlog into a proposed two-week sprint plan with estimates, a dependency ordering, and an explicit cut line, written as a document for the team to edit.
/goal SPRINT-PLAN.md contains a proposed 2-week plan — read all open issues labeled `ready`, estimate each as S/M/L based on the code it touches, order them by dependency and value, draw a cut line at a realistic capacity, and list what falls below it with reasons; make no changes to the issues themselves; stop after 6 turns