Architecture

The workflow-server is a small state machine wrapped in an MCP tool surface. Agents call tools; the server validates every request against the workflow definition, composes techniques and resources just in time, and persists canonical session state on disk in your project's workspace. The architecture is organized as models — dispatch, checkpoints, state, artifacts, resolution, and fidelity — so long-running, multi-agent runs stay bounded, pauses reach the user-facing agent, and transitions never depend on guesswork.

Models

• 1. Hierarchical dispatch

  Three agent layers — a user-facing meta orchestrator, a per-workflow orchestrator, and ephemeral activity workers — with clear boundaries between user interaction, state management, and task execution.

  Dispatch model

• 2. Just-in-time checkpoints

  Declarative gates that pause execution for user decisions. Yields bubble up from background workers to the user-facing agent; the server enforces the pause and the response timing.

  Checkpoint model

• 3. State management

  Deterministic transitions: a schema-validated variable bag, mutation through checkpoint effects and worker outputs, and first-matching-condition transition evaluation — never a guess.

  State model

• 4. Artifact and workspace isolation

  Strict separation between your codebase and the orchestration workspace: a per-session planning folder holds plans, state, and traces, with predictable artifact naming.

  Artifact model

• 5. Technique and resource resolution

  All behaviour is composed from techniques, referenced by ::-paths, resolved workflow-first with a shared meta fallback, and delivered as bundles — with reference material lazy-loaded.

  Resolution model

• 6. Workflow fidelity

  Seven enforcement layers — from HMAC token integrity to the execution trace — that keep agents on the defined path and make deviations visible.

  Fidelity model