Files
solution_architecture_agent/docs/adr/0002-skills-are-the-portable-unit-of-behaviour.md
Jonathan Boniface c84dbdea20 feat: the solution architecture agent on the shared Execution engine
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>
2026-10-21 19:49:28 +01:00

3.9 KiB

status
status
accepted

Skills are the portable unit of behaviour

This agent exists to replace the google-cloud-solution-architecture skill with an agent that runs anywhere. Its solution-architecture behaviour lives in Skills that follow the Agent Skills specification (SKILL.md plus references/, assets/ and scripts/). The agent framework's own skill runtime loads them: Google ADK's SkillToolset, or LangChain's skills pattern (Deep Agents skills= / SkillsMiddleware). Our code supplies the tooling those Skills call on: grounding, IaC validation and environment scanning. It doesn't restate the work the Skills describe.

Google Cloud is the first and, for now, only Cloud provider. Other hyperscalers should be addable as new Skills plus new tooling, without rewriting the agent's core.

Refinements (2026-09-15)

  • Hybrid sequencing. Our code owns Phase boundaries and the Approvals between Phases. Within a Phase, the Skill, run by the skill runtime, decides the work. We rejected letting the Skill sequence everything: Phase checkpoints give us resumable, recordable, testable progress. We rejected code-owned Phase bodies because they would bypass the Skill.
  • Hierarchical and ReAct, not linear. Work isn't a fixed chain. Agents are organised in a hierarchy that follows the dependencies between Deliverables. Work whose dependencies are satisfied may proceed independently, and every agent reasons and acts in a ReAct loop of thought, tool call and observation. An Orchestrator sits above one Specialist per Deliverable, and a Specialist fans out further only where its work splits into independent parts. Code declares the dependency graph, and the Orchestrator chooses what to do next within it. The engine is recorded in ADR-0003.
  • Interactive by default. Executions are multi-turn with user Approval, as the upstream Skill requires. A pre-approved mode serves batch and evaluation runs.
  • Vendored upstream Skill. google-cloud-solution-architecture is copied unmodified and pinned to an upstream commit. Our additions live in separate Skills for our own tooling, so upstream changes arrive as a diff.
  • Discovery through the provider's own MCP servers. Current-state discovery and documentation grounding go through the remote MCP servers each Cloud provider hosts, for example Google Cloud's Resource Manager, Asset Inventory, Compute, GKE and Developer Knowledge servers, and the AWS MCP Server. Code carries no hand-written cloud API clients. Only reviewed read-only MCP tools are exposed, and reading a user's cloud requires their permission.
  • Cloud provider as configuration. A Cloud provider is a configured bundle of Skills, tools and remote MCP servers. There's no provider interface in code until a second Cloud provider exists, but core module names carry no provider prefix.

Consequences

  • Framework-specific code is confined to wiring a skill runtime and registering tools, so moving to another framework is a new wiring, not a rewrite.
  • Skills in app/skills/ must conform to the specification: kebab-case name matching the directory, a description of when to use the Skill, and no custom phase: key. They don't today. (2026-10-06: those five Skills were deleted with the original pipeline. The engine loads only the conforming Skills under skills/, and app/skills/ holds the discovery and validation code.)
  • This reopens ADR-0001 and the Phase pipeline spec (.scratch/phase-pipeline/spec.md). ADR-0003 settles the engine and supersedes ADR-0001.
  • Both known skill runtimes are young: ADK marks Skills Experimental (Python ≥ 1.25.0), and Deep Agents skills are new. Pin versions.