Skip to content

Workflow schema

A recipe's workflow.yaml is a directed acyclic graph of nodes. Each node is one agent invocation or one deterministic verifier; each edge states why the next node runs. mini-ork validate checks the file against schemas/workflow.schema.json before a run starts.

Top-level fields

Field Required Meaning
version yes Version string, e.g. 0.1.0
task_class yes Must match the name of a task class
nodes yes At least one node
edges yes Directed edges; the graph must be acyclic
description no Human-readable summary
dispatch_mode no Default for nodes that do not set one
rollback_strategy no Node name of type rollback invoked on hard failure
max_self_correction_iterations no Bounded repair rounds
recursion no Bounded recursive recipes (see below)
source_artifact, human_decision_artifact, selected_option_artifact no Named artifacts for publish and approval flows
tags no Free-form labels

additionalProperties is false: an unknown key fails validation rather than being ignored.

Nodes

Required

Field Meaning
name Unique id; lowercase, [a-z][a-z0-9_-]*
type One of the ten node types below
dispatch_mode serial · parallel · partitioned · speculative

Node types

Type Role
planner Decompose the objective into the plan
researcher Gather context, produce findings
transform Run a registered deterministic transform (transform: required)
implementer Write the change
reviewer Judge the change; may veto, never fabricate a pass
verifier Run a deterministic verifier (verifier_ref)
eval Advisory graded evaluation; never gates
reflector Extract lessons after a verdict
publisher Apply publish gates and deliver
rollback Restore the tree

Dispatch modes

Mode Behaviour
serial One work unit at a time
parallel All units at once
partitioned Shard by partition_key
speculative Race N copies; first successful result wins

Optional fields

Field Meaning
model_lane Lane to dispatch to (default sonnet)
prompt_ref Recipe-relative prompt template; null for deterministic nodes
verifier_ref Recipe-relative verifier script for verifier nodes
gates Gate ids that must pass before the node is done
tools Declared harness tools, e.g. {native: [...], mcp: [...]}
mcp_servers MCP servers the node may reach
skills Skills the node may use; anything unnamed is invisible
agent_doc Instruction document injected into the dispatch
env Node-scoped env declarations; values may be ${NAME} references
requires_capabilities Capability tags the lane must have
timeout_minutes Hard timeout; 0 inherits
max_cost_usd Per-invocation cost ceiling; 0 = none
retries Node retry count, 0–5 (default 1)
retry Infra-level retry policy: max_attempts, initial_interval, backoff_factor, max_interval, jitter
partition_key Artifact or item key used to shard work
strict_handshake When true, only the self-report counts as completion
inputs / outputs Typed artifact ports
transform Registered transform id, required for transform nodes
description Used in the DAG and as a fallback prompt

retries is not retry

retries: (an integer) counts node retries before escalation. retry: (an object) governs infrastructure attempts for transient failures with backoff and jitter. A retries edge governs revise rounds. The three caps compose independently.

Edges

edges:
  - { from: planner, to: implementer, edge_type: depends_on }
  - { from: implementer, to: test, edge_type: verifies }
edge_type Means
depends_on Target runs after source succeeds
supplies_context_to Source's output is injected into the target
verifies Target checks the source's artifact
blocks Source can prevent the target from running
retries Source failure sends work back to the target for bounded rounds
escalates_to Source failure invokes the target (typically rollback)
human_decision_gate Target records a human approval boundary
verifies_user_choice Target checks a decision the human recorded

Optional edge fields:

  • condition — a jsonschema-backed predicate (pointer, match, negate) evaluated against the source node's output artifact. Consumed on retries edges; the return code is authoritative everywhere else.
  • from_output / to_input — explicit artifact handoff between typed ports.
  • recursive — marks a bounded recursive control edge excluded from DAG readiness ordering.

Annotated example

The shipped code-fix graph, abridged:

version: "0.1.0"
task_class: code_fix

nodes:
  - name: planner
    type: planner
    model_lane: planner
    prompt_ref: prompts/planner.md
    dispatch_mode: serial

  - name: implementer
    type: implementer
    model_lane: worker
    prompt_ref: prompts/implementer.md
    dispatch_mode: serial
    gates: [scope_gate, budget_gate]
    tools:
      native: [Read, Write, Edit, Bash]
      mcp: [codegraph]

  - name: typecheck
    type: verifier
    prompt_ref: null
    verifier_ref: verifiers/typecheck.py
    dispatch_mode: serial

  - name: reviewer
    type: reviewer
    model_lane: reviewer
    prompt_ref: prompts/reviewer.md
    dispatch_mode: serial

  - name: rollback
    type: rollback
    prompt_ref: null
    dispatch_mode: serial

edges:
  - { from: planner,     to: implementer, edge_type: depends_on }
  - { from: implementer, to: typecheck,   edge_type: verifies }
  - { from: typecheck,   to: reviewer,    edge_type: depends_on }
  - { from: typecheck,   to: rollback,    edge_type: escalates_to }
  - { from: reviewer,    to: implementer, edge_type: retries, max_rounds: 2 }

rollback_strategy: revert_branch

Read it as: verify the patch, then review it; a failed gate first sends findings back to the implementer for at most two rounds, and only after those are spent does the escalates_to edge reach rollback.

Recursion

A recursive recipe declares a bounded loop:

recursion:
  max_iterations: 5
  convergence_check: <registered check>
  budget_cap_per_iter_usd: 0.50
  budget_cap_total_usd: 2.00
  divergence_kill: <registered check>

The executor derives the MO_RECURSION_* variables from this block. Set them by hand only to reproduce a run; a partial block fails mini-ork validate.

Tool boundary

Node tools and mcp_servers are an allow-list, not a suggestion. The union of tools.mcp and mcp_servers is the complete set the node can reach. A recipe that grants repo write, untrusted-content ingress and an outbound channel to the same node should not pass review — see the capability profiles at the top of the code-fix workflow.

Validating a change

mini-ork validate                 # static checks over recipes and config
mini-ork garden                   # drift detection against the registry