Files
tom_analysis_agent/IMPLEMENTATION_PLAN.md

394 lines
34 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Orchestration engine and target operating model agent: implementation plan
Status: seventh draft, 2026-10-13. Building has started: E1 to E5 are built, and the first slice of the operating model agent but for its digest and its evaluation. Each repository's `.agents/plans/` records what is done.
Two things are built, in two folders, and a third is left exactly as it is.
| Folder | What it is | Changed by this plan |
| --- | --- | --- |
| `gcp_solution_architecture_agent/` | The solution architecture agent, running on its own built-in engine. The reference. | No file is modified |
| `orchestration_engine/` | Two things. The **Execution engine**: the installable package an agent runs on. The **Orchestration engine**: the service every request comes through | New |
| `tom_analysis/` | The target operating model agent: its workflow, roles, Skills, provider bundle and evaluation, running on the Execution engine | New |
Terms in capitals without a definition here are the architecture agent's, from its `CONTEXT.md`. "The reference" means `gcp_solution_architecture_agent/` at commit `8b397cd`.
## 1. Decided
By the owner on 2026-10-13:
1. **The operating model agent is a separate agent, in `tom_analysis/`.**
2. **The Execution engine is built in `orchestration_engine/`.** The reference is read, never modified.
3. **The Execution engine is shown to be able to run the architecture workflow,** as an example in its own tests.
4. **The operating model agent starts from an operating spec.** Whatever it is given, the architecture agent's files among other things, is digested into that file first. The architecture's files are one source, not the only one.
5. **The operating spec holds the inventory inline.** It does not point at source files.
6. **Every request comes through the Orchestration engine,** which decides, with Jev, whether the work is solution architecture, an operating model, or both. The KAB platform does not route between agents, so nothing existing is duplicated.
7. **A gap in the architecture is never repaired by the operating model agent.** It is recorded as a finding and goes back as a Change request.
8. **Our own capability catalogue,** in our words, each entry citing the industry frameworks it draws on.
9. **The run is priced.** Staffing is costed from a rate card by country, in the currency the operating spec states. The rate card is a Skill, and its prices are set by the service provider who runs this agent: the owner. The customer's own staff are counted and never priced (section 9).
10. **How an agent's container build obtains the Execution engine is in scope** (step E7). Which means is used is still to be chosen.
Still open: section 11.
## 2. How the pieces run
```text
caller
│ A2A
┌────────▼────────┐
│ orchestration │ orchestration_engine: reads the request, asks Jev
│ engine │ which work it is, dispatches, relays every prompt
└───┬─────────┬───┘
A2A │ │ A2A
┌──────────▼───┐ ┌─▼──────────────────┐
│ architecture │ │ operating model │
│ agent │ │ agent │
│ (as it is) │ │ (tom_analysis, on │
│ │ │ the Execution engine) │
└──────────────┘ └────────────────────┘
```
Three containers. Each agent still has its own Orchestrator for its own Execution; the Orchestration engine sits above Executions and produces nothing itself. The architecture agent is called through the `/a2a` and `/generate` routes it already has.
Two names are kept apart throughout. The **Orchestration engine** is the service above Executions. The **Execution engine** is the package that holds one Execution; the reference already calls its own `ExecutionEngine`. The **Orchestrator** remains the top-level agent inside one Execution.
## 3. The Execution engine
### What is brought across
The reference's `app/` holds the Execution engine and the solution-architecture workflow together.
| | Modules in the reference |
| --- | --- |
| Engine, brought as it is (done, E2) | `config.py`, `checkpointing.py`, `customer_case.py`, `database.py`, `scope.py`, `baseline.py`, `providers.py`, `adk/runtime.py`, `adk/adk_runtime.py`, `skills/`, `states/execution_state.py`, `tools/jev.py`, `tools/guardrail.py`, `tools/mcp.py`, `tools/workspace.py`, `tools/skill_routing.py`, `learning/proposals.py`, `learning/proof.py`, `learning/skill.py` |
| Engine, rewritten as it is brought (E3): names architecture Deliverables, or imports a module that does | `nodes/execution_nodes.py`, `nodes/router.py`, `nodes/intake.py`, `tools/execution.py`, `tools/toolkit.py`, `tools/scoping.py`, `tools/meaning.py`, `states/ledger.py`, `states/lessons.py`, `recorder.py`, `adk/roles.py`, `adk/fake_runtime.py`, `workflows/execution_graph.py`, `learning/curator.py`, `learning/evidence.py`, `agent.py`, `a2a_server.py`, `card.py`, `main.py` |
| Split | `workflows/work_breakdown.py`: the scheduler comes, the rule about Elements stays behind |
| Not brought: the solution-architecture workflow | `workflows/deliverables.py` (its graph), `workflows/chain.py`, `workflows/target_architecture.py`, `workflows/changes.py`, `tools/pillars.py`, `tools/local.py`, `tools/modules.py`, the reviews, `tools/assessment.py`, `presentation.py` |
Also brought, because they are not about architecture: the Specialist protocol partial, the role files for the scope analyst, the reply writer and the lesson curator, and the evaluation harness.
### The seam
The second row refers to named Deliverables about 45 times. Each becomes something a **Workflow** supplies: one value, given to the Execution engine when it is assembled.
| In the reference | What is hard-coded | What a Workflow supplies |
| --- | --- | --- |
| `workflows/deliverables.py` | Phases, the Deliverable graph, data checks, sections for readers | The same, as data |
| `router.py` 161, 313–344, 631–652 | Which Deliverable is validation, how its verdicts are read, what a failure reopens | A validation policy |
| `router.py` 747–826 | Facts for an Approval summary | A function per Phase |
| `tools/execution.py` 320–413 | What code adds on submission: tables, diagram, rendered plan | A submission hook per Deliverable |
| `execution_nodes.py` 1016, `toolkit.py` 81 | Pillar advisors under design recommendations | A fan-out declared on a Deliverable |
| `execution_nodes.py` 1145, 1376–1449, `a2a_server.py` 178 | The final document; manifest entries | The final Deliverable and its manifest entries |
| `adk/roles.py`, `agent.py` | Required roles; the Terraform runner and the reviews | Roles, local tools and reviews, listed |
| `presentation.py`, `card.py` | Response fields and the card's wording | Supplied |
| `scope.py`, `tools/scoping.py` | One catalogue; a spec drafted from a sentence | The catalogue, and the digest adapters of section 5 |
### Two proofs, in the Execution engine's own tests
- **A toy workflow** of three Deliverables in two Phases, run on the fake runtime through questions, Approvals, a Revision and a Change request. It is what the brought-across tests for the Ledger, the router, intake and the A2A server are driven by.
- **The architecture workflow as an example.** Its Deliverable graph, data checks and hooks are written as a Workflow under the Execution engine's tests, from the reference, and the reference's tests for them are brought with it. All of it runs on the fake runtime.
The second shows the seam is wide enough for the real case. It does not show the same results with real models: that would need the architecture agent's Skills, roles and bundle on the new engine, which is moving that agent, and is not in this plan.
### What two Execution engines means
The reference keeps its built-in engine and has open steps in four iterations. Fixes do not flow between the two unless someone carries them. The Execution engine records the reference commit it was built from, so a later comparison has a starting point.
## 4. The Orchestration engine
### Deciding what a request is
In order, following ADR-0007: readings, disposition, playbook, record.
1. **Read by code.** What the caller named settles it: `work` set outright; an operating spec or `sources` supplied (operating model); a scope spec supplied (solution architecture); a `baseline` named (the agent that Execution belongs to).
2. **Read by Jev,** when code cannot tell. One typed choice about the message: solution architecture, operating model, both, a question about delivered work, or none of these. Jev is sent the message and the names of what was supplied, never file contents.
3. **Disposition.** A choice below the confidence threshold is not relied on. With someone present, the Orchestration engine asks them which they want, in plain terms. With nobody present, it starts nothing and says how to name the work. It does not guess: a wrong guess here starts an Execution of the wrong kind.
4. **Jev unreachable.** Step 1's rules, then step 3. Never a stop.
5. **Record.** The decision, the confidence and what was dispatched, per Customer case.
### Dispatching
| Decision | What happens |
| --- | --- |
| Solution architecture | The message and its metadata go to the architecture agent unchanged |
| Operating model | They go to the operating model agent |
| Both | Architecture first. When it completes, the files it returned are passed to the operating model agent as `sources`, with the Orchestration engine's own record that the Execution completed. An architecture Execution that ends with warnings stops here and the user is asked |
| A question | To the agent that delivered the work it is about |
| None | A reply saying what can be done. Nothing is started |
- **Relaying.** Each agent pauses for questions and Approvals. The Orchestration engine passes every prompt to the caller and every reply back, unchanged, and holds which downstream task is waiting.
- **"Both" is in sequence, not in parallel.** The operating model depends on the architecture. The user sees the digest of the architecture at the operating model's scoping Approval.
- **One Customer case across both agents.** The same slug is sent to each.
- **Two readings of one message.** The architecture agent's own intake still reads a message as new, a change or a question. The Orchestration engine does not replace that; it only chooses the agent.
## 5. The operating spec
The operating model agent's only input. The counterpart of the scope spec (ADR-0008), with the same rules: a structured file read against a catalogue in code; complete or partly filled; every field a value, `ask`, `decide` or `not_applicable`; the file supplied never altered; a completed copy written beside it with where each value came from; approved in scoping before anything is derived from it.
It differs in one way: it carries the system to be operated.
```yaml
metadata: {customer_case: acme-landing-zone}
engagement: {kind: platform_foundation}
intent:
statement: |
We need the landing zone run as a managed service from go-live ...
requirements:
- {id: REQ-01, statement: Platform foundation ready within 10 weeks.}
solution:
items: # what is to be operated
- {id: S-1, name: Hub network, kind: network, product: Shared VPC, environments: [prod], source_ref: E-1}
conditions: # what must be kept true
- {id: K-1, 'on': S-1, condition: Flow logs are retained for 400 days., source_ref: CHK-12}
build: {duration_days: 46, customer_owned: [Order the carrier circuit]}
inherited_risks:
- {'on': S-4, risk: Recovery was not verified in validation., source_ref: CHK-31}
operations: {support_hours: 24x7, change_process: ask}
sourcing: {model: decide, delivery_countries: [GB, PL, IN]}
organisation: {existing_teams: ask, headcount_limit: ask}
commercial: {currency: GBP, monthly_run_budget: ask}
service_management: {tooling: ask}
service_levels: {}
transition: {go_live_date: ask}
run: {pre_approved: false}
```
### Digesting sources into it
| Source | Read by | What is guaranteed |
| --- | --- | --- |
| An architecture Execution: a folder, files in the request, or forwarded A2A artefacts | A code adapter in `tom_analysis/`. It reads plain JSON for the fields it needs; nothing is copied from the reference | Every Element becomes an item and every Check a condition, with its id as `source_ref`. Counts in equal counts out, tested |
| Anything else: a design document, a spreadsheet, a diagram's description | A model, drafting records | Each record quotes the passage it came from. Nothing is guaranteed complete, which is why the customer approves it |
| A sentence, or nothing | The scope analyst, in conversation | As the architecture agent does today |
| An operating spec already written | Read as it is | |
- **Provenance per value:** supplied, digested (with the source file and its hash), answered, assumed, unknown.
- **The digest is a command and a step.** `python -m app.digest <sources> > operating-spec.yaml` runs nothing else. Started with `sources`, the agent runs the same code, and the Execution starts from the spec it wrote.
- **The mechanism is the Execution engine's; the adapters are the agent's.** The Execution engine already drafts a spec from a sentence; a Workflow lists the adapters for the formats it knows.
- **A format change in the architecture agent** is caught by a contract test against one captured Execution, since no version can be added to its files.
- **The inventory is not sent to every Specialist.** The reference puts the scope in every prompt. `solution.items` and `solution.conditions` travel as a data file to the Specialists that use them.
## 6. The capability catalogue
A Skill, `operating-capabilities`, holding `assets/catalogue.yaml`.
```yaml
- id: incident-management
name: Incident management
domain: service_operations
purpose: Restore a service that is degraded or down, and say what happened.
applies_when: {always: true}
typical_checks:
- A priority 1 incident is acknowledged within an agreed time, at any hour the service is offered.
sources:
- {framework: ITIL 4, reference: "Incident management practice"}
- {framework: Google SRE, reference: "Site Reliability Engineering, ch. 14, Managing Incidents"}
- {framework: ISO/IEC 20000-1:2018, reference: "8.6.1"}
- {framework: "Regulation (EU) 2022/2554 (DORA)", reference: "Art. 17"}
```
- **Sources are cited, never copied.** `references/sources.md` is the register: each framework, its version, publisher and licence, and how it is cited. Candidates: ITIL 4, ISO/IEC 20000-1, COBIT 2019, Google's SRE books, the FinOps Framework, NIST CSF 2.0, ISO/IEC 27001, SFIA for skills, the EU's DORA regulation, and each Cloud provider's architecture framework. The references in the example are illustrative; each is verified against its source when the entry is written.
- **Checked in code.** Every entry has a source that is in the register. Every Capability in a Target operating model names a catalogue entry, or is marked `custom` with its reason.
- **`applies_when` is read by code** against the operating spec: an item's kind, the engagement kind, a compliance framework. It proposes; the Specialist decides, and says why an applicable capability was left out.
- **No Cloud provider and no organisation.** The provider bundle maps capabilities to that provider's tooling. An organisation's role names, standards and service tiers are an overlay Skill.
- **Two things are called DORA:** the EU regulation and the DevOps research programme's metrics. The register names each in full.
## 7. The Target operating model graph, and findings
One graph, held as data, approved before detail is written. Vocabulary for `tom_analysis/CONTEXT.md`:
- **Operating spec**, **Item**, **Condition**: section 5.
- **Operational requirement**: a numbered statement of what running the solution must achieve, traced to a stated requirement, a Condition or a spec field.
- **Capability**: something the operating organisation must be able to do, from the catalogue, naming the Operational requirements it serves and the Items it covers.
- **Party**, **Role**, **Responsibility**: an organisation with a part in operating the solution; a position in it, with skills and hours; a Role's part in a Capability (accountable, responsible, consulted, informed).
- **Check**: a numbered verifiable condition on a Capability, Role or Responsibility, traced to its source.
```json
{
"parties": [{"id": "P-1", "name": "Customer platform team", "kind": "customer"}],
"roles": [{"id": "R-1", "party": "P-1", "name": "Platform engineer", "hours": "business", "skills": ["networking"]}],
"capabilities": [{"id": "C-1", "catalogue": "incident-management", "serves": ["OR-3"],
"items": ["S-1", "S-4"], "hours": "24x7", "effort_hours_per_month": 30}],
"responsibilities": [{"id": "RS-1", "capability": "C-1", "role": "R-1", "kind": "accountable"}],
"checks": [{"id": "OC-1", "on": "C-1", "condition": "A priority 1 incident is acknowledged within 15 minutes", "source": "OR-3"}]
}
```
Refused on submission, in code, against the approved operating spec:
- an Item that no Capability covers, or a Condition that no Check carries;
- an Operational requirement that no Capability or Check serves;
- a Capability without exactly one accountable Role, or with none responsible;
- a Role without a Party, or a reference to an id that is not in the graph or the spec;
- a Capability whose hours are wider than the hours of every Role responsible for it;
- support hours narrower than the availability the spec states;
- a stated `operations.*` choice that no Operational requirement names.
Written by code, never by a model: the responsibility matrix, the organisation chart, the capability map, and staffing and cost per Role (section 9).
### Findings
- A **finding** is something operating the solution needs that the solution, as the spec describes it, does not provide: nothing raises alerts, no Condition requires backups to be restored, the responding team has no means of access.
- A Specialist records it. It never adds an Item, alters a Condition, or designs around the gap in silence.
```json
{"id": "AF-1", "about": ["S-3"], "source_ref": ["E-3"],
"lacks": "No Condition requires the database's backups to be restored on a schedule.",
"needed_by": ["OR-6", "C-4"], "proposed": "Require a restore to be tested quarterly."}
```
- What depends on a finding is `not_verifiable` in validation, with the finding as the reason. The Execution still completes, with its findings listed at the Approval and in the guide.
- **When the spec was digested from an architecture Execution,** code writes `architecture-change-request.md` from the findings, in the form the architecture agent accepts as a Change request against that Execution. In a "both" request the Orchestration engine can offer to send it.
- **Otherwise** the findings are questions for whoever owns the design.
- When changed architecture files arrive, the agent runs a Change request of its own from a new digest. Findings that are now met close.
## 8. Phases and Deliverables
| Phase | Deliverable | Specialist | Depends on | Data file |
| --- | --- | --- | --- | --- |
| Scoping | operating scope | `scope-analyst` (Execution engine) | the operating spec | `operating-spec.yaml`, `scope.json`, `solution.json` |
| Operational requirements | operational requirements | `operations-analyst` | operating scope | `operational-requirements.json` |
| | current operating model | `current-state-assessor` | operating scope | `current-state.json` |
| Operating model design | service model | `service-designer` | operational requirements | `services.json` |
| | capability model | `capability-modeller` | operational requirements | `capabilities.json` |
| | design recommendations | `design-advisor`, with one `dimension-advisor` per dimension | service model, capability model | `recommendations.json` |
| | **Target operating model** | `operating-model-architect` | the three above | `target-operating-model.json`, `findings.json` |
| Operating model definition | process definitions | `process-author` | Target operating model | `processes.json` |
| | organisation design | `organisation-designer` | Target operating model | `organisation.json` |
| | tooling and observability | `tooling-author` | Target operating model | `tooling.json` |
| Validation | validation results | `validator` | the three above | `verdicts.json`, `scenarios.json` |
| Packaging | transition plan | `transition-planner` | validation results | `transition-plan.json` |
| | operating model guide | `packager` | validation results | |
- **Dimensions,** the counterpart of the pillars: process, people and organisation, tooling and automation, governance and risk, sourcing, security operations, financial operations. The bundle maps each to a Skill.
- **Scenario walk-throughs,** the counterpart of the dry run. Scenarios are generated from the graph and the spec: a priority 1 incident on a named Item outside business hours, a change to the network, loss of the primary region, a key rotation falling due, a month over budget. Code traces each: is it detected by a tool, is a responsible Role on hours, does a process exist, does it reach an accountable Role. A broken path is a failed Check.
- **Transition plan.** The Execution engine's scheduler, with Capabilities where the work breakdown has Elements. It is checked against the build duration the spec gives, so nothing goes live before the Capability that runs it is ready.
## 9. Staffing, rates and cost
The Target operating model already gives each Capability an effort in hours a month and each Role its hours. Pricing adds two facts to a Role and one file.
- **A Role has a country and a level.** `{"id": "R-2", "party": "P-2", "name": "Platform SRE", "country": "PL", "level": "senior", "hours": "24x7"}`.
- **The rate card is a Skill, `skills/rate-card/`, and it is the actual card.** Its prices are the service provider's, set by the owner and changed only by the owner, in review like any other Skill. It is not an overlay and not the Cloud provider's: every Execution prices from it, whichever Cloud provider the solution is on. A caller cannot name another card, and an operating spec cannot state a rate: a customer does not set the provider's prices.
- **The figures in it today are placeholders** drafted with this plan. They are the owner's to replace before any priced result is shown to a customer.
What the card holds, per country: a day rate for each level, the productive days in a year, and the working hours in a day. For the whole card: the currency its rates are written in, fixed conversion rates to other currencies with the date they were set, the smallest team that can cover each pattern of hours, and an uplift for work outside business hours.
Computed by code, never by a model:
1. **People per Role.** The effort of the Capabilities the Role is responsible for, divided by the productive hours of its country. Where the Role covers hours wider than a working day, never fewer than the card's minimum roster for that cover: a rota is sized by the hours it must fill, not by the work done in them.
2. **Cost per Role a month.** People, times the day rate for its country and level, times productive days over twelve, times the uplift where it applies.
3. **Conversion** into `commercial.currency`, at the card's rate for it.
4. **Totals** by Party, by country and by Capability, and against `commercial.monthly_run_budget` when the spec states one.
Rules:
- A Role whose country or level the card does not have is refused at submission, by name.
- **The operating spec states the currency.** `commercial.currency` is an essential field: asked for when someone is present, and a start with nobody to ask is refused without it. A currency the card has no conversion rate for is refused at the start, by name.
- **The customer's own staff are never priced.** A Role in a Party of kind `customer` is counted as people and carries no cost, whatever the card says. Of the other Parties, only the kinds the card lists are costed.
- The Specialist chooses where Roles sit, within `sourcing.delivery_countries` when the spec states them. It never writes a number of people or a cost.
- A plan over a stated budget is not refused. It is shown as over, with the Capabilities that cost most, as a plan over its delivery window is today.
- The card's version and its hash are recorded with the Execution and named in the guide, so a result can be traced to the prices in force when it was written.
- No exchange rate is looked up. Conversion uses the fixed rates in the card, and the guide states the rate and its date beside every converted total.
Later: the same graph priced under a different mix of countries, side by side.
## 10. Iterations
Each repository keeps its own `.agents/plans/iter-NN-<slug>/` with `MAP.md`, `DETAIL.md` and `steps/`. Every step ends with `pytest`, `ruff` and `mypy` passing.
### E: the Execution engine (`orchestration_engine/`)
| Step | What | Done when |
| --- | --- | --- |
| E1 | The repository: package layout, `CONTEXT.md` with the Execution engine's vocabulary, ADR-0001 (the Execution engine takes a Workflow), ADR-0002 (built from a reference that is never modified, at a recorded commit) | The package installs |
| E2 | The modules brought as they are, with their tests | Those tests pass |
| E3 | The Workflow value and the hooks of section 3; the ten modules rewritten to use them | No engine module names a Deliverable |
| E4 | The toy workflow | It completes on the fake runtime through a question, an Approval, a Revision and a Change request |
| E5 | The architecture workflow as an example in the tests | The reference's tests for its graph, checks and hooks pass against it |
| E6 | The digest step: sources to a spec, adapters listed by a Workflow, provenance per value | The toy workflow starts from a digested spec |
| E7 | How an agent's container build obtains the Execution engine: a dependency on its repository at a pinned commit, a package registry, or a submodule | One agent image builds from a clean checkout, with no file copied by hand |
### F: the Orchestration engine (`orchestration_engine/`)
| Step | What | Done when |
| --- | --- | --- |
| F1 | ADR-0003: one Orchestration engine above the agents; what it decides and how | Accepted by the owner |
| F2 | The service: an A2A server, a configured list of agents, a request passed through to one agent with every prompt relayed | An architecture Execution runs through it, Approvals included, with the architecture agent untouched |
| F3 | The decision: readings in code, the Jev question, thresholds, the fallbacks, the record | A labelled set of messages is routed correctly; low confidence asks; no Jev key still routes what is named |
| F4 | "Both": architecture, then its files as `sources` to the operating model agent | One request yields both sets of Deliverables under one Customer case |
| F5 | Later messages: a question or a Change request goes to the agent that owns the work; a finding's Change request offered back | A change to the architecture is followed by a change to the operating model |
### T: the operating model agent (`tom_analysis/`)
First slice, six Deliverables: operating scope, operational requirements, capability model, Target operating model, validation results, operating model guide.
| Step | What | Done when |
| --- | --- | --- |
| T1 | The repository on the Execution engine: `CONTEXT.md`, ADR-0001 (the Target operating model is an explicit graph), ADR-0002 (it starts from an operating spec), `CLAUDE.md`, `.agents/plans/` | The container starts and `/health` answers |
| T2 | The operating catalogue, the scoping Skill, `python -m app.scope check` | A spec with an unknown field is refused by name |
| T3 | The architecture adapter and `python -m app.digest`; one captured Execution as the fixture | The fixture digests to the same spec from a folder, from files in the request and from artefacts; every Element and Check is accounted for |
| T4 | The model-drafted digest for other documents | A design document yields records that each quote their source |
| T5 | The capability catalogue Skill: first entries, the sources register, the checks on both | An entry without a registered source fails a test |
| T6 | `operational-requirements.json` and `capabilities.json`, their checks, and an `operating-chain` Skill giving each file's format | A requirement with no source, and a Capability serving nothing, are refused |
| T7 | The graph: parsing, the refusals of section 7, the rendered matrix and chart | One test per refusal; the matrix is byte-identical for the same graph |
| T8 | Findings: the tool, the file, `not_verifiable` verdicts, the drafted Change request | A graph that relies on something the spec lacks is refused unless a finding names it |
| T9 | Role files, the provider bundle, the Workflow value | An Execution completes on the fake runtime |
| T10 | Validation in code: structural verdicts and scenario walk-throughs | A graph with a Role off hours fails the matching scenario |
| T11 | The guide template and packager | The guide names every Capability and finding |
| T12 | The rate card Skill: its format, the checks on it, Roles with a country and a level, and `commercial.currency` in the catalogue | A Role in a country the card lacks, and a currency it cannot convert to, are each refused by name |
| T13 | Staffing and cost in code: people per Role with the roster minimum, cost per Role, conversion, totals against the budget | The figures for a fixed graph and card are reproduced exactly; a 24x7 Role is never below the minimum roster; a customer Role has no cost |
| T14 | Evaluation: one case digested from an architecture Execution, one from a hand-written spec | Both run with real models; results recorded |
Later slices, as before: the full design Phase (service model, current operating model, dimension advisors); definition and transition (processes, organisation, tooling, the transition plan); change and learning.
### Order
```text
E1 → E2 → E3 → E4 ─┬─ E5, E6, E7
└─ T1 → T2 … T14
F1 → F2 → F3 ───────────────────── F4 → F5
```
- T starts when the toy workflow runs (E4), not when the Execution engine is finished, so the Workflow's shape is settled by a real user of it.
- F1 to F3 need only the architecture agent as it is, and can start at once.
- F4 needs the first operating model slice.
## 11. Risks and what is still open
- **Two Execution engines.** Section 3. Accepted with decision 2.
- **A wrong routing decision** starts work of the wrong kind. The Orchestration engine asks or declines when it is not confident; it never guesses.
- **A lossy digest.** A model reading a document can drop or invent records. Each record quotes its source, the code adapter is used wherever a format is known, and the customer approves the spec.
- **Nothing objective to validate against.** An operating model has no `terraform validate`. The structural refusals and scenario walk-throughs are the substitute, which is why they are in the first slice.
- **Generic output.** The defence is the chain: every Capability names Items and requirements of this spec, and evaluation fails a model that could have been written without reading it.
- **Client data.** Operating specs and operating models name people, teams and suppliers. They stay with the Customer case, never in a repository.
- **Placeholder prices.** Until the owner sets them, a priced operating model is an illustration. The card's `version` says `draft`, and the guide prints the version beside every total.
- **Prices in a repository.** The actual card is now in `tom_analysis/`, so whoever can read the repository can read the prices.
- **Open: the means for E7.** Recommended: each agent depends on the engine's repository at a pinned commit, with access given to the build as a secret. It needs no registry and pins exactly what was tested. The first agent image cannot be built until this is chosen.
- **Stale conversion rates.** The owner sets them with the prices; the guide prints their date.
- **Open: framework licences.** Citing is safe. Confirm each framework's terms before any wording is taken from it.
## 12. Where it stands
Built on 2026-10-13:
- `orchestration_engine/`: the Execution engine takes a Workflow (E1 to E3). Two Workflows run on it in its tests: the architecture agent's own (E5), and a toy with nothing of that subject in it (E4). 521 tests pass.
- `tom_analysis/`: the operating model agent's Workflow and its folder (T1, T2, T5 to T13). From a written operating spec it produces operational requirements, a capability model from the catalogue, the Target operating model with its matrix, staffing and cost, and a validation with scenario walk-throughs. 106 tests pass, among them whole Executions on the scripted runtime. The record is `.agents/plans/iter-01-first-slice/steps/step-1.md`.
Not yet done:
- **The digest** (E6, then T3 and T4). An Execution starts from an operating spec that is already written; nothing reads the architecture agent's files yet.
- **Any run with a real model** (T14). No role file, Skill or catalogue entry has been read by one.
- **The Orchestration engine** (F1 to F5).
- **The container build** (E7).
Next:
1. E6 and T3: the digest step in the engine, and the adapter that turns an architecture Execution into an operating spec. This needs one completed architecture Execution to capture as a fixture.
2. T14: a first run with real models.
3. F1 to F3 beside them.
Accepted by the owner on 2026-10-13: the engine's ADR-0001 and ADR-0002, and the vocabulary in both `CONTEXT.md` files.
Waiting on the owner: this repository's three ADRs (`docs/adr/`), which record decisions already taken in conversation; the means for E7; prices in the rate card; a completed architecture Execution to use as a fixture.