codex-workflows

# 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:
   ```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