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. The skill id and command stay suede-codex-fleet on purpose: GitHub search, skill marketplaces, and MCP catalogs match the terms people actually type — Codex CLI orchestration, codex exec, multi-agent worker fleet — not the brand name. Do not rename the folder or frontmatter name to match the brand.

> "Fable" in the brand name is not the model claude-fable-5. The workers in this fleet are always OpenAI Codex CLI processes. Never read "Fable Fleet" as license to spawn Claude models.

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)

• which codex && codex --version — CLI present (validated against codex-cli 0.138.0).
• 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.

• 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.
• Workspace has briefs/ and out/ directories (create as needed).

The loop

• Decompose. Split the job into independent worker-sized tasks. Independent means: no worker needs another worker's output.
• 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/.
• 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.
• 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.
• 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.
• Ship. Claude assembles the reviewed survivors into the final deliverable. Report what was spawned, what passed, what got fixed.

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/. 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 -> suede-verify
• Skill authoring/lint questions about this file -> suede-skill-forge