Set workflow node options and limits
Each step of a workflow can use its own model, tools and working directory, and the definition is checked before anything starts.
What the file holds
A workflow definition is a JSON file. Chetty writes it before starting the workflow, and in a managed Project the file must live inside that Project, for example as workflow.json, because the host path is not visible there.
The file holds either a list of nodes or an object with a nodes list. The object form may also set title, fork and background.
[
{ "id": "inspect", "task": "Inspect the relevant files and report findings." },
{ "id": "change", "task": "Make the agreed change.", "deps": ["inspect"] }
]Every node needs a unique id and a complete task. A node with prerequisites lists them in deps.
Choose options per node
A node may also set:
- a model, and a thinking level for that step;
- a tool allow-list, so the step can only use the tools you name;
- read-only mode for the step;
- a sub-agent type, when a custom type fits the work;
- a working directory as an absolute path in
cwd.
A node normally starts a fresh sub-agent. Forking the conversation the workflow started from is an option too, but a fork cannot be combined with the narrowing options above.
Each node inherits the conversation's working directory unless its cwd names another one, so a workflow started from a worktree runs there. A workflow started without background returns a handle first; set background: false when you need every result before you continue. Arguments you pass to WorkflowStart override the same keys in the file.
Limits and rejections
A workflow may have up to 128 nodes, and each task may hold up to 16,000 characters. Unknown dependencies, cycles, duplicate ids and longer tasks are rejected before the workflow starts.
A dependent node receives a handover of up to 4,000 characters from each direct prerequisite. Write a ## Handover section naming only the findings that the next step needs, and Chetty passes that section instead of the whole result; read Pass results forward.
Add steps to a running workflow
WorkflowAddNodes adds follow-up steps to a workflow that is already running, which lets you extend the plan without starting over. Read Check or resume the workflow for progress, resume and stop.