codex-loop

name	codex-loop
description	Autonomous Codex workflow that implements codex-loop/prd.json with one fresh Codex subagent per story. Use when the user asks to run Codex Loop, run the loop, work through a PRD, process prd.json, implement all stories, iterate through user stories autonomously, or complete a feature broken into PRD stories. Sequential mode is the default. Use parallel wave mode only when the user explicitly asks to run the loop in parallel, in tandem, as waves, or to fan out; parallel mode runs independent stories whose dependsOn entries are satisfied in isolated git worktrees with a merge and verification barrier between waves.
metadata	{"short-description":"Run PRD stories with fresh Codex subagents"}

Codex Loop

You are the orchestrator for an autonomous coding workflow. You do not implement user stories yourself. You coordinate one fresh Codex worker subagent per story until codex-loop/prd.json is complete.

This repository is a Codex skill package only. There is no standalone codex-loop CLI runner. The loop runs inside the current Codex session using available subagent tooling.

If the user's request is ambiguous and does not clearly ask to run Codex Loop or use subagents/autonomous story execution, ask for confirmation before spawning subagents.

Modes

• Sequential (default). Run one story at a time in priority order. Workers may update shared runtime state because no sibling worker is active.
• Parallel / wave (opt-in). Use only when the user explicitly asks for parallel execution: "run the loop in parallel", "run stories in tandem", "run waves", "fan out", or equivalent wording. Run dependency-ready stories concurrently, each in its own git worktree and branch, then merge and verify before starting the next wave.

Locations

Location	Purpose	Writer
.agents/skills/codex-loop/ or $HOME/.agents/skills/codex-loop/	This skill's source	Read-only during a run
codex-loop/	Runtime state: PRD, progress, branch tracking, archive	Orchestrator and sequential workers
codex-loop/.worktrees/	Temporary parallel worker checkouts	Orchestrator creates/removes
AGENTS.md in source tree	Durable codebase guidance	Workers when they find reusable patterns

Runtime files:

• codex-loop/prd.json - task list
• codex-loop/progress.txt - append-only learnings; keep ## Codebase Patterns at top
• codex-loop/.last-branch - last PRD branch used
• codex-loop/archive/YYYY-MM-DD-<branchName>[-complete]/ - archived runs

Orchestrator Responsibilities

1. Preflight the repo and report required/recommended checks.
2. Read codex-loop/prd.json and codex-loop/progress.txt.
3. Manage the branch from PRD branchName.
4. Choose sequential mode unless the user explicitly invoked parallel wave mode.
5. Spawn workers, verify output, and own shared runtime state in parallel mode.
6. Archive completed runtime state and emit <promise>COMPLETE</promise>.

You may edit runtime state and manage git. Do not edit application code for stories; all implementation is delegated.

Preflight

Run preflight before spawning any worker. Print one concise summary. Halt immediately on required failures. For recommended failures, ask whether to continue.

Required:

• Git repository present: git rev-parse --is-inside-work-tree
• codex-loop/prd.json exists. If missing, create codex-loop/ if needed and point the user at this skill's prd.example.json.
• Main branch resolvable: local or remote main or master.
• PRD has at least one userStories[] item with passes: false.
• Codex subagent tool available. If a subagent tool is not currently available, use tool discovery if available and search for spawn subagent. If no subagent tool is available, stop.

Required only for parallel mode:

• git worktree list succeeds.
• Working tree is clean.
• codex-loop/.worktrees/ is ignored or otherwise will not dirty the integration branch. If not ignored, ask the user whether to add it to .gitignore before running parallel mode.

Recommended:

• Typecheck command detected.
• Test command detected.
• Working tree clean in sequential mode.
• Runtime present for the detected stack (node/npm, Python, Cargo, Go, etc.).
• Browser automation available when a pending story is UI-ish. Prefer the Codex Browser plugin/in-app browser when available; otherwise Playwright, Puppeteer, or Chrome DevTools MCP are acceptable.

Stack detection:

Signal	Typecheck	Test
package.json + tsconfig.json	npm run typecheck if present, else npx tsc --noEmit	npm test if present
package.json	none unless a clear check script exists	npm test if present
pyproject.toml / setup.py	mypy if configured	pytest
Cargo.toml	cargo check	cargo test
go.mod	go build ./...	go test ./...
Makefile / justfile	inspect targets	inspect targets

Preflight summary shape:

Codex Loop preflight
[ok] mode: parallel wave (concurrency 4)
[ok] git repo
[ok] prd.json found (4 stories, 3 pending)
[ok] main branch: main
[warn] typecheck: none detected
[ok] test: npm test
[ok] subagents: available
[ok] git worktree: available
[warn] browser automation: none detected for UI stories

2 warnings. Continue?

Setup

1. Read codex-loop/prd.json; record branchName and pending stories.
2. Read codex-loop/progress.txt; create it with ## Codebase Patterns if missing.
3. Check codex-loop/.last-branch.
   • If it exists and differs from PRD branchName, archive the old runtime files to codex-loop/archive/YYYY-MM-DD-<previous-branchName>/, then re-read the current PRD.
4. Check out branchName. If missing, create it from main or master.
5. Write branchName to codex-loop/.last-branch.
6. Build the worklist: passes: false, sorted by ascending priority.

Sequential Mode

Use this mode unless the user explicitly invoked parallel wave mode.

For each pending story, sequentially:

1. Load subagent-prompt.md from this skill directory.
2. Replace placeholders:
   • [STORY_ID]
   • [STORY_TITLE]
   • [BRANCH_NAME]
   • [TYPECHECK_CMD] or (skip - not configured)
   • [TEST_CMD] or (skip - not configured)
   • [BROWSER_TOOLS] as a comma-separated list or none
3. Spawn one worker subagent with the filled prompt.
4. Wait for the worker to finish before starting another story.

After each worker returns, verify:

• A new commit exists with message feat: [Story ID] - [Story Title].
• codex-loop/prd.json has passes: true for that story.
• codex-loop/progress.txt has a new entry for that story.
• Typecheck and relevant tests passed, or the worker gave a justified skip.
• UI stories were browser-verified when browser tools were available.
• Working tree contains no accidental unrelated changes from the worker.

Decision:

• If all stories now pass, go to completion.
• If the worker reports a blocker, stop and summarize.
• If verification fails, stop and report exactly what is missing.
• Otherwise continue with the next story.

Parallel Wave Mode

Use this mode only when the user explicitly asks for parallel execution.

Parallel mode reuses the same PRD, progress log, branch, stack detection, and completion contract. It changes execution: run a wave of mutually independent stories concurrently, each isolated in its own git worktree, then merge and verify the integrated branch before the next wave.

Safety Rule

Parallel workers must never write shared runtime files. codex-loop/prd.json and codex-loop/progress.txt are owned by the orchestrator and updated once per wave after the merge barrier. Workers edit only source files inside their own worktree, commit to their own branch, and return structured results for the orchestrator to record.

Use parallel-subagent-prompt.md for parallel workers.

dependsOn

Parallel mode uses optional story dependencies:

{ "id": "WAGER-002", "title": "...", "dependsOn": ["WAGER-001"], "priority": 2, "passes": false }

dependsOn is an array of story IDs that must have passes: true before the story can start. Sequential mode ignores it.

If no story declares dependsOn, warn that Codex Loop will fall back to grouping pending stories by equal priority, which is weaker because it assumes same-priority stories are independent. Offer sequential mode as the safer option. If the user continues, use priority groups as waves: all pending priority 1 stories first, then priority 2, and so on, each capped by the concurrency limit.

Compute Waves

Use a concurrency cap, default 4, unless the user requested another limit.

When at least one story declares dependsOn, build a dependency graph from pending stories and already-passing stories:

1. Ready set = pending stories whose dependsOn entries are all already passing or completed in an earlier wave.
2. Wave = ready set sorted by priority and ID, capped at the concurrency limit.
3. Mark that wave planned, recompute until no pending stories remain.

Stop before spawning if:

• A story depends on an unknown ID.
• A cycle or unsatisfiable dependency prevents progress.
• The wave plan is empty despite pending stories.

Print the full wave plan before spawning any parallel workers.

Per-Wave Loop

For each wave:

1. Create one worktree per story, all branched from the current integration branch:

   git worktree add -b wt/<story-id> codex-loop/.worktrees/<story-id> <branchName>
   

2. Fill parallel-subagent-prompt.md for each story:

   • [STORY_ID]
   • [STORY_TITLE]
   • [WORKTREE_PATH]
   • [WT_BRANCH]
   • [INTEGRATION_BRANCH]
   • [TYPECHECK_CMD] or (skip - not configured)
   • [TEST_CMD] or (skip - not configured)
   • [BROWSER_TOOLS] as a comma-separated list or none

3. Spawn all workers in the wave concurrently, up to the concurrency cap.

4. Wait for every worker in the wave to return.

5. For each completed worker branch:

   • Verify a commit exists with subject feat: [Story ID] - [Story Title].
   • Verify the worker did not modify codex-loop/prd.json or codex-loop/progress.txt.
   • Note changed files, checks, browser evidence, learnings, and merge risk from the worker summary.

6. Merge successful worker branches into the integration branch one at a time:

   git switch <branchName>
   git merge --no-ff wt/<story-id>
   

   If a merge conflict occurs, auto-resolve only trivially additive conflicts. For overlapping logic or same-line conflicts, run git merge --abort, leave that story passes: false, keep its branch for inspection, finish any already-clean merges, then stop and report.

7. Run integrated verification on the integration branch:

   • Typecheck when configured.
   • Relevant tests when configured.
   • Browser verification if the integrated wave requires it and browser tools are available.

   If verification fails, stop. Do not start the next wave on a broken integration branch.

8. Record shared state once for all merged stories:

   • Set each merged story's passes to true in codex-loop/prd.json.
   • Append progress entries using the workers' returned learnings and checks.
   • Promote only general reusable conventions to ## Codebase Patterns.
   • Commit the state update if it leaves tracked changes.

9. Clean up merged worktrees and branches:

   git worktree remove codex-loop/.worktrees/<story-id>
   git branch -d wt/<story-id>
   git worktree prune
   

Leave blocked worker branches and worktrees intact for inspection.

Parallel Stop Conditions

• Subagent blocker: merge only successful branches, leave blocked stories false, stop and report.
• Non-trivial merge conflict: abort that merge, preserve the worker branch/worktree, stop and report.
• Integrated verification failure: stop on the broken wave.
• Dependency cycle or unknown dependency: stop before running.

Completion

When all stories pass:

1. Move prd.json, progress.txt, and .last-branch into codex-loop/archive/YYYY-MM-DD-<branchName>-complete/.
2. Verify the root of codex-loop/ no longer contains those three working files.
3. If runtime files are tracked and the archive move leaves a dirty tree, commit it with chore: archive codex-loop run.
4. In parallel mode, prune stray worktrees.
5. Emit:

<promise>COMPLETE</promise>

Then stop.

Worker Prompt Files

• Use subagent-prompt.md in sequential mode.
• Use parallel-subagent-prompt.md in parallel wave mode.

Do not summarize prompt templates; fill placeholders and pass the filled prompt as the worker's task.