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
- Inspect whether the user needs setup/status help or active tracked execution.
- For setup/status help, read
references/runtime-setup.md and follow that lane only.
- For continuation configuration, read
references/continuation-config.md before advising or editing config.
- For tracked execution, continue to Step 2.
Step 2: Bootstrap or resume tracking
- Determine the loop name from the
[[CODEX_LOOP name="..."]] header when present; otherwise derive a short kebab-case name from the task.
- Run
python3 <codex-loop-skill-dir>/scripts/detect-next.py <name> from the workspace root.
- If the action is
bootstrap, gather the original request and task list. If the user did not provide tasks, decompose the request first.
- Run
python3 <codex-loop-skill-dir>/scripts/init-tracking.py <name> --request-file <path> --tasks-json '<json>' or use --request "<text>" for short prompts.
- 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
- Re-run
detect-next.py after bootstrap or at the start of every continuation.
- Follow the printed action exactly:
execute_task, verify, resolve_blocker, or done.
- For
execute_task, work on only the printed task. Write the iteration memory file before calling update-tracking.py --complete-task.
- For
verify, run the repository-appropriate validation command and only pass --verify-pass when real evidence supports it.
- For
resolve_blocker, clear blockers only after the underlying issue is actually resolved and recorded in memory.
- 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
- Run
python3 <codex-loop-skill-dir>/scripts/validate-tracking.py <name> before printing an iteration summary.
- Fill
assets/iteration-summary.template.md and make it the final block of the assistant message for non-final iterations.
- 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.
- 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.
1---2name: codex-loop3description: Guides Codex Loop setup and long-running tracked execution by installing or refreshing the runtime, explaining activation headers, bootstrapping durable tracking artifacts, decomposing broad requests into tasks, and maintaining per-iteration memory and state. Use for Codex Loop installation, status, activation, or tracked restart-safe implementation, QA, review, and remediation loops. Do not use for one-off coding tasks that do not need Codex Loop or persistent tracking.4---56# Codex Loop78Use this skill for two lanes: runtime setup and restart-safe tracked execution.9The tracking lane creates project-local artifacts under `.codex/loop/<name>/`10so every continuation can resume from durable state instead of chat memory.1112## Required Reading Router1314Match the task to the row. Read the listed files in full before producing15output or running helper scripts. Inline content in this file is a dispatcher,16not the contract.1718| Task | MUST read |19| --- | --- |20| Install, refresh, upgrade, status, uninstall, or explain activation | `references/runtime-setup.md` |21| Configure automatic continuations or project `codex-loop.toml` | `references/continuation-config.md` + `references/runtime-setup.md` |22| Bootstrap a tracked loop or create tasks from a broad request | `references/tracking-protocol.md` + `references/task-decomposition.md` + `references/state-schema.md` |23| Resume a tracked loop after a Codex Loop continuation | `references/tracking-protocol.md` + `references/phase-transitions.md` + `references/state-schema.md` |24| Audit or finalize a tracked loop | `references/checklist.md` + `references/phase-transitions.md` |2526## Reference Index2728- `references/runtime-setup.md`: install, upgrade, status, uninstall, activation header, and current runtime behavior.29- `references/continuation-config.md`: default built-in skill wiring with `optional_skill_name`, `optional_skill_path`, project config, and goal-header examples.30- `references/tracking-protocol.md`: bootstrap, one-action-per-iteration execution, memory-before-state sequencing, blockers, summaries, and done signature.31- `references/task-decomposition.md`: conversion of broad requests into task objects accepted by `init-tracking.py`.32- `references/state-schema.md`: authoritative `state.json` fields, status values, and invariants.33- `references/phase-transitions.md`: deterministic next-action mapping used by `detect-next.py`.34- `references/checklist.md`: required self-audit before iteration summaries and final completion.3536## Helper Scripts3738Resolve `<codex-loop-skill-dir>` to the directory containing this `SKILL.md`.39Invoke helpers with `python3 <codex-loop-skill-dir>/scripts/<name>.py`; do40not rely on the current working directory matching the skill directory.4142| Script | Role | Purpose |43| --- | --- | --- |44| `scripts/init-tracking.py` | bootstrap, mutating | Create `.codex/loop/<name>/`, `request.md`, `state.json`, memory, and task files. |45| `scripts/detect-next.py` | read-only | Print the single next action for the current tracked loop. |46| `scripts/update-tracking.py` | mutating | Apply task, blocker, verification, and history transitions atomically. |47| `scripts/validate-tracking.py` | read-only | Validate tracking artifacts before summaries or final completion. |4849## Procedures5051**Step 1: Route the request**521. Inspect whether the user needs setup/status help or active tracked execution.532. For setup/status help, read `references/runtime-setup.md` and follow that lane only.543. For continuation configuration, read `references/continuation-config.md` before advising or editing config.554. For tracked execution, continue to Step 2.5657**Step 2: Bootstrap or resume tracking**581. Determine the loop name from the `[[CODEX_LOOP name="..."]]` header when present; otherwise derive a short kebab-case name from the task.592. Run `python3 <codex-loop-skill-dir>/scripts/detect-next.py <name>` from the workspace root.603. If the action is `bootstrap`, gather the original request and task list. If the user did not provide tasks, decompose the request first.614. Run `python3 <codex-loop-skill-dir>/scripts/init-tracking.py <name> --request-file <path> --tasks-json '<json>'` or use `--request "<text>"` for short prompts.625. **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.6364**Step 3: Execute exactly one tracked action**651. Re-run `detect-next.py` after bootstrap or at the start of every continuation.662. Follow the printed action exactly: `execute_task`, `verify`, `resolve_blocker`, or `done`.673. For `execute_task`, work on only the printed task. Write the iteration memory file before calling `update-tracking.py --complete-task`.684. For `verify`, run the repository-appropriate validation command and only pass `--verify-pass` when real evidence supports it.695. For `resolve_blocker`, clear blockers only after the underlying issue is actually resolved and recorded in memory.706. **STOP. Read `references/phase-transitions.md` in full before updating state.** The helper output is authoritative for the next action.7172**Step 4: Audit, summarize, and stop**731. Run `python3 <codex-loop-skill-dir>/scripts/validate-tracking.py <name>` before printing an iteration summary.742. Fill `assets/iteration-summary.template.md` and make it the final block of the assistant message for non-final iterations.753. 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.764. **STOP. Read `references/checklist.md` in full before claiming an iteration or loop is complete.** The checklist is the completion gate.7778## Error Handling7980- If `init-tracking.py` reports that state already exists, switch to resume mode and run `detect-next.py`.81- If a helper reports invalid JSON or an invalid transition, fix the input or complete the missing prerequisite; do not hand-edit `state.json`.82- If validation fails, record the failure as a blocker with `update-tracking.py --blocker "<summary>"`, print an iteration summary with `outcome=blocked`, and stop.83- If the repository verification fails, fix production code or task artifacts rather than weakening checks; then rerun verification before marking `PASS`.
compozy