| name | loop-engineering |
| description | Design agent loops instead of one-off prompts: scheduled or goal-driven automation, worktree isolation, durable state, skills/policies, connectors/MCP, maker-checker subagents, cost budgets, safety gates, and human approval boundaries. Use when setting up recurring AI engineering workflows, repo maintenance loops, CI/PR/issue triage loops, long-running agents, autonomous or semi-autonomous coding tasks, or when replacing repeated manual prompting with a system that discovers, acts, verifies, records state, and escalates. |
Loop Engineering
Replace repeated prompting with a small control system that prompts agents for you.
A loop discovers work, isolates execution, applies persistent project knowledge, uses tools/connectors, splits maker from checker, records durable state, and decides whether to continue, stop, or escalate.
The goal is not maximum autonomy. The goal is reliable leverage: deterministic checks where possible, explicit human judgment where needed, and state that survives beyond one chat.
Primitives
Every loop should name these pieces:
- Trigger / automation — manual command, scheduled task, cron, CI, hook,
/loop, /goal, or event from a connector.
- Isolation — branch, git worktree, disposable checkout, or read-only mode so parallel agents do not collide.
- Skill / policy — durable project knowledge: skills, AGENTS/CLAUDE instructions, ADRs, conventions, local commands.
- Connectors — GitHub, CI, issue tracker, logs, metrics, Slack, database, browser, MCP, or other real tools.
- Maker/checker split — one agent/step proposes or edits; another verifies against spec, tests, gates, and risk.
- State / memory — file or tracker item outside chat:
LOOP.md, .ai/STATE.md, issue, Linear ticket, run log.
- Budget / boundary — max cadence, runtime, token/cost budget, permissions, allowlist, denylist, and kill switch.
If a loop lacks state, it rediscovers the same work. If it lacks a checker, it grades its own homework. If it lacks isolation, parallelism becomes chaos. If it lacks boundaries, it turns mistakes into repeated mistakes.
Maturity
- L0 One-off prompting — human manually prompts and checks everything.
- L1 Report-only loop — automation discovers and summarizes; no writes beyond state/report.
- L2 Assisted loop — loop drafts changes in isolated worktree/branch; human approves before commit/PR/merge.
- L3 Allowlisted action loop — loop may perform narrow low-risk actions with deterministic checks and rollback path.
- L4 Operating loop — trigger → triage → state → worktree → maker → checker → CI/tooling → ticket/PR/state update, with monitoring and kill switch.
Default rollout: L1 report-only → L2 assisted → L3 allowlisted. Do not start with unattended writes.
Design workflow
When asked to design or upgrade a loop:
- Define the repeated human prompting being replaced.
- Identify input signals: PR comments, CI failures, issues, logs, dependency alerts, recent commits, TODOs, review failures.
- Choose the smallest useful trigger and cadence.
- Define scope and permissions: read-only, draft-only, patch-only, specific directories, specific labels, no secrets, no prod writes.
- Choose isolation: branch/worktree/disposable checkout/read-only.
- Define state: exact file/tracker location and required fields.
- Split maker/checker: independent verifier or deterministic gate must decide whether done is true.
- Define human gate: what requires approval, what can be auto-closed, what must escalate.
- Define budget and kill switch.
- Validate with a dry run or intentional small violation before increasing autonomy.
Common patterns
- Daily triage — read CI, issues, recent commits, TODOs; update state with ranked findings.
- PR babysitter — monitor PR checks/reviews; summarize blockers and next actions.
- CI sweeper — reproduce failing CI, draft a fix in a worktree, run local gate, request review.
- Dependency sweeper — patch-only updates with changelog links and tests; escalate majors.
- Issue triage — label/dedupe/summarize; draft reproduction steps; no product decisions without approval.
- Post-merge cleanup — detect temporary flags, dead code, migration residue, stale TODOs.
- Observability-to-task — group logs/errors into actionable tickets with user/business/error context.
- Guardrail hardening — convert repeated review comments and agent mistakes into lint/CI/pre-commit checks.
Safety rules
- Start read-only unless the user explicitly asks for implementation.
- Prefer deterministic gates over prose reminders.
- Keep the maker away from the checker.
- Use worktrees for parallel write work.
- Store state outside the conversation.
- Make autonomy boring: narrow scope, explicit allowlist, clear rollback.
- Escalate ambiguity, architecture decisions, security-sensitive changes, destructive operations, and high-cost loops.
- Track cost and cadence. Subagents and frequent loops can burn tokens quickly.
- Reduce loop parallelism when human review bandwidth is the bottleneck.
- Quarantine flaky checks quickly; ignored signals destroy the loop.
Useful artifacts
A minimal LOOP.md or state file should include:
# Loop: <name>
Purpose: <repeated work replaced>
Trigger: <manual/scheduled/event>
Scope: <what it may read/write>
Isolation: <branch/worktree/read-only>
State: <where findings and attempts are recorded>
Maker: <agent/step that proposes or edits>
Checker: <agent/step/gates that verify>
Human gate: <approval/escalation rules>
Budget: <cadence/runtime/token/cost cap>
Kill switch: <how to stop/quarantine>
Last run: <date/result>
Next action: <smallest next step>
A loop is ready to increase autonomy only when its state, checker, human gate, budget, and kill switch have been tested.
