Run a bounded agent loop

Use this runbook when an agent can make several related changes but must not decide for itself when the work is safe to release. The loop ends on evidence, a limit, or a named blocker—not on confidence.

Define the envelope

Write down five things before the first edit:

• Outcome: one observable result.
• Scope: exact repositories, directories, systems, and data the agent may touch.
• Authority: allowed reads, writes, commands, network access, and external side effects.
• Evidence: checks that can support completion, plus checks that remain human review.
• Limits: maximum iterations or elapsed time, and conditions that stop immediately.

Keep publication, deployment, spending, credential use, destructive cleanup, and messages to other people as separate permissions unless explicitly included.

Use one small control loop

1. Observe. Read current state, relevant instructions, and recent failures. Preserve unrelated work.
2. Choose. Select the smallest change that can test the current hypothesis.
3. Act. Make only that change within the envelope.
4. Verify. Run the narrowest meaningful check first, then broader agreed checks when warranted.
5. Decide. Finish, continue with a revised hypothesis, or stop with evidence.

An iteration record can be short: hypothesis, files changed, command or review performed, result, and next decision. Another person should be able to reconstruct why the next iteration happened.

Stop conditions

Stop and hand back control when:

• acceptance checks pass and the diff stays inside scope;
• the iteration or time limit is reached;
• the same failure repeats without new evidence;
• a required input, permission, credential, or owner decision is missing;
• observed state conflicts with task assumptions;
• an action would publish, deploy, spend, delete material data, or widen access beyond stated authority; or
• verification cannot distinguish success from a plausible-looking result.

“Keep going” extends persistence toward the stated outcome. It does not expand authority.

Review the result

Inspect the actual diff and report what changed, checks executed and their environment, checks not run, assumptions, residual risks, unrelated work preserved, and the next required decision. A screenshot can support a visual claim; it cannot prove hidden behavior, persistence, authorization, or deployment. A test result supports only the tested revision and environment.

Recover from a bad iteration

Prefer a new corrective edit over broad rollback. If reversal is necessary, target only files changed by this loop and first verify their exact paths. Never erase unrelated work to restore a clean status. Preserve failed evidence long enough to explain the correction.

Worked synthetic example

Suppose a fictional parser must accept an optional owner field. Limit scope to its parser, fixture, and tests; allow local edits and tests but no dependency updates or network access; require focused tests followed by the unit suite; stop after three iterations or on an ambiguous schema decision.

If the focused test exposes unspecified empty-string behavior, stop for a product decision. Do not invent a rule merely to make the suite green. If both test layers pass, report the exact commands and diff. Do not commit or publish unless separately authorized.

This example is illustrative. It is not evidence that a real repository or agent run completed.