workflows

Workflows

A workflow is a plain-JS orchestration script that fans out to parallel sub-agents and keeps intermediate results in script variables (not your context). You author it, run it with workflow run, and — once it's good — workflow save it as a reusable command.

When to reach for a workflow

• A sweep over many files/items where each unit is independent (lint, classify, summarize).
• A migration applied across a codebase in parallel, then aggregated.
• Research that fans out to several sources and cross-checks them.
• Multi-angle planning (draft N approaches in parallel, then synthesize).

If it's a single self-contained task, just use a plain scoop or the agent command — a workflow is overhead you don't need.

The API (available inside a workflow script)

• agent(prompt, opts?) → the sub-agent's text (or parsed JSON when opts.schema is set), or null on failure. opts: { model?, thinking?, schema?, phase?, label? }.
  • model: a bare model id (run models to see the ids you can use) to run this sub-agent on a specific model; omit to inherit the workflow's model. Always pass the bare id (e.g. claude-opus-4-8), never a provider:model form.
  • thinking: off | minimal | low | medium | high | xhigh (per-agent reasoning effort).
  • schema: a JSON Schema; the result is constrained to it and JSON-parsed for you.
  • phase / label: display-only grouping (no execution effect yet).
• parallel(thunks) → runs an array of () => Promise concurrently (bounded by the cap).
• pipeline(items, ...stages) → maps items through stages.
• phase(title) / log(message) → progress markers.
• args → the value passed when the workflow is invoked (<name> '<json>').

Authoring

A workflow MUST export a meta block with a name (description optional):

export const meta = { name: 'weekly-audit', description: 'Audit each package in parallel' };

const pkgs = args?.packages ?? ['webapp', 'node-server'];
phase('audit');
const findings = await parallel(
  pkgs.map((p) => () => agent(`Audit packages/${p} for TODOs. One line each.`, { thinking: 'low' }))
);
return findings.filter(Boolean);