Loop Engineering.  🔗 **Source:** [Loop Engineering.](https://twitter.com/addyosmani/status/2064127981161959567/?rw_tt_thread=True) > [!note]+ Document Notes > tags: [ai-agents, loop-engineering, claude-code, codex, agent-orchestration, devrel, ai-coding, automation] > author: Addy Osmani > source: https://twitter.com/addyosmani/status/2064127981161959567 > reference: x.com/addyosmani > date_created: 2026-06-08 > > # 🏷️ Loop Engineering > <!-- deep-read:sections start --> ## 🧭 Table of Contents - Summary - Main Content (the five building blocks + memory) - Paraphrase - Newsletter - Action Items - Hypotheses - Questions - Future Research - Implications - Learning Styles - Accessibility - DEIB - Logical Validity - Conclusion - Refactor Appendix ## 🔗 References (in-page) - Peter Steinberger (@steipete) — "You should be designing loops that prompt your agents." - Boris Cherny (@bcherny), head of Claude Code at Anthropic — "I have loops running that prompt Claude… My job is to write loops." - Osmani's prior essays referenced inline: *agent harness engineering*, *the factory model*, *long-running agents*, *the orchestration tax*, *agent skills*, *intent debt*, *the code agent orchestra*, *adversarial code review*, *code review in the age of AI*, *comprehension debt*, *cognitive surrender*. ## 📝 Summary **What it argues:** "Loop engineering" is the shift from *prompting* a coding agent turn-by-turn to *designing a system* that prompts the agent for you — a recursive goal where you define a purpose and the AI iterates until done. Osmani frames it as plausibly "the future of how we work with coding agents," while staying explicitly skeptical (token-cost variance, slop/quality risk). **The structure:** A loop is five capabilities plus one memory store, and Osmani's claim is that Claude Code and Codex now *both* ship all five — so the argument stops being "which tool" and becomes "design a loop that works in either." 1. **Automations** — scheduled discovery/triage that runs itself (Codex Automations tab; Claude Code `/loop`, cron, hooks, GitHub Actions). The heartbeat. 2. **Worktrees** — git worktrees so parallel agents don't collide on the same files (Codex built-in; Claude Code `--worktree` flag + `isolation: worktree` on subagents). 3. **Skills** — `SKILL.md` folders that write down project knowledge so the agent stops re-deriving context every session ("intent debt" written down on the outside). 4. **Plugins & connectors** — MCP-based connectors that let the loop touch real tools (issue tracker, DB, staging API, Slack); plugins bundle skills+connectors for sharing. 5. **Sub-agents** — split the maker from the checker; a second agent (often a different model) grades work the first one talked itself into. Codex `.codex/agents/*.toml`; Claude Code `.claude/agents/`. This is also what `/goal` does under the hood — a fresh model judges the stop condition. 6. **Memory** — a markdown file or Linear board outside the conversation holding what's done/next. "The agent forgets, the repo doesn't." **Why it matters:** The leverage point moved. You design the loop once instead of prompting each step. Osmani's worked example: a morning automation calls a triage skill → reads CI failures/issues/commits → writes findings to a state file → spawns an isolated-worktree sub-agent to draft each fix → a second sub-agent reviews against skills+tests → connectors open the PR and update the ticket → anything unhandled lands in a triage inbox. **The honest caveats (the strongest part):** Three problems get *sharper*, not easier, as the loop improves — (a) **verification is still on you** ("done" is a claim, not a proof); (b) **comprehension debt** grows faster (the gap between code that exists and code you understand); (c) **cognitive surrender** — the comfortable posture of taking whatever the loop returns. His kicker: two people build the identical loop and get opposite results — one moves faster on work they understand deeply, the other avoids understanding the work at all. "The loop doesn't know the difference. You do." **Bottom line:** "Build the loop. Stay the engineer." Loop design is *harder* than prompt engineering, not easier, because judgment moves from per-turn correction to system design — and the failure mode (surrendering thinking) wears the same clothes as the success mode (designing with judgment). ## 📖 Main Content ### 🗒️ Notes (by section) - **The reframe** — For ~2 years the agent was a tool you held one turn at a time. Loop engineering ends that: you build a small system that finds work, hands it out, checks it, records what's done, decides next — and lets *that* poke the agents. - **Not a tooling problem anymore** — A year ago a loop meant a pile of bespoke bash you maintained forever. Now the pieces ship inside the products. Steinberger's list maps almost 1:1 onto Codex, then nearly the same onto Claude Code → "you stop arguing about which tool." - **Automations = the heartbeat** — Codex: pick project/prompt/cadence/checkout; results go to a Triage inbox, empty runs self-archive. OpenAI uses them internally for issue triage, CI-failure summaries, commit briefings, bug hunts. Automations can *call a skill*. Claude Code: `/loop` (re-runs on cadence), cron, lifecycle hooks, GitHub Actions. **`/goal` is the loop-native primitive** — keeps going until a verifiable condition holds, with a separate small model grading "done" so the writer isn't the grader. Codex has `/goal` too. - **Worktrees = parallel without chaos** — A git worktree is a separate working dir on its own branch sharing repo history. *Human ceiling caveat:* worktrees remove mechanical collision but **your review bandwidth** caps how many you can run ("the orchestration tax"). - **Skills = stop re-explaining** — `SKILL.md` runs on `/`/skills` call or auto when task matches the *description* → "a tight boring description beats a clever one." Skills are *intent written on the outside*. Without skills the loop re-derives the project from zero every cycle; with them it compounds. **Skill = authoring format; plugin = how you ship it.** - **Plugins/connectors = touch real tools** — Connectors (built on MCP) read the issue tracker, query a DB, hit staging, post to Slack. Both speak MCP → connectors port across. The difference between "here is the fix" and a loop that opens the PR, links the Linear ticket, pings the channel once CI is green. - **Sub-agents = keep maker away from checker** — "The model that wrote the code is way too nice grading its own homework." Usual split: one explores, one implements, one verifies against spec. Burns more tokens → spend where a second opinion is worth paying for. This *is* `/goal`'s stop-condition logic applied to the maker/checker split. - **Memory = the spine** — Outside the single conversation. The model forgets between runs, so memory lives on disk, not in context. The state file remembers what was tried/passed/open so tomorrow's run resumes where today stopped. ## 🗣️ Paraphrase You stop being the hand on the tool and become the designer of the machine that holds the tool. Five parts make the machine (scheduled triggers, isolated checkouts, written-down project knowledge, real-tool connectors, a separate grader) plus a notebook the machine writes to so it doesn't forget. Both major coding agents now ship all five, so portability beats tool tribalism. The catch: the machine running unattended is also failing unattended, so verification, comprehension, and the temptation to stop thinking all get *worse* as the machine gets *better* — unless you design it as someone who still intends to understand the output. ## 📰 Newsletter (WordPress-focused) For the WordPress agent-tooling crowd: "loop engineering" is the same `/loop` + skills + MCP-connector stack landing in the broader ecosystem, and it maps cleanly onto plugin-maintenance drudgery — a nightly automation that triages Trac tickets or Patchstack advisories, drafts a fix in an isolated worktree, runs a reviewer sub-agent against your plugin's `SKILL.md` and PHPUnit suite, then opens the PR via a GitHub connector. The honest part Osmani nails: it doesn't remove the maintainer, it moves the maintainer's job from typing fixes to designing the loop and *still reading the diff*. Comprehension debt is the WordPress-security version of technical debt — a loop that ships code you didn't read is a supply-chain risk wearing a productivity costume. ## ✅ Action Items - **DevRel** — Build a tool-agnostic reference "loop" demo (automation → worktree → maker/checker subagents → MCP connector) across Claude Code + Codex; strong talk/workshop spine. - **Core / Core AI** — Evaluate `/goal`-style verifiable stop conditions; the maker≠checker split is the governance hook. - **Community / Training** — Teach "skill description discipline" (boring > clever) as the highest-leverage lesson. - **Documentation** — `SKILL.md` as the canonical "intent written on the outside" pattern for plugin/theme repos. - **Hosting** — Connectors hitting staging APIs inside a loop is the ops-adjacent risk surface; pair with the AI Agent Safety gateway pattern. - **Plugins** — A nightly triage loop over Trac/Patchstack is a concrete maintainer-capacity play. - **FAIR / The WPCC** — "Two people, same loop, opposite results" is a governance argument for review culture, not just tooling. ## 🧪 Hypotheses 1. Teams that codify project knowledge in skills show *lower* per-session token cost over time than teams that re-prompt context each run. 2. Loops with an independent verifier sub-agent ship fewer regressions than single-agent loops, at higher token cost. 3. The dominant failure mode of loop adoption will be comprehension debt (un-read merged code), not loop mechanics. 4. "Boring, specific skill descriptions" out-trigger "clever" ones on auto-invocation accuracy. 5. Tool-portability (Codex↔Claude Code) holds only while both keep MCP + worktree + skill parity. 6. Individual outcome variance exceeds tool variance — who designs the loop matters more than which tool runs it. ## 📊 Methodology Not applicable as empirical study — a practitioner synthesis/opinion essay. Its "evidence" is two named-practitioner quotes plus a feature-parity mapping across two products. No data, no measurement; claims are argued, not tested. ## ❓ Questions - Where's the line between "designing the loop with judgment" and "designing the loop to avoid thinking" — observable before the quality spiral, or only after? - What's the actual token-cost distribution of a maker/checker loop vs. a single agent on the same task? - Does "design once" portability survive the first major feature divergence between Codex and Claude Code? - At what team size does comprehension debt become unrecoverable? ## 🔮 Future Research - Empirical comparison of verifier-sub-agent loops vs. single-agent loops on regression rate + cost. - A "comprehension debt" metric: % of merged LOC no human read, tracked over time. - Skill-description linting: what description features predict correct auto-invocation. ## 💡 Implications - **Practice:** The unit of skill becomes *system design*, not prompt phrasing. - **Policy/governance:** Verifiable stop conditions + maker/checker separation are the auditable controls for unattended agents. - **Security:** Connectors touching real infra inside an unattended loop = the new privileged-automation surface (pair with gateway isolation). - **Education:** Apprenticeship risk intensifies — a junior who only "presses go" never builds the comprehension the loop assumes. - **Funding/maintainer capacity:** Loops can extend maintainer reach (triage drudgery) *or* hollow out understanding; same tool, opposite outcomes. ## 🧠 Learning Styles Assessment - **Visual** — moderate; implicit "floor above the harness" spatial metaphor helps, but no diagram. - **Aural** — high; reads as spoken argument, quotable lines ("the agent forgets, the repo doesn't"). - **Verbal** — high; definitional and analogical throughout. - **Kinesthetic** — high; the worked morning-loop example is reproducible. - **Logical** — high; clean part-by-part decomposition then synthesis. - **Social** — moderate; leans on community practitioners. - **Solitary** — high; reflective, self-skeptical register. - **Naturalistic** — low. - **Reading level:** ~grade 10–11; conversational but conceptually dense. ## 📊 Accessibility Assessment (WCAG 2.2 AA, as content) - **Perceivable** — text-only; would benefit from a 5-blocks+memory diagram (alt-text if added). - **Operable** — N/A (prose). - **Understandable** — strong; jargon ("worktree," "MCP," "harness") defined inline. - **Robust** — N/A. - **Readable** — short paragraphs, plain analogies aid comprehension. - **Predictable** — consistent "Codex does X / Claude Code does the same" parallel structure. - **Input assistance** — N/A. ## 🌍 DEIB Assessment - **Cultural breadth** — narrow (elite AI-tooling practitioner milieu). - **Inclusive language** — neutral. - **Neurodiversity** — the externalized-memory framing is unintentionally friendly to working-memory differences. - **Representation** — two prominent insider practitioners; no source diversity. - **Psychological safety** — the "stay the engineer" tone is empowering rather than gatekeeping. ## ✅ Logical Validity **Strong reasoning:** - The maker≠checker argument is sound and self-applies (it's also how `/goal` works). - The "design once, runs in either tool" claim is properly *conditioned* on feature parity rather than asserted absolutely. - The honest-caveats section names failure modes that *grow* with success, resisting the usual hype arc. **Fallacies / weak spots:** - **Appeal to authority** — the thesis leans on two practitioner quotes; persuasive but not evidence. *Fix:* pair with outcome data. - **Hasty generalization** — "both products have all five now" flattens real maturity differences. *Fix:* qualify per-capability maturity. - **Bandwagon adjacency** — "this may be the future" is hedged but still future-hype framing; partly inoculated by explicit skepticism. - **No quantification** — every cost/benefit claim is directional, never measured. **Tone of voice:** Measured-evangelist. Enthusiastic about the shift, repeatedly self-skeptical, ends on responsibility ("stay the engineer"). Unusually honest for the genre. ## 🛡️ DARVO Analysis Not applicable — no accusation/defense dynamic; technical advocacy with self-directed caution. ## 🎯 Conclusion **Bottom line:** Loop engineering reframes agent work from prompting to system design, built from five now-standard primitives plus a disk-backed memory. The real contribution isn't the taxonomy — it's the refusal to pretend the loop removes the engineer. Verification, comprehension, and the temptation to stop thinking all *intensify* with loop quality. **Next steps:** design a tool-agnostic loop, keep the maker/checker split, measure comprehension debt before it compounds. ## 🧱 Refactor Appendix ### 📚 Literature Split Pad **H1 — Strongest (verbatim):** - "Loop engineering is replacing yourself as the person who prompts the agent. You design the system that does it instead." - "The most useful structural thing in a loop, by far, is splitting the one who writes from the one who checks. The model that wrote the code is way too nice grading its own homework." - "Two people can build the exact same loop and get completely opposite results… The loop doesn't know the difference. You do." **H2 — Secondary:** - "Without skills the loop re-derives your whole project from zero every cycle, with skills it kind of compounds." - "The model forgets everything between runs so the memory has to be on disk and not in the context. The agent forgets, the repo doesn't." - "The worktrees take away the mechanical collision but YOU are still the ceiling, your review bandwidth decides how many you can actually run." **H3 — Supporting:** - A tight, boring skill description beats a clever one (auto-invocation depends on the description). - Skill = authoring format; plugin = shipping format. - `/goal` keeps going until a verifiable stop condition holds, judged by a separate model. ### 🔖 Atomic Split Pad (Zettel candidates) - **"The maker should not grade its own homework"** — independent-verifier sub-agents are the structural core of a trustworthy loop (twin of *adversarial code review* / backup-verify-rollback atoms). - **"Intent written on the outside compounds; intent re-derived each session is debt"** — skills as externalized, compounding project intent (connects to *Notes Are Files* externalization atom + *agents start cold and fill gaps with confident guesses*). - **"Comprehension debt grows faster as the loop gets smoother"** — the gap between code-that-exists and code-you-understand is the AI-era technical debt (connects to *AI Compresses the Knowledge-Worker Pipeline*). - **"The same automation amplifies judgment or replaces it — depending on the operator, not the tool"** — outcome variance is human, not tooling (bridges AI-Agent-Safety and AI-&-Future-of-Knowledge-Work). - **"Tool portability is conditional on capability parity"** — "design once, run in either" holds only while MCP + worktree + skill parity holds. ### 🗒️ Fleeting Queue - Map the 5 blocks onto a WordPress plugin-maintenance loop as a concrete DevRel demo. - Does "boring description beats clever" generalize to MCP tool descriptions too? (Plausibly yes.) - "The orchestration tax" (human review bandwidth as the real ceiling) deserves its own atom alongside the centaur/reverse-centaur cluster. <!-- deep-read:sections end --> 📄 **Full text:** ![[Full Document Contents/Tweets/Loop Engineering..md|Loop Engineering. by Addy Osmani]] ## Highlights - **Loop engineering is replacing yourself as the person who prompts the agent. You design the system that does it instead.** **A loop here can be thought of a recursive goal where you define a purpose and the AI iterates until complete.** It's roughly five building blocks and Claude Code and Codex both have all five now. ([View Highlight](https://read.readwise.io/read/01ktn426q91nb8mx39d9dh97s7)) - Note: Thesis: the unit of work shifts from prompting the agent to designing the loop that prompts it. - Tags: atom/literature/h1 - Now you build a small system that finds the work, hands it out, checks it, writes down what is done and then decides the next thing, and you let that system poke the agents instead of you. I wrote before about the cousin of this, [agent harness engineering](https://addyosmani.com/blog/agent-harness-engineering/), which is making the environment one single agent runs inside and the [factory model](https://addyosmani.com/blog/factory-model/) - the system that builds the software. Loop engineering sits one floor above the harness. The harness but it runs on a timer, it spawns little helpers, and it feeds itself. ([View Highlight](https://read.readwise.io/read/01ktn42a1cfgk6kbrcycdpz6sy)) - Note: Loop sits one floor above the harness: timer + helpers + self-feeding. - Tags: atom/literature/h2 - Skills are also where intent stops costing you over and over. I argued in [the intent debt](https://addyosmani.com/blog/intent-debt/) that an agent starts every session cold and it will fill any hole in your intent with a confident guess. A skill is that intent written down on the outside, the conventions, the build steps, the “we dont do it like this because of that one incident”, written one time where the agent reads it every run. Without skills the loop re-derives your whole project from zero every cycle, with skills it kind of compounds. ([View Highlight](https://read.readwise.io/read/01ktn42dqp3rss766aa5mn8zcx)) - Note: Skills = intent written on the outside; it compounds instead of being re-derived cold each session. - Tags: atom/zettel/z1 - The most useful structural thing in a loop, by far, is splitting the one who writes from the one who checks. The model that wrote the code is way too nice grading its own homework. A second agent with different instructions and sometimes a different model catches the stuff the first one talked itself into. ([View Highlight](https://read.readwise.io/read/01ktn42g7cjq4wp5x7mp0sgqdh)) - Note: Maker != checker. The structural core of a trustworthy loop; twin of adversarial code review. - Tags: atom/zettel/z1, atom/literature/h1 - **Your understanding still rots if you allow it.** The faster the loop ships code you did not write, the bigger the gap between what exists and what you actually get. Thats [comprehension debt](https://addyosmani.com/blog/comprehension-debt/) and a smooth loop just makes it grow faster unless you read what the loop made. ([View Highlight](https://read.readwise.io/read/01ktn42js95c8g9bvy1pq1zab8)) - Note: Comprehension debt: a smoother loop widens the gap between code that exists and code you understand. - Tags: atom/zettel/z1, atom/literature/h2 - Loops can also result in different outcomes depending on you. Two people can build the exact same loop and get completely opposite results. One uses it to move faster on work they understand deeply. The other uses it to avoid understanding the work at all. The loop doesn't know the difference. You do. ([View Highlight](https://read.readwise.io/read/01ktn42myb6w222s3e0k7fk4r7)) - Note: Outcome variance is human, not tooling: same loop, opposite results depending on the operator. - Tags: atom/literature/h1