Skip to content
Skills Library
AI & agents · Automation

workflow

/workflow

Orchestrate a MULTI-PHASE, dependent, or resumable run over many 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. NOT a flat fan-out of independent tasks (that is /cc-fleet:subagent — cheaper, no script); NOT interactive collaboration (that is /cc-fleet:team); NOT trivial single-shot work for the main session.

Repository
cc-fleet ↗
Licence
Apache-2.0
Last repository change
24.10.2026

Assessment and security

98/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene13 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Orchestrate a MULTI-PHASE, dependent, or resumable run over many 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. NOT a flat fan-out of independent tasks (that is /cc-fleet:subagent — cheaper, no script); NOT interactive collaboration (that is /cc-fleet:team); NOT trivial single-shot work for the main session.

Original author description

Orchestrate a MULTI-PHASE, dependent, or resumable run over many 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. NOT a flat fan-out of independent tasks (that is /cc-fleet:subagent — cheaper, no script); NOT interactive collaboration (that is /cc-fleet:team); NOT trivial single-shot work for the main session.

How it works

  1. When to use it
  2. The provider ask ladder (ask at most once per task)
  3. The script API (mirrors the native Workflow tool)
  4. What a workflow script can NOT use (determinism — the journal depends on it)
  5. Running it
  6. Waiting on a run: arm wait in a backgrounded Bash (push, not poll)
  7. Leaf failures — dispatch on errorcode (do not parse prose)
  8. Resume (content-hash journal)
  9. Non-goals (state plainly, don't oversell)
  10. Worked example — research sweep (fan-out → pipeline → loop)
Original SKILL.md headings · 173 lines, 4,133 words
SKILL.md preview
---
name: workflow
description: Orchestrate a MULTI-PHASE, dependent, or resumable run over many 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. NOT a flat fan-out of independent tasks (that is /cc-fleet:subagent — cheaper, no script); NOT interactive collaboration (that is /cc-fleet:team); NOT trivial single-shot work for the main session.
---

# workflow — multi-phase JS orchestration over provider subagents

**Wrong lane?** A flat one-shot fan-out of independent tasks → /cc-fleet:subagent; interactive collaboration you message back and forth → /cc-fleet:team; arbitration in cc-fleet-shared/routing.md.

When this skill cites `cc-fleet-shared/<file>.md`, OPEN it with the Read tool 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 your shell tool executes on the host where cc-fleet is installed. In sandboxed or remote agent sessions, a tool named Bash may run on an isolated machine with a different filesystem, PATH, processes, and tmux server — `command not found`, a healthy-looking `doctor` whose leaves can't reach your files, or a wrong working directory should prompt you to verify whether you are in a sandbox shell, not conclude that cc-fleet is broken. If so, route commands through a host-executing bridge tool (for example, desktop-commander) and pass host paths for any files you reference; do not retry the same Bash call expecting different results. If no host-executing tool is available, stop and explain that cc-fleet must run on its installation host.

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()`.

## 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)
1. The user named a provider or model → use it.
2. 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)").
3. 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.)
4. 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.
   STOP freezes the affected provider operation and any unapproved provider switch, not independent authorized work. The error table's single rate-limit retry remains allowed; do not retry uncertain writes before establishing their prior result. Main-session handling is allowed only where the workflow already permits it and the user has not required that provider. Changing a provider or the saved default still requires the corresponding explicit authorization.

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);
    - needs claude ≥ 2.1.88 (the slim-profile floor); an older claude fails the leaf with a classified usage error.
    Client-side validation backstops with a recursive JSON-Schema subset: `type` (object/array/string/number/integer/boolean/null; `integer` accepts `5.0`), `required`, nested `properties`, array `items`, scalar `enum`, string `pattern` (RE2 best-effort — the wire enforces the authoritative ECMA regex) / `format` (email/uri/uuid/date/date-time), `additionalProperties`, `allOf`/`anyOf`/`oneOf`, and intra-document `$ref` (`#/…` pointers; an external URI is unsupported and fails).
  - **`isolation: "worktree"`** runs the leaf with cwd = a fresh git worktree, so parallel file-editing leaves don't collide (requires a git repo). When the leaf ends, a clean worktree is removed; one with changes or new commits is first snapshotted to the branch `cc-fleet/wf-<job>-a<n>` in your repo (list them with `git branch --list 'cc-fleet/wf-*'`; the engine log — `workflow watch` — has a `kept` line naming it), then removed. If the snapshot fails, the directory stays where it is with a `.cc-fleet-keep` marker — save the work, then delete the directory yourself. If `workflow watch` shows `UNPROTECTED` for it, the marker could not be written and nothing shields that directory from cleanup: copy it out by hand before any `workflow restart`, `rm` or `prune`, or a new run in this repo. The worktree starts at `HEAD`, so uncommitted changes in your checkout are not visible to the leaf, and its edits reach your checkout only when you merge or cherry-pick the `cc-fleet/wf-*` branches; cc-fleet never deletes them (`git branch -D` once merged). A whole-run `workflow stop` or an engine crash can cut a leaf off before its snapshot finishes (a `stop --leaf` hold saves normally): the next `--resume` / `restart` or `workflow rm` / `prune` rescues that work to `cc-fleet/wf-salvage-<run>-<8 chars>` without logging it, and a later run's startup sweep in the same repo rescues it with an `isolation worktree salvaged` line in that run's events. A resume or restart also clears the old `kept` lines — after a stop, find the work with `git branch --list 'cc-fleet/wf-*'`, not `workflow watch`.
  - **`profile`**: `"slim"` (the default; write-capable) / `"slim-ro"` (read-only research) / `"full"` (ONLY to compare against a full session or diagnose a suspected slim regression). Writes files → `slim`, read-only → `slim-ro`. `tools`, `skills` (default `true`) and `mcp` refine a slim leaf, are rejected with `profile: "full"`, and `tools` REPLACES the whole set, never appends. Tool whitelists / per-profile `mcp` defaults / the pre-2.1.88 fail-open downgrade: cc-fleet-shared/providers.md. The run journal folds the effective profile + tools, so a `--resume` re-runs a leaf whose shape changed.
- **Background = an unawaited promise.** There is no `run_in_background`/`wait()`: start a leaf with `const p = agent(...)`, keep working, `await p` later (`Promise.all` for a batch). Every leaf — awaited or not — is pool-bounded, journaled at completion, and the run only finalizes after all of them settle. A leaf that **rejects with nobody ever handling it fails the run** (a silently dropped failure is still a failure); fire-and-forget tolerance is an explicit `p.catch(() => null)`.
- `parallel(thunks) → Promise<array>` — run each 0-arg thunk concurrently; **BARRIER** (settles once all finish), `null` where an element failed: `await parallel([() => agent("a", {provider: "glm"}), () => agent("b", {provider: "glm"})])`. Concurrent execs stay ~pool size even for a huge list (excess queues).
- `pipeline(items, ...stages) → Promise<array>` — push each item through all stages independently with **NO inter-stage barrier** (item A can be in stage 3 while B is in stage 1). Each stage is `(prev, item, index) => …` (sync or async; its return value is awaited). A failing stage drops that item to `null` and skips its remaining stages. **DEFAULT to `pipeline` over `parallel`** — only use `parallel` when a stage genuinely needs ALL prior results together.
- `workflow(path, args?) → Promise` — run another `.js` inline on the same engine (shared pool/journal/budget), **one level deep** only; resolves with the child's top-level `return` value. A relative `path` resolves against the run's directory (where `workflow run` was launched, kept for `--resume` / `restart`), not the calling script's directory — use an absolute path when the scripts live elsewhere. The child script is read and checked only when `workflow()` reaches it, not at launch.
- `budget` — two parallel cap surfaces. **USD:** `budget.total` (the `--budget-usd` cap in USD, or `null`), `budget.spent()`, `budget.remaining()` (`Infinity` when uncapped) — USD floats (an Anthropic list-price estimate). **Tokens:** `budget.tokens_total` (the `--budget-tokens` cap, or `null`), `budget.tokens_spent()`, `budget.tokens_remaining()` — ints (input+output, cache-read excluded). `agent()` throws when the next leaf does not fit: each call reserves $1.00 (or its larger `max_budget_usd`) and 50,000 tokens as soon as it is made — before it waits for a slot — until the leaf is charged its real cost, and is refused when spent + held reservations + its own would pass **either** cap (a leaf replayed from the journal on `--resume` reserves nothing). A refused call never waits (a lower `--max-concurrency` does not help): a cap under $1.00 / 50,000 tokens runs no leaf, a fan-out of N leaves needs about N × $1.00 of room (the rest come back `null` from `parallel()`, each refusal logged in `workflow watch`), and a `while (budget.remaining() > N)` loop scales depth to the cap only with N ≥ one reservation (`remaining()` does not subtract reservations). (Native's `budget.total` is a token target; here it is **USD** — `--budget-usd` is the cross-provider cap since providers price tokens differently — and tokens are the separate `tokens_*` surface.) A `provider: "claude"` leaf spends the **lead session's own subscription window**, not a metered provider — use it for one or two synthesis / judgement nodes, never a wide fan-out. Its usage still flows into the run's token / USD surfaces, but the USD is claude's notional list-price (a subscription is not metered per token); `max_budget_usd` / `--budget-usd` still gate against that notional figure.
- `phase(title, detail?)` — name the current phase (tags subsequent agents lacking an explicit `phase`; the detail shows on the board row). `log(msg)` — a narrator line (board live log + stderr); `console.log/info/warn/error/debug` alias onto it (non-strings render as JSON, Errors by message).
- `args` — the parsed `--args-json '<json>'` value (or the `workflow(child, args)` value); `undefined` when none was given.

## 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
```bash
cc-fleet workflow run audit.js               # detached; prints ONLY the bare run id ("$RUN" below)
cc-fleet workflow status "$RUN" --json       # manifest + every tagged leaf (run→phase→agent)
cc-fleet workflow list --json                # all runs, newest first
cc-fleet workflow stop "$RUN"                # reap a running run (engine + in-flight leaves)
cc-fleet workflow stop "$RUN" --leaf <job|label>  # hold ONE agent in place (run keeps going); --phase <title> holds a phase
cc-fleet workflow restart "$RUN" --leaf <job|label>  # re-run a held/running agent in place; --phase <title> a phase;
                                             # on a FINISHED run: keyed re-run (whole run, --leaf, or --phase)
cc-fleet workflow wait "$RUN" --timeout 3m --json  # block silently until the run settles ("Waiting on a run" below)
# or watch the board's Dynamic Workflows view: live log, token/cost columns, prompt/answer drill-in.
# x/r there are level-scoped: run row = the run, Phases pane = the phase, agent pane = the leaf
# (a held agent shows ▶ until you restart it). --foreground runs inline (debug).
# `held` in status output = parked by the control plane: an operator paused it (board
# x, stop --leaf/--phase) or a restart was refused (budget gate); a restart in flight
# may show it briefly. Not an error/retry/backoff — the run waits on it indefinitely.
# If held persists across polls, resume it with restart --leaf/--phase or tell the
# user it is parked; never wait it out.
# --max-concurrency N overrides the default pool (min(16, cores-2));
# --budget-usd N caps total spend (each leaf holds max($1, its max_budget_usd) of it from its
# agent() call, queued or running, until it finishes);
# --no-persist-io disables the prompt/answer drill-in.
```
The run is detached so it outlives this call and your session stays responsive. A non-zero exit from `workflow run` means no run started and no id was printed; stderr says why — e.g. a script or `meta` error, or `engine failed to start: <cause>` when the detached engine died before registering. Do not arm `wait` then (`wait` exits 2 on an empty or unknown id).

## Waiting on a run: arm `wait` in a backgrounded Bash (push, not poll)
Right after launching, arm the notifier — a backgrounded Bash whose EXIT is your wake-up. Put the printed run id into it literally: a separate Bash call does not inherit `$RUN`:
```bash
cc-fleet workflow run audit.js
# a separate Bash call with run_in_background=true; the harness wakes you when it exits:
cc-fleet workflow wait <run-id> --timeout 3m --json
```
End your turn and keep working — never spawn an agent (or loop yourself) to poll a run.
On the wake, dispatch on the envelope's `wait_outcome` (+ exit code); exit **2** has none (`ok:false`) — an IO error or an empty or unknown run id: check the id against `workflow list --json`, don't re-arm blindly:
- **`terminal`** (exit 0 done/stopped · 1 failed) — fetch the detail with `workflow status "$RUN" --json` (it carries `run_error` and the per-leaf list; the wait envelope deliberately doesn't) and report.
- **`engine_gone`** (1) — the engine died without finalizing; propose `cc-fleet workflow run <script> --resume "$RUN"` (the journal replays the finished leaves).
- **`parked`** (3) — every remaining leaf is held. FIRST re-check `workflow status`: leaves running/queued again means it was a transient (the engine was between leaves) — re-arm silently. Still parked → name the envelope's `held` leaves to the user and propose `restart --leaf`; never wait it out.
- **`timeout`** (124) — a heartbeat, not a verdict. Compare `counts`/`spent_*` with the previous snapshot: progress → one short progress line and re-arm with a longer window; zero delta → inspect (`workflow status`; is one long leaf still inside its own `timeout`?) and escalate only on a real anomaly, else re-arm.

Window sizing: make the FIRST window short (2–3m — a provider auth/balance failure surfaces on the first leaf call), then 10–15m per re-arm. One wait per run; they are independent. After a session restart, re-arm every `running` run from `workflow list --json`.

For a human live view: `cc-fleet workflow watch "$RUN"` streams the run's events as text (in a terminal, or a backgrounded shell → the `/tasks` panel) 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 `error_code` is in `workflow status --json` (`jobs[]`) and in the rejection that reaches the script. 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 (a codex provider has no key: the user runs `cc-fleet codex login --credential <its secret_ref>`; `protocol` `codex-oauth` and `secret_ref` in `cc-fleet list --json`); `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` | Give the failing leaf a slot as its `model` (`default` / `strong` / `fast`; see `cc-fleet models <provider> --json`) — also when it inherited the id from `meta.model`. Change `meta.model` only when every leaf inheriting it was rejected: it re-keys all of them, so `--resume` re-runs the finished ones. Then `cc-fleet workflow run <script> --resume "$RUN"` (`restart` re-runs the saved, unedited script). If the user named that model, tell them it was rejected and confirm the substitute before retrying. If a configured slot itself is rejected, the user fixes it with `cc-fleet edit <provider> --default-model/--strong-model/--fast-model <id>` (or the TUI); `cc-fleet refresh` changes nothing a leaf uses. |
| `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 — raise its `max_turns` in the script (a research / multi-file leaf needs ~1 turn per file read or command: give it 30–50, or omit the cap), then `cc-fleet workflow run <script> --resume "$RUN"`; `restart --leaf` re-runs the saved script with the old cap. |
| `SUBAGENT_FAILED` / `PROVIDER_API_ERROR` | Inspect (`workflow status`); `restart --leaf` once, or propose a provider switch (ask first). A `schema` leaf with missing or invalid structured output fails here too, and a restart re-runs the same spec: fix its schema, prompt or `max_turns`, then `cc-fleet workflow run <script> --resume "$RUN"`. 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. A codex / openai-* leaf with `leaf did not complete` and no `leaf launch` line in `cc-fleet workflow watch "$RUN" --timeout 5s` never started: its proxy (or its `isolation: "worktree"` worktree) could not be set up, and only the script's rejection names the cause (`run_error` when uncaught; `parallel` / `pipeline` swallow it) — for `codex proxy unavailable: …` follow the `CODEX_PROXY_UNAVAILABLE` row instead of restarting. |
| `PROVIDER_UNREACHABLE` | claude reported a transport failure with no HTTP status (connection refused or reset, DNS, TLS, timed out) — the provider is down, or a codex / openai-* loopback proxy died mid-leaf. `cc-fleet doctor`, then `restart --leaf` once; if it persists, tell the user and propose a provider switch (ask first). |
| `FINGERPRINT_STALE` | The `claude` binary was not found (the code keeps its old name) — the user installs/fixes Claude Code or PATH; `cc-fleet doctor` confirms. |
| `CODEX_PROXY_UNAVAILABLE` / `CODEX_CLOUDFLARE_BLOCKED` | The loopback proxy could not start: `cc-fleet codex-proxy status`, then the user frees the port in the provider's `base_url` or fixes the cause the error names — a missing codex login does not cause this (it fails on the request as `KEY_INVALID`). A Cloudflare block → switch network, don't rotate credentials. |
| `UNKNOWN_PROVIDER` / `PROVIDER_DISABLED` / `CONFIG_LOAD_FAILED` | Config problem — `cc-fleet list --json`, `cc-fleet add` / `edit --enable`; `CONFIG_LOAD_FAILED` → `cc-fleet doctor`. |
| `PROVIDER_RESERVED` | A providers.toml row is named `claude` (reserved for the native leaf) — the user renames or removes it. |
| `SUBAGENT_BAD_ARGS` | Bad leaf options — fix the script, re-run. |

## 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:
```bash
cc-fleet workflow run audit.js --resume "$RUN"   # journaled leaves return cached (no provider exec); only un-run leaves run
```
A leaf is keyed by its determinant (provider + model + prompt + schema + isolation + 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.

`--resume` and `restart` run the remaining leaves in the directory the run was first launched from (recorded with the run), whatever your cwd; only the script path you pass to `--resume` is resolved from your cwd. If that directory is gone, they fail with `run directory <dir> no longer exists` — tell the user to restore it or start a fresh run from the project directory. `--resume` checks the script before touching the run (parse, compile, `meta`): a broken one is refused (exit 1, the error on stderr) and the run and its saved script — the one `restart` runs — stay as they were; fix the script and re-issue the same command.

## 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)
```js
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);  // e.g. --args-json '["auth","billing","users"]'

phase("build");
// pipeline (no barrier): each map flows straight into its own checklist draft
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 < 10) {           // loop-until-dry (the runtime hard-caps 1000 leaves/run)
    const g = await agent("Given these checklists, name ONE uncovered risk, or reply NONE:\n"
                          + checklists.join("\n"), {provider: "kimi"});
    if (g.trim() === "NONE") break;
    gaps.push(g);
}

// one final synthesis node on your OWN subscription — a single judgement leaf, not a fan-out
const verdict = await agent("Rank these gaps by severity and name the top three:\n"
                            + gaps.join("\n"), {provider: "claude", model: "opus", label: "verdict"});

log(`done: ${maps.length} maps, ${checklists.length} checklists, ${gaps.length} gaps`);
return { 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.
- A long-lived collaborator you message back and forth → /cc-fleet:team.
- `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).

Versions

RepositoryScoreLicence
This page · ethanhq/cc-fleet98Apache-2.0
jeremylongshore/tons-of-skills-marketplace100MIT
SimHacker/moollm100MIT
mlophez/polix-ai100Apache-2.0
stellarie/minimal-agent-kit100MIT
waynesutton/builder-skills100Apache-2.0
claude-world/director-mode-lite100MIT
DawitLemmaBalcha/agent-workflow100MIT
zhinkgit/embeddedskills100MIT

Database snapshot: 13.11.2026 · package version 6a1ef46c2363 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100subagent
    Run a one-shot or flat parallel batch of provider LLM subagents (headless `cc-fleet subagent`) that return a result. Use when fanning out N independent tasks, doing bulk per-file work, or calling a specialized provider model (DeepSeek / GLM / Kimi / Qwen / MiniMax). NOT a…
  • 100subagent
    Fan out a one-shot or flat parallel batch of cc-fleet PROVIDER subagents (headless `cc-fleet subagent`) that return a result — DeepSeek / GLM / Kimi / Qwen / MiniMax, or a Codex/Claude subscription. Trigger ONLY to delegate a task to a cc-fleet provider worker (parallel…
  • 100codex-workflow
    Run deterministic multi-step agent workflows in Codex - fan-out, parallel, schema-validated structured output - via the codex-workflow MCP orchestrator (run_workflow), with native in-chat fallbacks. Use when you want Claude-Code-Workflow-style orchestration in Codex: 'run a…
  • 100run-workflow
    How to write and run a dynamic workflow script with the `run_workflow` tool: a Python script that orchestrates many agents with `agent`, `parallel`, `pipeline`, and `phase`. Use when a task splits into many independent or staged pieces of agent work (fan out over files, modules,…
  • 90fleet-runs
    Summarize Workflow-tool fleet runs from the Agent Monitor — these fleets emit no hooks and are ingested from on-disk run journals. List recent runs with status and agents-per-run, then drill into a single run's per-agent detail. Reconciles against the live run-state endpoints.…
  • 100workflow-builder
    Design and write deterministic multi-agent workflow scripts (.js files in .claude/workflows/) for Claude Code's Workflow tool. Use when a user wants to build, create, author, scaffold, or run a custom Claude Code workflow, orchestrate sub-agents (fan-out, pipeline, loop,…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.