codex-workflows

name	codex-workflows
description	Run a dynamic-workflow script on a local Codex App Server — orchestrate many Codex / GPT agents (the agent / parallel / pipeline / phase / budget DSL) instead of Claude subagents, for codebase audits, large migrations, and multi-agent review or research. Give it one or two rough sentences and it compiles the right harness for you; add --multi for a supervised fleet of concurrent workflows. Manual-invoke only via /codex-workflows.
disable-model-invocation	true

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.

Compile, don't babysit. When you author a sessionful workflow, the human sets policy (goal, budget, sandbox, involvement mode, stop/escalation triggers) — they do not steer each child. A controller agent makes the semantic call; the script enforces it; the human re-enters only at a checkpoint. Declare an involvement mode and default to checkpointed:

• hands_off — never pause; safe defaults, mark uncertainty, avoid risky/destructive actions.
• checkpointed (default) — pause only at plan / write / budget / scope gates.
• interactive — pause at declared forks via the human(question, { id, choices, default, timeoutMs }) global: with --gui the live viewer shows an answer card; with --tui/--interactive the human appends to <journal>.answers.jsonl. It resolves from args.checkpointAnswers / the journal (--resume never re-asks) before the live channel, and falls back to default on timeout — never hangs.

Never make the workflow block on live human input. When a decision truly needs a human (scope, cost, risk, destructive action, value judgment), return a structured checkpoint — { status: "needs_human", question, choices?, recommendedDefault, reason, ledger, resumeInstructions } — and stop. The pattern is in examples/sessionful-workers.workflow.js and references/authoring.md → Sessionful workers.

5 · Build the task contract

A small contract that guides the script. Define: objective · non-goals · assumptions · allowed files/actions · forbidden files/actions · success criteria · failure criteria · required artifacts · stop condition · human-review triggers (if any) · sandbox requirement — and classify the workflow as read-only, report-writing, or execution-capable. (This mirrors GoalLint's hardened_goal schema — see examples/harness-zoo/goal-lint/.)

Inputs & context reconstruction. Tell agents which local files/dirs to inspect to reconstruct project state — likely: README.md, CLAUDE.md, AGENTS.md, .claude/, workflows/, examples/, reports/, results/, runs/, logs/, docs/, experiments/, data/, .workflow-journal/, and recent artifacts. Require the workflow to infer state and state its uncertainty. If freshness or external/current facts matter and there is no source/web access, require a source-gap report rather than fabrication.

6 · Compose phases

Pick only the phases the chosen scale needs (a quick_harness may be just two):

Phase	What it does
Context reconstruction	reconstruct objective, assets, recent attempts, constraints, success criteria, uncertainty
Inventory	locate relevant files, reports, logs, journals, code paths
Diverse fanout	parallel agents with genuinely different cognitive roles (not superficial personas)
Discovery loop	loop-until-dry; dedup vs all seen items; hard max-round / budget guard
Cross-pollination	force recombination across pains / mechanisms / user types / primitives / wedges / failures / analogies
Adversarial verification	independent verifiers; default to refuted/unsupported if evidence is weak
Harsh critique	skeptics attack novelty, feasibility, self-deception, overbuild, thin-wrapper, metric gaming, source weakness
Tournament / pairwise	rank where 1–10 is unreliable; preserve weird/high-upside losers separately
Scoring	structured dimensions; prefer pairwise over 1–10 for subjective taste
Fresh-context review gate	producers don't judge themselves; reviewers get artifacts + rubric, not self-justification
Portfolio synthesis	select best outputs by category, not one winner
Goal writer	write strict Codex /goals for the top 1–3 next actions
Report writer	reports/<name>.md when workspace-write is allowed, else Markdown in the final JSON
Run summary	for an existing journal: agents / cached / failed, tokens by phase, slowest / costliest, model·effort, warnings, a --resume hint

7 · Cast personas

Use functional personas (each performs a specific operation) — never generic "optimist / pessimist."

• Ideation: Falsifier · Signal Miner · Mechanism Theorist · Benchmark Surgeon · Weird Analogist · Toolsmith · Workflow Anthropologist · Developer-Tool Founder · Enterprise Buyer · OSS Maintainer · Eval Maximalist · Agent-Ops Engineer · Historical Skeptic · Product Translator · Alien Reviewer · Bitter Reviewer · Regulated-Workflow Designer · Skeptical Customer · Timing Critic · Wrapper Critic.
• Verification: Claim Extractor · Evidence Finder · Refuter · Source-Freshness Checker · Counterexample Finder · Methodology Reviewer · Artifact Auditor · Reproducibility Reviewer.
• Debugging / root cause: Log Reader · Code-Path Tracer · Environment/Resource Investigator · Recent-Diff Reviewer · Hypothesis Generator · Hypothesis Refuter · Minimal-Repro Designer · Fix-Scope Controller.

8 · Apply standards

Anti-wrapper (ideation / product archetypes): reject generic "AI assistant for X" and "LLM + UI" unless there is a new workflow primitive / provenance / eval loop / artifact graph / coordination / memory / trust mechanism / distribution wedge. Reject "run more seeds / scale up / improve prompts / add RAG / make a dashboard" unless tied to a non-obvious mechanism and a falsification test. Favor ideas where the hard part is evidence, workflow, eval, provenance, memory, coordination, or trust — not the model call — that change a workflow (not just automate a task) and carry hard-to-fake usefulness signals.

Epistemic discipline (always): state assumptions; don't overclaim; separate confirmed evidence from plausible inference; never fabricate current facts or source support; preserve uncertainty; include adversarial review where claims could be wrong; give falsification criteria for claims / experiments / hypotheses; no producer self-judging; don't modify source unless explicitly requested; keep untrusted-input readers separate from privileged/write agents; treat missing metrics, artifacts, or source evidence as failure or uncertainty — not success.

Anti-overbuild rule

Not every rough intent needs a fleet. Simple task → quick_harness. One-off analysis → don't write files you weren't asked for. Use a deep_harness only when breadth / loops / tournaments are clearly justified. Overbuilding is itself a failure mode: don't turn "check my README for typos" into a 12-agent panel.

Run defaults

Policy for every run (flag syntax and precedence live in Running and Effort — this section is the policy, not the reference):

Situation	Setting	Why
Always	the Codex runner, not the native Workflow tool	routes work to Codex/GPT, not Claude subagents
Always	write the script into the repo	reproducible and rereadable
Model	--frontier	one frontier model for every agent (see Model)
Effort — quick_harness	--effort medium (or --pin-effort medium)	a small analytical run doesn't need layer-scaled effort; a flat, cheaper tier suffices
Effort — standard / deep	--auto-effort	scales effort to layer width; lone synthesis/judge gates get xhigh, fan-outs floor at high
Default sandbox	--sandbox read-only (pass it explicitly)	the runner's own default is workspace-write — don't rely on it
Writing a report / running experiments / requested edits	--sandbox workspace-write	only when the run must write
Never (unless explicitly requested and justified)	--sandbox danger-full-access	unsandboxed
Cost	a bounded --budget, sized via --plan	hard ceiling; --plan estimates it
Expensive / complex run	--plan first	no-token dry run before the live run
Structured output	JSON schemas with additionalProperties: false	strict and parseable
After the run	viewer via view-run.js --open; summary via summarize-run.js or --summary	inspect cost / shape

Three facts to encode correctly, since they're easy to get wrong:

• No workflow linter exists — the only pre-flight is --plan. Use it.
• No --concurrency flag exists — concurrency is fixed at min(16, cores−2). Don't recommend one; if a run is resource / eval-bound, lower the fan-out width in the script instead.
• --summary prints inline; summarize-run.js --out PATH writes a file — use the latter when you need a run-summary path. The HTML viewer is a file from view-run.js --open; --gui is a live window, not a saved artifact.

Productization (for reusable harnesses): parameterize with args; avoid hardcoded one-off paths; add a short README/usage note for a harness-zoo workflow; name it for future install into .claude/workflows/; keep the script plain JavaScript using only the injected globals (no imports / fs — agents do all I/O).

Model: one frontier model for every agent

Use a single model — the latest frontier model — for every agent in the run. Do not mix models, and do not downgrade "cheap" or "simple" stages to a smaller or older model. The GPT-5.6 Codex series is Sol (flagship), Terra (balanced), and Luna (efficient). The frontier model is the newest flagship identified at preflight (isDefault; currently gpt-5.6-sol) — never gpt-5.4/gpt-5.2 or a -mini/-spark variant.

Enforce it with --frontier (always pass it): the runner auto-detects the latest frontier model from model/list and pins every agent to it, overriding any per-call model a script sets. This is a hard guarantee — even if a script asks for gpt-5.4, --frontier forces it to the frontier and logs the override. (To pin a specific model instead, use --pin-model gpt-5.6-sol.)

Also good practice, though --frontier makes it non-essential: don't set a per-call model in scripts — leave model out of every agent() opts object.

Need to bound cost? Lower effort (see below) and set --budget — do not switch models.

Effort: scale thinking to layer width

Thinking effort is the second dial (after model). The principle: the fewer agents run in parallel at a step, the more pivotal each one is, so the harder it should think. A lone agent in its layer is almost always a critical gate — a consolidation, a judge/synthesis, a final report — where one weak output sinks the whole run; it earns the auto-policy's extra-high xhigh tier. A 12-wide persona fan-out is the opposite: each agent is one voice among many, and redundancy covers individual misses.

For a standard or deep harness, pass --auto-effort (a small quick_harness runs at a flat --effort medium instead — see Harness scale selector). The runner reads each layer's parallel width (the number of thunks in a parallel(), or items in a pipeline() stage) and sets effort automatically:

Parallel agents in the layer	Effort	Typical role
1 (lone)	xhigh	consolidate / judge / synthesize / report — critical gate
2+ (any fan-out)	high	floor — wide fan-outs still think hard

So in a forge-style run, the consolidate, portfolio-judge, and report-writer agents automatically get xhigh; every fan-out — the 3–4-wide pain/mechanism/ recombination waves and the 12-persona / 8-critic layers alike — gets high. The floor is high; the policy never drops to medium. No per-agent bookkeeping.

Precedence (highest first): --pin-effort E (force every agent to E) → a script's per-call effort → --auto-effort layer policy → flat --effort E → inherited user config or model default. Because per-call effort overrides the policy, do not hand-set effort in scripts — leave it out and let --auto-effort govern; reserve a per-call effort for a rare, deliberate exception (e.g. forcing xhigh on one unusually hard agent inside a wide layer).

Bound cost without touching the model: keep --auto-effort but add a --budget backstop, or drop everything a tier with --pin-effort medium. For a small quick_harness, flat --effort medium is the right default (cheaper, uniform); the layer-aware policy matters most for multi-phase standard/deep runs.

Authoring (quick reference)

A script is a JS module that starts with a pure-literal meta and then uses the injected globals. Top-level await and a top-level return (the workflow's result) are supported.

export const meta = {
  name: 'audit-auth',
  description: 'Check every route for missing auth',
  phases: [{ title: 'Scan' }, { title: 'Verify' }],   // titles match phase() calls
}

phase('Scan')
const findings = await pipeline(
  args.files,                                               // args = value passed via --args
  (file) => agent(`Audit ${file} for missing auth checks.`, { schema: FINDINGS, label: file }),
  (res, file) => parallel(res.findings.map((f) => () =>     // verify each as soon as its scan lands
    agent(`Adversarially confirm: ${f.title} in ${file}. Default to refuted if unsure.`,
          { schema: VERDICT }).then((v) => ({ ...f, verdict: v })))),
)
return findings.flat().filter(Boolean).filter((f) => f.verdict?.real)

Globals:

• agent(prompt, opts?) → the agent's final text, or (with opts.schema) the parsed object, or null if interrupted. This is the only global that calls a model.
• parallel(thunks) → barrier fan-out; a thunk that throws becomes null (so .filter(Boolean)).
• pipeline(items, ...stages) → per-item staging, no barrier; a stage that throws drops that item to null. Stages get (prev, originalItem, index).
• phase(title) / log(msg) → progress (stderr).
• human(question, { id, choices, default, timeoutMs }) → a declared checkpoint fork (the answerer can be a human or a supervising agent): resolves from args.checkpointAnswers / the journal first, then the live channel (--gui answer card, fleet.js answer, or the answers sidecar), else the default on timeout — never hangs unattended. Journaled (--resume never re-asks); not an agent. In fleet mode this is the steer channel — author gates whose free-text answers the script applies (see Fleet mode).
• args → the value passed via --args / --args-file.
• budget → { total, spent(), remaining() } (token accounting).
• workflow(ref, args?) → run another script inline (one level). ref is a { scriptPath }, a path string, or a saved-workflow name resolved from .claude/workflows/ then ~/.claude/workflows/.
• agent.start(prompt, opts?) → an AgentSession (long-lived worker; returns before the turn finishes). agent.waitAny(sessions, opts?) → the first actionable one. session.steer(msg, {wait}) runs a follow-up turn on the same thread; session.wait/poll/cancel/close. Sessions resume warm on --resume (thread/resume re-attaches the persisted thread; completed turns replay free); use sessions for steerable/iterative work (see 4b · One-shot vs sessionful workers).

Key agent() opts: schema (JSON Schema → Codex outputSchema, result parsed), model (Claude ids/aliases auto-map to a Codex model), agentType (loads .claude/agents/<name>.md as the system prompt), systemPrompt, effort (usually omit — let --auto-effort scale it to layer width; see Effort), sandbox (read-only | workspace-write | danger-full-access), isolation: 'worktree', cwd, personality, retries, label, phase (group/attribute this agent — set it inside concurrent pipeline/parallel stages), timeoutMs.

Read references/authoring.md for the full guide and the standard quality patterns (adversarial / majority refute-by-default verify, judge panel, loop-until-dry, fresh-context review gate, multi-modal sweep), and examples/ for runnable templates — hello, review, bug-hunt (loop-until-dry + majority verify), review-gates (producer ≠ reviewer), and the sessionful demos sessionful-workers, warm-context-interrogation (load once, ask many), flaky-bug-perturbation (hold + perturb live state), hedged-take-first-win (race + cancel), lead-following-research, stateful-dialogue, agent-foreman.

Running

run-workflow <script.js>
  --args JSON | --args-file PATH   value exposed to the script as `args`
  --frontier       pin ALL agents to the auto-detected latest frontier model (recommended; overrides per-call model)
  --pin-model M    pin ALL agents to model M (overrides per-call model)
  --model M        fallback model when not pinned; Claude ids/aliases auto-map
  --effort E       none|minimal|low|medium|high|xhigh; flat fallback; unset → user config or model default
  --auto-effort    scale effort to layer width: 1→xhigh, 2+→high (floor) (recommended; overrides --effort)
  --pin-effort E   force ALL agents to effort E (overrides per-call effort)
  --sandbox S      read-only | workspace-write | danger-full-access  (default workspace-write)
  --budget N       token ceiling backing budget.total / budget.remaining()
  --budget-meter M what budget.spent() counts: total (default) | output (native pool)
  --plan           dry run: count agents per phase/effort + estimate a --budget (no tokens)
  --tui            open a LIVE ASCII map of the run in a new terminal window
  --gui            open a LIVE HTML viewer of the run in your browser (--monitor = both)
  --interactive    enable the human() answer channel headlessly — answered via
                   fleet.js answer (a supervising agent) or the answers sidecar
  --run-id NAME    suffix the default journal/sidecars so concurrent runs of the
                   SAME script don't collide (fleet mode)
  --notify-cmd C   run shell command C (detached, best-effort; event JSON in
                   $WORKFLOW_EVENT) when a gate goes pending / the run ends;
                   implies --interactive
  --retries N      transient-error retries per agent (default 3)
  --resume         reuse prior results from the journal (skip unchanged agents)
  --journal PATH | --fresh | --no-journal

• Live monitoring (--tui / --gui) — when the user wants to watch the run, add --tui and/or --gui. The runner auto-opens a live monitor that tracks the journal + event stream as the run progresses, showing every agent (running + done) with constant updates: --tui opens the ASCII execution map in a new terminal window; --gui opens the self-contained HTML viewer in the browser; --monitor opens both. They run alongside the workflow (which still prints its result JSON to stdout as usual), so pass them in addition to --frontier --auto-effort. Both need journaling (not --no-journal). The --gui viewer updates in place (no reload/flicker), shows each running agent's streaming output in the drawer, and settles to the finished run automatically.

• Cost — a run can spawn many agents and use real tokens. Keep the single frontier model (see Model) and bound cost with --auto-effort (already cheaper on wide layers) plus a --budget backstop — not by downgrading to a smaller model. To squeeze further, --pin-effort low. Use --sandbox read-only unless agents must edit files.

• Sizing --budget — it is a hard ceiling that throws mid-run, not an advisory: size it for the whole fan-out, not one agent. Run --plan first — a no-token dry run that counts agents per phase/effort and prints an estimated --budget (a lower bound for fan-outs sized from agent output). Based on the existing GPT-5.5 measurements, a medium-effort frontier run spent ~0.3–0.5M tokens/agent (reasoning included), so an N-agent run wants --budget ≈ N × 500k with headroom. (A 35-agent run blew past an 8M ceiling after only ~17 agents.) Read-heavy agents break the per-effort estimate: an agent that reads a repo/corpus costs ~400–600k even at --effort low (input dominates) — cost those at ~500k each no matter the effort tier. Tripping it isn't fatal — the CLI prints a ready-to-paste --resume command with a higher ceiling, and the cached agents replay at 0 tokens.

• Effort (important) — prefer --auto-effort, which sets each agent's effort from its layer's parallel width (1→xhigh, 2+→high; the floor is high; see Effort). Otherwise the runner only sends an effort when you set one (per-call effort or --effort); when nothing is set, each agent inherits an explicit model_reasoning_effort from the user's Codex config, or the selected model's catalog default when that setting is absent. GPT-5.6 Sol's catalog default is low, so unspecified effort does not universally mean xhigh. For any multi-agent run, pass --auto-effort (best) or at least a flat --effort; never leave effort unspecified.

• Resume — every run journals each completed agent() result. If a run is interrupted or trips --budget, rerun with --resume (and the same model + effort flags + sandbox) — completed agents return from cache (0 tokens) and only the rest run. The effective effort is part of each agent's cache identity, so toggling --auto-effort/--pin-effort between runs re-runs the agents whose effort changed. --fresh discards the journal.

Behaviors to know

• Isolation — the script runs in a locked-down node:vm context: it can only coordinate agents, with no process/fetch/require/import()/fs/timers. The agents do all file/command I/O (via the Codex sandbox). Don't write a script that tries to read files itself — have an agent() do it.
• Model mapping — a script that requests claude-opus-4-8 or a bare opus/sonnet/haiku maps Opus → Sol, Sonnet → Terra, and Haiku → Luna when those GPT-5.6 Codex tiers are available, with an available-model fallback. Don't rely on that: pin every agent with --frontier (or --pin-model gpt-5.6-sol) — see Model. (--model is only the fallback default; a per-call model in the script overrides it, so it does NOT guarantee one model for every agent.)
• Determinism — Math.random(), Date.now(), and argless new Date() are blocked inside scripts (they'd desync resume). Pass values via args.
• Per-turn timeout, and "failed" ≠ "did nothing" — each agent() turn must finish within 600s (codexAgent.js default; raise it per-call with timeoutMs for a heavy agent). A single monolithic agent — huge input + long output + a file write — is the usual culprit and trips Timed out waiting for app-server notification. Two takeaways: (1) split heavy synthesis/report stages or bump their timeoutMs; (2) a timed-out/"failed" run may have already written files and journaled completed agents — inspect the workspace and .workflow-journal/<name>.jsonl before redoing work, then --resume to finish (or assemble the final artifact from the journal results).
• Limits — up to min(16, cores−2) agents run concurrently; 1,000 per run.

Output behavior

When you surface the result (loop step 6), the final reply should include, as relevant to the archetype:

• a concise executive summary;
• the archetype and harness pattern chosen, and the failure mode it prevents;
• the assumptions you made compiling the rough intent;
• the strongest outputs — top findings / ideas / experiments / claims / hypotheses — each with why it matters, why it's non-obvious, the evidence for it, the evidence against or weakening it, and what would falsify it;
• the single best next action;
• generated Codex /goal prompts, if relevant;
• uncertainty and source gaps, if relevant;
• safety notes, if relevant;
• paths: workflow script, journal, viewer, report/output artifacts, run summary.

Keep confirmed evidence separate from plausible inference, and don't overclaim — missing metrics / artifacts / evidence are uncertainty, not success.

When not to use

• The user wants Claude subagents → use the native Workflow tool, not this.
• A single quick task that doesn't need fan-out → just do it directly.
• The user wants the in-app /workflows progress UI or to save a /command — that's the native feature; this skill is a standalone Codex-backed runner.

View a past run

Every completed run leaves a journal at <project>/.workflow-journal/<name>.jsonl. To inspect it as a polished GUI, generate a self-contained HTML viewer:

node ~/.claude/skills/codex-workflows/runner/bin/view-run.js <project-dir> --open

For a terminal-native view (no browser), render the run as an ASCII map — add --watch to redraw it live as the run progresses:

node ~/.claude/skills/codex-workflows/runner/bin/map-run.js <project-dir> [--watch]

It auto-finds the journal and the *.workflow.js script in that dir (or pass --journal PATH / --script PATH / --out PATH), writes <name>.run.html, and --open launches it. When a run directory holds several journals, all three tools (view-run, map-run, summarize-run) default to the most recently modified one; pass --list to see them all and --journal PATH to pick a specific one. Offline/self-contained (data embedded). Per-agent tokens, time, model, and effort (recorded by the runner) show per agent, per phase, and per run; add --watch for a live monitor that updates in place — no reload, no flicker (theme / view / selected node / open drawer / scroll / zoom all survive each update). Two views, toggled top-right:

• ◇ Map (default) — the execution map: orchestrator → one row of parallel agents per phase → barrier merges → result. Each node shows its model / time / tokens; click any for a docked inspector (the map stays visible behind it) with its full result — and a running agent streams its partial output there live. The result node shows the workflow's actual return value. Wide phases fold into an aggregate node you expand inline (running agents are never hidden); not-yet-started phases show a "pending" placeholder. Opens at a readable 100%; F=fit whole graph, 0=reset, scroll zooms toward the cursor, drag pans.
• ☰ Tree — a dense Run → Phase → Agent inspector: phase progress bars with inline per-agent time / tokens / model, and the run's actual result at the top.

A Dark / Light toggle (top-right) switches themes; the light/cream theme is a clean diagram style (black orchestrator/result nodes, white agent nodes, dark arrows). Both views render results generically: tables for arrays-of-objects, color swatches for palettes, severity/effort badges, 1–10 score pills, and a raw-JSON toggle per agent.

It works for any run: barrier/phase or pipeline shapes, flat label-less runs (grouped under one phase), huge fan-outs (phases over ~12 agents fold into an aggregate node you expand inline; the Tree shows all), journal-only runs with no script (no model chips), and string/null results. runner/test/view-run.test.js smoke-renders all these shapes.

Summarize a run

For a cost / performance / reliability report instead of a visual — what the run cost, where the time and tokens went, and whether anything looks off — point summarize-run at the journal (or run dir):

node ~/.claude/skills/codex-workflows/runner/bin/summarize-run.js <project-dir>
#   --json        structured (the summary object)        --markdown   paste-ready
#   --out PATH    write to a file                         --include-result  preview the return value

It reports agents (total / completed / null / cached / interrupted), agents· tokens·agent-time by phase, the top 10 costliest and slowest agents, a model & effort breakdown, budget usage (when the run recorded a ceiling), and cache hit rate on a resumed run — plus warnings (missing metrics, many nulls, interrupted agents, a single huge fan-out, default-effort cost). It's read-only (never touches the journal) and handles older journals that predate the per-agent metric fields. Use it to answer "how much did that cost / what was slow / did it all complete?" Paste the text report inline, or --markdown for a table. run-workflow … --summary prints the full report inline at the end.

References

• references/authoring.md — full DSL + standard quality patterns.
• references/runner-readme.md — architecture, the Codex protocol mapping, faithfulness vs. the native runtime, and limits.
• references/fleet-protocol.md — the sidecar file contract behind fleet supervision (states, questions/answers, notify), for supervising or producing runs outside this runner.
• examples/ — runnable templates: hello, review, bug-hunt (loop-until-dry + majority refute-by-default), review-gates (fresh-context review gate), deep-research, tournament-sort, triage, classify-route.