# Codex Dispatch

Read this before dispatching Codex CLI workers.

## Cost And Auth Policy

Codex can be authenticated through a ChatGPT plan or an API key. ChatGPT-plan
auth consumes plan usage and plan limits vary. API-key auth is token-priced.
Do not promise unlimited or flat-rate worker capacity. Size waves to the user's
available plan, credits, and tolerance for spend.

Useful public docs:

- <https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan>
- <https://learn.chatgpt.com/docs/pricing>
- <https://learn.chatgpt.com/docs/models>
- <https://github.com/openai/codex>

## Preflight

Run once at campaign kickoff:

```bash
codex --version
codex login status
codex exec -s read-only -m gpt-6-sol "Reply with the single word ok"
codex exec -s read-only -m gpt-6-luna "Reply with the single word ok"
```

Record the result in `preferences.md`. The smoke tests confirm the account can
reach the worker and leaf models; GPT-6 rollouts are staged by plan, and
Enterprise workspaces need an admin to enable them. If a model is rejected,
auth fails, or limits are exhausted, route that work to Claude workers until
the user changes the setup, and record the change.

## Worker Brief Contract

Every Codex brief must include:

- Goal and success criteria
- Branch, worktree path, and base commit
- Files/directories owned by this worker
- Files/directories excluded because siblings own them
- Repo conventions to preserve
- Verification command to run from the worktree root
- Required commit message
- Required final report schema
- Fan-out policy: run alone, or spawn at most five named leaves that must not spawn further agents

Codex workers are fire-and-collect. The initial brief must be complete enough to
run without follow-up questions.

## Standard Dispatch

Use `read-only` for scouts, reviewers, and consultations. Use `workspace-write`
for writers.
Keep network on only when the task needs dependency installation, package docs,
or live research. `workspace-write` keeps `.git` read-only, so a brief that
requires a commit needs the worktree's `.git` in `writable_roots`; without it
the worker cannot create `.git/index.lock`.

`approval_policy=never` keeps the envelope fixed: anything the sandbox blocks
fails instead of asking. If a host blocks `never` for unattended runs,
`--approve-for-me` routes escalation requests through Codex's automatic
reviewer. Record that choice in `preferences.md`, since it lets a model widen
the envelope mid-run.

One writer:

```bash
codex exec --json -s workspace-write \
  -c approval_policy=never \
  -c sandbox_workspace_write.network_access=true \
  -c 'sandbox_workspace_write.writable_roots=["<worktree>/.git"]' \
  --output-schema docs/campaign-hq/schemas/worker-result.json \
  -C <worktree> \
  -o docs/campaign-hq/out/<task>.json \
  - < docs/campaign-hq/briefs/<task>.md
```

Read-only scout with live web search:

```bash
codex exec --json -s read-only \
  -c approval_policy=never \
  -c web_search=live \
  -C <repo> \
  -o docs/campaign-hq/out/<task>.json \
  - < docs/campaign-hq/briefs/<task>.md
```

`codex exec` enables web search by default, but in `cached` mode (an
OpenAI-maintained index, no live fetch), so a scout needing the live web must
set `web_search=live`. Values are `live`, `indexed`, `cached`, and `disabled`;
set it per call with `-c web_search=<mode>` or as a top-level config key.
`codex exec` has no `--search` flag; the interactive `codex` command still does.
Check `codex exec --help` for the version in use.

Second Codex home, when the user has configured one:

```bash
CODEX_HOME="<second-codex-home>" codex exec --json -s workspace-write \
  -c approval_policy=never \
  -c sandbox_workspace_write.network_access=true \
  -c 'sandbox_workspace_write.writable_roots=["<worktree>/.git"]' \
  --output-schema docs/campaign-hq/schemas/worker-result.json \
  -C <worktree> \
  -o docs/campaign-hq/out/<task>.json \
  - < docs/campaign-hq/briefs/<task>.md
```

Omit `--skip-git-repo-check` for normal campaign worktrees. A bad `-C` should
fail quickly instead of running outside the intended repo.

## Model And Effort

Three independent controls set a worker's cost and quality: the model, the
reasoning effort (`low`, `medium`, `high`, `xhigh`, `max`, `ultra`), and the
optional `fast` service tier, which runs about twice as fast for more usage.
Codex lists three GPT-6 models:

- `gpt-6-sol`: the campaign worker and the judgment leaves. Default effort in
  this skill is `high`.
- `gpt-6-luna`: the mechanical leaf and scout model, at `max`. Efforts stop
  at `max`.
- `gpt-6-astra`: the most capable model, outside the default fleet. It runs at
  `max`, read-only, only when the user explicitly asks for an exceptional
  effort on a rare, very hard question.

`ultra` is `max` plus automatic delegation, so a worker on `ultra` spawns its
own subagents. No default shape uses it; run it only on an explicit request,
never for a leaf, a consultant, or the Astra run.

Every shape the conductor or an Opus squad lead calls directly:

| Shape | Model | Effort | Sandbox | Use |
|---|---|---|---|---|
| Worker | `gpt-6-sol` | `high` | `workspace-write` | the default; runs alone or fans out to at most five leaves |
| Consultant | `gpt-6-sol` | `high` | `read-only` | architecture answers, review of a Claude worker's diff |
| Arbiter | `gpt-6-sol` | `xhigh` | `read-only` | bake-off judging, final arbitration between a critic and an author |
| Scout | `gpt-6-luna` | `max` | `read-only`, `-c web_search=live` for research | surveys, current APIs, advisories |
| Deep consult | `gpt-6-astra` | `max` | `read-only` | explicit user request only; one very hard question |

Raise a Sol worker to `xhigh` for a task that already failed at `high` or for
thorny debugging, and record the change in the fleet table. A cheap model on
genuinely hard work produces rework, so give Luna only mechanical work.

Above 272K input tokens the API adds a long-context premium. The CLI compacts
near that point unless `auto_compact_token_limit` is raised, so raise it only
for a task that needs a larger window.

Precedence is the user's live request, then a task-specific policy, then
configured defaults, bounded by what the active CLI and account support. A live
request for a specific model or effort wins; do not silently "upgrade" or
"downgrade" it. Prefer per-call flags such as `-m <model> -c
model_reasoning_effort=<level>` when one task needs a different policy; do not
rewrite the user's global config unless asked. If a requested model or effort
value is unavailable, stop and record the limitation instead of pretending the
requested policy was used.

Avoid hard-coded model names in briefs unless they come from `preferences.md` or
the user just specified them. When the user specifies a model or effort policy,
write it into the brief and the fleet table.

## Sol Worker And Leaves

Subagents inherit the parent's model, reasoning effort, and sandbox policy
unless a role sets them. A role is a standalone TOML file under `.codex/agents/`
(project-scoped) or `~/.codex/agents/` (personal). Each file defines `name`,
`description`, and `developer_instructions`, and may set `model`,
`model_reasoning_effort`, and `sandbox_mode`. Built-in roles are `default`,
`worker`, and `explorer`.

- <https://learn.chatgpt.com/docs/config-file/config-reference>
- <https://learn.chatgpt.com/docs/agent-configuration/subagents>

Bootstrap copies three roles from the skill's `assets/codex-agents/`, and
a campaign can edit them, add roles, or ignore them. Roles are named for the
job, so the next model generation changes one line per file:

```toml
# .codex/agents/grunt.toml
name = "grunt"
description = "Mechanical leaf: refactors, fixtures, search, small tests, and routine edits."
developer_instructions = "Own only the files named in your task. Run the verification command before reporting. Do not spawn agents."
model = "gpt-6-luna"
model_reasoning_effort = "max"
```

| Role | Model | Effort | Sandbox | Leaf work |
|---|---|---|---|---|
| `feature` | `gpt-6-sol` | `high` | inherited | A bounded sub-feature, bug fix, or test suite that needs design care. |
| `critic` | `gpt-6-sol` | `medium` | `read-only`, set in the file | Second opinion on a sibling leaf's diff from a fresh session; it cannot patch what it reviews. |
| `grunt` | `gpt-6-luna` | `max` | inherited | Mechanical refactors, fixtures, search, small tests. Move a task that fails verification twice to `feature`. |

A Sol brief can name roles instead of models: "spawn a `feature` leaf for the
parser rewrite, a `grunt` leaf for the fixture updates, then a `critic` on the
parser diff". Leave the decomposition to the Sol worker when the split is not
obvious from outside.

Cap the team at five concurrent leaves:

```bash
codex exec --json -s workspace-write \
  -c approval_policy=never \
  -m gpt-6-sol -c model_reasoning_effort=high \
  -c agents.max_concurrent_threads_per_session=5 \
  -c 'sandbox_workspace_write.writable_roots=["<worktree>/.git"]' \
  --output-schema docs/campaign-hq/schemas/worker-result.json \
  -C <worktree> \
  -o docs/campaign-hq/out/<task>.json \
  - < docs/campaign-hq/briefs/<task>.md
```

`agents.max_concurrent_threads_per_session` caps open subagent threads.
`agents.default_subagent_model` and `agents.default_subagent_reasoning_effort`
set fallbacks; an explicit spawn choice or a role file wins over both. Leaves
inherit the Sol worker's sandbox policy unless their role sets `sandbox_mode`,
so a `workspace-write` worker gives its leaves write access to the same
workspace. The brief must assign each leaf disjoint files.

The `--json` stream shows only the worker's wait calls. Each leaf writes its own
rollout file under `~/.codex/sessions/`, whose `turn_context` records carry the
model and effort it ran with. Read those to confirm a leaf's role took effect;
a worker's self-report about its leaves is not reliable.

No config key limits nesting depth. Every Sol brief must forbid its leaves
from spawning further agents, and leaves stay off `ultra` because that tier
delegates on its own.

## Capabilities

| Capability | Invocation | Campaign use |
|---|---|---|
| Structured final report | `--output-schema docs/campaign-hq/schemas/worker-result.json` | machine-checkable collection |
| Live web search | `-c web_search=live` (default is `cached`, an index with no live fetch; `codex exec` has no `--search` flag) | volatile facts, current APIs, advisories, versions |
| Image input | `-i current.png -i target.png` | UI bug reproduction from screenshots and mocks |
| Image generation | prompt the built-in `image_gen` tool | asset generation; the tool saves under `~/.codex/generated_images/<session>/`, so the brief must require copying the file into the repo and verifying it exists |
| Review mode | `codex exec review --base <ref> -m gpt-6-sol -c model_reasoning_effort=high` | read-only review gate in the consultant shape |
| Session continuation | `codex exec resume <session-id> "<correction>"` | incremental steering after a finished run |
| Native subagents | prompt the built-in multi-agent tools (`spawn_agent`, `wait_agent`, `send_input`, `close_agent`); role files in `.codex/agents/` set each leaf's model and effort; leaves without a role inherit the worker's | a Sol worker fans out up to five leaves inside one workspace; see Sol Worker And Leaves above |

## Steering And Retry

Capture each worker's session id from the `--json` event stream and record it in
the fleet table. Resume when the result is mostly right and needs a correction:

```bash
codex exec resume <session-id> "<correction>"
```

Redispatch from a clean brief when the approach is wrong. Use `codex fork
<session-id>` only when exploring an alternative from the same context is more
valuable than a clean retry.

## Collection

Treat the worker's report as a claim. Inspect the commit, rerun the verification
command, and record the result in `CAMPAIGN.md` and `LEARNINGS.md`.

# Fleet Operations

Read this when more than one writer is active, when work may overlap, or when a
wave must be integrated.

## Invariant

One writer per tree. Shared-tree writes are acceptable only for 2-3 workers with
naturally disjoint file boundaries. Anything larger or overlapping gets one git
worktree and branch per worker.

## Worktree Pattern

Create worktrees from a clean base:

```bash
git status --short
git rev-parse HEAD
git worktree add ../wt-<task> -b campaign/<task>
```

Each writer brief must state:

- Base commit
- Branch name
- Worktree path
- Owned files
- Excluded files
- Verification command
- Required commit message: `campaign/<task>: <summary>`

Uncommitted worker output is not ready for integration.

## Fleet Table

Record every active dispatch in `CAMPAIGN.md`:

| Task | Worker | Branch | Worktree | Session | Dispatched | Status |
|---|---|---|---|---|---|---|

Status should include expected duration for running workers. A worker whose
output file is empty past roughly 3x expected duration is stalled: stop it,
inspect its worktree, then resume or redispatch.

## Waves

Structure large campaigns as waves:

1. Dispatch from the current integrated base.
2. Collect worker reports.
3. Inspect diffs and rerun worker verification commands.
4. Integrate branches in dependency order.
5. Run the decisive project verification command.
6. Update campaign files.
7. Start the next wave from the integrated result.

Cap concurrent writer waves at what the conductor can verify when they land.
Four to six writer branches is a sane default. Read-only scouts and reviewers
can fan out wider because they do not create merge debt.

Do not stack new writer work on unintegrated branches unless the dependency is
explicit. That compounds conflicts and makes verification ambiguous.

## Integration Routing

Merge 1-3 small, independent branches yourself and run tests between merges.

Dispatch an integration worker when there are many branches or semantic overlap.
The integration brief must include:

- Branch list
- Merge order
- Conflict-resolution policy
- Files or subsystems each branch owns
- Full verification command
- Rule that the integration branch stops before merging to main

Route integration by judgment required: Fable 5.1 or Opus 5.5 for design or
product tradeoffs, a Sol worker for mechanical large-scale reconciliation.

## Cleanup

After integration:

```bash
git worktree remove ../wt-<task>
git branch -d campaign/<task>
```

Use `git worktree list` to find stale worktrees, but trust `CAMPAIGN.md` for
purpose and status. Update the fleet table when a worktree is merged and
removed.

# Review Gates

Read this when collecting worker outputs, integrating a wave, handling risky
diffs, or pausing a campaign.

## Worker Report Schema

Every worker report must include:

- `status`
- `branch`
- `commit`
- `files_changed`
- `verify_cmd`
- `verify_result` with `passed` and `output_tail`
- `blockers`

Codex workers should use:

```bash
--output-schema docs/campaign-hq/schemas/worker-result.json
```

Claude workers should end with a fenced JSON block matching the same schema.

## Schema Template

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "worker-result",
  "type": "object",
  "required": ["status", "branch", "commit", "files_changed", "verify_cmd", "verify_result", "blockers"],
  "properties": {
    "status": { "enum": ["done", "partial", "blocked", "failed"] },
    "branch": { "type": "string" },
    "commit": { "type": "string", "description": "sha of the final commit; empty if none" },
    "files_changed": { "type": "array", "items": { "type": "string" } },
    "verify_cmd": { "type": "string" },
    "verify_result": {
      "type": "object",
      "required": ["passed", "output_tail"],
      "properties": {
        "passed": { "type": "boolean" },
        "output_tail": { "type": "string" }
      }
    },
    "blockers": { "type": "array", "items": { "type": "string" } }
  },
  "additionalProperties": false
}
```

## Cross-Model Review

Author and reviewer must be separate. Model families that can review: Claude,
Codex, and Gemini, Grok, or Muse through their OAuth-backed CLIs.

- After a Codex worker lands a high-risk diff, dispatch a Claude reviewer or a
  review from one of the other CLIs.
- After a Claude worker lands a high-risk diff, run a Codex consultation:
  read-only on `gpt-6-sol` at `high`.
- After each wave integration, review the merged result to catch semantic
  conflicts that appear only after individually valid branches combine.

High-risk means auth, permissions, billing, data migration, shared state,
security boundaries, persistent storage, or broad refactors.

Codex consultation, also the shape for architecture questions. Inside a Sol
fan-out the same review runs as a `critic` leaf (Sol at `medium`), read-only
by role file:

```bash
codex exec -s read-only -m gpt-6-sol -c model_reasoning_effort=high \
  -C "$PWD" - < docs/campaign-hq/briefs/<task>.md
```

`codex exec review --base <ref>` runs the built-in review flow and takes the
same `-m` and `-c` flags. Keep the consultant off `ultra`: that tier delegates
on its own, and a consultation is one model reading and advising.

When the user explicitly asks for an exceptional effort on a rare, very hard
question, run the same command with `-m gpt-6-astra -c
model_reasoning_effort=max`. Give it the question, the relevant files, and the
conductor's current answer, and ask for an independent answer with its
reasoning. The conductor weighs both; Astra's answer does not override
verification.

Read-only review from another model family, whichever CLI the user has.
These reviewers are optional and roughly Luna-tier; use them for a different
family's perspective, not as the primary review:

```bash
agy --model gemini-3.8-flash-high --mode plan --sandbox \
  --dangerously-skip-permissions --add-dir "$PWD" --print-timeout 20m \
  -p="<prompt>"

grok -m grok-4.7 --effort xhigh --permission-mode plan --cwd "$PWD" \
  --no-subagents --prompt-file <brief> < /dev/null

muse exec --workspace "$PWD" --trust-workspace \
  --model muse-spark-1.3-contributor --reasoning-effort max \
  --disable-write --prompt-file <brief> < /dev/null
```

For `agy`, attach `-p` to its value with `=` and omit `--effort` in plan mode,
since the tier is part of the slug; a write-mode agent swaps `--mode plan
--sandbox` for `--effort high --mode accept-edits`. `muse` keeps its sandbox
and approval prompts on by default, and its headless options go after `exec`.
Close stdin with `< /dev/null` on headless `grok` and `muse` runs: from a
backgrounded shell they can otherwise exit with no output. Check each CLI's
`--help` for the installed version.

Without a second model available, substitute a fresh reviewer agent that did
not author the diff. Weaker than a different model, still far better than
self-review. Author and reviewer stay separate in every gate.

## Bake-Offs

For a high-stakes task with uncertain solution shape, dispatch the same brief to
two workers in separate worktrees. Pair model families by default: Codex on
`gpt-6-sol` against Claude Opus 5.5. Give a judge explicit criteria before
dispatch, correctness first. The judge is the conductor, or a read-only Codex
arbiter on `gpt-6-sol` at `xhigh`:

```bash
codex exec -s read-only -m gpt-6-sol -c model_reasoning_effort=xhigh \
  -C "$PWD" - < docs/campaign-hq/briefs/<task>-judge.md
```

Give the judge diffs, verification output, and screenshots rather than worker
summaries.

Use bake-offs sparingly because they double worker usage and add judge time.

## Verification

After every worker return:

1. Parse the report.
2. Inspect the commit and diff.
3. Rerun the verification command from the brief.
4. Update `CAMPAIGN.md`.
5. Record a durable lesson in `LEARNINGS.md` when the result teaches something.

Re-verify after each merge to the campaign main line and after each squad hands
back an integration branch.

## Campaign Memory

Keep `LEARNINGS.md` cheap to read:

- Put durable rules at the top under `Standing rules`.
- Keep raw log entries newest first.
- Record a lesson in the same turn when the user corrects routing, effort
  policy, check-in cadence, brief quality, integration frequency, or verification
  expectations.
- Record a lesson after any worker failure that changes future briefs or routing.
- When a lesson repeats or the log passes roughly 40 lines, promote durable
  lessons and delete stale raw entries.
- Put routing preferences in `preferences.md`, not `LEARNINGS.md`.
- Overwrite stale preferences instead of appending history.
- A lesson that holds for any project belongs in the skill itself: offer to
  fold it into the user's installed copy, tightening existing text rather than
  appending.

## Pause Or Stop

On "pause" or "stop":

1. Dispatch nothing new.
2. Let in-flight writers finish when practical.
3. If a worker is clearly stalled, stop it and record what was preserved.
4. Collect reports and note uncollected work.
5. Update `CAMPAIGN.md`, `LEARNINGS.md`, and `preferences.md`.
6. Tell the user the exact branch, wave, and task state for resumption.

# Squads

Read this only when a phase contains a cohesive sub-goal that needs nested
delegation.

## When To Use A Squad

A Sol worker's leaf fan-out is not a squad: it runs inside one worktree and
returns one commit, and the conductor dispatches it like any worker.

Use a squad when several Sol workers must integrate with each other before the
conductor needs the result, when the sub-goal needs design judgment or
mid-flight steering, or when verification is expensive enough that it should
run once at the sub-goal boundary.

Use flat dispatch when tasks can land directly on the campaign main line.
Without intermediate integration, a squad only adds reporting overhead.

## Shape

A squad is one Claude Opus 5.5 lead at high effort that:

1. Receives a sub-goal and namespace from the conductor.
2. Dispatches Sol workers with `codex exec`, one worktree each. Each Sol worker
   may fan out to at most five leaves inside its own worktree.
3. Integrates the Sol branches into one squad integration branch.
4. Runs the squad verification command.
5. Reports one structured result to the conductor.

The conductor merges the squad integration branch later. The squad never merges
to main.

Any worker that can dispatch, integrate, and verify can lead. Opus 5.5 is the
default because squad leads make integration and design calls; drop the lead
to medium effort for a mechanical sub-goal.

## Hard Rules

- Depth caps at three below the conductor: conductor -> Opus lead -> Sol
  workers -> leaves. A Sol worker the conductor dispatches directly has two
  levels: worker -> leaves.
- Only Sol workers spawn leaves. Leaf briefs and role files forbid further
  spawning; Codex workers carry the native spawn tools (nested `codex exec`
  processes are sandbox-blocked; the native tools are not), so the rule has to
  be stated.
- Every lead brief caps concurrent Sol workers, and every Sol brief caps
  concurrent leaves at five.
- Branches and worktrees stay inside the squad namespace.
- The squad lead verifies the integrated branch before reporting.
- The conductor reruns verification when merging the squad branch.
- One conductor fleet-table row tracks the squad integration branch.
- The squad report must enumerate every Sol worker with status, commit sha,
  leaf count, and verification evidence.
- Squads live for one wave and clean up worker worktrees before reporting.

## Namespaces

Assign an exclusive prefix:

- Squad integration branch: `campaign/<squad>`
- Sol worker branches: `campaign/<squad>/<subtask>`
- Sol worker worktrees: `../wt-<squad>-<subtask>`

The brief must forbid branches or paths outside the prefix.

## Squad Lead Brief

Include:

- Sub-goal
- Sibling squads and file boundaries
- Base commit
- Namespace prefix
- Decomposition, or explicit authority to decompose
- Sol worker cap, and the five-leaf cap each Sol brief must carry
- Sol brief requirements (the Codex dispatch brief contract)
- Verification command
- Stop-at-integration-branch rule
- Worktree cleanup requirement
- Report schema

Squad leads orchestrate. They may resolve small merge conflicts, but they should
not write feature code.