codex-loop

# Codex Loop Use this skill for two lanes: runtime setup and restart-safe tracked execution. The tracking lane creates project-local artifacts under `.codex/loop/<name>/` so every continuation can resume from durable state instead of chat memory. ## Required Reading Router Match the task to the row. Read the listed files in full before producing output or running helper scripts. Inline content in this file is a dispatcher, not the contract. | Task | MUST read | | --- | --- | | Install, refresh, upgrade, status, uninstall, or explain activation | `references/runtime-setup.md` | | Configure automatic continuations or project `codex-loop.toml` | `references/continuation-config.md` + `references/runtime-setup.md` | | Bootstrap a tracked loop or create tasks from a broad request | `references/tracking-protocol.md` + `references/task-decomposition.md` + `references/state-schema.md` | | Resume a tracked loop after a Codex Loop continuation | `references/tracking-protocol.md` + `references/phase-transitions.md` + `references/state-schema.md` | | Audit or finalize a tracked loop | `references/checklist.md` + `references/phase-transitions.md` | ## Reference Index - `references/runtime-setup.md`: install, upgrade, status, uninstall, activation header, and current runtime behavior. - `references/continuation-config.md`: default built-in skill wiring with `optional_skill_name`, `optional_skill_path`, project config, and goal-header examples. - `references/tracking-protocol.md`: bootstrap, one-action-per-iteration execution, memory-before-state sequencing, blockers, summaries, and done signature. - `references/task-decomposition.md`: conversion of broad requests into task objects accepted by `init-tracking.py`. - `references/state-schema.md`: authoritative `state.json` fields, status values, and invariants. - `references/phase-transitions.md`: deterministic next-action mapping used by `detect-next.py`. - `references/checklist.md`: required self-audit before iteration summaries and final completion. ## Helper Scripts Resolve `<codex-loop-skill-dir>` to the directory containing this `SKILL.md`. Invoke helpers with `python3 <codex-loop-skill-dir>/scripts/<name>.py`; do not rely on the current working directory matching the skill directory. | Script | Role | Purpose | | --- | --- | --- | | `scripts/init-tracking.py` | bootstrap, mutating | Create `.codex/loop/<name>/`, `request.md`, `state.json`, memory, and task files. | | `scripts/detect-next.py` | read-only | Print the single next action for the current tracked loop. | | `scripts/update-tracking.py` | mutating | Apply task, blocker, verification, and history transitions atomically. | | `scripts/validate-tracking.py` | read-only | Validate tracking artifacts before summaries or final completion. | ## Procedures **Step 1: Route the request** 1. Inspect whether the user needs setup/status help or active tracked execution. 2. For setup/status help, read `references/runtime-setup.md` and follow that lane only. 3. For continuation configuration, read `references/continuation-config.md` before advising or editing config. 4. For tracked execution, continue to Step 2. **Step 2: Bootstrap or resume tracking** 1. Determine the loop name from the `[[CODEX_LOOP name="..."]]` header when present; otherwise derive a short kebab-case name from the task. 2. Run `python3 <codex-loop-skill-dir>/scripts/detect-next.py <name>` from the workspace root. 3. If the action is `bootstrap`, gather the original request and task list. If the user did not provide tasks, decompose the request first. 4. Run `python3 <codex-loop-skill-dir>/scripts/init-tracking.py <name> --request-file <path> --tasks-json '<json>'` or use `--request "<text>"` for short prompts. 5. **STOP. Read `references/tracking-protocol.md`, `references/task-decomposition.md`, and `references/state-schema.md` in full before bootstrapping or resuming tracked execution.** The bullets above are route markers, not the tracking contract. **Step 3: Execute exactly one tracked action** 1. Re-run `detect-next.py` after bootstrap or at the start of every continuation. 2. Follow the printed action exactly: `execute_task`, `verify`, `resolve_blocker`, or `done`. 3. For `execute_task`, work on only the printed task. Write the iteration memory file before calling `update-tracking.py --complete-task`. 4. For `verify`, run the repository-appropriate validation command and only pass `--verify-pass` when real evidence supports it. 5. For `resolve_blocker`, clear blockers only after the underlying issue is actually resolved and recorded in memory. 6. **STOP. Read `references/phase-transitions.md` in full before updating state.** The helper output is authoritative for the next action. **Step 4: Audit, summarize, and stop** 1. Run `python3 <codex-loop-skill-dir>/scripts/validate-tracking.py <name>` before printing an iteration summary. 2. Fill `assets/iteration-summary.template.md` and make it the final block of the assistant message for non-final iterations. 3. For `done`, run `validate-tracking.py <name> --expect-done`, print the summary, then print the literal contents of `assets/done-signature.txt` on the final line. 4. **STOP. Read `references/checklist.md` in full before claiming an iteration or loop is complete.** The checklist is the completion gate. ## Error Handling - If `init-tracking.py` reports that state already exists, switch to resume mode and run `detect-next.py`. - If a helper reports invalid JSON or an invalid transition, fix the input or complete the missing prerequisite; do not hand-edit `state.json`. - If validation fails, record the failure as a blocker with `update-tracking.py --blocker "<summary>"`, print an iteration summary with `outcome=blocked`, and stop. - If the repository verification fails, fix production code or task artifacts rather than weakening checks; then rerun verification before marking `PASS`.