Architecture
An execution architecture designed to keep AI work controlled, reproducible and auditable.
The runtime is a headless library: it runs AI agents and workflows, but makes no business decision on their behalf. It is driven by a dated workflow file rather than clicked through, so the procedure on paper and the work actually performed cannot drift apart — the file is what the runtime executes.
The architecture separates three responsibilities — the same three layers as the stack:
- Expertise — versioned agents and their knowledge.
- Process — declarative workflows that state what happens and in what order.
- Control — gates that decide whether each step may continue.
This separation matters because an AI system should not be trusted just because its output looks convincing. So the architecture controls the process before, during and after execution — the four points below.
How it fits together
%%{init: {"themeVariables": {"fontSize": "40px"}, "flowchart": {"padding": 26, "nodeSpacing": 85, "rankSpacing": 110, "subGraphTitleMargin": {"top": 14, "bottom": 22}}}}%%
flowchart LR
subgraph S1["<b>① Direct launch — current</b>"]
OP["Operator selects<br/>an agent or workflow"]
end
subgraph S2["<b>② Dispatch intake — WF-000</b>"]
BRIEF["Free-form brief"] --> DISP{"route<br/>or refuse"}
DISP -- refuse --> REF["Named refusal<br/>(no match / missing params)"]
end
OP -- direct --> WF["Declarative workflow<br/>(WF-0xx)"]
DISP -- route --> WF
WF --> RT
subgraph RT["<b>Agentic Runtime (headless)</b>"]
direction TB
ORCH["Step orchestrator"] --> GATE{"Eval-gate<br/>(blocking / advisory)"}
GATE -- pass --> NEXT["Next step"]
GATE -- fail --> STOP["Run stops"]
end
CAT[("Versioned agent catalog<br/>pinned imports, read-only")] -. imports .-> ORCH
RT --> TRACE["Per-step traces<br/>(JSON live proofs)"]%%{init: {"themeVariables": {"fontSize": "30px"}, "flowchart": {"padding": 18, "nodeSpacing": 60, "rankSpacing": 75, "subGraphTitleMargin": {"top": 10, "bottom": 16}}}}%%
flowchart TB
subgraph S1["<b>① Direct launch — current</b>"]
OP["Operator selects<br/>an agent or workflow"]
end
subgraph S2["<b>② Dispatch intake — WF-000</b>"]
BRIEF["Free-form brief"] --> DISP{"route<br/>or refuse"}
DISP -- refuse --> REF["Named refusal<br/>(no match / missing params)"]
end
OP -- direct --> WF["Declarative workflow<br/>(WF-0xx)"]
DISP -- route --> WF
WF --> RT
subgraph RT["<b>Agentic Runtime (headless)</b>"]
direction TB
ORCH["Step orchestrator"] --> GATE{"Eval-gate<br/>(blocking / advisory)"}
GATE -- pass --> NEXT["Next step"]
GATE -- fail --> STOP["Run stops"]
end
CAT[("Versioned agent catalog<br/>pinned imports, read-only")] -. imports .-> ORCH
RT --> TRACE["Per-step traces<br/>(JSON live proofs)"]
S1 ~~~ S2
REF ~~~ WF
NEXT ~~~ STOPRead the diagram as a production line: a run reaches it two ways, then flows through four points.
1 · Before the work — route or refuse. A free-form brief can enter through the dispatch gate (WF-000). The system does not guess which workflow should handle it: it either routes the request to exactly one workflow, or refuses it with a clear reason — no matching workflow, or missing information. (A run can also start directly, when an operator selects a known agent or workflow.) Business value: incomplete or unsupported requests are stopped before they spend a billed run or produce a plausible-but-wrong deliverable.
2 · During the work — control every step. Once a workflow starts, the runtime executes its steps in a defined order, and after each one an eval-gate checks the result: a blocking failure stops the workflow, while an advisory finding is recorded but lets it continue. Business value: an error found at step 3 does not silently become the input to step 4, 5 or 6.
3 · Keep execution reproducible. Agents are imported from the catalog read-only and at an exact version, so the runtime cannot quietly change the expertise it is using mid-run; the workflow itself is a versioned, declarative file that states which steps run and in which order. Business value: the same process can be reviewed, reproduced and compared over time, instead of depending on undocumented changes.
4 · After the work — prove what happened. Each step produces a trace — the dated record of what was run, what was checked, what passed, what failed, and where the run stopped. These traces are what the live proofs are made of. Business value: the result is not a black box. A team can investigate a run after the fact and show how the result was produced.
It controls what enters, what continues, and what can be proven afterwards — so the system does not guess when a request is unclear, does not let failed checks propagate silently, and does not leave its history in an opaque box.
Key decisions (ADRs)
Important architectural choices are documented rather than left implicit. Each ADR — Architecture Decision Record — is a short dated note that records one decision, why it was made, and what it costs, which makes the architecture easier to review, maintain and evolve without silently changing how the system behaves.
Most are written when the decision is taken; where one is recorded later, the record dates both the decision and its writing and says so — what lets someone audit this runtime without asking its author, and what makes a later change of mind visible instead of silent. The titles below are the ones the records carry in the repository.
- ADR-0001 — The runtime is a read-only consumer of the catalog.
- ADR-0002 — Pinned, versioned catalog import.
- ADR-0003 — The sidecar manifest belongs to the catalog.
- ADR-0004 — Propagation guarded by eval gates + contract validation.
- ADR-0005 — Runtime → catalog feedback flows only through a human PR.
- ADR-0006 — Quality standards retained, deferred, and rejected.
- ADR-0007 — Handoff contracts & eval-gate criteria: a spine manifest owned by the runtime.
- ADR-0008 — The dispatch gate routes or refuses: nothing runs on an unrouted or under-qualified brief.
- ADR-0009 — Open-core boundary: the public runtime proves the method; a future private control plane owns governed execution.
- ADR-0010 — The output schema owns structure; eval criteria own DoD semantics and are the audit record.
- ADR-0011 — Non-optional governance made testable: an enumerated guard-set no feature may weaken, and an adapter/core boundary no vendor coupling may cross.
Technical note. Two words recur in those titles. The sidecar is the catalog's machine-readable index — the single file that lists what the catalog holds. A spine is one workflow's ordered chain of steps, from the first to the last.