Workflow architecture

Workflows are declarative files, not code. This page explains what each file type means, how the pieces connect, and what the server delivers to the agent as work progresses.

For server enforcement (checkpoints, dispatch, fidelity), see architecture overview. For file shapes, see the schema reference.

Overview

Think in two layers:

On disk — a workflow is a folder of YAML and markdown. Nothing in it is executable code; the files describe a process the agent follows step by step.
At runtime — the agent does not open those files. It calls MCP tools, and the server returns one piece at a time so context stays on the work in front of it — workflow overview, then the current activity, then each technique as the worker reaches it (Resolution).

The four file types in a workflow directory and how they reference each other.

Workflows

A workflow is the whole process from start to finish. A document-review workflow, for instance, takes a document from intake through outlining and peer review to sign-off.

The workflow is defined by a single manifest file, workflow.yaml. That file holds:

Identity — id, title, version
Variables — named slots in session state, with optional defaults seeded at session start
Graph — each activity's exits, bound to the destination each leads to
Borrowed activities — an activities list naming activity files borrowed from other workflows; the workflow's own activities are the files in its activities/ folder
Initial activity — where a new session begins
Rules and techniques — grouped by audience: techniques.workflow and rules.workflow for the orchestrator, techniques.activity and rules.activity for every worker, and rules.universal for both

A run of steps shared between activities is not in the manifest: it is a file of its own under routines/, beside activities/ (see below).

When a session starts, the server reads this manifest. The first get_workflow call returns:

orchestrator techniques and rules
variable definitions
the graph
initialActivity — the id of the activity where work begins

The orchestrator uses initialActivity for its first next_activity call. After that, workflows describe structure only: the agent follows steps, and the server enforces:

which activity is current
whether a checkpoint is blocking progress
what values sit in the variable bag

What the workflow manifest holds. Variables and rules span the entire run; the graph says where each activity's exits lead. The workflow's own activities are the files in its activities/ folder, and an activities list names only files borrowed from other workflows.

Example: an invented document-review workflow moves through these activities. intake is the initialActivity; later phases depend on variables set along the way.

Activities

An activity is one phase of a workflow — a stretch of work with a clear goal. Outline, Peer review, and Sign-off are activities inside document-review.

Each activity lives in its own YAML file under activities/. That file has two main parts:

steps[] — the ordered list the worker runs from top to bottom
exits — the named outcomes the phase can end with; the workflow's graph binds each to the activity it leads to

Only one activity is current at a time. Two roles split the work:

Orchestrator — calls next_activity to move between phases, naming the destination of the exit the worker took
Worker — calls get_activity with context_tokens to load the step list and receive eagerly bundled step techniques that fit the derived budget, runs the steps, and picks the exit the phase ends with

Borrowed activities

An activity file can be listed in more than one workflow — the borrowing workflow runs the phase, but the activity file's technique refs resolve against the workflow it was authored in. One rule covers every bare reference: a borrowed activity's technique refs, its routine references, and binding-provenance scans all use the source workflow, not the session workflow. See Resolution — borrowed activities.

Shared runs of steps

A run of steps carried at more than one activity is declared once under the workflow's routines/ and referred to by a kind:routine step naming [namespace::]name. The routine declares what it takes, what it produces and what its own steps pass between themselves, so its body can be checked against that signature on its own. The server materializes the reference before delivery, so agents always see ordinary steps — with every identifier the run contributes prefixed from the referring step, which is what lets two sites carry the same run without colliding on a step id or a replay key. A gate shared on its own is a one-step routine. Details are in Resolution — routines and Checkpoints — a checkpoint used at several sites.

How an activity file is organised. Steps are the work inside the phase; exits are its named outcomes, and the workflow's graph binds each to the activity it leads to.

Example: the peer-review activity checks the draft, runs review techniques and loops over comment rounds. The worker then takes the needs-rework exit while open_comments > 0, and the default ready exit otherwise; the graph binds them to rework and sign-off.

Step kinds

Every entry in steps[] has a kind that tells the agent what sort of work it is. There are five kinds. They run in file order unless a loop repeats a block or an exit marked immediate, chosen at a checkpoint, ends the sequence there.

The five step kinds and what each one asks the agent to do.

Kind	What it is	Agent behaviour
`technique`	Reference to a capability by `::` path, with optional input bindings	Call `get_technique` for the step (or use content already bundled in `get_activity`), follow the protocol, record outputs
`action`	One or more inline actions (`validate`, `message`, …)	Execute the listed actions against current variables; the server does not interpret action verbs
`checkpoint`	A declared pause with options and effects	Call `yield_checkpoint`; orchestrator presents and `respond_checkpoint`; worker `resume_checkpoint` — see Checkpoints
`loop`	A nested step list that walks a collection or carries a continuation test	Walk the collection a `forEach` names in `over`; for a `while` or `doWhile`, repeat the nested steps while its `continueWhile` test holds — `while` taking that test before the first pass, `doWhile` after one
`routine`	A reference to a shared run of steps under `routines/`, named `[namespace::]name`, with input and output bindings	Nothing to resolve: the server splices the routine's steps in before delivery, each identifier prefixed from the referring step (shared runs of steps)

Techniques

A technique is a markdown file with a fixed shape — capability, inputs, outputs, protocol, and rules — not an ambient agent skill that loads when a description matches. Activity steps name techniques by :: path; the server composes, binds, and delivers them per step. The agent never reads technique files from the repository directly. Path resolution and bundling are on Resolution.

The standard sections in a technique file. Full rules are in the technique protocol specification (source).

Compared to agent skills

Skills suit opt-in guidance: a short description and instructions the model loads when a request seems to match. Orchestrated workflows need a contract the server can schema-check, merge with ancestor contracts, and deliver step by step. Bulky templates and API guides stay in resources/ and load via get_resource only when a running technique links to them — the protocol states what to execute; reference material is separate (Resources).

Resources

A resource is long-form reference material — templates, checklists, tables — stored as markdown under resources/. Techniques link to resources instead of inlining them; the agent calls get_resource only when a running technique needs the linked material.

Resolution rules, section anchors, and cross-workflow prefixes are on Resolution.

Variables and binding

Workflow variables are named values stored in session.json — things like draft_path, reviewer_count, or flags set by checkpoint choices. The server fills in defaults when a session starts; steps and checkpoints update them as the run proceeds.

When a technique step runs, each input must come from somewhere:

a workflow variable
a value written on the step itself
an output from an earlier step
a default declared in the technique

The server records where each value comes from and where each output should go. If something cannot be resolved, the delivered technique says so plainly.

The same variables drive exits. When an activity ends, the worker tests its exits' conditions against the current variable bag, and the workflow's graph names the activity the chosen exit leads to.

How data moves through a run. Variables feed technique inputs; technique outputs and checkpoint choices write back to the bag; exits read the bag, and the graph names the next activity.

Runtime delivery

The agent never opens the corpus tree directly. Every piece of content arrives through MCP tool calls, and the server decides how much to send based on where the run is.

The orchestrator and worker play different roles:

Orchestrator — calls get_workflow once at the start, then next_activity each time the run should move to a new phase
Worker — calls get_activity to load the current step list, then get_technique for each technique step (unless the activity response already bundled it)

Two patterns interrupt that rhythm:

Checkpoints — the worker yields, the orchestrator presents your choice, and the worker resumes before continuing
Resources — load only when a technique the worker is executing links to one

Tool call order, bundling, and errors are in Protocol. Technique and resource resolution are on Resolution.

Normative references

JSON shapes: schema reference. Authoritative prose specs: Specifications.

Definitions covers sessions from a user perspective. Checkpoints explains deliberate pauses and your choices. Dispatch explains how orchestrators and workers run those workflows.