/codex-workflow

name: codex-workflow
description: >-
  Author and run a custom Workflow (the Workflow tool's agent()/pipeline()/parallel()
  orchestration, a.k.a. "ultracode") that BLENDS Codex headless (`codex exec`) nodes
  into otherwise-Claude orchestration — for cross-model adversarial verification, judge
  panels with a Codex juror, and second-opinion generation. This is "Pattern A": the
  orchestration logic stays in Claude's Workflow JS, and selected nodes shell out to a
  genuinely different model family (the Codex CLI / GPT) to catch correlated Claude
  failure modes. Use this skill whenever the user asks to run a task as a "custom workflow
  using codex", "a workflow that mixes in codex", "blend codex into a custom workflow",
  "cross-model verify while orchestrating", "have codex verify/double-check the findings",
  "use codex as a verifier/juror/second opinion in the workflow", "Claude and codex both
  in one workflow", or any equivalent phrasing. Trigger even when the user only implies it
  — if they want a Workflow AND a second model family in the loop, this is the skill. Do
  NOT use it for a pure single Codex handoff (use a dedicated codex handoff command/agent
  instead), for codex image generation, or for a plain Claude-only Workflow with no second
  model.

Codex-in-Workflow (Pattern A)

Authoring custom Workflows with the **Workflow** tool (`agent()`, `pipeline()`, `parallel()`, `phase()`, schemas, loop-until-dry, etc.) is assumed knowledge. This skill is the know-how for **mixing Codex headless into one** so that the orchestration stays Claude's but selected nodes run on a *different model family*.

Mental model

A Workflow's `agent()` normally spawns a **Claude** subagent. Pattern A keeps every orchestration primitive exactly as-is and only changes *who does the work at chosen nodes*: a "codex node" is a normal `agent()` whose subagent does nothing but shell out to `codex exec` and relay its output back.

Workflow (Claude JS orchestration)
 ├─ find / generate ............... Claude agent()  ← Claude is broad, fast, cache-warm
 └─ verify / judge / 2nd-opinion .. codex node      ← GPT, independent failure modes

The value is **diversity, not replacement.** Two model families disagree in different places, so a Codex verifier catches Claude's *correlated* false positives (and vice versa) in a way that N more Claude verifiers cannot. The single highest-ROI use is **adversarial verification**: Claude finds, Codex tries to refute.

Prerequisites — preflight before trusting any codex node

This skill assumes the Codex CLI is installed and authenticated in the environment running the Workflow. Do NOT assume a specific version or default model — confirm them, because they change between installs. Run the **preflight** (CLI present, auth live, structured-output path works) from `references/codex-headless.md` once before relying on any node; if it errors on auth, the user must `codex login` (interactive) — that cannot be done headlessly.

Step 0 — should this task even use Codex?

Don't bolt Codex on for its own sake; each node costs a separate Codex/OpenAI run plus a Claude wrapper turn. Route a node to Codex only when a *second, independent model* materially de-risks the result:

• **Yes:** verifying findings/claims, judging candidates, an independent attempt

in a diverse panel, sanity-checking a risky Claude conclusion.

• **No / don't blend when:**
• it's bulk throughput work (Claude subagents are cheaper, faster, cache-warm);
• it's a **correlated check** — Codex would only re-derive from the *same*

evidence Claude already used, with no independent angle (an echo, not a second opinion);

• it's a **blind check** — the node can't give Codex what it needs to verify

independently (no files/tools in read-only, and the evidence isn't inline);

• there's no verifiable/judgeable artifact (pure open-ended ideation) —

diversity adds noise, not signal.

If none of the **Yes** cases apply, skip the skill and ship a plain Claude Workflow.

The codex node (the core mechanism)

In `exec` mode the Codex CLI runs non-interactively with approvals disabled, and `-s read-only` stops the *model* from writing to your workspace — so a verify/judge node has no model-driven side effects on your files (Codex still writes its own session files and the `-o` output file; that is expected). The node writes both the task and the schema to temp files *inside the subagent*, runs Codex read-only, and relays the clean `-o` output file.

> **Why self-contained:** a Workflow script's JS body has **no filesystem > access** — it can't write the schema file itself. So the node embeds the > schema as a string and the (Bash-capable) wrapper subagent writes it. One > `schema` object is the single source of truth: `JSON.stringify` feeds Codex's > `--output-schema`, and the same object is passed to `agent()` for re-validation.

The helper's **contract** (the full copy-paste implementation lives canonically at the top of `references/workflow-templates.md` — paste it once near the top of your script):

codexNode(taskText, { schema, sandbox='read-only', model, cwd, effort, revalidate=true, phase, label, timeoutMs=1200000 })
  → Promise<parsedObject>

• **taskText** — the verify / judge / generate prompt for Codex.
• **schema** — a JS JSON-Schema object, the single source of truth: feeds Codex's

`--output-schema` AND (when `revalidate`) re-validates the result in `agent()`.

• **cwd** — optional working root (`-C`) so Codex can read files itself (variant

below). **effort** — optional reasoning-effort knob (`-c model_reasoning_effort`; ladder `low`→`xhigh`, plus `max` on all GPT-5.6 tiers and `ultra` on Sol/Terra). **model** — optional model override (`-m`; use fully-qualified tier IDs like `gpt-5.6-sol`/`-terra`/`-luna`). Both are open, per-node choices — see "Picking tier & effort per node" below.

• **timeoutMs** — watchdog deadline for the codex run: default 120