Skip to main content

Workflow Loops

Lumie's execution model is loop-based. Plan Mode owns planning and user acceptance. After the plan is accepted, loop contracts own bounded execution, verification repair, review repair, and maintenance cleanup.

The canonical loop source is .codex/routing/loops/loop-contract.md.

Loop Model​

Loops are not slash-command phases. They are control loops that observe work, check output, review output, or maintenance signals and decide the next allowed action inside the accepted scope.

Every loop defines the same fields:

FieldMeaning
triggerWhen the loop starts
inputAccepted plan, diff, failure, finding, or audit signal
ownerMain agent, specialist, checker, hook, or human owner for the current step
observeSignal the loop reads before deciding
decidePass, fail, fix, escalate, defer, or stop criteria
actAllowed next action inside the accepted scope
stopCondition that exits the loop
evidenceOutput needed for Report, Review, Verify, or commit readiness
max_iterationsGuardrail against unbounded retries
escalationWhen to return to Plan Mode or ask the user

End-To-End Flow​

Work Loop​

Use the Work Loop for normal execution after an accepted Plan Mode plan, and for obvious bounded edits that do not require Plan Mode.

The Work Loop frames the outcome, resolves repo scope and owner surface, routes specialists when required, edits inside the accepted scope, runs affected checks, routes review coverage from the review matrix, and reports evidence.

For product docs, the Work Loop routes through .codex/routing/repos/document.md and applies the Docs Sync checkpoint when public docs, developer docs, routing docs, workflow policy, or documentation structure changed.

Verify-Fix Loop​

Use the Verify-Fix Loop when an affected check, lint, test, hook, or checker fails or cannot run inside the accepted Work Loop scope.

The loop reads the exact failing command, assertion, hook message, checker finding, no-run reason, and changed files since the last pass. It applies the smallest relevant fix, reruns the same failing check, and reruns any required checks invalidated by that fix.

The loop escalates after two attempts for the same failure signature, or earlier when the fix would change scope, risk, owner surface, or required checks.

Review-Fix Loop​

Use the Review-Fix Loop when a human owner, reviewer agent, checker agent, or required review evidence reports findings inside the accepted Work Loop scope.

The loop records the finding, affected files, review-matrix rows, fix diff, stale approvals, and follow-up review scope. Reviewer agents and checker agents can provide required evidence, but they cannot satisfy mandatory human-owner:* coverage.

Maintenance Loop​

Use the Maintenance Loop for .codex audits, SSOT cleanup, stale-reference cleanup, rule pruning, and repeated workflow failure learning.

The loop looks for duplicate authority, stale references, missing Tier 0 enforcement, dead invocation paths, oversized docs, and broken agent registry state. It can prune, merge, reroute, promote a Tier 0 candidate, defer with an owner, or escalate to Plan Mode.

Stop Rules​

  • Stop when the next action would exceed the accepted plan.
  • Stop when human-owner approval is required and unavailable.
  • Return to Plan Mode when a fix touches a new repo, owner surface, security-sensitive path, migration, public API, generated artifact, or architecture decision outside the accepted plan.
  • Stop after two unsuccessful attempts to fix the same check failure or review finding unless the user explicitly approves another iteration.
  • Stop when evidence is stale, contradictory, scope-mismatched, or missing for a required gate.

Verification​

Use these source files to verify loop behavior:

sed -n '1,220p' .codex/routing/loops/loop-contract.md
sed -n '1,160p' .codex/routing/loops/work-loop.md
sed -n '1,160p' .codex/routing/loops/verify-fix-loop.md
sed -n '1,160p' .codex/routing/loops/review-fix-loop.md
sed -n '1,160p' .codex/routing/loops/maintenance-loop.md

Expected success signal: the files show the standard loop fields, active loop set, stop rules, and evidence requirements described on this page.