Files
orchestration_engine/CONTEXT.md

3.8 KiB

Orchestration and Execution

Two engines. The Execution engine holds one piece of work from request to approved result, for any subject a Workflow describes. The Orchestration engine receives every request and decides which agent the work belongs to.

Accepted by the owner on 2026-10-13.

Language

The two engines

Execution engine: The package an agent runs on. It holds one Execution: the state of its Deliverables, its Phases and Approvals, and the agents that produce them. It knows no subject. Avoid: framework, core, runtime (which is how one agent is run)

Orchestration engine: The service every request comes through. It decides which agent a request is for, dispatches it, and relays every question and Approval. It produces no Deliverable. Avoid: front door, gateway, router, Orchestrator (which is inside one Execution)

Workflow: What makes the Execution engine about a subject: its Phases, its Deliverables and their Dependencies, the checks on each, and the points where its own code runs. An agent is the Execution engine and one Workflow. Avoid: pipeline, graph (which is a Target architecture or a state graph), template

Reference: The solution architecture agent, at a recorded commit, which the Execution engine was built from. It is read and never modified. Avoid: upstream, source, original

Running an Execution

Execution: One engagement for a single request, from the first message to an approved final Deliverable. It may span many user turns. Avoid: run, job

Customer case: A caller-supplied grouping of the Executions run for one customer engagement, identified by a short slug. One Customer case may hold Executions of more than one agent. Avoid: project, account, tenant

Baseline: The completed Execution, in the same Customer case, that a Change request starts from. It is never modified. Avoid: parent, previous run

Change request: An Execution started to say how what the customer wants has changed. It begins from a Baseline. Avoid: amendment, re-run

Phase: A named grouping of Deliverables. It is complete when all are submitted and the user has granted its Approval. Avoid: step, node, stage

Approval: A user's explicit acceptance of a Phase's Deliverables, required before work that depends on them starts. A pre-approved Execution treats its Approvals as granted. Avoid: sign-off, gate

Revision: Reopening a Deliverable. It returns that Deliverable and everything that depends on it to draft and withdraws any Approval that covered them. Avoid: retry, review round

Deliverable: A document an Execution produces, of a kind its Workflow declares. Avoid: artifact, output file

Dependency: The relationship between two Deliverables in which one can only be produced once the other has been accepted. Avoid: prerequisite, edge

Spec: The structured statement an Execution starts from: a file of fields read against a catalogue in code, complete or partly filled, completed in conversation and approved before anything is derived from it. A Workflow supplies the catalogue and gives its spec a name. Avoid: brief, questionnaire, intent (which stays in the customer's words)

Digest: Turning whatever a caller supplied into a spec, recording where each value came from. Code does it for a format it knows; a model drafts it for anything else. Avoid: import, ingest, parse

Agents

Orchestrator: The top-level agent of one Execution, and the only one that talks to the user. It routes and produces nothing. Avoid: supervisor, manager, Orchestration engine

Specialist: An agent that produces one kind of Deliverable. Avoid: sub-agent, worker

Skill: A self-contained package of domain guidance in the Agent Skills format, loaded on demand. Behaviour lives in Skills; the Execution engine holds none. Avoid: prompt template, playbook