# Codex Workflows

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-scasella-claude-dynamic-workflows-codex-claude-dynamic-workflows-codex`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [scasella](https://agentstack.voostack.com/s/scasella)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [scasella](https://github.com/scasella)
- **Source:** https://github.com/scasella/claude-dynamic-workflows-codex

## Install

```sh
agentstack add skill-scasella-claude-dynamic-workflows-codex-claude-dynamic-workflows-codex
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 (`./.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:
   ```bash
   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 — `./.workflow.js`, or
   `workflows/.workflow.js` / `examples/harness-zoo//` 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*):
   ```bash
   node ~/.claude/skills/codex-workflows/runner/bin/run-workflow.js  --frontier --auto-effort [other flags]
   #   quick_harness:  …  --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):
   ```bash
   node ~/.claude/skills/codex-workflows/runner/bin/map-run.js --journal  --no-color
   ```
   (`` is the path the run logged as `✎ journal: …`, default
   `.workflow-journal/.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:

```js
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 ` supervises).
Launch each with `run_in_background`, **always with `--interactive`** (it
enables the answer channel headlessly):

```bash
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):

```bash
node ~/.claude/skills/codex-workflows/runner/bin/fleet.js status    # --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  --id '' --answer ''` (`--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  --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 (`.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` — composit

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [scasella](https://github.com/scasella)
- **Source:** [scasella/claude-dynamic-workflows-codex](https://github.com/scasella/claude-dynamic-workflows-codex)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** yes

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-scasella-claude-dynamic-workflows-codex-claude-dynamic-workflows-codex
- Seller: https://agentstack.voostack.com/s/scasella
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.