# Loop Engineering > >- - **Type:** Skill - **Install:** `agentstack add skill-maxmilian-loop-engineering-loop-engineering` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [maxmilian](https://agentstack.voostack.com/s/maxmilian) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [maxmilian](https://github.com/maxmilian) - **Source:** https://github.com/maxmilian/loop-engineering ## Install ```sh agentstack add skill-maxmilian-loop-engineering-loop-engineering ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Loop Engineering Loop engineering is the discipline that comes after prompt engineering. A prompt optimizes a single interaction. A **loop** optimizes the autonomous behavior that surrounds it — *when* the agent runs, *what* triggers it, *how* it verifies its own work, *when* it stops, and *when* it hands back to a human. The hard part is never the loop itself. A bare agent loop (call model → run tool → observe → repeat) is ~30 lines and every framework's core is the same. The whole job is the engineering *around* it: verification, stopping conditions, guardrails, context management, and escalation. Build those wrong and you are one edge case away from an agent that loops forever, burns the budget, or silently ships garbage. This skill has two modes. Detect which one the user needs: - **Design mode** — the user is building a new loop. Walk the whiteboard, then the seven principles, then hand them a concrete design. - **Review mode** — the user has a loop already (a script, a workflow, an agent). Use the seven principles as a diagnostic checklist and report what's missing. Most requests are one or the other; some are both. Don't force the framework on a user who just wants a quick answer — but for anything that will run unattended, the failure modes below are real and worth raising. ## Principle 0 — Whiteboard before platform Before writing any code or choosing any framework, answer five questions on paper. If you can answer these, the implementation is a few hours. If you skip them, you are building a demo, not a production loop. 1. **What triggers it?** Time (cron), interval (heartbeat), external event (hook), or a goal it chases until met? (See `references/loop-patterns.md`.) 2. **What does it check each cycle?** The single observation that decides whether there's work to do. 3. **What action does it take?** Ideally one well-scoped action per cycle. 4. **When does it stop?** This must be *machine-checkable*, not "when it's done." 5. **When does it escalate to a human?** The path out when the goal can't be met. > "Write the loop on a whiteboard before you open any platform." ## The seven principles These are the load-bearing ideas, distilled across the field. In **design mode** build each one in; in **review mode** check each one off and flag what's absent. ### 1. Leverage has moved from the prompt to the loop What the agent does in any single cycle matters less than when it runs, what triggers it, and when it stops. Spend your design effort on the loop's control flow, not on perfecting one prompt. ### 2. "Done" must be a machine-checkable endpoint `tests pass` ✓. `improve the code` ✗. `researched the competitors` ✗. `covered competitors X, Y, Z, each with at least one named source` ✓. A goal without a checkable success condition has no convergence criterion — it just iterates until the budget is gone. **Define "done" before the loop starts**, and write success/failure criteria into the agent's prompt where it can evaluate them. ### 3. Verify with deterministic tools, never the agent's self-report The agent saying "I'm done" is not evidence. A CI run, a test runner, a schema check, a diff against expected output — that is evidence. Verify in layers: per-action, per-iteration, and terminal. The verifier is the part you trust; the agent is the part you check. **Beware the agent gaming the proxy.** A success signal is a *proxy* for the goal, and an agent optimizing to make the signal go green will, if it can, satisfy the signal instead of the goal — delete or skip the failing test, weaken the assertion, edit the validator's config, add `continue-on-error`, hardcode the expected output. This is reward hacking / Goodhart's law, and it is one of the most common ways an autonomous loop "succeeds" while producing garbage. Defend it: make the verifier and its config **read-only / out of reach** of the agent, diff every change and reject ones that touch tests/CI/the checker or weaken coverage, and keep an invariant the agent can't edit (e.g. test count must not drop). When you choose a success condition, ask "how would a lazy agent make this green *without* doing the work?" and close that path. ### 4. Define all exits and guardrails before going live A production loop needs, at minimum: - a **success** exit (verifier confirms the goal), - a **failure** exit (unrecoverable error, retry limit hit), - a **budget** exit (max iterations, token cap, wall-clock timeout — whichever trips first), - **no-progress detection** (state stops changing across recent steps → break; a.k.a. loop fingerprinting), and - an **escalation path** (can't reach the goal → stop and alert a human queue, never silently continue). Success and failure criteria belong in the prompt; budget and no-progress caps belong in the controller code, because you cannot trust the agent to enforce its own ceiling. For hook-triggered loops, add **rate limiting / backpressure** — a webhook storm (10,000 events → 10,000 runs) can drain a day's budget in minutes. ### 5. Treat context as a finite resource Every token spends the model's attention budget, with diminishing returns; recall degrades as context grows ("context rot"). Aim for the *smallest set of high-signal tokens*. Tool outputs — not the system prompt — are usually the token hog (often the majority of what the agent sees), so trim raw tool results to the fields that matter before they enter context. For long-horizon loops use the three levers in `references/context-engineering.md`: **compaction**, **structured note-taking**, and **sub-agent architectures**. ### 6. Use the filesystem as memory; start each cycle with fresh context Conversation history is a fragile place to keep state — it drifts and rots as it grows ("Ralph Wiggum drift"). Durable state lives *outside* the context window: in the codebase, a TODO/PROGRESS file, git history, or a state JSON. Each cycle should reconstruct what it needs from that external memory rather than depending on what's still in the conversation. Re-read the state file every cycle instead of trusting a number you saw twenty steps ago. This is what makes a loop survivable across hundreds of iterations and context resets. ### 7. The hard part is verification, stopping, and escalation — not autonomy Don't sell or build "fully autonomous." The credible, safe design is **semi-autonomous**: the agent runs freely up to the point of an irreversible or outward-facing action (publishing, merging, deleting, emailing), then stops and asks. Reversible internal work → automate. Irreversible/external work → gate it behind a human. This is both safer and more trustworthy than full autonomy. ## Design mode: produce a concrete loop design When the user is building a loop, work through this and hand back an actual design, not a lecture: 1. **Run the whiteboard five** (Principle 0) with the user. Pin down the trigger pattern using `references/loop-patterns.md`. 2. **Write the machine-checkable success condition** (Principle 2). If you can't write one, the goal is underspecified — surface that now, it's the most common root cause of runaway loops. 3. **Specify all exits and guardrails** (Principle 4) with concrete numbers: iteration cap, token/cost budget, wall-clock timeout, no-progress rule. 4. **Choose the verification mechanism** (Principle 3) — name the actual tool/check. 5. **Decide the context strategy** (Principles 5–6) — what's durable state on disk, what's reconstructed each cycle, when compaction/sub-agents kick in. 6. **Mark the escalation boundary** (Principle 7) — exactly which actions stop and wait for a human. 7. **Sketch the control flow** — the loop body as pseudocode or a real script, with the exits wired in. Keep the body small; the intelligence is in the guardrails, not the loop. ## Review mode: diagnose an existing loop When the user already has a loop, read it (the script, the policy doc, the agent config) and produce a findings report. Use `references/review-checklist.md` for the full diagnostic; the short version is one pass per principle: For each of the seven principles, answer: **present / partial / missing**, cite where in their code or config it lives (or should), and give the single most valuable fix. Lead with the missing guardrails — a loop with no budget exit or no escalation path is the highest-severity finding. Don't pad the report with principles they already nailed; spend the words on the gaps. ## References Load these as needed — don't pull them all in at once. - `references/loop-patterns.md` — the four trigger patterns (heartbeat, cron, hook, goal), their failure modes, and how production loops combine them. - `references/context-engineering.md` — managing context across long-horizon loops: compaction, structured note-taking, sub-agents, just-in-time retrieval. - `references/review-checklist.md` — the full per-principle diagnostic for review mode, with severity ordering. - `references/sources.md` — the 12 source articles this skill distills, with one-line summaries, for when the user wants to go deeper or cite origins. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [maxmilian](https://github.com/maxmilian) - **Source:** [maxmilian/loop-engineering](https://github.com/maxmilian/loop-engineering) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-maxmilian-loop-engineering-loop-engineering - Seller: https://agentstack.voostack.com/s/maxmilian - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.