autonomous-loop

name	autonomous-loop
description	Use when running an active autopilot-codex session — explains the plan→implement→review→verdict cycle, state machine, and termination conditions. Required reading when status='running' and the implementer needs to act inside the loop.
when_to_use	status=running and you need to know how the loop drives | unsure what verdict 'continue' means | mapping decision values to state transitions
allowed-tools	Bash(autopilot-codex:*), Read, Edit, Write, MultiEdit, Glob, Grep

AutoPilot Codex — autonomous loop

You are the implementer. Codex (the manager) plans, reviews each diff, and decides at the end of every turn whether the goal is achieved. Your job is to keep the loop honest: implement one task at a time, commit when green, never invent scope.

State machine

            ┌──────────────────────────────────┐
            │              idle                │
            └──────────────────────────────────┘
                           │ codex-plan
                           ▼
            ┌──────────────────────────────────┐
       ┌───▶│            running               │───┐
       │    └──────────────────────────────────┘   │
       │      │       │       │       │       │   │
       │ Edit │       │ Stop  │       │       │   │
       ▼      │       ▼       │       ▼       ▼   │
    review    │   verdict     │     budget   iter │
    (fix?)    │  (continue?)  │     (over?)  cap? │
       │      │       │       │       │       │   │
       │      │       │       │       │       │   │
       └──────┘       │       │       ▼       ▼   │
                      ▼       ▼   stopped_   stopped_
                    done    aborted  budget   iteration_
                                              limit

State lives at ${CLAUDE_PLUGIN_DATA}/state.json. current_task is the ONE task you should be implementing right now. base_sha is what review diffs against. iteration is incremented per verdict call.

What you do per task

1. Read current_task from state — its id, title, files, steps, acceptance, tests. The acceptance array is your contract; review judges by it.
2. If the task has tests listed, write the failing test first (RED), then implement (GREEN), then refactor.
3. Make the change. Keep the diff focused on the listed files.
4. Run tests / build / lint as appropriate.
5. Commit when green: <type>(<scope>): <task title> ≤ 72 chars.
6. End your turn — Stop hook will run bridge verdict and either advance you to the next task or terminate the loop.

Honour the verdicts

• decision: "approve" → green light; move to next task on next Edit.
• decision: "fix" → PostToolUse hook returns decision:"block" with the issue list. Do not advance. Address the issues; the next Edit re-fires review.
• decision: "reject" → revert the change (git restore -SW <files> or git reset depending on staging) and consult codex-manager for a re-plan. Do not try a different fix on top of a rejected change.
• decision: "continue" from verdict → Stop hook returns decision:"block" with the next task contract baked in. Implement it.
• decision: "done" from verdict → loop terminates; status='done'.
• decision: "abort" from verdict → status='aborted'; user takes over.

Termination

The Stop hook lets Stop proceed (no block) when any of:

• status == "done" — Codex says goal achieved.
• status == "aborted" — Codex aborted (or no_progress_streak ≥ 3 consecutive 'continue' verdicts without commits).
• status == "stopped_iteration_limit" — iteration >= max_iterations (default 30).
• status == "stopped_budget" — budget_used_usd >= budget_usd (default $5.00). See safety-rails skill.
• codex CLI missing or codex login broken — Stop hook logs and lets the user finish manually.

Iron rules

• One task at a time. No optimistic look-ahead.
• One commit per task when green. No "wip" commits.
• Do not change scope. If you discover the plan is wrong, surface it to the user and run /autopilot-codex:codex-plan <revised goal>. Don't paper over with a different fix on top.
• Do not silence Codex's verdict.
• Do not run destructive shell commands. Even if you don't hit safety-rails, side-effecting operations (git push, npm publish, terraform apply) need explicit user approval.

Inspecting the loop without spending

• /autopilot-codex:codex-status — full state JSON.
• /autopilot-codex:codex-next — just the current task contract.
• /autopilot-codex:codex-stop [reason] — disable the loop; hooks become no-ops on the next turn.