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 under the engineering root (feature work under a separate workspace root). 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 the workspace root (feature worktrees) and the engineering root (planning folders hold 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