Skip to main content

Codex 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

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 follows this shape:

  1. Frame the outcome, repo scope, risk, owner surface, relevant rules, expected checks, and whether Plan Mode already accepted the work.
  2. Route product-doc work through .codex/routing/repos/document.md before editing when docs are required by the accepted scope or Docs Sync trigger.
  3. Work inside the accepted scope with the smallest safe diff.
  4. During Check, run the Docs Sync checkpoint from .codex/routing/doc-sync.md when the diff affects public docs, developer docs, routing docs, workflow policy, or documentation structure.
  5. Run affected checks selected by .codex/routing/verification/selector.md.
  6. Enter Verify-Fix when a required check fails or cannot run.
  7. Route Review coverage from .codex/routing/review-matrix.md, including product-doc reviewers when Docusaurus pages or placement changed.
  8. Enter Review-Fix when review or checker findings require changes.
  9. Report changed files, verification evidence, Docs Sync status, review evidence, blockers, and optional commit-readiness status.

The Work Loop stops when the requested outcome is completed, blocked, escalated, or returned to Plan Mode. It returns to Plan Mode when scope, risk, owner surface, required checks, or user intent materially changes.

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 then applies the smallest relevant fix, reruns the same failing check, and reruns any selector-required checks invalidated by that fix.

Do not keep iterating forever. 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.

Review-Fix stops when findings are resolved, explicitly deferred by the user or human owner, blocked by missing approval, or escalated back to Plan Mode.

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.

Maintenance work that changes .codex files must declare exact control-plane write scope and route Review through .codex/routing/review-matrix.md.

Stop Rules​

All loops share 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.

Evidence​

Loop evidence is audit state. It does not replace hooks, lint, tests, checkers, review-matrix ownership, or commit-policy requirements.

LoopEvidence to report
WorkChanged files, checks run, no-run reasons, Docs Sync status when triggered, review routing, findings, fixes, and commit-readiness status when relevant
Verify-FixFailing command, failure summary, fix files, rerun command, status, no-run reason, and remaining blockers
Review-FixFinding, disposition, fix files, invalidated approvals, follow-up review scope, unresolved blockers, and human-owner status
MaintenanceDrift detected, SSOT owner, Tier 0 candidate classification, files changed, checks run, review coverage, and follow-ups

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.