The reference agent's subject, cloud solution architecture, as an agent in the operating model agent's pattern: the Execution engine (from orchestration_engine) and one Workflow in app/solution_architecture, built for the settings and provider bundle by assembly.workflow_for. Copied from gcp_solution_architecture_agent at 8b397cd without its own engine: its role files, Skills, provider bundle, ADRs, vocabulary, scripts and evaluation datasets. The image takes the engine from a named build context and installs Terraform. It is called through the Orchestration engine, and its files are what the operating model agent digests. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
5.0 KiB
status
| status |
|---|
| accepted |
The target architecture is an explicit graph, and code comes after it
Today the design passes from Specialist to Specialist as prose, and the infrastructure code is written before anyone has stated what it must satisfy. In an evaluation run on 2026-10-06 the validator found 4 problems, then 7, then 5 different ones, across three Revisions of the same Terraform: the bar was discovered after the code existed, and it moved. We decide that the Target architecture is one explicit graph, held as data, that is established before any infrastructure code is written, and that everything after it is derived from it and checked against it.
The graph has three kinds of thing:
- Elements: every component of the solution and the resource that realises it, with the product selected for it.
- Relationships: how Elements connect: calls, publishes to, reads from, is granted access to.
- Checks: on each Element and Relationship, the numbered, verifiable conditions it must meet. Each Check names the requirement or design recommendation it comes from.
This makes the Requirements chain explicit: every requirement leads to the components that serve it, to the Elements and Checks that realise it, to the code that implements them, and to a validation verdict. A link that is missing is refused, not discovered later.
Who provides what
The user states what they want to achieve, at a high level, in the Workflow request, and answers the questions that only they can answer. The agents produce everything in the graph: every Element, Relationship and Check is derived by Specialists from the requirements, the Cloud provider's architecture framework and its documented best practices. The user never writes or edits the graph. They approve it, from a summary, before code is written.
What changes
- A new Deliverable, the Target architecture, follows product selection and design recommendations. Its graph is an attachment; its content is the readable summary.
- Completeness is a submission rule. The Target architecture is refused when a requirement, a selected product or a design recommendation has no Element or Check, or when a Relationship or Check refers to an Element that is not in the graph.
- Later Deliverables are views of the graph. The architecture diagram is rendered from its Elements and Relationships. The architecture description describes them. The deployment guidance implements every Element, Relationship and Check.
- Validation is a verdict per Check, pass or fail with evidence, not a list the validator composes on each pass. Something the validator notices that the graph lacks is a proposed addition to the Target architecture. It cannot fail the code. If it matters, the Target architecture is revised, and the code follows.
Decisions
Accepted by the owner on 2026-10-07, with each of these:
- The user approves the Target architecture before code is written. The solution architecture Phase splits in two: design, which ends with the Target architecture, and implementation, which holds the deployment guidance. The upstream Skill has four Phases; this makes five, and is a deliberate departure from it.
- A new Specialist produces the Target architecture. The design advisor stays responsible for recommendations only.
- Code renders the diagram from the graph. No model draws it, so the picture cannot disagree with the architecture, and the diagrammer role goes.
Considered Options
- Keep the prose chain and tighten the validator's instructions: rejected. The validator would still decide what to check after the code exists, and nothing would make two passes agree.
- A build plan for the infrastructure code only, beside the architecture: rejected. It would be a second description of the same system, free to drift from the diagram and the description. The graph has to be the architecture itself.
- Let the infrastructure code be the model and derive the diagram and checks from Terraform: rejected. It puts code first, which is the order that failed, and it ties the architecture to one infrastructure-as-code tool.
- Raise the Revision limit: rejected. It spends more on a loop that has no fixed target.
Consequences
- Requirements reach code through data, not prose, so a requirement that nothing implements is caught when the Target architecture is submitted.
- A Revision either closes a known Check or it does not. Validation findings stop growing between passes.
- More is decided before code: the Specialist that writes the Target architecture carries work the infrastructure author and validator did implicitly, and a gap in the graph now costs a Revision of the Target architecture and everything after it.
- The Phase list is no longer the upstream Skill's. The solution guide still follows the upstream template; only where Approvals fall changes.
- The vocabulary of the graph is part of the glossary: Target architecture, Element, Relationship, Check, Requirements chain. "Dependency" keeps its existing meaning, between Deliverables.