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).

Workflows

A workflow is the whole process from start to finish. The work-package workflow, for instance, takes you from opening an issue through planning, implementation, validation, and merge.

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

• Identity — id, name, version
• Variables — named slots in session state, with optional defaults seeded at session start
• Activities — the phases the orchestrator can move between
• Initial activity — where a new session begins
• Rules and orchestrator techniques — behaviour that applies across the whole run
• Fragments — shared rule texts and checkpoint bodies, imported by { ref } from rules slots and checkpoint steps (see below)

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

• orchestrator techniques and rules
• variable definitions
• 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

Activities

An activity is one phase of a workflow — a stretch of work with a clear goal. Plan & Prepare, Implement, and Validate are activities inside work-package.

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
• transitions — rules for which activity to enter next once the phase is done

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

• Orchestrator — calls next_activity to move between phases
• Worker — calls get_activity with context_tokens to load the step list and receive eagerly bundled step techniques that fit the derived budget

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. This mirrors fragment scoping: a borrowed activity's bare refs, checkpoint fragment refs, and binding-provenance scans all use the source workflow, not the session workflow. See Resolution — borrowed activities.

Shared fragments

Rule texts and checkpoint bodies reused at several sites are declared once under fragments in workflow.yaml and imported by { ref: "[workflow::]name" }. Rules slots and kind:checkpoint steps carry the ref; the server materializes the body before delivery, so agents always see full content. A ref-form checkpoint step carries only its site-local id and, when the fragment declares none, a condition — body fields like message and options are forbidden locally. Details are in Resolution — workflow fragments and Checkpoints — shared checkpoints.

Step kinds

Every entry in steps[] has a kind that tells the agent what sort of work it is. Four kinds are in use today. They run in file order unless a loop repeats a block or a transition sends the run to another activity.

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.

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 protocols, 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 target_path, issue_number, 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 transitions. When an activity ends, the orchestrator checks transition conditions against the current variable bag to decide which activity comes next.

Runtime delivery

The agent never opens the workflows/ folder 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.

Next

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