Codex AutoLoop

Turn a product goal into a locked specification and verified implementation. Continue autonomously after intake while evidence passes; stop closed as AUTOMATION_BLOCKED if a limit or safety boundary is reached.

Start

1. Read AGENTS.md, .autoloop/config.json, .autoloop/state.json, and .autoloop/policies/*.md completely.
2. Run python scripts/autoloop/autoloop.py doctor and python scripts/autoloop/autoloop.py validate. Use python3 if required by the host.
3. Inspect the repository and existing product before proposing behavior. Preserve unrelated user changes.
4. If the state has an active unfinished feature, resume it. Do not start a second feature over it.
5. Read only the phase reference needed next:
   • intake and scope: references/intake.md
   • specification and critique: references/specification.md
   • implementation and local convergence: references/implementation.md
   • Issue, pull requests, review loops, and merge: references/shipping.md

State discipline

Use scripts/autoloop/autoloop.py for all state transitions, counters, evidence, and specification locking. Do not hand-edit .autoloop/state.json to bypass validation.

After every phase:

1. validate the repository;
2. record current evidence;
3. transition only through an allowed edge;
4. continue immediately if the next step is authorized and safe.

On failure, diagnose and repair within the corresponding configured loop limit and total runtime. Increment the counter before retrying. If a limit is exhausted or the same cause repeats beyond its limit, run:

python scripts/autoloop/autoloop.py block --reason "concise evidence-backed reason"

Do not merge in the blocked state.

Required lifecycle

1. Intake - obtain or infer enough information to specify observable behavior. Questions gather requirements, not approval.
2. Specification - create the five artifacts under specs/<slug>/, critique them independently, repair findings, validate, and lock the digest.
3. Specification delivery - when GitHub is configured, put the locked specification on a dedicated spec/<slug> branch and managed pull request; let required checks and auto-merge complete.
4. Issue - create one implementation Issue from the locked specification and store its URL or number as evidence.
5. Implementation - create feat/<issue>-<slug> and implement tasks against the acceptance criteria and locked traceability plan.
6. Local verification - run validate, verify, and repository tests. Repair within bounds.
7. Implementation delivery - open a managed pull request that closes the Issue, wait for current-head CI and the native Codex review gate, repair actionable findings, and re-run all evidence.
8. Merge - arm GitHub auto-merge only through the included workflow. Confirm the merged commit, then transition through MERGED to DONE and close the Issue if it was not closed automatically.

Non-negotiable rules

• Do not begin product implementation before SPEC_LOCKED.
• Do not rewrite locked specification files from an implementation branch.
• Do not modify protected control paths in a managed feature pull request.
• Do not weaken, skip, delete, or suppress a gate to make it pass.
• Require codex-review-gate evidence from a native Codex review of the latest head; do not accept a stale review from an older commit.
• Do not force-push.
• Do not expose secrets.
• Do not claim completion without evidence tied to the latest or merged commit.

Handoff

For DONE, report the goal, locked-spec path, Issue, pull requests, merged commit, tests and gates, and any recorded assumptions. For AUTOMATION_BLOCKED, report the exact phase, failure evidence, attempts used versus limit, and the smallest safe action needed to resume.