Autonomous Agent Loop

Overview

This skill is the controller contract for a goal-bounded autonomous run. It turns approved scope into ready tasks, dispatches bounded workers, records runtime evidence, reconciles state, and continues until the goal is complete, blocked, paused, or stopped by an explicit policy/budget/approval gate.

Boundary: this is the loop controller, not a generic worker-dispatch helper. Use supervibe:dispatching-parallel-agents only for small ad-hoc fan-out, and use supervibe:subagent-driven-development for graph-backed worker waves inside a loop-ready or accepted execution graph.

Keep detailed evidence packet templates, side-effect ledgers, wave examples, resume checks, and final-report matrices in [Loop Evidence Patterns](/references/skills/loop-evidence-patterns.md).

When to Use

Use when a user asks for an autonomous run, epic execution, goal-until-complete loop, long worktree session, or multi-step delivery that must keep working until done or safely stopped.

Do not use for one small local edit, a read-only explanation, or non-dry execution of a plan that is not user-approved as loop-ready or already atomized into an accepted work graph with the current user handoff answered.

Expert Operating Standard

Follow <resolved-supervibe-plugin-root>/docs/references/skill-expert-operating-standard.md: start from source of truth, preserve context evidence, apply scope safety, use real producers with runtime receipts for durable delegated outputs, verify before completion claims, and keep confidence below gate when evidence is partial.

Step 0 - Read source of truth

Read the approved user request, current plan/spec or work graph, Goal Coverage Contract, Goal Source Drift Guard, active host instructions, .supervibe/memory/ workflow state, recent project memory, CodeGraph health, command-agent plan output, and receipt recovery status. If scope, evidence, or receipts are missing or stale, enter readiness repair or dry-run instead of dispatch.

Decision tree

Scope, stop condition, user gate, or verification target is missing
  -> readiness repair or one focused user question.

Accepted graph has independent tasks with disjoint write sets
  -> dispatch a small parallel wave with explicit worker packets.

Tasks share files, public contracts, migrations, or release state
  -> serialize, split, or quarantine until rollback and ownership are clear.

Provider permission, context evidence, receipts, or policy preflight is absent
  -> policy/readiness stop before non-dry work.

Ready work remains after a wave
  -> continue; do not report final completion from a partial checkpoint.

Loop execution practice framework

Do not close the loop until every required Goal has accepted evidence or an approved waiver with owner, expiry, impact, and next action.

Scope Safety Gate

Before dispatch or resume, classify each task, subtask, or emergent issue as include, defer, reject, or spike. Stop or quarantine scope expansion until the tradeoff, complexity cost, concrete harm, owner, verification, rollback, and user approval are recorded.

Plan Approval And User Gate

When a loop starts from a plan, pre-plan, epic, or atomized graph, require a user-approved loop-ready plan or accepted work-item graph plus a current explicit user answer for the latest handoff. Unanswered plan-scope, optional review, atomization, or execution handoffs block non-dry execution. Surface Next User Decision before execution or resume.

Before resume, dispatch, claim, or wave planning, compare the current PRD/plan source hash and current Goal Coverage Contract hash against the graph goalSourceDriftGuard. If either changed or cannot be read, block the loop and route to graph refresh, goal replan, or explicit user approval before launching agents.

Reviewer coverage is mandatory before production or release completion. The loop must record which final reviewer checked each completed task, the verdict, production-readiness status, and trusted runtime receipt evidence before closing the graph.

Controller Model

• Controller: owns task graph, scope, approvals, budget, policy, state, and final truth.
• Worker: owns one bounded task with declared write set, acceptance criteria, verification, rollback, and stop conditions.
• Reviewer: independently checks worker evidence, scope safety, regression risk, and acceptance before production/release completion.

Workers are not trusted because they sound confident or finish a first step. Completion requires reviewer-grade evidence and controller reconciliation.

Definition Of Ready

A task is ready only when approved scope, Goal IDs, dependencies, disjoint write set, acceptance criteria, verification, rollback, risk level, policy preflight, minimal context pack, stop conditions, and readiness score are present. Score must be at least 9/10 unless the run is dry-run or explicitly accepted as partial with remediation recorded.

Definition Of Done

A task is done only when acceptance criteria are satisfied, mapped Goal IDs have evidence or final-sweep verification scheduled, required verification ran, worker evidence is complete, reviewer evidence is attached or deliberately reserved for the final sweep, the side-effect ledger matches reality, scope safety passes, rollback and residual risks are recorded, and confidence is at least 9/10.

Continuation Contract

Continue ready work until the approved goal is complete, the user pauses/stops, an explicit budget is reached, policy or approval gates block progress, verification fails, no-progress policy fires, or required evidence is missing. Final output must distinguish COMPLETE, BLOCKED, PARTIAL, POLICY_STOP, BUDGET_STOP, and USER_PAUSED; COMPLETE is forbidden while any required goal is UNMET, FAIL, PARTIAL, DEGRADED, or NOT_VERIFIED without accepted user-approved waiver or replan closure, while the post-execution goal audit is missing specialist or tester receipts, while the user-visible goal completion report lacks goal, state, evidence, verifier, remaining gaps, or next action, or while goal regression checks after implementation changes have not passed before final release proof. Use the tester/specialist goal verification matrix for PASS, UNMET, FAIL, PARTIAL, DEGRADED, and NOT_VERIFIED; each state needs tester evidence, specialist evidence, and a block/replan rule before the loop can claim completion.

If the user changes topic while loop state or a queued handoff exists, surface run id, phase, active task/wave, artifact path, next safe action, and blocker, then ask one resume/pause/switch/stop question.

Workflow Signal Contract

Every loop status must include workflowSignal so resume, compact context, worktree sessions, and subagent cleanup can distinguish continue, pause, stop/archive, blocked, and complete states.

Topic Drift / Resume Contract

If a saved loop, NEXT_STEP_HANDOFF, or workflowSignal exists and the user changes topic, surface the saved phase and ask whether to continue, skip/delegate safe non-final decisions, pause and switch topic, or stop/archive.

Execution Packet

Each ready task gets an Execution Packet with task id, owner, write set, required Goal IDs from PRD/intake, goal done signal, Goal Health Preview state for covered, uncovered, satisfied, partial, unmet, degraded, and waived goals, acceptance criteria, required skills, context citations, verification commands, rollback path, stop conditions, receipt requirements, post-execution goal audit receipt requirements, goal regression checks, Goal Source Drift Guard status, unmet-goal replan rule, and expected output contract. Store durable loop state and packet pointers under .supervibe/memory/loops/<run-id>/ when the owning workflow uses loop memory.

Wave Planning And Dispatch

Plan waves from the ready front, not from urgency alone. Dispatch parallel work only when write sets are disjoint, state dependencies are satisfied, required Goal IDs and verifier ownership are preserved, and worker packets are self-contained. Workers optimize for mapped goal completion, not isolated task closure, and their handoff must report goalMap plus replanRequired when any required goal remains unresolved. Do not stop after the first task or wave while ready work remains; reconcile results, quarantine failures, and launch the next safe wave until the goal is complete or a real stop condition fires.

Recovery And Resume

On compact context, interruption, stale claim, worker failure, or process restart, reread durable loop state, graph status, Goal Source Drift Guard, receipts, active agents, and side-effect ledger before continuing. Close completed or stale subagent sessions that no longer own active work, recover safe claims, and resume from the next ready action instead of relying on hidden chat memory.

Procedure

1. Normalize the request or read the user-approved loop-ready plan/work graph.
2. Run preflight for scope, autonomy level, explicit budgets, environment, MCP or tool permissions, secrets, provider permissions, approvals, and rollback.
3. Apply <resolved-supervibe-plugin-root>/docs/references/scope-safety-standard.md; reject, defer, or ask about tasks that do not map to approved scope.
4. Build execution contracts for every ready task and score autonomy readiness; include Goal IDs, goal done signal, verifier, and unmet-goal replan rule.
5. Build or refresh the durable task graph with dependencies, write sets, verification, policy risk, required capability, stop conditions, and ready ordering.
6. Build a minimal context pack with memory, CodeGraph when relevant, citations, context quality, graph warnings, and fallback reasons.
7. Dispatch only ready-front tasks. Parallelize only disjoint write sets or read-only investigations.
8. Require structured worker handoff with verification evidence, side effects, residual risks, rollback, and reviewer needs.
9. Reconcile state after each task or wave; quarantine failing tasks without blocking unrelated ready work.
10. Stop on policy, budget, cancellation, approval expiry, provider permission failure, repeated no-progress, state migration failure, or missing evidence.
11. Before completion, reread source scope and Goal Coverage Contract, rerun the Goal Source Drift Guard, run the post-execution goal audit, verify every acceptance criterion and required goal, close or block every risk, confirm production-readiness gates, and run the final tester/reviewer sweep. Each required goal needs both specialist and tester receipts. After implementation changes and before final release proof, run goal regression checks for required goal status, goal audit receipts, unmet-goal replan state, and no silent implementation regression. If any goal remains UNMET, FAIL, PARTIAL, DEGRADED, NOT_VERIFIED, missing required audit receipts, failed regression checks, missing goal completion report proof, missing accepted waiver proof, or open replan state, propose new or updated Delivery Epics, Work Packages, Atomic Task Inventory rows, dependencies, and verifier ownership; then continue/replan instead of closing. A waiver is accepted only when the goal cannot or should not be completed in the current graph and the record includes reason, current-graph scope boundary, user approval evidence, owner, verifier, expiry or recheck condition, impact, and next action. The user-facing summary must match the user's language and say simply what is missing and that execution continues or replans.
12. Write the final report with status, evidence, receipts, score, rollback, artifact retention, and next action.

Anti-patterns

• Ignoring the boundary: Do not bypass the command or workflow that owns durable loop artifacts.
• Accepting the rationalization: "One failed task means the whole run should stop"; quarantine the failed task, preserve graph state, and continue only through a bounded recovery branch.
• Proceeding despite this red flag: A ready task lacks write set, verification, rollback, or stop conditions.
• Letting the known failure mode happen: Controller-authored summaries substitute for worker or reviewer receipts.

Examples

• Valid: a user-approved loop-ready plan has five independent documentation fixes and two shared validator changes. Dispatch the doc fixes as one receipt-backed wave, serialize the validator tasks, then run a final reviewer sweep before closing the graph.
• Invalid: a worker reports npm test passed but the graph still has open blockers, overlapping write sets, and no reviewer receipt. Mark the task incomplete or blocked; do not report COMPLETE.

When not to use

• Do not bypass the command or workflow that owns durable loop artifacts.
• Do not use stale context, missing receipts, or legacy migrated evidence as production completion proof.
• Do not replace specialist producers, workers, or reviewers with controller summaries when runtime receipts are required.

Common rationalizations

• "One failed task means the whole run should stop" - reject; quarantine it and continue unrelated ready work when scope and write sets allow.
• "The worker says tests passed, so the graph is complete" - reject; reconcile acceptance, side effects, reviewer evidence, and open blockers first.
• "The user said continue earlier, so unanswered handoffs are implied" - reject; each handoff needs a current explicit answer.
• "Legacy evidence is close enough for release" - reject; production completion needs current trusted reviewer or validator evidence.

Red flags

• A ready task lacks write set, verification, rollback, or stop conditions.
• Two active workers can modify the same file without a conflict exception.
• Final status says COMPLETE while blockers, risks, or reviewer gates remain.
• Side-effect ledger omits commands, files, spawned processes, or approvals.

Checklist

• Reviewed scope and latest user gate confirmed.
• Memory, CodeGraph, and receipt status checked.
• Task graph has dependencies, write sets, acceptance, verification, rollback, policy risk, stop conditions, and ready-front ordering.
• Worker packets are bounded and self-contained.
• Final reviewer sweep and production readiness evidence are recorded.

Failure modes

• Controller-authored summaries substitute for worker or reviewer receipts.
• The loop stops after the first successful wave while ready work remains.
• Scope expands through "helpful" optional work without approval.
• Resume relies on hidden chat state instead of durable loop state.

User-facing output

When this skill reports to the user, write the visible summary in the user's current language. Lead with the practical result, blocker, or next decision in 1-3 plain sentences. Keep structured fields, evidence ledgers, command output, and checklist details as supporting material after the summary, not as the whole answer. If the skill emits machine-readable artifacts, keep artifact keys in English but localize the surrounding explanation.

Output contract

• status: PASS, FAIL, PARTIAL, BLOCKED, or ADVISORY for the autonomous-agent-loop handoff.
• evidence: exact commands, exit codes, artifacts, receipts, citations, screenshots, runtime proof, or source paths used.
• confidence: evidence-backed score or boundary, including any cap or degraded reason when proof is partial.
• nextAction: concrete repair, rerun, handoff, waiver, stop, or resume step for the caller.
• blockers: missing source, command, receipt, approval, owner, validator, or unsafe scope condition.
• receipts: runtime-issued receipt ids when a command, producer, reviewer, worker, or external tool is claimed.

Guard rails

• Do not mutate files, provider state, network resources, or external tools unless procedure, policy, and user approval allow it.
• Do not skip prerequisites, confidence gates, explicit approvals, or reviewer gates.
• Do not claim completion without concrete verification and receipt evidence.
• Preserve unrelated worktree changes.

Verification

• Run the loop validator, dry-run, audit, or task-local command named by the owning workflow.
• For production completion, prefer /supervibe-loop --validate-completion --require-trusted-evidence when trusted receipts are available.
• Confirm emitted loop state and final report match the Output contract.
• If verification cannot run, state the blocker and keep confidence below gate.

Supporting references

Resource tree hardening

• references/practice-pack.md - Load when autonomous-agent-loop needs deeper load rules, local evidence anchors, gotchas, or the final checklist.

• scripts/self-check.mjs - Run with --check before claiming the autonomous-agent-loop resource tree is complete; add --json when machine-readable evidence is needed.

• evals/regression.json - Use when tuning the autonomous-agent-loop trigger boundary or checking should-trigger and should-not-trigger prompts.

• examples/workflow.md - Load when a concrete Autonomous Agent Loop execution example or anti-example would clarify the next action.

• templates/output-contract.md - Use when emitting loop-state so status, evidence, blockers, confidence, and nextAction stay consistent.

• [Loop Evidence Patterns](/references/skills/loop-evidence-patterns.md) - worker packet schema, evidence ledger, wave examples, resume checks, and final report matrices.

• Regression eval: <resolved-supervibe-plugin-root>/tests/autonomous-loop-runner.test.mjs, <resolved-supervibe-plugin-root>/tests/autonomous-loop-dispatcher.test.mjs, and <resolved-supervibe-plugin-root>/tests/autonomous-loop-final-acceptance.test.mjs cover loop execution, dispatch, and final acceptance behavior.

Related

• supervibe:subagent-driven-development - executes ready worker waves.
• supervibe:dispatching-parallel-agents - parallelization safety.
• supervibe:using-git-worktrees - isolation for long-running work.
• supervibe:verification - verification evidence before completion claims.