Codex Workflows

Run a Claude Code dynamic-workflow script against a local Codex App Server. The authoring surface is identical to native dynamic workflows — export const meta plus a body using agent(), parallel(), pipeline(), phase(), log(), args, budget, workflow() — but every agent() call runs as one Codex (GPT) thread+turn instead of a Claude subagent.

Manual-invoke only. Claude does not auto-trigger this skill (disable-model-invocation: true); it runs only when the user types /codex-workflows or explicitly asks for a Codex workflow. Once invoked, follow the loop below — the work runs on Codex/GPT agents. If the user actually wanted Claude subagents, say so and point them at the native Workflow tool.

RUNNER below means the bundled runner directory: runner/ relative to this skill's base directory (shown when the skill loads). For a classic skills-dir install that is ~/.claude/skills/codex-workflows/runner — the literal paths in the examples below assume it; substitute your base directory if this skill is installed as a plugin. It is dependency-free Node ≥ 18.

Default rough-intent mode

One or two rough sentences is enough. You do not need to hand this skill a fully-engineered spec — describe what you want (e.g. /codex-workflows Harden this goal before I run it) and the skill compiles it into an operational harness itself: it classifies the job, picks the smallest workable scale, an archetype, and a harness pattern, builds a task contract, composes phases, casts personas, applies the quality/epistemic standards, authors the script, picks safe run settings, and runs it — stating its assumptions as it goes.

Operating rules in this mode:

• The rough intent is the contract. Make reasonable assumptions for anything left unspecified and state them; do not interrogate the user with follow-ups.
• Choose the smallest useful harness, not the largest possible one (see the Anti-overbuild rule).
• Do not emit a giant prompt for the user to paste back. Compile and proceed to authoring/running. (The one exception is prompt-only mode — see Mode detection.)
• This replaces any external "metaprompt": the expansion now happens inside the skill. The whole Compiling rough intent into a workflow section below is that compiler.

Default execution checklist

Every run, in order (the sections below expand each step):

1. Preflight Codex once (handshake.js); note the latest frontier model.
2. Compile the rough intent: classify the job → scale → archetype → pattern (name the failure mode it prevents) → task contract. State your assumptions.
3. Author the script into the repo (./<name>.workflow.js).
4. Settings: --frontier · effort by scale (--effort medium for a quick_harness, --auto-effort for standard/deep) · --sandbox read-only unless it must write · a bounded --budget · strict schemas (additionalProperties:false).
5. Size it — run --plan first for any expensive or complex workflow.
6. Run on the Codex runner (never the native Workflow tool).
7. Surface — inline ASCII map + summarize-run highlights; cite the script, journal, viewer, report, and run-summary paths (see Output behavior).

Mode detection

Read the mode from the user's phrasing, then behave accordingly:

Mode	Trigger	Behavior
default (rough-intent)	1–2 rough sentences	Compile internally → author → run. State assumptions.
--multi (fleet)	the --multi flag, or "fleet" / "several workflows at once"	Compile a fleet plan (2–4 concurrent variant workflows, similar and/or diverse), launch them in the background, and supervise: poll fleet status, answer gates, steer, kill, fork, then synthesize. See Fleet mode.
prompt-only	"prompt-only", "just the invocation", "don't run it"	Emit a complete /codex-workflows invocation/spec (the A–L structure below) and STOP — do not author or run.
write-only	"write it but don't run", "author only"	Author the workflow script, print its path, stop before running.
run-existing	a script path or saved-workflow name is given	Skip compilation; run that script/name through the runner.
quick	"quick", "small", "cheap"	Bias to a quick_harness (2–5 agents).
deep	"deep", "thorough", "exhaustive"	Allow a larger / deep_harness; justify the size.
no-write	"don't write files", "just tell me"	Return final JSON/Markdown only; no report/source files; --sandbox read-only.

Two precedence rules: if the user gives a script path or saved name, run it (don't recompile). If the user gives a detailed spec, honor it as written but still apply the safety + run defaults below. Otherwise it's rough intent → compile.

In prompt-only, the invocation you emit follows the same A–L structure the skill builds internally: A name · B purpose · C task contract · D inputs / context reconstruction · E phases · F personas · G anti-wrapper standards · H outputs · I run settings · J safety / epistemics · K final-response format · L productization. Then stop — do not run.

The loop

In default rough-intent mode, do steps 1–2 silently and state your assumptions before authoring. The mechanics below — handshake, the run command, the inline map — are unchanged; steps 2 and 4 are where rough intent gets compiled.

1. Preflight — once per session, or whenever a run fails to connect, confirm Codex is reachable and authed:

   node ~/.claude/skills/codex-workflows/runner/test/handshake.js
   

   It prints state: ready and the available models. If it fails, tell the user to run codex login (the runner needs a logged-in codex CLI on PATH). From that list, note the latest frontier model — the newest flagship general model (not a -mini/-spark variant; model/list flags it isDefault and its description calls it the strongest). The GPT-5.6 Codex series is Sol (flagship), Terra (balanced), and Luna (efficient); today the frontier is gpt-5.6-sol. Every agent in the run uses it (see Model).

2. Compile the rough intent into a workflow (see Compiling rough intent into a workflow): classify the job → pick the scale → pick the archetype → pick the pattern and name the failure mode it prevents → build the task contract → compose the phases → cast the personas → apply the standards. State the resulting assumptions to the user before authoring.

3. Author a workflow script from that compile (see Authoring). Write it into the user's project so they can read and rerun it — ./<name>.workflow.js, or workflows/<name>.workflow.js / examples/harness-zoo/<name>/ for a reusable harness. Scripts are plain JavaScript using only the injected globals (no imports).

4. Choose run settings (see Run defaults): --frontier, the effort flag for the chosen scale (--auto-effort for a standard/deep harness, --effort medium for a quick one), a read-only sandbox unless the run must write, and a bounded --budget. For an expensive or complex workflow, --plan first — a no-token dry run that counts agents per phase/effort and estimates a --budget.

5. Run it — always pass --frontier, plus the effort flag for the chosen scale: --auto-effort for a standard/deep harness (it scales each agent's effort to its layer's parallel width, so lone synthesis/judge gates think hardest), or --effort medium for a quick harness (see Effort). --frontier pins every agent to the latest frontier model (see Model):

   node ~/.claude/skills/codex-workflows/runner/bin/run-workflow.js <script.js> --frontier --auto-effort [other flags]
   #   quick_harness:  … <script.js> --frontier --effort medium [other flags]
   

   Progress streams on stderr; the workflow's return value prints as JSON on stdout. Capture stdout for the result (… 1>/tmp/result.json) when it's large. To watch the run live, add --tui (live ASCII map in a new terminal window) and/or --gui (live HTML viewer in the browser) — see Running → Live monitoring.

6. Surface the result to the user (see Output behavior) — summarize it, mention the script path, and render the run's ASCII map inline in this conversation so they see the execution graph natively (no window to open):

   node ~/.claude/skills/codex-workflows/runner/bin/map-run.js --journal <journal> --no-color
   

   (<journal> is the path the run logged as ✎ journal: …, default .workflow-journal/<name>.jsonl.) Paste that output into your reply inside a ```text block — it's the orchestrator → phase layers → agent grid → result DAG with per-agent model/effort/tokens/time and a one-line result snippet per agent. Always use --no-color inline (raw ANSI would render as garbage in chat). For live, in-session monitoring, run the workflow with run_in_background and re-render this snapshot a few times while it's in flight (running agents show as ⠋ … running…); for a smooth live window instead, add --tui/--gui (see Running → Live monitoring).

   The run also prints a one-line cost/reliability recap when it finishes. For a fuller breakdown — tokens by phase, the costliest/slowest agents, and any red flags (many nulls, an un-staged huge fan-out, default-effort cost) — run summarize-run on the journal and fold the highlights into your reply (see Summarize a run).

Do NOT call the native Workflow tool while using this skill. Authoring the script and running it through the CLI above is exactly what routes the work to Codex; invoking the native tool would spawn Claude subagents instead.

Fleet mode (--multi): launch, supervise, steer

When the user passes --multi (or asks for a fleet / several workflows at once), you are the operator of N concurrent runs — not a fire-and-forget launcher. You compile a fleet plan, launch every variant in the background, then run a supervision loop: poll status, answer gates, steer drifting workers, kill dead ends, fork promising leads, and synthesize at the end. The human sets policy once (goal, total budget, risk tolerance); you make the mid-run judgment calls the variants can't make for themselves.

1 · Compile the fleet plan

Decompose the intent into 2–4 variants and state the plan (variants, what each bets on, per-run budgets) before launching. Two axes, freely mixed:

• Similar — the same harness, different slices: split a big input across runs via --args, or attack the same question from different starting hypotheses/seeds. One script + per-run --args + --run-id (so the journals don't collide), or N copies of the script.
• Diverse — different harness shapes betting on different theories of the task: e.g. a loop_until_dry bug hunt vs an adversarial_verification sweep vs a sessionful_controller_loop investigation, all aimed at the same goal. One script per variant.

Split the user's overall budget across variants (status shows each run's spend against its ceiling). Size read-heavy fan-outs realistically using the existing GPT-5.5 measurements: an agent whose job is reading a repo/corpus costs ~400–600k tokens regardless of its effort tier — the input dominates, so --effort low does not make a sweep cheap, and --plan's per-effort estimate undercounts it (measured: four "low" sweeps = 2.1M, 525k each, vs a 150k/agent plan estimate). At xhigh — which --auto-effort gives every sessionful worker's turns (width 1) — a reading turn runs ~1–1.5M (measured: a walkthrough worker's first turn + one steer tripped a 2.5M ceiling). Budget ≈ readers × 500k + xhigh reading turns × 1.2M + non-readers × the plan estimate, with headroom. A tripped ceiling is recoverable (--resume replays the prefix free) but costs a supervision round-trip. Apply the Anti-overbuild rule to the fleet too: 2 well-differentiated variants beat 4 redundant ones — every variant must bet on something the others don't.

2 · Author for supervision

Every variant gets supervisor checkpoints — human() gates at the junctures where an outside judgment can redirect the run:

const directive = await human(
  `Round ${round} findings: ${summary}. Directive for next round?`,
  { id: `round${round}`, choices: ["continue", "stop"], default: "continue", timeoutMs: 240_000 })
if (directive === "stop") break
if (directive !== "continue") await worker.steer(directive)   // free text = a steer

This is the steer channel: a free-text answer is the directive, and the script applies it (session.steer(...), re-aiming the next round, narrowing scope). Place gates between rounds, before expensive phases, and on uncertainty. Defaults must be safe — an unanswered gate times out to its default and the run degrades hands-off, never hangs. (This rides the journaled human() channel, so a --resume replays answers instead of re-asking.)

3 · Launch — one directory per fleet, every run in the background

Variants share one directory (that's what fleet status <dir> supervises). Launch each with run_in_background, always with --interactive (it enables the answer channel headlessly):

node ~/.claude/skills/codex-workflows/runner/bin/run-workflow.js hunt-orm.workflow.js \
  --frontier --auto-effort --interactive --budget 1500000 1>hunt-orm.result.json
# same script, different slice → isolate with --run-id:
node …/run-workflow.js hunt.workflow.js --args '{"slice":"auth"}' --run-id auth --interactive …

4 · Supervise — the loop

Poll the fleet digest between other work (and promptly while gates may be pending — they time out to defaults). For long unattended stretches, add --notify-cmd at launch so a pending gate pushes instead of waiting to be polled (e.g. append $WORKFLOW_EVENT to a file you watch, or a macOS osascript notification):

node ~/.claude/skills/codex-workflows/runner/bin/fleet.js status <fleet-dir>   # --json to parse

(When the user wants to watch alongside you, add --watch for an in-place terminal redraw, or --html fleet.html --open for a card-per-run browser dashboard that auto-refreshes while runs are live.)

One line per run — state (running / completed / stopped / idle), phase + agent progress, tokens vs budget — plus an ⚠ line per condition needing you. React:

Signal	Your move
⚠ waiting on [id] "question"	Decide with your full conversation context, then fleet.js answer --journal <J> --id '<id>' --answer '<choice or free-text directive>' (--answer-json for structured)
⚠ stalled (no activity past threshold)	Inspect its stderr/--gui; if hopeless, kill the background task, then rerun with --resume (completed agents replay at 0 tokens; sessionful workers re-attach to their threads warm)
A run chasing a dead end	Kill its task; note why, fold the negative result into the synthesis
A run onto something big	Fork it: copy the journal to a new name, point an edited/extended variant at it with --journal <copy> --resume — the unchanged prefix replays free and only the new direction spends tokens
⚠ at/over budget · stopped	Decide: resume the most promising with a higher --budget, or harvest what's journaled (summarize-run shows where the tokens went)

5 · Harvest and synthesize

When all runs are terminal: read each run's result (<journal>.result.json or the stdout you captured), reconcile agreements/conflicts across variants, and report per-variant: what it bet on, what it found, what it cost (fleet.js status --json has tokens; summarize-run has the breakdown). Negative results from killed runs are findings too. To chain fleets, feed one run's result.json into the next launch's --args-file — composition happens at this level, not inside scripts.

Compiling rough intent into a workflow

This is the skill's internal recipe — the work an external metaprompt used to do. Run these eight steps in order during loop step 2. Keep it lightweight: the output is a small task contract and a phase plan, not a document.

1 · Classify the job

What kind of work is it? This points you at the archetype. One of: analysis · ideation · verification · experiment design · bounded execution · drafting · productization · goal hardening · run summarization · harness design.

2 · Pick the harness scale

Scale	Agents	Use for
quick_harness	2–5	goal hardening, assumption checks, small critiques, quick ranking, small claim verification
standard_harness	6–20	repo analysis, research triage, product-spec review, policy drafting, claim checking, idea generation
deep_harness	20+ / loops	broad discovery, tournaments, large artifact coverage, bounded empirical execution — only when explicitly requested or clearly needed

Rule: choose the smallest harness that can reliably solve the task (see the Anti-overbuild rule).

Effort by scale: a quick_harness runs at a flat --effort medium (or --pin-effort medium) — a small analytical run doesn't need layer-scaled effort. standard_harness and deep_harness run at --auto-effort (lone gates get xhigh, fan-outs floor at high). See Run defaults and Effort.

3 · Pick the archetype

Archetype	When to use
goal_lint ✓	harden a vague Codex/Claude /goal before an expensive agent run
claim_check / proofpack ✓	verify claims in a post / README / report / memo / result / agent output against repo artifacts or sources
research_result_triage	decide whether an experiment / benchmark / result is real, overfit, useful, or worth continuing
next_experiment_designer	design concrete next experiments, falsification gates, and Codex /goals
eureka_forge	surprising, high-upside ideas: diverse personas, forced recombination, hidden mechanisms, falsification
industry_invention_studio	net-new-to-industry products: real pain, workflow novelty, prototype speed, defensibility, anti-wrapper, distribution wedge
repo_deep_read	deep analysis of a repo: what it does, how it works, what's novel, what's brittle, what's buildable
autoresearch_epoch	actually run bounded empirical experiments/evals (not just design them) — explicit execution only
product_spec_review	turn an idea into an MVP spec, architecture, risks, prototype plan, first build /goal
policy_or_grant_builder	an advocacy, policy, grant, research, or memo work product
manuscript_or_citation_audit	manuscript revision, citation checking, claim-support review, journal-fit editing
investment_deep_dive	source-grounded financial analysis, scenario valuation, thesis critique, portfolio fit
root_cause_lab	diagnose a failure / bug / flaky test / broken workflow / failed experiment / confusing logs
agent_rule_miner	mine recurring agent failures, review comments, or corrections into durable CLAUDE.md / AGENTS.md / workflow rules
run_summary ✓	summarize a workflow journal: cost, phase timing, tokens, cached / failed agents, reliability warnings
harness_forge	design the best workflow/harness for a rough task rather than solving it directly

✓ = a concrete template ships today: goal_lint → examples/harness-zoo/goal-lint/, claim_check → examples/harness-zoo/claim-check/ (the trust loop's "after"), run_summary → summarize-run.js (see Summarize a run). The rest are shapes to author from the patterns below, not prebuilt files. Note that harness_forge and the goal_contract_compiler pattern are the skill's own meta-operations — the default rough-intent path is essentially those two.

4 · Pick the pattern + name the failure mode

Choose one or more patterns; state in your final reply which pattern you used and the failure mode it prevents.

Pattern	Failure mode it prevents	Typical shape
fan_out_and_synthesize	premature convergence / single-view bias	parallel independent answers → one synthesizer
adversarial_verification	unsupported claims, self-deception	each finding gets independent refuters; default refuted if weak
generate_filter_improve	thin-wrapper ideation	generate many → filter → improve the survivors
tournament_or_pairwise_judgment	weak ranking (unreliable 1–10)	pairwise / bracket; preserve high-upside losers
loop_until_dry	agentic laziness, missing coverage	keep finding until N dry rounds; dedup vs all-seen; max-round guard
classify_and_act	mis-routing mixed inputs	classify each input → route to the right agent
quarantined_triage	untrusted-input risk	untrusted readers (read-only) kept separate from privileged/write agents
root_cause_hypothesis_lab	confident wrong diagnosis	evidence streams generate competing hypotheses, then refute them
fresh_context_review_gates	self-preferential judging	producers never judge their own work; reviewers get artifacts + rubric only
bounded_empirical_epoch	metric gaming, runaway cost	run evals with keep/discard rules + a hard budget/round cap
goal_contract_compiler	vague goals, missing artifacts/falsification	compile intent → objective, non-goals, allowed actions, success/failure, artifacts, stop
sessionful_controller_loop	babysitting, lost worker context, blind fan-out	spawn long-lived agent.start workers → agent.waitAny for the first → a controller agent decides accept / steer (same thread) / spawn / verify / stop → human only at checkpoints

Full failure-mode vocabulary to draw from: agentic laziness · vague goals · self-preferential judging · unsupported claims · context contamination · weak ranking · premature convergence · thin-wrapper ideation · untrusted-input risk · overbuilding · missing artifacts · missing falsification · metric gaming · source fabrication · file-edit collisions · runaway cost.

4b · One-shot agent() vs sessionful workers

Most workflows use one-shot agent() — a fresh thread+turn per call, which is what fights goal drift and self-preferential bias, and it's the only resumable form. Reach for sessionful workers (agent.start / agent.waitAny / session.steer) only when the job genuinely needs a worker to keep its context across turns:

Use sessionful when —

• a child worker may need follow-up steering on the same context (steer it, don't restart it from a cold prompt);
• the workflow benefits from waiting for the first of several long-running workers (agent.waitAny) and reacting, rather than blocking on all of them;
• a controller loop will inspect snapshots and decide accept / steer / spawn / verify / stop (the sessionful_controller_loop pattern);
• the task is exploratory, long-running, or iterative (investigation, debugging, incremental build-and-correct).

Prefer one-shot agent() when —

• the work is one-shot (a finding, a judgment, a synthesis);
• independent fresh-context review is the point (review gates, adversarial verify — a steered worker carries bias forward);
• the work is a pure cacheable artifact (sessions resume warm via thread/resume, but one-shot replay never depends on a persisted rollout);
• no follow-up steering is expected.