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:
~/.claude/skills/codex-workflows/runner (also at runner/ relative to this
skill). 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.
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, strongest
   general model (highest gpt-5.x/successor that is not a -mini/-spark
   variant; model/list flags it isDefault and its description calls it the
   strongest). Today that is gpt-5.5. 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.

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 frontier model is the one identified at preflight (newest,
strongest, isDefault; currently gpt-5.5) — 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.5.)

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 maximum reasoning. 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 → Codex config 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 human
  fork: resolves from args.checkpointAnswers / the journal first, then the live
  channel (--gui answer card or the answers sidecar), else the default on timeout
  — never hangs unattended. Journaled (--resume never re-asks); not an agent.
• 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 → Codex config 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)
  --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). Rule
  of thumb: medium-effort frontier (gpt-5.5) spends ~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.)
  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 the Codex
  config default — model_reasoning_effort in ~/.codex/config.toml, currently
  xhigh — so an effort-less workflow runs every agent at the highest tier
  (slow and token-heavy across a fan-out). So 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 is remapped to an available Codex model. Don't rely on
  that: set the frontier model explicitly with --model gpt-5.5 (see Model)
  and keep it identical 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.
• 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.