Files
orchestration_engine/CONTEXT.md

86 lines
3.8 KiB
Markdown

# 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