loop-engineering

name	loop-engineering
description	Use when shifting from manual prompting of coding agents to designing automated loops. Apply the 4-condition test, 5 building blocks, and MVP construction order for repetitive machine-verifiable tasks like CI triage, dependency bumps, or lint fixes. Trigger on automation, loop design, or agent orchestration requests.

Loop Engineering

Loop engineering replaces you as the prompter with a small system that finds work, hands it to the agent, verifies results, records state, and decides the next action — autonomously. You design the system once. The system prompts the agent forever after.

The leverage point moved from typing prompts to designing the loop that prompts.

The 4-Condition Test (Run Before Building Anything)

A loop only pays off if all conditions hold. Miss one and it costs more than it returns.

1. The task repeats — at least weekly. One-off or rare work amortizes setup cost poorly.
2. Automated verification exists — tests, type checker, linter, or build that can objectively fail bad output. No gate means the agent grades its own homework.
3. The agent has senior tools — reproduction environment, ability to run the code it writes, see logs and failures. Blind iteration wastes tokens.
4. Budget absorbs waste + hard stop — loops re-read context and retry. Cap tokens, iterations, or time. Human review gate required for irreversible actions (merge, deploy, secrets).

Good first loops: CI failure triage (nightly classify + draft fixes), weekly dependency bump PRs, lint-and-fix on PR open, flaky test reproduction (loop until theory holds), issue-to-PR on strong test suites.

Skip loops for: architecture rewrites, auth/payments, production deploys, vague product decisions, anything where "done" is human judgment.

Tactical 30-second checklist (all must pass or keep manual):

• Happens ≥ weekly
• Objective automated gate exists
• Agent can run its own changes
• Hard stop (tokens/iterations/time) defined
• Human approval before irreversible action

The 5 Building Blocks

1. Automations (the heartbeat)
Everything hangs off scheduled or event-triggered runs.

• Claude Code: /loop for regular cadence, /goal for "run until condition true" (separate small model checks completion — maker vs checker split). Use Desktop scheduled tasks or cloud Routines for persistence.
• Codex: Automations tab — prompt + cadence → Triage inbox.
  Use /goal + objective checker model to avoid early-exit on partial work.

2. Worktrees (parallel without chaos)
Multiple agents collide on files. Git worktree gives each its own isolated checkout on a fresh branch.

• Codex and Claude Code both support worktree isolation (flag or setting).
  Review bandwidth, not tool limits, caps parallelism.

3. Skills (write knowledge once, read every run)
A folder with SKILL.md (plus optional scripts/references/assets). Stores conventions, build steps, "we don't do X because of Y incident".
Without skills, every loop run re-derives context from zero. With skills, intent compounds across runs. This skill is an example.

4. Connectors via MCP
A filesystem-only loop is tiny. Model Context Protocol (MCP) connectors let the loop touch real tools:

• GitHub (read repos, create branches/PRs, comment, react to webhooks) — biggest day-one win.
• Linear/Jira (update tickets, link PRs, auto-close on verify pass).
• Slack (triage summaries, escalation pings).
• Sentry/error trackers (investigate alerts, draft fixes).
  Both Codex and Claude Code speak MCP — write once, works in both. The loop doesn't just "suggest a fix" — it opens the PR, links the ticket, pings the channel when CI green.

5. Sub-agents (maker away from checker)
The model that wrote the code is "way too nice grading its own homework."
Split: one explorer/implementer, one verifier (different instructions, sometimes different model).
Define in .claude/agents/ or .codex/agents/ (TOML: name, description, instructions, optional model).
Essential for unattended loops — the verifier you trust lets you walk away.

Minimum Viable Loop (Strict Order — Do Not Skip)

If the 4-condition test passes:

1. Make one manual run reliable first (good prompt + full context + verification).
2. Turn reliable knowledge into a Skill (SKILL.md).
3. Add state file (STATE.md at root or in .claude/, or Linear board). Records "what is done / what is next". Tomorrow's run resumes instead of restarting. "The agent forgets — the file does not."
4. Add the objective gate (test/build/lint that can fail the work).
5. Wrap in automation (schedule or trigger) + hard stop condition.
6. Layer sub-agents and connectors only after MVP works.

Metric that matters: cost per accepted change (not tokens spent). Below ~50% acceptance rate means the loop creates more review work than it saves.

Pair long-running loops with standing VISION.md or AGENTS.md reread each cycle to fight goal drift.

Critical Failure Modes & Mitigations

• Ralph Wiggum loop (fails quietly): No real verifier, soft "done when it looks good", no hard stop. Agent emits completion early on half-done work. Fix: objective gate (test passes/fails, build compiles, linter zero/non-zero).
• Comprehension debt: Loop ships code faster than you read it. Debt compounds until you debug a system no one understands. Mitigation: read diffs, spot-check gates, block loop from architecture/judgment work.
• Cognitive surrender: Stop forming opinions and accept whatever loop returns. Mitigation: deliberate pair-design of loops, read outputs.
• Security tax: Unattended loop = unattended attack surface. Generated insecure code merges automatically, skills can be injection vectors, logs leak secrets, permissions creep. Mitigations: include SAST/secret-scan/dependency-audit in gate; audit permissions every 30 days; disable verbose logging in prod; audit skill sources before install.
• Other: goal drift (lossy summarization drops constraints), self-preferential bias (maker verifies own work), agentic laziness (declares done at partial).

Common money-pit mistakes:

• Building without passing 4-condition test.
• No objective gate (second optimist reviewing).
• No state file.
• Vague stop conditions.
• No token/iteration cap.
• Running heavy verification on consumer plans.
• Auto-installing un-audited skills (many leak credentials).
• Letting loop do judgment-call work.
• Never reading the diffs.

How to Help Users With This Skill

When a user describes a repetitive coding task:

1. Apply the 4-condition test out loud. If any fails, recommend manual prompt or script instead.
2. If it passes, guide through MVP construction in strict order.
3. Recommend starting small: one automation + one skill + one state + one gate.
4. Suggest concrete first loops (CI triage, dependency bumps, lint-and-fix).
5. Warn explicitly about the pitfalls above.
6. For implementation, reference tool-specific primitives (Claude /loop /goal, Codex Automations, MCP connectors, worktrees, sub-agents, SKILL.md format).

This skill distills the 14-step roadmap (sourced from Anthropic engineering docs and Addy Osmani’s loop engineering work). The honest truth: most developers do not need loops yet. Only build when the task genuinely repeats, verification is automated, budget covers waste, and the agent has real tools. Miss one condition and the loop loses money.

Stay the engineer. Design the loop. Let it run.