Codex Implement

---
name: codex-implement
description: Delegate a well-scoped implementation to OpenAI Codex through its Claude Code companion plugin in an isolated git worktree, then independently verify it with tests and adversarial review before a user-approved merge. Use when the user wants Codex to implement a bounded change, wants a second model's implementation attempt, or wants a safe Codex implementation-and-review workflow.
---

# Delegate implementation to Codex, then verify

Use the Codex companion's `task --write` runtime. It gives the implementation
session `workspace-write`; it is not a permission to modify the main checkout.
Create the worktree yourself, keep the task inside it, and retain merge
authority.

The review gate for work implemented here is a **non-GPT reviewer, at every
risk level** — the cross-family rule
([`docs/methodology.md`](../../docs/methodology.md) §1) has no LOW-risk
exemption. A `codex-adversarial-review` pass over
Codex's own work is a fresh context, **not** model diversity: legitimate as
an *additional* supplement, never as the gate. HIGH-risk work takes two
reviewers from two non-GPT families.

## Before the first run of a session

Read **[`../codex-adversarial-review/references/codex-runtime.md`](../codex-adversarial-review/references/codex-runtime.md)**.
It holds
the family-level mechanics shared by both codex roles — companion
resolution, the `--background` launcher-output trap, `status` lying about
liveness, report recovery from session rollouts, what the sandboxes can and
cannot do, and the model/effort plumbing. This file assumes them and covers
only what makes a run an *implementation*.

## Preconditions

Use this only for a bounded change with acceptance criteria. Do not delegate a
vague investigation, a destructive migration, production operations, or a task
whose premise has not been checked against the current code.

Before creating a worktree:

```bash
git status --short
git branch --show-current
BASE=$(git rev-parse HEAD)
```

Stop if the target checkout is dirty, the target branch is unclear, or another
agent already owns the same files. Record the exact `BASE`; never replace it
with a moving branch name during verification.

## Create the isolation boundary

```bash
WORKTREE=../<repo>-codex-<short-task-slug>
git worktree add -b codex/<short-task-slug> "$WORKTREE" "$BASE"
```

Worktrees isolate tracked working files, not databases, ports, credentials,
absolute paths, or the shared `.git` directory. They also **omit** everything
git does not track — the virtualenv, the `.env`, built assets — so a pinned
test command naming any of those cannot run there at all; see `dev-lead`
Phase 1 for the measured incident and what to do before dispatch. **Provision
the delegate a sanitized minimum, never the real `.env`** — this sandbox is
`workspace-write` over the whole worktree, so a secrets file copied in is a
secrets file handed over. Do not run two writers in the
same worktree. Serialize tests that share a schema or service, or use an
isolated test resource. Do not pass `--add-dir` unless the extra writable
directory is necessary and explicitly in scope.

## Prepare a premise-checked task

Create a session-specific prompt file with `mktemp -d`; do not use predictable
shared files under `/tmp`:

```bash
RUN_DIR=$(mktemp -d "${TMPDIR:-/tmp}/codex-implement.XXXXXX")

# The helper lives in the SUITE's tree, cwd is the TARGET repo — a bare
# `scripts/…` resolves against the target and exits 127.
DEV_LEAD=${DEV_LEAD_ROOT:-$(ls -d "$HOME"/.claude/plugins/cache/dev-lead/dev-lead/* 2>/dev/null | sort -V | tail -1)}
[ -x "$DEV_LEAD/scripts/snapshot-refs.sh" ] || { echo "dev-lead root unresolved — set DEV_LEAD_ROOT"; exit 1; }
"$DEV_LEAD/scripts/snapshot-refs.sh" save "$WORKTREE" "$RUN_DIR/remote-refs.before"   # push-detection baseline
TASK_FILE="$RUN_DIR/task.md"
```

The prompt must include:

1. Exact acceptance criteria and allowed files/directories.
2. Governing agent-instruction files (`AGENTS.md`/`CLAUDE.md`), ADRs, and
   target tests to read first.
3. A **premise preflight**: compare every factual claim in the task with
   current code, ADRs, and tests. If any premise conflicts, stop before
   editing and report the contradiction with evidence.
4. Required tests — with two shapes measured to matter across delegate
   families (the weakness is the delegate role, not the model): **name the
   existing tests/mocks whose seams the change moves** (the lead greps the
   touched symbols' test-side patches before dispatch; a delegate told where
   the seams are fixes them, one left to discover them breaks them — 18
   broken existing tests in one field test), and **anchor every new test to a
   position** ("class `TestX`, immediately after `test_y`") — a test placed
   outside its class parses as a nested function and is silently never
   collected; only a mutation check catches that after the fact.
5. Tell the delegate to LEAVE its work uncommitted and say so in its report —
   in a worktree it cannot commit anyway (the shared `.git` index is outside
   its sandbox; see below), and asking for a commit it cannot make wastes a
   denied attempt. The LEAD makes the checkpoint commit after verifying.
   State the standing rules verbatim: never push, never reset/clean, never
   alter another branch, no AI-authorship trailers.
6. **Ask it to end by saying where it stopped and what state the file is
   in** — one line, free when the run finishes normally, and the difference
   between a minutes-long handoff and a restart when it does not. See
   "Resuming a run that was CUT OFF" below for what that line buys you.
7. No recursive delegation to Codex, other CLIs, or review scripts. Say it in
   words the delegate cannot read past: **"You are the implementer. Reviews,
   freezing a target and the leg roster are the LEAD's job: do not run any
   review leg and do not read roster.json."** Measured: a write delegate read
   this suite's own skills from its skills directory (a symlink to the lead's),
   took the lead's role, copied the worktree to a temp directory and launched
   three review CLIs, which all died in its sandbox; the implementation was
   complete but the job ended FAILED. A delegate whose skills path contains
   dev-lead can read the lead's instructions — the preamble is what tells it
   they are not its own.

Use a fresh thread for a new task. Resolve the companion per the runtime
file, then:

```bash
cd "$WORKTREE" && node "$SCRIPT" task \
  --background --write --fresh --model <model> --effort high --prompt-file "$TASK_FILE" \
  > "$RUN_DIR/launch.log" 2>&1
JOB=$(grep -o 'task-[a-z0-9-]*' "$RUN_DIR/launch.log" | head -1)   # the id the waiter below takes
```

Model and effort (verified against companion source at 1.0.6: `--effort`
accepts `none|minimal|low|medium|high|xhigh` — the flag's maximum is spelled
`xhigh`). Adapt tiers to your account's catalogue; the shape of the decision:

| tier / effort | when |
|---|---|
| mid tier + `high` | **default** — balanced for well-scoped delegated work |
| frontier tier + `xhigh` | escalation: a fix round failed on reasoning grounds (not test-harness integration), or the domain is concurrency/auth/partial-failure |
| fast tier + `medium` | cheap mechanical sweeps (renames, comment/doc passes) |

Measured caveat before escalating effort: in live rounds the delegate's
failures were test-harness *integration* (broken seams, an uncollected test),
which more reasoning effort does not fix — the lead's verification does.
Escalate effort for reasoning failures, not integration failures.

The effort ladder above the flag (global-config inheritance, and when
omitting `--effort` is a legitimate, deliberate act) is in the runtime file.
Launch under the host's own background mechanism with output to a file, per
the runtime's launcher rules. Do not use
`--dangerously-bypass-approvals-and-sandbox`; `workspace-write` is the
intended write boundary.

**Then await the job, or you will not learn that it finished.** `task
--background` returns as soon as the job is ACCEPTED, so the host's completion
notification fires for the launcher — seconds later — and never for the work.
Measured across a long session: every codex round was discovered only when the
user asked whether it was done, while agy and opencode rounds notified
normally, because those CLIs run in the foreground of the backgrounded command
and codex's does not.

```bash
DEV_LEAD=${DEV_LEAD_ROOT:-$(ls -d "$HOME"/.claude/plugins/cache/dev-lead/dev-lead/* 2>/dev/null | sort -V | tail -1)}
"$DEV_LEAD/scripts/await-codex-job.sh" "$JOB" "$WORKTREE"
```

Run THAT under the host's background mechanism — it blocks until the job
reaches a terminal state, so its completion notification is the job's. The
helper and the reasons not to hand-roll a poll loop are in the
[runtime file](../codex-adversarial-review/references/codex-runtime.md); this
pointer exists because reading only this file leaves you waiting for a
notification that is never coming.

Two sandbox limits from the runtime file shape this role directly: the
delegate **cannot commit from a git worktree** (structural — expect the work
back UNCOMMITTED, and say so in the task prompt so it doesn't waste a denied
attempt; the lead commits as the first verification step) and **cannot bind
AF_UNIX sockets** (pre-brief socket-based tests as an environment limit —
run what it can, list what it could not, never claim unrun tests as proven —
or the delegate burns its run discovering it). Lost reports are recoverable
from session rollouts — runtime file.

## Verify before review

The work comes back UNCOMMITTED (see above), so the order matters: a
`$BASE..HEAD` diff on an uncommitted tree shows NOTHING and reads as a clean
scope check while the entire change sits unexamined in the working tree — a
measured false green.

```bash
cd "$WORKTREE"
"$DEV_LEAD/scripts/snapshot-refs.sh" check "$WORKTREE" "$RUN_DIR/remote-refs.before" || exit 1   # 0. push tripwire, fail-closed
git status --short          # 1. the actual change set, file by file
git diff                    # 2. the actual content (HEAD == BASE here)
# 3. re-run the relevant tests yourself, against this uncommitted state
git add <only in-scope paths>            # 4. the LEAD stages, deliberately
git commit                  # 5. checkpoint commit — REQUIRED before any
                            #    mutation testing or review (git restore
                            #    can only restore what is committed)
git log --oneline "$BASE"..HEAD          # 6. now the ranged checks are real
git diff --check "$BASE"...HEAD
```

Confirm the diff is within scope and the commit carries no AI-authorship
trailer. Do not accept the implementation session's report as evidence for
any of it.

For every new regression test, prove it protects the change: run it on the
base commit or apply a minimal mutation that removes the fix, and confirm it
fails; then restore HEAD and confirm it passes. If this is impractical, state
why and do not call the test a regression proof.

## Review and merge gate

Run the **cross-family** review — Codex implemented, so the gate reviewer is
`claude-`, `agy-`, or a named-family `opencode-adversarial-review` — from
the worktree against `$BASE`, with the changed properties named explicitly.
Use a fresh review job after implementation has stopped; never review a
moving diff. A `codex-adversarial-review` pass may run *in addition* (a
fresh context finds real things), but it never substitutes for the non-GPT
gate. High-risk changes take two non-GPT families.

Verify each finding against code or an executable reproduction. Report the
verified findings, rejected false positives, test results, exact base SHA,
and the complete diff scope to the user. Only after that is approved — by the user, or, where
the roster sets `merge_gate.mode = lead`, by a fully green verdict itself;
anything not green, and any stricter project contract, still goes to the person — may you
fast-forward merge, push to the ref the project's contract names, and remove
the worktree; report the ref. The delegate never pushes.

## Resuming a run that was CUT OFF, not one that was wrong

A delegate that hits its limit mid-edit is a different handoff from one whose
work needs fixing, and confusing them wastes the round. Measured across a long
session: a run ended while "making the first rendering slice", having written
twelve correct tests and left one source file with an unterminated string
concatenation. The suite then reported 265 failures.

**That number was one syntax error.** A file that will not parse fails every
test that imports it. Handed to the next round as-is, the obvious reading is
catastrophe, and the delegate starts "fixing" things that were never broken.
So the resume task must say, in this order:

1. **You were cut off; this was not your decision.** Otherwise the delegate
   treats its own half-finished file as a mistake to undo, and the completed
   part goes with it.
2. **The exact broken state** — file and line, and that it is a half-applied
   edit rather than a reasoning error.
3. **Which failure counts are artefacts.** "Fix the syntax first, run the
   suite ONCE, report that number before changing anything else" — a real
   baseline before any judgement is made against a fake one.
4. **What is already done, and what is left**, measured by you rather than
   taken from the delegate's last message.
5. What NOT to redo. Its tests were fine; rewriting them costs a round and
   risks losing the cases it had already reasoned through.

Ask every implement task to end by saying where it stopped and what state the
file is in — one line, cheap when unused. The run above did that unprompted
("I'm now making the first rendering slice") and it was the whole reason the
handoff cost minutes instead of a restart. A task that instead reports only
success or silence leaves you diffing to find out how far it got.

Do not reach for `--fresh` here. The half-finished worktree IS the context;
a fresh thread re-derives what the previous one already worked out.

When verified findings require fixes, iterate in the SAME worktree: launch a
follow-up task that quotes each verified finding verbatim, with why it is
real and what fix is required, and commits on top — then re-run the full
verification (tests, mutation proof for new regression tests, fresh review of
the new diff). **The verify-order above applies to EVERY round, not just the
first: checkpoint-commit the fix round BEFORE any mutation proof.** Measured
(2026-08-26): a lead ran a mutation against an uncommitted fix round and
restored with `git checkout -- <file>` — which restores to HEAD, wiping the
delegate's entire uncommitted fix in that file; recovery required replaying
`apply_patch` payloads out of the codex session rollout. The commit-first
rule exists in dev-lead Phase 2; the second round is where it gets skipped,
because the first round's commit makes the tree FEEL safe. Measured across
families: findings-quoted-verbatim follow-up
tasks fixed everything on the first try. Small, precisely diagnosed defects
you find during verification are cheaper to fix directly than to delegate a
third round for. When quota is tight, spend Codex on the review gate and
delegate implementation to cheaper pools — review leverage is higher.

## Do not use this when direct implementation is cheaper

For a tiny change, writing and supervising this task costs more than
implementing it directly. This workflow earns its cost when a separate
implementation attempt or an independent review boundary materially reduces
risk.