Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.
TypeScript agentic-aiai-agentsai-codinganthropicautomationclaudeclaude-codecodexcoding-agentsdevops-automationdevtoolsgithub-actionsgrokllmloop-engineeringmcpprompt-engineering
---
name: loop-guard
description: >
Circuit breaker for fix-capable loops. Before each iteration, append the last
attempt to loop-ledger.json and run loop-context --check; if it escalates,
stop and hand the human a clean summary instead of looping in vain.
user_invocable: true
---
# Loop Guard (Circuit Breaker)
You keep a fix loop from burning tokens on a problem it cannot solve. You wrap
every iteration of an action skill (`minimal-fix`, `ci-triage`, `dependency-triage`, …)
with a deterministic circuit-breaker check powered by
[`loop-context`](https://github.com/cobusgreyling/loop-engineering/tree/main/tools/loop-context).
The breaker needs no LLM call, so it is cheap enough to run on every iteration.
## The ledger
`loop-ledger.json` records the loop's goal, its pattern/level, and one entry per
attempt:
```json
{ "goal": "Get failing CI green", "pattern": "ci-sweeper", "level": "L2", "attempts": [] }
```
`pattern` and `level` are seeded by `loop-init`; the breaker ignores them but the
budget step below reads them to size `--token-budget` from real cost data.
After every iteration, append what you just tried:
```json
{ "iteration": 3, "action": "patch flaky auth test", "outcome": "failure",
"error": "AssertionError: expected 200 got 500", "tokensUsed": 1800 }
```
`outcome` is `success | failure | noop`. Always include `error` on failures —
that is how the breaker detects a repeated (stagnant) failure.
## Size the token budget from the pattern
Don't hand-type a token cap — `loop-context` can derive it directly from the
pattern's realistic per-run cost
([`loop-cost`](https://github.com/cobusgreyling/loop-engineering/tree/main/tools/loop-cost)
computes this from `patterns/registry.yaml`) so the breaker trips on genuine
cost blowup, not a made-up number. Substitute the ledger's own `pattern`/`level`
(here: `ci-sweeper` / `L2`):
```bash
npx @cobusgreyling/loop-context --check --ledger loop-ledger.json \
--budget-from-pattern ci-sweeper --budget-level L2
```
## Track the daily cap across runs (optional)
`--budget-from-pattern` only guards a single run's ledger. `loop-budget.md`'s
daily table ("Max tokens/day") is a cross-run cap — track it with
`--daily-budget-from-pattern`, which accumulates spend into
`.loop-context/daily-spend.<pattern>.json` (resets at UTC midnight) and
escalates with trigger `daily-budget` once the pattern's suggested daily cap
is reached, even if this run's own ledger is nowhere near its per-run budget:
```bash
npx @cobusgreyling/loop-context --check --ledger loop-ledger.json \
--budget-from-pattern ci-sweeper --budget-level L2 \
--daily-budget-from-pattern ci-sweeper \
--on-exceed ./scripts/on-budget-exceed.sh
```
`--on-exceed <script>` turns `loop-budget.md`'s manual "On budget exceed"
checklist into a hook: on any escalate, the decision is piped as JSON to the
script's stdin (fire-and-forget — the script's exit code doesn't change
`--check`'s own). A typical script disables the scheduler, appends to
`loop-run-log.md`, and opens a maintainer issue.
## Before each iteration
1. Append the previous attempt to `loop-ledger.json`.
2. Run the breaker with the resolved budget:
```bash
npx @cobusgreyling/loop-context --check --ledger loop-ledger.json \
--budget-from-pattern ci-sweeper --budget-level L2
```
3. Act on the exit code:
- **0** → continue. Optionally trim the next prompt first:
`npx @cobusgreyling/loop-context --inject --ledger loop-ledger.json`
- **2** → **STOP.** The breaker tripped — same error N× in a row, too many
consecutive failures, the per-run or daily token budget, or the
iteration cap. Do not retry.
## On escalate (exit 2)
1. Capture a clean, pruned summary for the human:
```bash
npx @cobusgreyling/loop-context --inject --ledger loop-ledger.json > escalation.md
```
2. Write the escalation into STATE.md High Priority (or open an issue).
3. Exit the loop. A human decides the next step.
## Rules
- Never widen thresholds just to keep looping — escalation is a feature, not a failure.
- Never edit the ledger to hide a repeated error; the breaker exists to catch it.
- Defaults: 3× same error, 5 consecutive failures, 10 iterations. Tune with
`--stagnation`, `--no-progress`, `--max-iterations`, or an explicit
`--token-budget` (wins over `--budget-from-pattern` if both are given).
## Interaction with other skills
- `minimal-fix` / `ci-triage` — record each attempt's outcome + error in the ledger.
- `loop-verifier` — a verifier rejection is a `failure`; log it so repeats trip the breaker.
- `loop-constraints` — honors "escalate after N attempts"; this skill makes it mechanical.
- `loop-budget` — the per-run budget comes from `--budget-from-pattern`, the
daily cap from `--daily-budget-from-pattern`; `--on-exceed` automates the
"On budget exceed" steps loop-budget.md otherwise leaves manual.