codec-build — one model types, the other verifies

If a Codex call fails before any build work starts, re-run Step 0's checks, then read ../codec-review/references/troubleshooting.md. The Windows sandbox/ACL failure and the two model-slug failures all surface as an identical hard error from Codex's stderr, and that file is the only place the three are told apart. It does not load by itself.

The role-flip of codec-review. There, Claude drafts and Codex critiques read-only. Here a builder writes real code and a reviewer judges the diff like a contributor PR.

The user is asked exactly one question: commit or not (plus, only when Codex can't be reached, the Step 0a same-family offer before anything starts). Everything before it — topology, rounds, arbitration — is Claude's call, and none of it is reported mid-run. The commit gate stays because a commit is outward-facing and hard to reverse; refereeing the build is not.

Build rounds run against the real worktree — this is the one thing to get right. Build rounds run against the real worktree with cwd_root = project_root. Staging is a read-scope control for reviews and must never be used here: a build launched with -C pointing at a staging directory writes into the staged copy and leaves the project untouched, producing a build that reports success and changes nothing.

codec-loop.md (bundled with codec-review) is reference for when something breaks — read §1 (asymmetry) and §8 (build completion) on failure or when changing this skill, not on every run.

Adapted from chaseai-yt/claudex-loop's codex-build (MIT — see the repository's NOTICE): its spec-as-work-order contract, bounded fix loop, and round reporting. Its grill-me-codex / grill-with-docs-codex / claudex-loop skills are out of scope.

Spec quality decides success. The builder starts with zero session context — everything it needs must be in the spec file. A plan that survived codec-review is the ideal input.

Which shell

Every command in the loop comes in two forms (the full blocks are in codec-loop.md §5, §8 and §4). In the PowerShell tool (Windows) use the PowerShell form. In the Bash tool (macOS or Linux; Git Bash on Windows also works) use the bash form. Never mix the two in one call, and re-assign variables at the top of every call — they and the working directory do not survive between tool calls. The bash forms use only bash, POSIX tools that ship with macOS, git and node. They were tested under Git Bash on Windows; macOS itself is untested. Advice marked Windows-only does not apply on macOS or Linux.

Hard rules

• Claude writes every commit. Codex never commits. Commits, pushes, and any GitHub mutation happen Claude-side, after the human gate.
• Never skip the diff read. The builder's report is advisory until Claude has read the full diff and run the proof command itself. A pasted proof output is not proof.
• Arbitrate in the main session, never a subagent. If you set CLAUDE_CODE_SUBAGENT_MODEL (for example to sonnet), an "Opus" subagent may silently be a smaller model. The main session is already the stronger model, so judging inline is both correct and free.
• The fix loop terminates. After MAX_FIX_ROUNDS, Opus finishes directly. No unbounded delegation ping-pong.
• Never --yolo. It works but is a hidden, undocumented alias. See codec-loop.md §3b for the bypass rules.
• Run silent. No per-round status in the conversation. The only interruptions are the finished-build banner in step 4 and the commit gate in step 7.
• No per-run exposure prompt — but know what this does. Codex sends whatever it reads to OpenAI, under the user's own account, and in this skill it also writes in the real project (workspace-write). A sandbox restricts writes, not reads: Codex can read any file the user's account can read — the project's .env and data files, and also files elsewhere such as home-directory credentials and global config. Do not raise the topic on every run (the repository README carries the warning), and never describe scope exclusions as enforced. The user should run this skill only on projects and machines where that exposure is acceptable.

Tunables

Step 0 — Can this app reach Codex?

A one-time setup check per computer, shared with codec-review. Codex is needed in both modes (it builds in Mode 2 and reviews in Mode 1). Stop at the first check that fails: tell the user in two or three plain sentences what you found and what to do next. Check 1 failing ends the run. Checks 2–3 failing end it too, unless the user takes the same-family offer in Step 0a.

• Check 1 is free and always applies — it only looks at this session's tool list.
• Checks 2–3 run only when ~/.claude/state/codec/codex-ready.json is absent. When both pass, write that file ({"codex_version": "...", "checked": "<ISO date>"}, creating the folder if needed) and continue silently. When it exists, skip them.
• If any later Codex call fails before build work starts, delete the marker and re-run checks 2–3 before reading ../codec-review/references/troubleshooting.md — a since-logged-out or uninstalled Codex must get this plain explanation, not a raw error.
• Any failed check 2–3 deletes the marker — no exceptions, even when the cause looks temporary or session-specific (a probe kept it once, reasoning "the real setup is probably fine"). The marker means "verified working", never "probably fine".

1. Shell access. No Bash or PowerShell tool in this session (Claude Desktop's Chat tab, claude.ai, mobile) → this skill cannot run here: it drives the Codex command-line program on this computer and builds in the real project folder, and this app can reach neither. Next step: open the project in Claude Code — the Claude Desktop Code tab with a Local session, a terminal, or VS Code — and run the skill again. If a Codex-looking MCP tool is connected, say it isn't used: OpenAI removed the official codex mcp-server, and the build needs local files anyway.
2. codex --version. Fails → Codex isn't installed or isn't on PATH. Next step: npm install -g @openai/codex (needs Node.js), then codex login. With the Codex plugin for Claude Code installed, /codex:setup checks the same things.
3. codex login status. Non-zero exit / Not logged in → Next step: the user runs codex login in a terminal (it opens a browser; a ChatGPT plan or an API key works). Never run codex login yourself — it is interactive.

Step 0a — No Codex connection: offer same-family mode

Same check and same offer as codec-review Step 0a (../codec-review/SKILL.md; look for any other usable Codex route — none of the known ones can build here), worded for a build: "…or reply "use Claude" and a Claude subagent builds it while a different Claude model reviews the diff. That is weaker than a different AI company's model checking the work — same-family models share more blind spots — but it is still a valid, independent review." No answer or anything but a clear yes → end the run. Never switch silently; never write the codex-ready.json marker.

In same-family mode the topology is fixed (no Mode choice):

Claude subagent, model "sonnet"   → builds from the spec (Mode 1 contract: closing JSON manifest)
Claude subagent, a different model ("opus"), subagent_type "Plan" (read-only)
                                  → adversarial review of the diff, codec-review Step 0a critic rules
Opus (main)                       → reads the full diff, runs PROOF_CMD, arbitrates
fresh "sonnet" builder subagent   → applies accepted fixes ... up to MAX_FIX_ROUNDS

Skip Step 4's codex login status re-check. The commit question becomes "A Claude subagent built it, a different Claude model reviewed it (no Codex), proof passes, diff reviewed. Commit?", and the report's header names both models and says "same-family mode — weaker than a cross-vendor review, still independent".

Step 1 — Topology (Claude decides)

Default to Mode 2. It is the more reliable of the two and needs no question. Choose Mode 1 only when the build is large enough that keeping the writing off the main context matters more than reliability, and say which you picked in the report — do not ask.

If the user named Codex ("build it with Codex", "have codex build this"), Mode 2 is fixed — never switch to Mode 1 for context reasons. Once a user planned a Codex build and got Sonnet agents instead, which ended the day with untested code.

Mode 1 — Sonnet builds, Opus judges, Sonnet fixes

Sonnet subagent  → builds from the spec
Codex            → adversarial review of the diff (read-only)
Opus (main)      → judges which findings are legitimate, writes a fix list
Sonnet subagent  → applies the accepted fixes
Codex            → re-reviews          ... up to MAX_FIX_ROUNDS

State the caveats honestly when offering it. Subagents share no context, so the spec and the fix list must be self-contained files passed by absolute path. They return prose, not a patch, so the arbiter re-derives what changed from the diff. And they can silently drop tasks — mitigated by a numbered one-file-per-task list plus a required closing JSON manifest (files_touched, tasks_completed) that the arbiter diffs against the spec. Mode 2 is the more reliable default; Mode 1 exists to keep the heavy writing off the main context.

Mode 2 — Codex builds, Opus reviews, fixes ride the same Codex thread

Codex (workspace-write) → builds from the spec
Opus (main, inline)     → reads the full diff, runs PROOF_CMD
Codex (same thread)     → applies the accepted fixes  ... up to MAX_FIX_ROUNDS

Opus reviews inline, not in a subagent — the arbiter needs the spec, the diff, and every prior round at once, which a subagent gets none of for free. The one legitimate fork is a read-only Explore gatherer on a diff of thousands of lines, which condenses and never decides.

Step 2 — Spec gate

SPEC_FILE must exist and read as a work order: goal, concrete steps, bounds. No spec → route to codec-review to produce one, or write it with the user first. Do not build from a rough idea — that is designing by delegation, and it fails.

Fill the work-order contract in references/build-prompt.md completely. When chained from codec-review, derive it from the converged plan's sections.

Step 3 — Safety gate (before any write)

Never let a builder write with no way back.

Git repo:

1. git check-ignore adversarial-review must succeed. This is a hard gate, not an offer — excluding the directory from a clean-tree pathspec does nothing to stop a later git add . staging briefs and raw model output containing source excerpts, and many Claude Code setups pre-allow git add in their settings. If yours does, this gate is the only thing between those files and a commit.
2. Clean tree, scoped: git status --porcelain -- . ':(exclude)adversarial-review'. Dirty → stop and ask the user to commit or stash. Non-negotiable: a dirty tree means the diff cannot be isolated or cleanly reverted. The exclusion matters because this skill's own logs would otherwise dirty the tree and deadlock its own gate by round 2.
3. Record base_sha.

Not a git repo:

1. Pass --skip-git-repo-check — codex exec otherwise refuses to run at all.
2. Snapshot outside the project: $env:TEMP\codec-snap-<safe_id>\ (Windows) or ${TMPDIR:-/tmp}/codec-snap-<safe_id>/ (macOS/Linux). A snapshot inside the worktree lands inside its own comparison and can recurse while copying. The bash snapshot, manifest and test-restore commands are in codec-loop.md §4.
3. Write a per-file SHA-256 manifest, and verify a test restore into a scratch directory before treating it as a rollback base. An unverified snapshot is not a rollback plan.

Then go. No scope statement, no round-by-round approvals; the gate is at the end.

Step 4 — Build

Re-run codex login status right before launching any builder — this step and every Step 6 fix round, in either mode, whatever the Step 0 marker says. Non-zero → delete the marker, give Step 0's check-3 explanation, and stop before anything writes. The marker cannot cover this: in Mode 1 Sonnet edits the real worktree before Codex's first call, so a since-logged-out Codex would leave changes nobody can review.

• Mode 2: launch per codec-loop.md §5d (PowerShell and bash forms) — -s workspace-write, cwd_root = project_root, no --output-schema. Capture the thread UUID; persist state before launching.
• Mode 1: Agent tool with model: "sonnet", handed the absolute spec path. Require the closing JSON manifest.

Backgrounded rounds are the default. When one finishes, the first line of your next message must be a standalone banner — 🔔 CODEX FINISHED — <what> (exit ok/fail) — verifying now — before any verification output. The user is not watching tool calls; never let a completed build slide silently into the verify phase.

Step 5 — Verify completion, then review

Check the five build completion conditions in codec-loop.md §8 — not the review verdict ladder, which expects a schema object a build never produces.

The condition that matters most: at least one changed application file, computed with the run's own artifacts excluded. Briefs, JSONL, exit files and the run log all live inside the worktree and change on every attempt, so an unscoped diff reports changes even when the builder touched nothing. An empty application diff is the exact symptom of the staging misconfiguration in §1.

Then review properly:

1. Read the full diff. Judge it like a contributor PR: correctness, spec fidelity, style match with surrounding code, nothing touched outside scope.
2. Run PROOF_CMD yourself.
3. Append to the run log: the builder's report summary, then your verdict with what passed and what failed, per-finding.

Completion is not acceptance. It only means the round produced something reviewable.

Step 6 — Fix loop (MAX_FIX_ROUNDS = 2)

Snapshot before each fix round, not once — otherwise round 2 has no clean base to return to.

Write the fix list to a file with the same contract discipline as the spec: exact problem, exact file, expected proof. Mode 2 sends it through the same Codex thread; Mode 1 hands it to a fresh Sonnet subagent by absolute path.

Arbitrate every finding with accepted / rejected / deferred / escalated and a one-line reason. A rejection must cite a file:line or a test result.

After 2 rounds without convergence: stop delegating. Opus finishes the remaining fixes directly and logs the takeover — what was left, and why. Ping-ponging trivia through delegation burns more than it saves.

Step 7 — Human commit gate

Present: a 3-bullet summary of what was built, the files-changed list, the verbatim tail of the proof output with pass/fail, rounds used, any spec deviations, and any accepted risks that materialised.

If a bypass round ran, say so explicitly here (codec-loop.md §3b). A bypass run is unsandboxed and, on Windows with [windows] sandbox = "elevated", can write outside the project, where nothing appears in this diff and no rollback covers it — so the diff must never be presented as a complete account of what changed.

Then ask: "Codex built it, proof passes, diff reviewed. Commit?" — the one question in this skill.

• Commit only on yes, and Claude writes it.
• Rejected → ask what is wrong, route back to step 6, or take over directly if fix rounds are spent.
• Never auto-commit, and never let the builder commit.

Step 8 — The report

Write ~/.claude/reports/<run_id> report.md (central, not per-project — same reasoning as codec-review's report) and give the user its path in one line. Same format — a table of topics and how each resolved, then the short notes — plus the topology used, PROOF_CMD and its result, and whether a bypass round ran. One row per topic, not per finding. No round numbers, no Codex quotes; those stay in the run log under <project>/adversarial-review/.

Step 9 — Rollback

Git: git restore to base_sha. Non-git: restore from the verified snapshot manifest. Either way, state what was restored and what was not.

References

• codec-loop.md — failure playbook and mechanics; §1 asymmetry and §8 build completion are the two that bite
• troubleshooting.md — Windows sandbox ACL fix, model-slug and old-CLI errors, stale broker
• references/build-prompt.md — the work-order contract and the manifest requirement