Definitions

Plain-language definitions for terms you will see across the docs, the site, and your agent's workflow runs. The model diagram on the home page shows how the core pieces chain from a user goal down to tool calls. For file layout, step kinds, and runtime delivery, see Workflows; for checkpoint mechanics, see Checkpoints.

Terms

Action

An action is a step kind with inline instructions — validate something, emit a message, set a flag — rather than delegating to a technique file. The agent executes the listed actions against current variables; the server records progress but does not interpret the action verbs themselves. See step kinds.

Activity

An activity is one phase of a workflow: planning, implementation, review, validation, and so on. Each activity is a YAML file listing ordered steps and optional transitions to other activities. The orchestrator moves between activities as the run progresses; the server tracks which activity is current in session.json. See Activities.

Artifact

An artifact is a planning output the workflow stores in your session folder — design notes, compliance reviews, implementation plans — separate from your application source code. Artifacts give later activities and checkpoints something concrete to reference. See Artifacts.

Bootstrap rule

The bootstrap rule is a short always-applied instruction in your IDE that routes workflow requests through discover before any other workflow-server tool. Without it, agents may skip the startup sequence and call tools out of order. Add it during setup — see Getting started.

Checkpoint

A checkpoint is a deliberate pause where the workflow stops until you approve, choose, or confirm something. The server records an active checkpoint in session state and refuses to advance until it is resolved; your choice can also set variables that change what runs next. See Checkpoints.

Discover

Discover is the bootstrap MCP tool that returns the ordered startup procedure — which tools to call, in what sequence — for starting or resuming a workflow. Agents should call it on every workflow request when the bootstrap rule is in place. See Tool reference.

Dispatch

Dispatch is how the server hands work to the right agent layer: a user-facing orchestrator manages state and checkpoints, while ephemeral workers execute activity steps in the background and bubble pauses back up when they need your input. See Dispatch.

Fidelity

Fidelity is the server's job of enforcing the workflow definition instead of trusting the agent to follow it voluntarily — validating transitions, gating advancement at checkpoints, and keeping session state on disk as the single source of truth. See Fidelity.

Goal

A goal is what you state in natural language — implement issue #42, start a work package for authentication — and the agent matches to a workflow. You never name tools or session tokens; the server and bootstrap procedure handle routing once the goal is understood.

Loop

A loop is a step kind that repeats a nested list of steps until a condition is satisfied or the loop declares completion. Loops let activities revisit work — retry a validation, iterate on a plan — without duplicating step definitions. See step kinds.

Manifest

The manifest is the workflow.yaml file at the root of a workflow directory. It declares the workflow's identity, variables, activity list, initial activity, and orchestrator-level techniques and rules — the map the server reads when a session starts. See Workflows.

MCP

MCP (Model Context Protocol) is the wire format your IDE uses to talk to external tools. The workflow-server registers as an MCP server; your agent calls its tools through the client's MCP configuration. See modelcontextprotocol.io and Getting started.

Orchestrator

An orchestrator is the agent layer that owns workflow navigation — calling next_activity, presenting checkpoints to you, and spawning workers for individual activities. In a typical run you interact with the top-level orchestrator; background workers stay out of your chat. See Dispatch.

Planning folder

A planning folder is the per-session directory under .engineering/artifacts/planning/ where the server writes session.json, artifacts, and traces. Because state lives in your project tree, sessions survive IDE restarts and can be resumed by name across conversations.

Resource

A resource is reference material — extra markdown the server can attach when a technique links to it. Resources load lazily with get_resource only when needed, so the agent's context stays focused on the step in front of it. See Resources and Resolution.

Rule

A rule is a behaviour constraint declared in workflow or activity YAML — conduct the agent must follow across a whole run or a single phase. Rules complement techniques: techniques describe how to do one capability; rules set boundaries that apply while those techniques run. See Workflows.

Session

A session is one run of a workflow from start to completion (or pause). The server creates or resumes a planning folder, writes canonical state to session.json, and returns a session index token for every subsequent tool call. Ask the agent to resume a work package and it picks up from the saved state.

Session index

The session index is the short token returned by start_session that identifies which planning folder a tool call belongs to. Agents pass it on later workflow-server calls so the server can load the right session.json without you copying paths or IDs. See start_session.

Step

A step is one ordered unit of work inside an activity. Steps run in file order unless a loop or transition sends execution elsewhere; each step has a kind — technique, action, checkpoint, or loop — that tells the agent what to do. See step kinds.

Technique

A technique is a markdown file that defines one capability: what it does, what inputs it needs, what outputs it produces, and the protocol steps to follow. Activity steps bind techniques by :: path; the agent fetches each one just-in-time with get_technique rather than reading repository files directly. See Techniques.

Tool

A tool is an MCP operation exposed by the workflow-server — discover, start_session, get_activity, yield_checkpoint, and others. The agent invokes tools; the server validates each call against the workflow definition and updates session state. You do not call these yourself. See Tool reference.

Transition

A transition is a rule that decides which activity runs next when the current one finishes. Transitions read variables and checkpoint outcomes from session state; the server evaluates them deterministically rather than letting the agent guess. See State.

Variable

A variable is a named slot in session state — target_path, issue_number, flags set by checkpoint choices — that steps and transitions read and write. The manifest seeds defaults at session start; techniques and checkpoints update the bag as the run proceeds. See Variables and binding.

Work package

A work package is the bundled work-package workflow for planning and implementing one unit of work — a feature, an issue, a remediation. You start or resume it in natural language; the server handles session creation, activity navigation, and checkpoints along the way. See Run and resume.

Worker

A worker is a background agent spawned to execute the steps inside one activity. Workers call techniques and yield checkpoints; they do not prompt you directly — pauses bubble up to the orchestrator that faces you. See Dispatch.

Workflow

A workflow is the whole process from start to finish — a directory of declarative YAML and markdown files, not executable code. It lists activities, variables, techniques, and rules; the server reads the manifest and enforces the path the agent follows. See Workflows.

Workflow server

The workflow server is the MCP server in this repository. It loads workflow definitions from the workflows/ worktree, exposes tools for agents to navigate them, enforces fidelity and checkpoints, and persists session state in your project's workspace. See Home and Getting started.

Workspace

The workspace is your project root — the repository the server manages sessions for, set via WORKFLOW_WORKSPACE or --workspace. Session folders and artifacts live under its .engineering/ tree; the server refuses to start without a workspace path. See Configure your MCP client.

Next

Workflows — file layout, step kinds, binding, and runtime delivery. Architecture overview — the enforcement models behind the server.