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 the named exits it may take; the workflow graph binds each exit to a destination. 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 the planning folder.

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.

Exit

An exit is a named outcome an activity can end with, and the workflow's graph binds each exit to the activity it leads to. Exit conditions read variables and checkpoint outcomes from session state; the worker takes the first exit whose condition holds, or the default, and the server enters the destination the graph binds to it. See State.

Fidelity

Fidelity is the server's job of enforcing the workflow definition instead of trusting the agent to follow it voluntarily — validating the exits agents report, 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 — once per item of a collection it walks, or for as long as its continueWhile test holds. 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, borrowed activities, the graph, the initial activity, and orchestrator-level techniques and rules; the workflow's own activities are the files in activities/ — 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 the engineering root that holds the server's session.json and the artifacts the run produces — typically artifacts/planning/<slug>/ on an engineering-branch checkout, or .engineering/artifacts/planning/<slug>/ in legacy single-root mode. Because state lives on disk under the install layout, sessions survive IDE restarts and can be resumed across conversations.

Engineering root

The engineering root is where planning and session files live (ServerConfig.engineeringDir). Under the projects multi-root it is $HOST_PROJECTS_ROOT/<repo>/.engineering/ (basename checkout you manage). Setup: the workspace README.

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 repeats them or an immediate exit chosen at a checkpoint ends the sequence; each step has a kind — technique, action, checkpoint, loop, or routine, a shared run of steps the server splices in — 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.

Variable

A variable is a named slot in session state — output_dir, ticket_id, flags set by checkpoint choices — that steps and exit conditions read, and steps write. At session start the server seeds the manifest's declared defaults plus user_request and repository facts; checkpoint effects and the worker's reported variables_changed then update the bag as the run proceeds. See Variables and binding.

Work package

A work package is one unit of work — a feature, an issue, a remediation — that a workflow plans and delivers. 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 tree, exposes tools for agents to navigate them, enforces fidelity and checkpoints, and persists session state under the engineering root. See Home and Getting started.

Workspace

The workspace is the feature-worktree root (ServerConfig.workspaceDir) — typically nested $HOST_PROJECTS_ROOT/<repo>/.worktrees/, the projects multi-root bind, or an explicit path via --workspace / WORKFLOW_WORKSPACE. Domain code lives in checkouts you manage; planning does not. See Install layout and the planning folder.

Next

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