# The Execution engine Status: needs-triage The design for iteration 1. Vocabulary is in `CONTEXT.md`; the decisions are ADR-0001 and ADR-0002. The plan across both repositories is `../tom_analysis/IMPLEMENTATION_PLAN.md`. ## What it is A package, `execution_engine`, that holds one Execution of any Workflow. It is the Reference's engine with everything about cloud solution architecture taken out and passed in. It keeps the Reference's decisions unchanged: - A LangGraph state graph holds the Execution, checkpoints after every step and interrupts when the user must answer or approve. - Every agent runs behind one agent-runtime interface; the ADK runtime is the first implementation and the only module that imports `google.adk`. - The Orchestrator is a router: readings, a disposition by threshold, a playbook in code, with Jev for the judgements and a fallback for each. - The Ledger refuses what Dependencies, Approvals and the Revision limit do not allow, whatever was decided. - Behaviour lives in Skills, assigned to roles by a provider bundle. ## The Workflow One value, given to the engine when an agent is assembled. Built on 2026-10-13. `execution_engine/workflows/workflow.py` is now the definition; the sketch below is the design it was built from, and differs from it in names and in a few parts added while building. `.agents/plans/iter-01-execution-engine/steps/step-3.md` lists the parts as built. ```python @dataclass(frozen=True) class Workflow: name: str about: str # what intake says this agent does phases: tuple[str, ...] # in order deliverables: Mapping[ str, DeliverableSpec ] # kind -> phase, specialist, depends_on, # sections, attachments, reads_in_full, # not_shown, working_copy, written_from final: str # the Deliverable handed over as the result data_checks: Mapping[ str, DataCheck ] = {} # kind -> (data file, check on submission) for_readers: Mapping[str, str] = {} # sections code adds for a person on_submit: Mapping[str, SubmitHook] = {} # what code adds to a submission validation: ValidationPolicy | None = None approval_facts: ApprovalFacts | None = None # (phase, deliverables) -> facts fan_out: Mapping[str, FanOut] = {} # kind -> the further agents it consults roles: tuple[str, ...] = () # required beyond one per Deliverable local_tools: LocalTools | None = None # (bundle, settings) -> tools by tier reviews: Mapping[str, SubmissionReview] = {} # kind -> a review before acceptance options: Mapping[str, OptionSpec] = {} # per-Execution options a caller may set manifest: ManifestEntries | None = None # state -> entries for execution.json response: Response | None = None # state -> the one-shot reply card: CardText | None = None spec: SpecSupport | None = None # catalogue, digest adapters, its name samples: Mapping[ str, Sample ] = {} # a passing submission per kind, for the fake runtime ``` Deliverable kinds and Phase ids are strings. A Workflow may write them as a `StrEnum` of its own; the engine sees strings, which is what state and storage already hold. ### What each part replaces in the Reference | Part | In the Reference | Notes | | --- | --- | --- | | `phases`, `deliverables`, `data_checks`, `for_readers` | `workflows/deliverables.py` | Data. `inputs_of`, `dependencies_for`, `shown` and `check_submission` stay in the engine and take the Workflow | | `on_submit` | `tools/execution.py` 320–413 | A hook receives the submission and what it builds on, and returns added content, added attachments and working memory. The Reference's are: tables and a diagram for the graph, the checklist review, the rendered plan, the scope's files | | `validation` | `router.py` 161, 313–344, 631–652 | Names the validation Deliverable and gives two functions: its data to failed Check ids, and a failure to the Deliverable to reopen. Without one, the playbook's validation group never applies | | `approval_facts` | `router.py` 747–826 | Facts only. The reply writer still writes the summary, and the assembled fallback still exists | | `fan_out` | `execution_nodes.py` 1016, `toolkit.py` 81, `tools/pillars.py` | The Reference's pillar advisors. Declares the consulting role, the list of parts with a Skill each, and how advice is kept between attempts | | `final`, `manifest`, `response` | `execution_nodes.py` 1145, 1376–1449; `a2a_server.py` 178; `presentation.py` | | | `roles`, `local_tools`, `reviews` | `adk/roles.py`, `agent.py` | The engine always requires the Orchestrator and the reply writer | | `options` | `terraform_modules` in state, in the manifest and in `baseline.py` | A named per-Execution option with a default, carried into a Change request from its Baseline | | `spec` | `scope.py`, `tools/scoping.py`, the bundle's `scope` section | Step 6 | | `samples` | `adk/fake_runtime.py` | The fake runtime's sample submissions are the Reference's Deliverables today | ### Settings and paths - `Settings` holds the engine's settings only. A Workflow brings a settings class of its own for the rest; in the Reference these are the Terraform settings and the coverage and requirements reviews. - The Reference resolves its bundle, Skills and role files from the package's own location. An agent gives its root; an installed engine has no files of its own there. - The provider bundle keeps what every Workflow needs: Skills, models, tools by tier, MCP servers, role Skills, the lessons Skill. Sections only one Workflow reads, such as `terraform` and `pillar_skills`, are read by that Workflow from the bundle's remaining keys. ## The steps | Step | Brings or builds | | --- | --- | | 2 | The modules that import nothing about a subject. Done | | 3 | `states/ledger`, `recorder`, `adk/fake_runtime`, `adk/roles`, `states/lessons`, `nodes/intake`, `nodes/router`, `nodes/execution_nodes`, `tools/execution`, `tools/toolkit`, `tools/scoping`, `tools/meaning`, `workflows/execution_graph`, the generic half of `workflows/deliverables`, the scheduler from `workflows/work_breakdown`, `learning/curator`, `learning/evidence`, `agent`, `a2a_server`, `card`, `main`. Each is brought, then changed to take the Workflow. `config` and `providers` lose what belongs to a Workflow | | 4 | Built with four Deliverables in three Phases; see `steps/step-4.md`. As designed: a toy Workflow under `tests/`: three Deliverables in two Phases, one with a data check, one with a submit hook, a validation policy. The Reference's engine tests (`test_engine`, `test_ledger`, `test_router`, `test_intake`, `test_change_requests`, `test_working_copy`, `a2a/test_server`) are brought and re-pointed at it | | 5 | The Reference's workflow under `tests/reference_workflow/`: its `deliverables`, `chain`, `target_architecture`, `changes`, the Element rule of `work_breakdown`, and its hooks, written as a Workflow. Its tests (`test_deliverables`, `test_requirements_chain`, `test_work_breakdown`, `test_pillars`) are brought | | 6 | The digest step | | 7 | The container build | Steps 3 and 4 are one piece of work: a module is not finished being changed until the toy Workflow runs through it. ## Not in this iteration - The Orchestration engine. It is iteration 2 and shares only the Jev client and the A2A plumbing with this package. - The Reference's Skills, role files, provider bundle and evaluation cases. Step 5 runs its workflow on the fake runtime only. - The evaluation harness. It is brought when the first agent on this engine needs it. ## Open - **How an agent's container build obtains this package** (step 7). A dependency on this repository at a pinned commit, with a build secret for access; a package registry; or a submodule. The owner's choice. - **Where the shared role files and the Specialist protocol live.** They are text, not code. Either package data here, or copied into each agent.