Orchestration patterns

Every pattern Gantry ships — what each declares, what it takes, and its whole annotated text.

build

The default milestone build: decompose a plan into ordered milestone briefs, then build each brief. What a flagless `gantry <plan>` runs, and what `until` calls to build one cycle's plan.

entry patterns.build default on_stop.any patterns.write_handover

parameter	default	what it is
plan_source path takes the run's plan	plan.md	The plan prose the milestone planner reads, and the run's identity.
protected_check path	.gantry/no-protected-check	An optional record-path check an enclosing recursive goal run freezes.
attempt_ceiling text	— declares no default	The ordinary build attempt ceiling passed to each sprint task.
troubleshoot_prompt prompt-id	troubleshoot	The troubleshoot pass's prompt, passed through the milestone and run-scoped gate repair paths.
merge_attempt_ceiling text	— declares no default	The finish-time merge repair ceiling passed to the bundled merge pattern.

map

Write a roster of independent tasks from a source document, check it, then build, gate and repair every task in turn. One failed task does not end the run; a streak of them does.

entry patterns.map on_stop.any patterns.map_write_handover flag --map → source

parameter	default	what it is
source path takes the run's plan	— declares no default	The document the roster is written from; it is also the run's identity.
merge_attempt_ceiling text	— declares no default	The finish-time merge repair ceiling passed to the bundled merge pattern.
troubleshoot_prompt prompt-id	troubleshoot	The troubleshoot pass's prompt, used by map task repair and finish-time merge repair.

Work toward a goal expressed as an executable acceptance check: run the check, and while it is red, plan the gap it reports, build that plan, and start over. Ends when the check goes green, or when the gap planner reports there is no actionable gap left.

entry patterns.until on_stop.any patterns.write_handover flag --until → until_source

parameter	default	what it is
until_source path takes the run's plan	— declares no default	The goal prose an absent acceptance check is authored from.
check path	bin/goal-check	The acceptance check record path: exit zero is achieved and non-zero is a gap.
max_cycles text	— declares no default	Optional operator ceiling for completed build cycles; `unbounded` means no ceiling.
merge_attempt_ceiling text	— declares no default	The finish-time merge repair ceiling passed to the bundled merge pattern.
troubleshoot_prompt prompt-id	troubleshoot	The troubleshoot pass's prompt, used by build cycles and finish-time merge repair.

The documents about the format

document	what is on it
The pattern format	The normative reference for the pattern format: every primary word, table, key, reference form and closed value vocabulary the engine conforms to.
Writing a pattern from scratch	Four stages, each one complete runnable file: a gated task, a decomposition, a map over a task directory, and an until pattern that recurses until a check passes.
The authoring guide	The narrative companion to the format reference: how to think while writing a pattern, and which shape the format wants for each kind of work.
The reference card	Condensed lookup: every word, key and closed vocabulary with a one-line meaning and a pointer into the format reference.
Among the orchestration formats	Where this format sits against Ansible, CI pipelines, Airflow, Temporal and the rest, and the design choices argued as positions rather than listed as features.
The pattern gallery	An annotated tour of the shipped corpus: what each pattern is for, how it is built, and the lines a fork of it would edit.

The pattern language contract

Pattern language reference contract — 22 sets exported from src/engine/pattern_language.rs

Primary words

The definition word, the producing-step and composition words, and the one value word. `if` is the one step recognized by its key rather than a `type` value.

description	kind	word
A named callable sequence of parameters and steps.	definition	pattern
Runs one fresh agent session.	producing_step	agent
Runs Gantry's authoritative project check package.	producing_step	gate
Runs a deterministic shell command with declared outputs.	producing_step	command
Runs one body pattern for each task in a directory list.	composition	for
Routes on an output, step outcome, or absence.	composition	if
Ends the run with one authored note.	composition	stop
Invokes another pattern in the composed namespace.	composition	call
Declares a path produced by exactly one producing step.	value	output

Effect-producing step kinds

The only step kinds that run an external effect and can declare outputs.

kind	stage role
agent	build
gate	gate
command	utility

Parameter kinds

The closed `kind` vocabulary for `[[patterns.<name>.parameters]]`.

kind
path
prompt-id
text

Parameter binding forms

The value forms accepted when a caller binds a callee parameter.

description	form
A string without whole-value reference syntax binds directly.	literal
A complete `{{name}}` slot binds a parameter, output, task value, or stop reason by handle.	whole_value_reference
`text` parameters may carry prose with embedded references resolved for prompts and notes.	text_prose

Agent selection keys

The optional keys an `agent` step may use to declare its stage and per-step selection overrides.

description	key	value kind
Declares which stage the agent step performs; omitted resolves to `execute`.	stage	closed_stage
Per-step model override; omitted lets the resolved role or global default decide.	model	non_empty_string
Per-step effort override; omitted lets the resolved role or global default decide.	effort	closed_effort
Per-step harness override; omitted lets the resolved role or global default decide.	harness	registered_harness

Step title keys

The step kinds accepting the optional `title` key, whose value the loader neither substitutes nor infers.

key	step kind	value kind
title	agent	literal_string
title	gate	literal_string
title	command	literal_string
title	for	literal_string
title	if	literal_string
title	call	literal_string
title	stop	literal_string

Step summarize keys

The step kinds accepting the optional `summarize` key, which are the kinds a bundled summarizer prompt fits; omission is off.

key	step kind	value kind
summarize	agent	boolean
summarize	gate	boolean

Agent stages

The closed `stage` vocabulary for an `agent` step; omission resolves to `execute`.

role	stage
plan	environment-build
plan	plan
plan	gate-build
build	execute
util	gate
build	fix
build	investigate
build	troubleshoot
review	review
plan	replan
util	merge
build	resolve
util	support
util	done

Agent efforts

The closed `effort` override vocabulary for an `agent` step.

effort
low
medium
high

Agent harnesses

The registered harness ids accepted by an `agent` step's `harness` override.

harness
claude
opencode
codex
gemini

on_stop header contract

The accepted `header.on_stop` shapes and hook-table keys for engine stops.

description	kind	name	syntax
A single pattern value is shorthand for the `any` catch-all hook.	accepted_input	header.on_stop	on_stop = "<pattern>"
A hook table keys handlers by hookable stop class plus `record` and the `any` catch-all key; `merge` is not an accepted key.	accepted_input	header.on_stop	[header.on_stop]
Class-specific hook for step stops; it takes precedence over `any`.	hook_key	step	step = "<pattern>"
Class-specific hook for absence stops; it takes precedence over `any`.	hook_key	absence	absence = "<pattern>"
Class-specific hook for plan stops; it takes precedence over `any`.	hook_key	plan	plan = "<pattern>"
Class-specific hook for gate stops; it takes precedence over `any`.	hook_key	gate	gate = "<pattern>"
`record` is a stop class name accepted in the hook table, but record hooks never dispatch and record stops never fall through to `any`.	hook_key	record	record = "<pattern>"
`any` is only the hook-table catch-all key; it is not a stop class.	catch_all_key	any	any = "<pattern>"

Stop classes

`any` is only an `on_stop` hook-table catch-all key; it is not a stop class. `record` and `merge` hooks never dispatch.

class	description	hookable
step	A producing step ended as `failed` and no pattern route handled that outcome.	true
absence	A required branch or runtime binding was absent and no pattern route handled that absence.	true
plan	Plan handling could not produce executable work, including a planning result that produced no work.	true
gate	Ordinary gate routing did not handle a gate stop, including a baseline or admission gate that failed before authored recovery could run.	true
record	The run record cannot support execution or resume. Record hooks never dispatch and a record stop never falls through to `any`.	false
merge	Merge or merge-repair work could not be completed. `merge` is not an accepted hook key, so a merge stop dispatches no hook.	false

Value references

The whole-value `{{...}}` references the loader resolves to handles before runtime.

description	kind	syntax
The current invocation's parameter value.	parameter	{{parameter}}
A same-named parameter another pattern declares; the first of them bound in the current frame supplies the value.	parameter_fallback	{{parameter}}
A declared output's current readable value, or its path in a path slot.	output	{{output}}
The active task file path inside a `for` body.	task	{{task}}
The active task name inside a `for` body.	task_name	{{task.name}}
The active task prompt inside a `for` body.	task_prompt	{{task.prompt}}
The active task gate command inside a `for` body.	task_gate	{{task.gate}}
The engine-forced stop reason inside an `on_stop` hook.	stop_reason	{{STOP_REASON}}

Task references

The references and command environment variables available inside a `for` body.

command environment	reference	syntax
task	task	{{task}}
task_name	task_name	{{task.name}}
task_prompt	task_prompt	{{task.prompt}}
task_gate	task_gate	{{task.gate}}

Command environment inputs

The environment variables a `command` or custom `gate.command` receives instead of template substitution in `run`.

description	name	presence
The active orchestration directory.	orchestration	always
Each currently bound parameter, keyed by its authored name.	<parameter name>	when_bound
Each declared output readable in this frame, plus the step's own declared outputs as absolute paths to write.	<output name>	when_present
The active task file path.	task	inside_for
The active task name.	task_name	inside_for
The task front matter prompt.	task_prompt	inside_for_when_present
The task front matter gate command.	task_gate	inside_for_when_present

Boundary references

The closed forms accepted by `agent.diff`, `gate.restore`, `command.restore`, and `call.restore`.

kind	resolved kind	syntax
run_base	run_base	run-base
iteration_start	iteration_start	iteration-start
previous_step	previous_step	previous-step
before	before	{ before = "<step>" }

If conditions

The condition forms an `if` step accepts.

kind	syntax
output_presence	if = "<output>"
output_value	if = { <output> = "<value>" }
step_outcome	if = { <step> = "<outcome>" }

If routing

The branch target forms and absence route exposed by `then` and `else`.

description	kind	syntax
Routes a step-outcome or equality match to one pattern.	then_pattern	then = "<pattern>"
Routes every declared output value by table entry.	then_values	then = { value = "<pattern>" }
Routes an absent output or an unmatched equality/outcome.	else_absence	else = "<pattern>"
The reserved no-op target a branch may name explicitly.	nothing	"nothing"

Step outcomes

The closed outcome words a step-outcome `if` may test.

outcome	step kinds
done	agent · gate · command
failed	agent · gate · command
green	gate
red	gate

For failure routing

The closed `fail` vocabulary for a `for` step; omission is `stop`.

value
stop
continue

Output scopes

The closed `scope` vocabulary for declared outputs; omission scopes the output to the current invocation.

value
run

Prompt-only substitution

The fields resolving `{{...}}` references, as a whole-value slot or inside prose, against `command.run`, which receives its data through the environment instead.

accepts references	description	field
true	Resolves a prompt id from a literal or whole-value reference.	agent.prompt
true	Resolves declared input paths before launching an agent.	agent.inputs
true	Resolves prose placeholders into prompt environment text.	agent.text
true	Resolves protected orchestration paths.	agent.protected
true	Resolves prose placeholders into the authored stop note.	stop.note
false	Must receive data through environment variables.	command.run

Which copy of a pattern wins

Pattern registry tiers — 3 rows exported from src/engine/pattern_language.rs

tier	shown as	consulted
project	project	1st
global	global	2nd
bundled	built-in	3rd

Supporting patterns

merge

Default finish-time merge repair: resolve textual conflicts, adjudicate main-side residue, and route red merge gates through the shared troubleshoot pass.

entry patterns.merge on_stop.any patterns.write_handover

parameter	default	what it is
merge_state text	— declares no default	The engine-derived merge state: `conflicted`, `residue`, or `gate-red`.
merge_attempt_ceiling text	— declares no default	The per-state attempt ceiling the engine enforces around this pattern.
merge_attempt text	— declares no default	The one-based attempt count the engine is running for the current merge state.
troubleshoot_prompt prompt-id	troubleshoot	The troubleshoot pass's prompt, used for a red declared gate after integrating the home branch.
protected_check path	.gantry/no-protected-check	The gate protection parameter the enclosing run freezes.
declared_gate_command path	bin/gate	The run-scoped gate command that judges the integrated worktree.
branch text	— declares no default	The run branch label the merge prompts name.
conflict_context text	— declares no default	The engine's conflict path list or marker-free gate-red fact.
files text	— declares no default	The per-file residue evidence the adjudicator prompt reads.
merge_last_refusal text	— declares no default	The engine's previous refusal reason for this merge state.

milestone

One milestone: brief the environment, plan the brief into task files under `sprints/`, author and ground the gate, build each task through the included `sprint` pipeline, then review the milestone as a whole. Called by `build` once per milestone brief.

entry patterns.milestone on_stop.any patterns.write_handover

parameter	default	what it is
plan_source path	— declares no default	The milestone brief the environment briefer, the task planner, and the gate author read.
execute_prompt prompt-id	execute	The task executor's prompt.
review_prompt prompt-id	review	The task reviewer's prompt.
troubleshoot_prompt prompt-id	troubleshoot	The troubleshoot pass's prompt.
merge_attempt_ceiling text	— declares no default	The finish-time merge repair ceiling passed to the bundled merge pattern.
protected_check path	.gantry/no-protected-check	An optional record-path check an enclosing recursive goal run freezes.
attempt_ceiling text	— declares no default	The attempt ceiling passed to each sprint task.

sprint

One sprint task: execute the brief, gate it, recover a red, review the result, gate the reviewer's own edits, repair or revert them, and commit. Included by `milestone` and called once per sprint task.

entry patterns.sprint on_stop.any patterns.write_handover

parameter	default	what it is
execute_prompt prompt-id	execute	The executor's prompt; a pass that wants its own names it in full.
review_prompt prompt-id	review	The reviewer's prompt; a pass that wants its own names it in full.
troubleshoot_prompt prompt-id	troubleshoot	The troubleshoot pass's prompt, passed whole into the troubleshoot pattern.
merge_attempt_ceiling text	— declares no default	The finish-time merge repair ceiling passed to the bundled merge pattern.
declared_gate_command path	— declares no default	The gate command that judges this task.
protected_check path	.gantry/no-protected-check	An optional record-path check an enclosing recursive goal run freezes.
attempt_ceiling text	— declares no default	The remaining attempts for this task; `unbounded` means no ceiling.

troubleshoot

Shared troubleshoot infrastructure: one red-gate repair pass, the shared plan-change review route, and the engine-stop handover hook used by bundled patterns.

entry patterns.troubleshoot on_stop.any patterns.write_handover

parameter	default	what it is
troubleshoot_prompt prompt-id	troubleshoot	The troubleshoot pass's prompt, named in full by the caller.
position text	— declares no default	The troubleshoot pass's own briefing: which red gate it is repairing and what it may do.
declared_gate_command path	bin/gate	The gate command that judges the troubleshoot pass.
protected_check path	.gantry/no-protected-check	An optional record-path check an enclosing recursive goal run freezes.