# Loops A loop runs an agent repeatedly toward a goal until a stop condition holds, so work keeps moving without a person prompting each step. > A loop runs an agent again and again toward a goal until a stop condition holds. Without a stop condition it is a runaway. Source: https://ai-sw-factory.mellicci.dev/fundamentals/loops **Diagram:** A goal loop repeats work and a check; the loop control stops it on success, at a cap, or when a person says stop. - Work — the agent edits and runs - Check — tests, criteria, review - Loop control — stop or continue - Progress notes — carried to the next round - Centre: Stop when the check passes or a limit is hit A loop turns a single agent run into repeated runs aimed at one goal. After each round, something decides whether the goal is met. If it is not, the loop starts another round, and the agent gets the result of the last check as input. Loops exist at three scales. The **inner agent loop** (reason, call a tool, observe) runs inside every turn; [How coding agents work](https://ai-sw-factory.mellicci.dev/fundamentals/how-coding-agents-work) covers it. The **goal loop** wraps many turns: work, check, continue until tests pass or criteria are met. The **recurring loop** starts a fresh run on a schedule or when an event happens, such as every night or on each new pull request. **Diagram:** Three nested loops; this page is about the two outer ones. - Recurring loop (schedule, event): - Goal loop: - Inner agent loop — reason, tool, observe ## Why it exists A single prompt ends when the model decides it is done, not when the work is done. The suite is still red, or half the call sites are migrated, and a person has to type "keep going" again. Work that needs ten rounds needs ten prompts and someone watching. The opposite failure is worse. A loop with no stop condition keeps spending tokens and changing files until something else stops it: a full disk, an empty budget, or a person noticing the next morning. ## How it works **Diagram:** A loop needs a verifiable goal, a check the harness runs, and stop conditions; without them it is a runaway. - Each round (progress kept in files and commits): - Goal and check — a verifiable end state - → - Agent works — fresh or compacted context - → - Check runs — by the harness or a script - → - Loop control — continue or stop - → stops at any of - Stop conditions: - Success — the check passes - Iteration cap — max rounds - Budget or time — tokens, money, clock - Human stop — someone ends it A recurring loop, started by a schedule or trigger, is an independent run each time, so keep its state in the repository or an issue. A loop multiplies whatever the agent can do. Unattended iterations need the same limits as [headless runs](https://ai-sw-factory.mellicci.dev/fundamentals/headless-execution): a sandbox, least-privilege tools and a spending cap. ## Use it when - The end state is checkable by a command: tests pass, a linter is clean, a queue is empty. - The work needs many rounds and no judgment call between them. - The same task should run on a cadence, such as nightly triage or a weekly dependency check. ## Use something else when - You need the agent to run once with nobody at the keyboard → [Headless execution](https://ai-sw-factory.mellicci.dev/fundamentals/headless-execution) - A rule must hold on every step, not just at the end → [Hooks](https://ai-sw-factory.mellicci.dev/fundamentals/hooks) - Part of the work should run in a separate context and report back → [Subagents](https://ai-sw-factory.mellicci.dev/fundamentals/subagents) - You want loops combined with gates and review into a working factory → [Your first feedback loop](https://ai-sw-factory.mellicci.dev/fundamentals/your-first-feedback-loop) ## Key terms - **Loop** — repeated runs toward a goal until a stop condition holds. - **Goal loop** — work, check, continue. - **Recurring loop** — a fresh run on a schedule or trigger. - **Stop condition** — the rule that ends the loop. - **Progress memory** — state kept between iterations.