Suede Codex Fleet

Suede Fable Fleet

The Suede Fable Fleet: a high-end Claude model is the admiral — it decomposes, briefs, and reviews — and parallel OpenAI Codex CLI workers are the fleet. Do not rename the folder or frontmatter name to match the brand.

The workers are Codex processes — never Claude models

This is the economic point of the skill. Codex workers bill to the user's OpenAI/ChatGPT subscription. Claude subagents bill to their Anthropic limit. Someone asking for a codex fleet is deliberately routing volume off the Anthropic meter — satisfying that request with Claude models inverts the cost model and spends the exact budget they were protecting.

codex exec is therefore the only way a worker runs here. Never substitute Agent, Task, Workflow, subagent fan-out, or any other in-house orchestration for a worker — not with fable, not with opus, not with any model, not "just for this one batch". Claude's role is admiral only: decompose, brief, review, assemble. If you are about to spawn something that is not a codex exec process, you have left this skill — stop and re-read the routing table below.

Preflight failure is a halt, not a fallback. If Codex CLI is missing, not logged in, or not on PATH, say which check failed and ask whether to proceed on Claude models, with a rough estimate of what that fan-out will consume. Never fall back silently.

What getting this wrong costs (measured, 2026-07-27): a Claude-model fleet ran in place of an explicitly requested codex fleet — 3,258 turns, ~1.29 billion tokens, 97% of them cache reads from workers each hauling ~500k tokens of context per turn. About $1,843 of API-equivalent spend, 23% of one weekly allocation, for work that should have cost nothing on that account.

When to use this skill instead of related skills

• suede-codex-fleet (this skill): offload high-volume, well-specified generation to Codex CLI workers; Claude plans, briefs, and reviews
• suede-agent-teams: multi-lane Claude agents coordinating one complex code change with gates and handoffs
• suede-copy / johnny-suede-write: Claude writes the copy itself; right choice when volume is low and judgment density is high

Core principle: Claude tokens buy judgment, Codex tokens buy volume. Clear spec + high volume goes to Codex. Fuzzy spec or expensive-if-wrong stays with Claude. Nothing ships unreviewed.

Preflight (run before first spawn)

1. which codex && codex --version — CLI present (validated against codex-cli 0.138.0).

2. codex login status — must show logged in (your ChatGPT subscription pays for the run).

   Checks 1 and 2 are the cost boundary. If either fails, stop and report which one — do not substitute Claude workers to keep the job moving.

3. Workspace has an AGENTS.md at its root. Codex auto-loads it; it carries voice, context, hard bans, and output conventions so briefs stay short. If missing, write it first — that is the highest-leverage file in the system.

4. Workspace has briefs/ and out/ directories (create as needed).

The loop

1. Decompose. Split the job into independent worker-sized tasks. Independent means: no worker needs another worker's output.
2. Brief. One markdown file per task in briefs/. Codex never sees the Claude conversation, so each brief is self-contained: job, inputs (file paths), exact deliverable, acceptance criteria it must self-check, and the exact output path in out/.
3. Spawn. One codex exec per brief, in parallel, in the background:

caffeinate -i codex exec -C <workspace> --sandbox workspace-write --skip-git-repo-check \
  -o <workspace>/out/<run-name>-final-message.txt \
  "Read AGENTS.md at the workspace root, then execute the brief at briefs/<brief>.md exactly. Write the deliverable to the output file the brief names, run the brief's acceptance-criteria self-check, and state pass/fail per criterion in your final message."

• -C sets the worker's root; --skip-git-repo-check is required outside git repos.
• caffeinate -i (macOS) is standard on every spawn: it blocks idle sleep for exactly the worker's lifetime and releases on exit, so the machine stays awake while any worker is alive and sleeps normally once the fleet drains. A slept Mac kills every in-flight worker silently. Lid stays open — closed-lid sleep overrides caffeinate unless the Mac is in clamshell mode (external display + power). On non-macOS hosts, drop the prefix.
• --sandbox workspace-write only. Never danger-full-access. Workers write files; they do not push, deploy, or touch secrets.
• Leave the model default unless explicitly asked to override with -m.
• Append one row per spawn to out/fleet-ledger.md as each worker starts: brief path, session id (printed at run start), output path, spawn time, and an empty disposition column. This file is the only durable record of the brief-to-session mapping — the transcript does not survive compaction, and without the session id step 5 degrades from a one-line delta into a full respawn of every in-flight worker.

4. Review gate (Claude, mandatory). Read every out/ file. Check against the brief's acceptance criteria and the AGENTS.md hard bans. Worker self-checks are evidence, not verdicts. If the output fails 0 acceptance criteria but has surface defects (typos, formatting, a wrong label), Claude edits the file directly; do not respawn for a comma. Write the verdict into that brief's ledger row — accepted, rejected, or fix brief — along with the running correction count.
5. Delta, don't regenerate. If the output fails 1-2 acceptance criteria, send a one-line correction: codex exec resume <session-id> "<delta>" (session id is printed at run start; resume --last is ambiguous with parallel runs). If it fails 3+ criteria or violates an AGENTS.md hard ban, respawn with the delta appended to the brief. Regenerating from scratch wastes the subscription and loses what was right. Correction budget per output: up to three genuinely different fixes — each attempt must change the diagnosis or the strategy, never rerun the last one. Stop early when the same root cause repeats across attempts; report the repeating cause and let the user pick the next move.
6. Ship. Claude assembles the reviewed survivors into the final deliverable. Prove the fleet is done rather than asserting it: read back a per-output acceptance-criteria pass/fail table from the files in out/, and reconcile out/fleet-ledger.md against the briefs spawned — every brief has a row, and every row carries a terminal disposition. Report spawned count, passed, fixed, and any brief with no accepted output.

Brief template

# Brief <id> — <task name>

Read `AGENTS.md` in the workspace root first. This brief only adds the task.

## Job
<one paragraph: what and why>

## Inputs
<file paths the worker must read>

## Deliverable
<exact structure, counts, variants, labels>

## Acceptance criteria (self-check before finishing)
<numbered, mechanically checkable: limits, bans, required elements>

## Output
Write to `out/<file>.md`. <structure spec>

Fleet workspaces

Keep a persistent workspace per recurring fleet job (a social-content fleet, a test-generation fleet, a refactor fleet) instead of rebuilding context every run. The workspace root holds the AGENTS.md contract, briefs/, and out/ (including out/fleet-ledger.md, which persists across runs). When a brief produces output that passes review cleanly, keep it — proven briefs are the templates for the next run of the same shape.

Hard boundaries

• Workers are codex exec processes, always. Never substitute Claude-model fan-out (Agent, Task, Workflow, subagents) for a worker, on any model — the brand name "Fable Fleet" is not a reference to claude-fable-5.
• Never ship worker output without the Claude review gate.
• Workers never run git push, deploys, or credentialed commands; content and code-edit tasks only, inside the sandbox.
• Secrets never go into briefs or AGENTS.md; workers get file paths, not tokens.
• If a worker's output violates evidence boundaries or hard bans, the fix is Claude's edit or a delta run, never "close enough".

Troubleshooting

• codex exec refuses to start outside a repo: add --skip-git-repo-check.
• Every worker died mid-run with truncated or missing output and no error: the machine slept. Spawn with the caffeinate -i prefix and keep the lid open (or use clamshell mode).
• Not logged in / usage errors: codex login status, then run codex login interactively.
• Worker wrote nothing to out/: read the -o final-message file and the task output log; usually a sandbox denial or a brief pointing at a wrong path.
• Parallel runs are independent processes; spawn each with its own background shell call and collect on completion.

Routing Reference

• Multi-lane Claude agent coordination with gates and handoffs -> suede-agent-teams
• Low-volume, judgment-dense copy -> suede-copy / johnny-suede-write
• Proving the assembled deliverable meets spec -> private Suede Labs companion, not in this pack: suede-verify
• Skill authoring or estate-lint questions about this file -> private Suede Labs companion, not in this pack: suede-skill-forge