| name | workflow-basics |
| description | When deciding between the Workflow tool and the Task tool for large-scale orchestration (50+ agents) -- use this. Covers what the Workflow tool is, its critical no-direct-I/O constraint, the fan-out + synthesize and chained design->impl->review shapes it fits, and when the simpler Task tool wins instead. |
Workflow basics
The Workflow tool (Claude Code v2.1.154+, research preview, Pro+
plans) runs a JavaScript orchestration script in an isolated
background runtime. The script holds the entire plan and spawns
agents; your conversation context receives only the final answer.
What it is
- A JavaScript script that describes the orchestration: which
agents to spawn, in what order, how to combine their output.
- Runs in an isolated background runtime, separate from your
conversation. The script is the plan; it persists across the run.
- Scale: up to 16 agents concurrent, scaling to 50-1000+ agents
per run.
- Context model: only the final synthesized answer returns to
your context. The intermediate fan-out stays in the runtime.
- Accepts an
args parameter for parameterized runs.
- A paused run can resume within the same session with cached
results from already-completed agents.
Critical constraint: the script has no direct I/O
The orchestration script itself cannot read or write files or run
shell commands. Only the agents the script spawns can do I/O.
This shapes how you write a workflow: the script is pure
coordination logic (spawn, gather, combine). Anything that touches
the filesystem, git, or a shell must be delegated to a spawned
agent. Don't write a script that tries to readFile or exec a
command -- it has no such capability.
When to use vs the Task tool
| dimension | Workflow tool | Task tool |
|---|
| Plan location | In the JS script (durable across run) | In the dispatching conversation |
| Context model | Only final answer returns | Each agent's output returns to context |
| Scale | 50-1000+ agents | A handful of parallel agents |
| Repeatability | Parameterized via args, resumable | One-shot per dispatch |
Reach for Workflow when the orchestration is large enough that
holding every agent's output in conversation context would blow the
budget, or when the same multi-agent plan should run repeatably with
different inputs.
Reach for the Task tool for everything smaller: a single runner,
a few parallel runners, anything where you want each agent's output
visible in your context.
Best-fit shapes
- Audit + remediate fan-out at scale. A survey phase spawns
dozens of read-only agents (one per file, module, or finding),
then a synthesis phase combines findings. When the fan-out is 50+
agents, the Task tool's per-agent context return doesn't fit;
Workflow keeps it in the runtime and returns only the synthesis.
- Chained design -> impl -> review. The script sequences the
phases and passes each phase's output to the next as script-local
data, returning only the final reviewed result.
NOT for
- Single-runner tasks. One issue, one PR -- use a runner via the
Task tool. A workflow script is pure overhead here.
- Small parallel tasks. A few independent edits across different
files -- the Task tool with parallel dispatches is simpler and
keeps each result in context.
The dividing line is scale and context pressure, not task type. If
the Task tool fits, it's the simpler choice.
Reference example
The bundled /deep-research workflow is the canonical pattern:
fan out web searches and source fetches across many agents,
cross-check claims adversarially, then synthesize a single cited
report. It demonstrates fan-out -> verify -> synthesize end to end.
Anti-patterns
- Using Workflow for single-runner tasks -- one issue, one PR, one runner; a workflow script is pure overhead here.
- Writing I/O in the orchestration script -- the script has no direct I/O; delegate filesystem and shell work to agents.
- Assuming each agent's output returns to context -- only the final synthesized answer
does; intermediates stay in the runtime.
Related
orchestration-patterns --
the broader execution-shape table; Workflow is the at-scale
implementation of the audit + remediate and chained shapes.dispatch-options -- the dispatch
mechanisms for everything below Workflow scale.
