agent-loop

Agent Loop

Role

Design one artifact: loop.md. It fixes the decisions a loop must settle and leaves execution to the user's external goal mode. Do not run the loop, write executors, generate launcher code, or prescribe mechanics such as while blocks, phases, tool dispatch, or state layout.

Use assets/loop-template.md as the blank output shape when drafting a new loop.md. Use references/review-checklist.md during review, whenever a residual appears, or when subagent policy is in scope.

Output Shape

loop.md is a design contract. Include only sections that are needed for the task, but keep the spine:

1. Goal & Success Signal - one goal and an observable completion test. Avoid vague signals such as "done", "looks good", or "task complete".
2. Termination Conditions - max iterations or budget, the concrete shape of no progress, and the goal-achievement check.
3. Progress Invariant - the bounded quantity every path advances toward an exit. A path that neither terminates nor advances is undeliverable.
4. Approval Gates - only for irreversible actions. State the gated action, grant consequence, and deny consequence. Do not gate separable safe work.
5. Measurement Domain - match verification to the output domain: code uses tests, visual work uses renders/screenshots, interactive work is driven, and data work uses queries or checks.
6. Residual Routing - route iteration failures to LOCAL (retry in loop), PLANNER (re-scope), or HUMAN (escalate).
7. Subagent Using Policy (only if dispatching subagents) - define the dispatch contract, not the dispatch mechanism: trigger, role capability, input contract, output contract and acceptance check, concurrency, failure routing, and sub-task termination.

For the exact blank document, copy the shape from assets/loop-template.md.

Workflow

compile goal -> survey role capability -> grill -> draft -> review -> user diff -> accept

1. Compile goal - extract task, success signal, risk surface, and output domains.
2. Survey role capability - before grilling subagent selection, inspect the current platform's available role capabilities and tool boundaries. Use this as the strawman for any subagent dispatch contract. Skip this only when the loop will not dispatch subagents.
3. Grill - resolve one design branch at a time with 2-3 related questions. Each question includes a recommended answer for the user to accept or correct. Push back on vague answers with a sharper strawman.
4. Draft - write Goal, Termination, and Progress Invariant first; then fill the needed optional sections from the decision log.
5. Review - read references/review-checklist.md; fix LOCAL residuals in place, re-scope PLANNER residuals, and escalate HUMAN residuals.
6. User diff - change only the sections the user names.
7. Accept - deliver when the user accepts and no residuals remain.