| name | loop-engineering |
| description | Design and run autonomous Claude Code loops safely — the 5-component pattern (Discovery, Handoff, Verification, Persistence, Scheduling), exit gates, budget caps, and guardrails. Use when setting up /loop, /schedule routines, overnight agents, ralph loops, or any recurring self-directed run. |
Loop Engineering
From prompting to looping: instead of prompting the model, you build a loop that prompts it. "I don't prompt Claude anymore. I have loops running that prompt Claude." (Boris Cherny). A loop is by design a machine that makes the number of turns large — every design decision below exists to shorten the distance between "mistake happens" and "someone sees it".
Companion skills: fable-mindset (how each iteration should think), orchestration (how to fan work across agents); this skill covers how the harness around iterations is built.
The 5 Components
Every production loop needs all five. A loop missing one is a demo, not a system.
1. Discovery — the loop finds its own work
Work comes from a queue the loop reads, never from a human typing a prompt: CI failures, open issues, TODO files, incoming commits, a backlog markdown.
- Claude Code: a
SKILL.md or LOOP.md freezes project context so every iteration starts from the same ground truth.
- The discovery source must be finite per iteration (e.g. "pick the top unclaimed item"), or the loop thrashes.
2. Handoff — isolate each unit of work
One git worktree per agent/iteration: separate branch + separate filesystem, zero collisions between parallel workers.
- Claude Code:
Agent(..., isolation: "worktree"), EnterWorktree, or workflow agents with isolation: 'worktree'.
- Never let two loop iterations write the same checkout.
3. Verification — a separate evaluator, always
"The agent that generated the change should not grade its own homework." A distinct agent (or hook, or CI job) checks tests, diffs, requirements, and failure modes before the result is accepted.
- Claude Code: a custom verifier subagent (
~/.claude/agents/verifier.md), a SubagentStop hook with exit-code 2 blocking, or /verify.
- The verifier must be cheaper and more reliable than the action it verifies — otherwise the loop just produces wrong answers faster.
- A fresh-context verifier beats self-critique: the generator re-reading its own work inherits its own blind spots.
4. Persistence — state on disk, never in context
The model forgets everything between runs. All loop state lives in files: STATE.md, a PR description, a DB row. Each iteration reads state, acts, writes state back.
- Claude Code: auto-memory dir, project
STATE.md, task files, PR bodies via gh.
- If an iteration learns something, it isn't learned until it's written to disk.
5. Scheduling — a timer or event triggers repetition
Cron, webhook, or interval — not a human pressing enter.
- Claude Code local:
/loop 5m <prompt> (interval) or /loop <prompt> (self-paced via ScheduleWakeup).
- Claude Code cloud: Routines (
/schedule daily PR review at 9am, managed at claude.ai/code/routines) — runs without the laptop open; triggers: cron / API / GitHub events.
- Set caps (max turns, max tokens, max calls/hour) before launch, never after.
Exit & Safety Patterns
- Dual exit gate: stop only when BOTH a natural-language completion heuristic (≥2 independent "done" indicators) AND an explicit signal (
EXIT_SIGNAL: true written by the agent) agree. Exact string-match alone (--completion-promise) is less reliable than a hard iteration cap — always keep the cap.
- Circuit breaker: 3 iterations without measurable progress, or 5 iterations hitting the same error → pause the loop (e.g. 30 min) and surface to the human. Never retry-forever.
- Budget caps first: max iterations, max tokens, tool whitelist (
ALLOWED_TOOLS-style) defined before the first run.
- Human gate — non-negotiable: merge, deploy, delete, close-issue, send-anything-external always requires explicit human approval. The loop prepares; the human pulls the trigger.
- Comprehension debt: unreviewed code accumulates while a loop runs. Schedule human diff-reading as part of the loop's output (PRs, not direct commits), or the codebase becomes unknown to its owner.
Maturity Ladder
Run every new loop through these stages — never start at L3:
- L1 Report: loop only observes and reports (no writes). Validate discovery + verification quality.
- L2 Assisted: loop writes code but every result goes through the human gate (PR + verifier verdict attached).
- L3 Unattended: only for loops with a proven verifier, hard caps, and reversible outputs.
Minimal Recipes
Native interval loop:
/loop 15m triage new issues in the repo, draft fixes as PRs, never merge
Cloud routine (no laptop needed):
/schedule weekdays at 8am: review open PRs, run the verifier agent on each, post findings as comments
Bare-metal ralph loop (use only with caps + sandbox):
i=0; while [ $i -lt 20 ]; do cat PROMPT.md | claude -p --max-turns 30; i=$((i+1)); done
Parallel batch over worktrees: spawn N agents with isolation: "worktree", one work item each, verifier pass on every result before any merge.
Reference Implementations
- github.com/frankbria/ralph-claude-code — dual exit gate, circuit breaker,
.ralphrc caps, tool whitelist
- github.com/cobusgreyling/loop-engineering —
loop-init scaffold (STATE.md/LOOP.md/loop-budget.md), loop-audit readiness score, L1→L3 ladder
- addyosmani.com/blog/loop-engineering — the foundational article
