Plan file schema

The complete field reference for plan YAML files. Concepts and worked examples live in the Plans section; this page is the lookup table. Every field name in a plan file is snake_case, at every depth — top level, steps, control-step grammar, and an agent step’s input alike. That is the one spelling to author in, and what everything writing a plan emits: graph plan show (including --json), the authoring commands, and the workbench’s save. The planner uses camelCase internally (toolName, queryToAnswer) because that is the schema the model is taught. You never see it: a plan it drafts is normalized to snake_case before it reaches disk. The camelCase spellings stay accepted on the way in, so a plan authored before this settled still loads — and rewriting it with any authoring command normalizes it. Optional fields you never set are omitted rather than written as null/[].

Top level

Field	Required	Type	Notes
`identifier`	yes	string	tool-name-safe (`[a-zA-Z0-9_-]+`); becomes `plan__<identifier>` in the catalog
`name`	yes	string	display name
`description`	yes	string	routing signal — what the agent reads when choosing tools
`exemplars`	no	list of string	example user phrasings; folded into the tool description verbatim (routing)
`requires_servers`	no	list of string	MCP server dependencies; unconfigured → plan hidden from the catalog, loud error by name (discovery)
`input_schema`	no	JSON Schema	validates inputs before any step runs; referenced as `{{input.*}}` (inputs)
`steps`	yes	list of step	run sequentially
`solver`	no	object	LLM-written finish (finish modes)
`output`	no	template map	structured JSON finish, zero LLM

solver and output are mutually exclusive; declaring neither makes the plan silent (side effects only).

`solver`

Field	Required	Notes
`query_to_answer`	yes	instructions for the solver; itself a template, so sections can adapt it to the data
`system_prompt`	no	extra system-level guidance for the solver call, on top of the built-in solver prompt
`data`	yes	template map of what the solver sees — whole results spliced by template; oversized payloads are truncated/sampled

Steps

Field	Required	Notes
`id`	yes	identifier (letters, digits, `_`, not digit-leading), unique across the plan including body sub-steps; may not shadow the reserved roots `input`, `item`, `index`, `accumulator`, `length`
`tool_name`	yes	a catalog tool (`server__`, `user__`, `builtin__`, `plan__`), `plan_and_execute`, or a control step below
`input`	yes	the tool’s arguments; string values are templates over `input` and earlier step results
`reasoning`	no	free text, shown in traces

Control steps

Seven reserved tool_names are executor-intercepted, never dispatched to a registry. Their input is the control grammar — snake_case like everything else, and the only part of a step’s input graph normalizes, since every other tool’s arguments belong to that tool:

`exit` — end the plan early

Field	Required	Notes
`when`	no	logical gate (below); mutually exclusive with `infer`; both omitted = unconditional exit
`infer`	no	yes/no question judged by the `judge` role
`model`	no	model for the `infer` verdict: a role name, `default`, or a named model; ignored without `infer`
`status`	yes	`success` \| `error` — error maps to exit code 4 on `plan run`
`message`	no	shown as the plan’s answer / error message; may use templates
`output`	no	template map emitted as the plan’s structured output when the exit fires

`decide` — fork into one of two branches

Field	Required	Notes
`if`	exactly one of `if`/`infer`	logical gate (same grammar as `when`)
`infer`	〃	yes/no question judged by the `judge` role
`model`	no	as on `exit`; may itself be a template
`then`	yes	body (below), run when the gate holds
`else`	no	body, run otherwise

`filter` — partition a list

Field	Required	Notes
`over`	yes	template that must render to an array
`where`	exactly one of `where`/`infer`	logical gate (same grammar as `when`), evaluated per element with `{{item}}`/`{{index}}` in scope
`infer`	〃	yes/no question judged per element by the `judge` role
`model`	no	as on `exit`; applies to every `infer` verdict
`concurrency`	no	max `infer` verdicts in flight; default 1; ignored for `where`

Legal everywhere, including inside decide branches and map/reduce bodies — the one nestable control step (it makes no tool call). Inside a body its {{item}}/{{index}} shadow the enclosing body’s within the gate.

`map` / `reduce` — run a body per item

Field	Required	Notes
`over`	yes	template that must render to an array
`do`	yes	body (below), run once per element with `{{item}}`/`{{index}}` in scope (`reduce` adds `{{accumulator}}`)
`concurrency`	no (`map` only)	max items in flight; default 1 (sequential); `results` stays in input order
`initial`	no (`reduce` only)	starting accumulator; default `null`

`agent` — delegate an open-ended sub-task

Field	Required	Notes
`prompt`	yes	the sub-task, as a self-contained instruction; may use templates (rendered when the loop starts)
`output_schema`	yes	JSON Schema the result must satisfy; must be `"type": "object"` or declare `properties`
`tools`	no	glob patterns selecting which catalog tools the agent may call (e.g. `linear__*`); defaults to the full catalog minus `plan_and_execute`
`max_iterations`	no	tool rounds before the loop gives up; default 8
`model`	no	model for the loop: a role name, `default`, or a named model
`system_prompt`	no	replaces the default agent system prompt; may use templates

Legal everywhere, including inside decide branches and map/reduce bodies.

`ask` — put a question to the user

Field	Required	Notes
`prompt`	yes	the question as the user sees it; may use templates
`output_schema`	yes	JSON Schema for the answer; must be `"type": "object"` with primitive-typed properties only (string, number, integer, boolean, enum)
`when_unanswered`	no	`fail` (default) \| `default` — behaviour when nobody can be asked
`default`	with `when_unanswered: default`	fallback answer; must conform to `output_schema`; may use templates

Legal everywhere, including inside decide branches and map/reduce bodies. Whether a human is reachable depends on the host, not the plan, so when_unanswered is what keeps one plan runnable both interactively and in CI.

Gate grammar (`when` / `if` / `where`)

A single comparison: { value, op, to }, where value is usually a template (typed splice keeps numbers numeric).

`op`	Meaning
`eq`, `ne`	equality on any JSON value
`gt`, `lt`, `gte`, `lte`	numeric ordering
`empty`, `not_empty`	arrays, strings, objects, null (`to` omitted)
`contains`	substring, or array membership

Body grammar (`then` / `else` / `do`)

Either form:

A single tool call — {tool_name, input}, no id. Any catalog tool, including plan__* and plan_and_execute.
An inline step list — normal steps with ids, run in order, with same-branch/same-iteration dataflow. Body ids must not reuse top-level ids and are invisible outside the body.

Bodies must not contain decide, map, or reduce (branches may contain exit; map/reduce bodies may not). agent, ask, and filter are legal in any body. For other nested control flow, call a plan__* sub-plan — cycles are detected and nesting is capped at 8.

Step results of control steps

Step	Result shape
`exit` (not fired)	`{passed: true, verdict?, reason?}`
`agent`	`{output, iterations, tools_called, final}` — `output` conforms to `output_schema` when `final` is true; when the budget ran out first, `final` is `false` and `output` is `{}`
`ask`	`{answer, answered, reason?}` — `answer` conforms to `output_schema`; `answered` is false when the `default` was used, and `reason` is then `"declined"` or `"unavailable"`
`decide`	`{branch, verdict, reason, result}` — `result` is the branch’s single-call result or its last step’s result
`filter`	`{count, items: […], dropped: […], dropped_count}` — both halves of the partition, input order
`map`	`{count, results: […]}` in input order
`reduce`	`{count, result}` — the final accumulator

Getting Started

Plans

Workbench

Tools

Models

Chat & ask

Cookbook

Reference

Architecture

Changelog

Plan file schema

Top level

`solver`

Steps

Control steps

`exit` — end the plan early

`decide` — fork into one of two branches

`filter` — partition a list

`map` / `reduce` — run a body per item

`agent` — delegate an open-ended sub-task

`ask` — put a question to the user

Gate grammar (`when` / `if` / `where`)

Body grammar (`then` / `else` / `do`)

Step results of control steps

​Top level

​solver

​Steps

​Control steps

​exit — end the plan early

​decide — fork into one of two branches

​filter — partition a list

​map / reduce — run a body per item

​agent — delegate an open-ended sub-task

​ask — put a question to the user

​Gate grammar (when / if / where)

​Body grammar (then / else / do)

​Step results of control steps

Top level

`solver`

Steps

Control steps

`exit` — end the plan early

`decide` — fork into one of two branches

`filter` — partition a list

`map` / `reduce` — run a body per item

`agent` — delegate an open-ended sub-task

`ask` — put a question to the user

Gate grammar (`when` / `if` / `where`)

Body grammar (`then` / `else` / `do`)

Step results of control steps