Workflow file reference
A workflow is a directory containing one flow.* file and any prompt files referenced by its steps. It is the durable program for a multi-agent run: it names the steps, which agents run each step, how results feed forward, and what nax must wait for before continuing.
Council-style workflows usually start with independent new-run submissions, feed all first-pass results into a cross-review step, then send those outputs into one final synthesis step.
- flow.yml
Supported files
flow.yml, flow.yaml, flow.json, and flow.toml are supported.
JavaScript and TypeScript flow files are blocked by safe mode during workflow discovery. Use static flow files for project workflows.
Top-level keys
| Key | Required | Purpose |
|---|---|---|
id | yes | Stable workflow id used by nax run <id>. |
title | yes | Human name shown in lists, prompts, and dashboard. |
description | recommended | One-sentence summary. |
disabled | no | Set to true to hide a workflow from nax list, nax run, and the dashboard without deleting its files. |
defaults | no | Default transport, notification, and agents. |
steps | yes | Ordered workflow steps. |
Step keys
| Key | Values | Purpose |
|---|---|---|
action | issue, comment, human-review | Submission or gate behavior. |
submit | new-run, follow-up | Start fresh or reuse prior context. |
agents | claude, gemini, codex | Agent fan-out targets. |
input | [{ step, results }] | Earlier results to include. |
waitFor | agent-results | Wait until every configured agent has a result. |
Example
id: review
title: Review
description: Review, cross-review, and synthesize findings.
defaults:
transport: auto
agents: [claude, gemini, codex]
steps:
- id: review
title: Review
prompt: prompts/1_review.md
action: issue
submit: new-run
agents: [claude, gemini, codex]
waitFor: agent-results
- id: cross-review
title: Cross Review
prompt: prompts/2_cross-review.md
action: comment
submit: follow-up
agents: [claude, gemini, codex]
input:
- step: review
results: all
waitFor: agent-results
- id: synthesize
title: Summarize Consensus
prompt: prompts/3_synthesize.md
action: issue
submit: new-run
agents: [codex]
input:
- step: review
results: all
- step: cross-review
results: all
waitFor: agent-resultsProject-local flows with the same id as bundled flows shadow the bundled version. This is useful when intentional and confusing when accidental.
See also
- Write custom workflows for a guided setup.
- Configuration reference for flow discovery.
- Security policies for safe-mode behavior.
- Council pattern for why independent passes feed cross-review and synthesis.
- Architecture for execution flow.