Workflows orchestrate multi-stage AI tasks as directed graphs. Where an agent handles a single task — reading files, running commands, reasoning about code — a workflow chains multiple agents together into a pipeline with branching, retries, parallel execution, and human-in-the-loop gates.

A workflow is a directory containing a WORKFLOW.md file that defines the pipeline using Graphviz DOT syntax. Each node in the graph is a stage — an LLM call, a shell command, a human review gate, or a conditional branch — and edges define the flow between them.

A workflow pipeline is a directed acyclic graph (with optional retry loops). The execution engine walks the graph from Start to End, running each node's handler and selecting the next edge based on conditions, outcomes, and edge weights.

Each node can:

Nodes communicate through a shared key-value context. After each node completes, its outcome and any context updates are available to subsequent nodes via prompt variable expansion and edge conditions. When an agent node has multiple labeled outgoing edges, the engine automatically provides routing instructions — via a tool call for tool-capable sessions, or an XML tag fallback otherwise — so routing decisions are decoupled from the agent's text output.

Workflows reference agents by name. A node like Build [agent="code-engineer", prompt="Implement the design"] tells the engine to run the code-engineer agent for that stage. This separation means a shared workflow committed to a repository can be executed with different agent configurations by different users — one user might have a code-engineer agent backed by Anthropic, another by OpenAI.

Workflows are discovered from .stencila/workflows/ in the workspace:

Each workflow gets its own subdirectory. The directory name must match the name field in the WORKFLOW.md frontmatter.