| name | workflow |
| description | Orchestrate a MULTI-PHASE, dependent, or resumable run over many cc-fleet PROVIDER subagents from a JS script, off the main context (`cc-fleet workflow`). Use for fan-out→barrier→synthesis, per-item pipelines, loop-until-dry, or a run that must survive a kill and `--resume` from its journal. Trigger ONLY to run a cc-fleet provider workflow. NOT a flat fan-out of independent tasks (that is /cc-fleet:subagent — cheaper, no script); NOT trivial single-shot work; NOT for editing or researching cc-fleet's own workflow code. |
workflow — multi-phase JS orchestration over provider subagents
Wrong lane? A flat one-shot fan-out of independent tasks → /cc-fleet:subagent.
When this skill cites cc-fleet-shared/<file>.md, read the file at ../cc-fleet-shared/<file>.md relative to this SKILL.md — the cited content is load-bearing, not optional background.
Execution environment — check before running anything. Confirm this shell runs on the machine where cc-fleet is installed. In a remote or split-host agent session the shell can run on a separate machine with its own filesystem and PATH, so cc-fleet: command not found or a wrong working directory can indicate that the shell is running on the wrong machine, not that cc-fleet is broken — route commands through a host-executing bridge and pass host paths for the files you reference, and stop cleanly if no such bridge exists. (Different-machine case only; for the same-machine codex sandbox — a clean doctor but network-blocked leaves — see Approval & sandbox below.)
A workflow is a JavaScript script that fans out provider cc-fleet subagent leaves and runs in a cc-fleet process, OFF the main session's context. You write the script; cc-fleet workflow run executes it. The orchestration plan lives in script variables (CPU, ~0 of your tokens) — you are invoked only when authoring the script, not on every scheduling decision. The API mirrors the native Claude Code Workflow tool — write the script exactly as you would a native workflow; the only addition is the provider option on agent().
Preflight (once per session)
On the first workflow run in a session, run cc-fleet doctor --json (your shell tool) and read the per-check results. The ONLY hard stops are the claude binary check and the fingerprint check — cc-fleet drives the claude CLI as the leaf worker engine, so if either fails no leaf can run: stop and tell the user to install or fix Claude Code. Do not stop on the "providers reachable" check — it aggregates every enabled provider, so one unrelated provider (especially a daemon-backed codex / openai-*, whose loopback proxy is only up during a spawn) flips the run to exit 1 while your target provider is fine. tmux checks are optional — workflow needs no tmux.
Approval & sandbox (non-bypass codex)
Each leaf is a network-using claude -p child (→ the provider API), and the run writes its script (/tmp) and a journal. On a codex that is not in full-bypass mode, expect — and pre-explain to the user — two things, neither a cc-fleet bug:
- Approval prompts are normal. A non-bypass approval policy asks the user to approve each
cc-fleet … call (workflow run, every chunked wait); approving is expected; to reduce the prompts the user can lower the approval friction (--ask-for-approval) or run codex bypassed.
- A sandbox can block every leaf. A workspace-write sandbox disables network by default, so each leaf fails looking like
PROVIDER_UNREACHABLE / a timeout while the real cause is the sandbox, not the provider. Heuristic: cc-fleet doctor is locally clean but all leaves are "unreachable" → the sandbox is blocking egress — approve the escalation, have the user enable network for the workspace-write sandbox, or run codex bypassed.
When to use it
- Multi-phase or dynamic orchestration over many provider subagents: fan-out + barrier, per-item pipeline, loop-until-dry, branch-on-result, with a board run-tree.
- A single flat batch of independent one-shots is not a workflow — that's /cc-fleet:subagent. Don't write a script for it.
The provider ask ladder (ask at most once per task)
- The user named a provider or model → use it.
- Else run
cc-fleet default --json: if it returns a provider (source "configured" or "auto"), use it and STATE it in your kickoff line (e.g. "using glm (default)").
- Else (several providers, none default) ask the user ONCE which to use — list the enabled providers from
cc-fleet list --json (name + default_model + the one-line note in cc-fleet-shared/providers.md). After they pick, run cc-fleet default <chosen> so you never ask again. (cc-fleet default <p> is user-layer; only run it to FILL a blank default, never with --force.)
- A mid-task provider failure (insufficient balance / rate limit / auth) → STOP, tell the user what happened, propose the next provider, and WAIT for their confirmation. Never switch providers silently.
Model tier within a provider: fan-out / leaf work → omit --model (or --model fast); judge / synthesis / sustained work → --model strong. The provider's roster decides the actual model — see cc-fleet-shared/providers.md.
In a script, agent()'s opts.provider is optional: omitted, the leaf uses the run's default provider, resolved ONCE at launch and recorded with the run — so --resume stays stable even if the default changes later. A script meant to be shared or reproducible should still pin provider explicitly.
The script API (mirrors the native Workflow tool)
const meta = {name, description, whenToUse?, model?, phases?: [{title, detail?}]} — a top-level pure literal (no calls/vars/spreads; the native export const meta form is also accepted). name + description are required; model is the default for agents that omit it. Read statically before the run → the board shows the named, phase-skeletoned run immediately.agent(prompt, opts) → Promise<string|object> — runs ONE provider subagent leaf. opts.provider is optional (omitted → the run's default provider, above); provider: "claude" runs the official claude CLI on the user's OWN Claude Code login (subscription OAuth) instead of a configured provider — a literal model id (fable/opus/sonnet/a full id, omitted → claude's login default, typically the costliest tier so name one), no roster keywords, no key material. The rest are optional: model, schema, label, phase, timeout (seconds), max_budget_usd, max_turns, isolation: "worktree", profile ("slim" default / "slim-ro" / "full"), tools, skills, mcp. An unknown option key throws (typos fail loudly). On a leaf failure the promise rejects — an un-caught top-level await agent() aborts the run; inside parallel/pipeline a failed element degrades to null. Leaf failures classify like subagent failures — dispatch table in "Leaf failures" below.
schema (a plain object) goes to the claude child via --json-schema: claude injects a forced StructuredOutput tool and enforces that it is CALLED (the native mechanism — no JSON instruction is added to the prompt); the promise resolves with the parsed structured payload. The three rules:
- a validation failure — or a result envelope without a structured payload — FAILS the leaf; there is NO automatic retry;
- the forced
StructuredOutput call costs turns — give a schema'd leaf max_turns ≥ 3 (a budget of 1 starves it);
What a workflow script can NOT use (determinism — the journal depends on it)
Date / Math.random() throw; eval / Function / dynamic code are removed; there is no setTimeout / require / fs / ESM import — pass timestamps or randomness in via args.- Plain script statements only (the body runs inside an async wrapper, so top-level
await and return work); async generators (async function*) are not supported.
Running it
RUN=$(cc-fleet workflow run audit.js)
cc-fleet workflow status "$RUN" --json
cc-fleet workflow list --json
cc-fleet workflow stop "$RUN"
cc-fleet workflow stop "$RUN" --leaf <job|label>
cc-fleet workflow restart "$RUN" --leaf <job|label>
cc-fleet workflow wait "$RUN" --timeout 3m --json
The run is detached so it outlives this call and your session stays responsive.
A codex-launched run is grouped on the board under your Codex launcher (a codex <thread> header, not (no session)) — still give each leaf a label (the script opt; --label on a bare cc-fleet subagent) and the run a clear meta.name so you can pick yours out within that group.
Where to write the script. For a one-off research / analysis run, write the script to /tmp/cc-fleet-<name>.js — do NOT add it to the user's repo unless they ask to keep the workflow. For read-only research, give the leaves profile: "slim-ro" and write the prompts so the leaves do not edit files.
Waiting on a run: block in chunks (codex has no background wake)
codex has no background-task wake, so you await a run by blocking the shell in bounded chunks — codex tolerates a long blocking command, and chunked blocking is the await. Keep the run id and re-issue wait until the run settles:
RUN=$(cc-fleet workflow run audit.js)
cc-fleet workflow wait "$RUN" --timeout 2m --json
wait returns the moment the run settles OR the window elapses. While the run is still progressing it exits 124 with wait_outcome timeout (a heartbeat, not a verdict) — re-issue the SAME wait "$RUN" for the next chunk. Always keep $RUN: a timed-out wait loses nothing, a fresh wait "$RUN" just resumes blocking and the run carries on detached. Never spawn an agent to poll, and never tight-loop status — wait is the blocking primitive.
If the codex shell yields with "Process running with session id …", that backgrounded wait is STILL the live wait — do NOT issue a second wait "$RUN" (a needless concurrent wait); let it return. Size each --timeout chunk SHORTER than your shell's foreground window so the command returns cleanly rather than being backgrounded. (Omitting --timeout / passing --timeout 0 blocks in one shot until the run settles — use only when you mean to block to the very end and will reattach to the yielded session; the chunked pattern is the default.)
Make the FIRST chunk short (2–3m — a provider auth/balance failure surfaces on the first leaf call), then 10–15m per re-issue. Dispatch each returned chunk on wait_outcome (+ exit code):
terminal (exit 0 done/stopped · exit 1 failed) — fetch the detail with cc-fleet workflow status "$RUN" --json (it carries run_error and the per-leaf jobs[]; the wait envelope deliberately omits them) and report. To read a leaf's actual ANSWER (status/wait omit answers), use cc-fleet workflow result "$RUN" --label <leaf> --json — so label the leaves whose output you'll want.engine_gone (exit 1) — the detached engine died without finalizing; propose cc-fleet workflow run audit.js --resume "$RUN" (the journal replays the finished leaves).parked (exit 3) — every remaining leaf is held. FIRST re-check cc-fleet workflow status "$RUN" --json: leaves running/queued again means it was a transient (the engine was between leaves) → re-issue wait. Still parked → name the envelope's held leaves to the user and propose cc-fleet workflow restart "$RUN" --leaf <job|label>; never wait it out.timeout (exit 124) — still running. Compare counts / spent_usd / spent_tokens with the previous chunk: progress → one short progress line and re-issue with a longer --timeout (10–15m); zero delta over several chunks → inspect (workflow status; is one long leaf still inside its own timeout?) and escalate only on a real anomaly, else re-issue.
After a session restart, re-issue wait for every running run from cc-fleet workflow list --json.
For a human live view: cc-fleet workflow watch "$RUN" streams the run's events as text and cc-fleet watch streams the whole fleet; the board's Dynamic Workflows view has the rich drill-in. Both print only canonical status — never a provider reply.
Leaf failures — dispatch on error_code (do not parse prose)
A failed leaf's structured error_code is in workflow status --json (jobs[]); an in-script catch receives a plain Error message (e.g. agent(provider): KEY_INVALID: …), so read the code from status --json rather than parsing the message for control flow. Same vocabulary as a one-shot subagent (the full table with context lives in /cc-fleet:subagent); the dispatch:
error_code | What you do |
|---|
INSUFFICIENT_BALANCE / KEY_INVALID / RATE_LIMITED | STOP — provider ask ladder, step 4 (never switch silently). KEY_INVALID → the user rotates the key; RATE_LIMITED → brief wait, one retry. |
NO_DEFAULT_PROVIDER / DEFAULT_PROVIDER_DISABLED / DEFAULT_PROVIDER_UNKNOWN / DEFAULT_PROVIDER_RESERVED | No usable default for a provider-less agent() (RESERVED = default_provider hand-set to claude, explicit-only — the user unsets/re-pins) — apply the provider ask ladder, then re-run. |
MODEL_NOT_FOUND | cc-fleet refresh <provider>, or drop the leaf's model to use the provider default. |
SUBAGENT_TIMEOUT | Raise the leaf's timeout or split the task; a leaf with no timeout defaults to 300s. |
SUBAGENT_OUTPUT_TOO_LARGE | The leaf's output exceeded the byte cap — have it write to a file and answer concisely; a blind retry overflows again. |
SUBAGENT_STOPPED | An operator stopped it (stop --leaf / run stop) — terminal, NOT a failure; never auto-retry. |
SUBAGENT_MAX_TURNS | A leaf hit the --max-turns cap. |
SUBAGENT_FAILED / PROVIDER_API_ERROR | Inspect (workflow status); restart --leaf once, or propose a provider switch (ask first). A provider: "claude" leaf on a logged-out machine fails here (the error preview names the login problem, no dedicated code) — tell the user to log in to Claude Code interactively. |
FINGERPRINT_MISSING / FINGERPRINT_STALE | MISSING = a corrupt ~/.config/cc-fleet/fingerprint.json (rare): cc-fleet doctor --json confirms; remove that file to fall back to the bundled recipe, then retry. = no claude binary — fix Claude Code / PATH. |
Resume (content-hash journal)
Each run records a content-hash journal of its completed leaves. Re-run the same script under an existing run id to replay:
cc-fleet workflow run audit.js --resume "$RUN"
A leaf is keyed by its determinant (provider + model + prompt + schema + slim shape), so an unchanged re-run is ~100% cache hits, a leaf whose prompt you edited (and anything downstream of its output) re-runs, and a run that was killed resumes by replaying what finished before the kill. The determinism lockdown makes this exact: with no clock/PRNG, the same script+args produce the same keys. A failed leaf is never journaled, so resume re-runs it.
Non-goals (state plainly, don't oversell)
- No pause. A running
claude -p can't be cleanly suspended; use workflow stop (reaps the run) + run --resume (cheap restart via the journal) instead.
- Client-side
schema validation is a JSON-Schema subset — the list above, not the full spec (an external $ref URI is unsupported and fails; an unknown format is an annotation, not enforced). claude enforces that StructuredOutput is called; this backstop checks what it was filled with, and a failure is terminal (no retry).
- Key-safety is unchanged: the provider key flows only via
apiKeyHelper; prompts go to the leaf via stdin, never argv; the journal/events/board carry no key.
Worked example — research sweep (fan-out → pipeline → loop)
const meta = {
name: "api audit",
description: "map endpoints, draft checks, then probe for gaps",
phases: [{title: "map"}, {title: "build"}, {title: "probe"}],
};
phase("map");
const maps = (await parallel(
args.map((m) => () => agent("List exported endpoints in module " + m,
{provider: "deepseek", label: "map:" + m}))
)).filter(Boolean);
phase("build");
const checklists = await pipeline(
maps,
(prev, item, i) => agent("Draft an audit checklist for these endpoints:\n" + prev,
{provider: "glm", label: "build:" + i}),
);
phase("probe");
const gaps = [];
while (gaps.length < ) {
g = (
+ checklists.(), {: });
(g.() === ) ;
gaps.(g);
}
verdict = (
+ gaps.(), {: , : , : });
();
{ maps, checklists, gaps, verdict };
One run, three phases, a barriered fan-out, a no-barrier pipeline, a bounded loop-until-dry, and a single claude synthesis node — all sequenced by the script in a cc-fleet process, off your context. The script's top-level return value is NOT persisted or retrievable — to read the run's output, fetch a labeled leaf's answer with cc-fleet workflow result "$RUN" --label verdict --json.
Anti-patterns
- A script for a single flat independent batch → /cc-fleet:subagent.
Date.now() / setTimeout — unavailable (determinism); pass timestamps via args.- Trusting
schema as deep validation, or treating a plain agent() result as JSON without schema.
- Unbounded ambition: the runtime hard-caps 1000
agent() calls/run, pools concurrency at min(16, cores-2), and caps a single parallel/pipeline list at 100,000 elements.
- Switching providers silently after a balance / rate-limit / auth failure → stop, tell the user, wait for their pick (provider ask ladder, step 4).
