Files
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.7 KiB

Lessons: target architecture

Rules learned from earlier work. Follow every one that applies.

L-01: Create Specific Checks for All Constraints

Rule. Create specific Checks for every explicit constraint, metric, or capability mentioned in a requirement, rather than relying on a single broad Check.

Why. If detailed constraints are missed, the validation phase will reject the design for incomplete coverage, forcing a revision.

Published 2026-10-10, from lesson proposal 01.

L-02: Assign Checks to Every Element

Rule. Give every Element at least one Check before you submit.

Why. The submission tool will reject the architecture if any Element lacks a Check, wasting an attempt.

Published 2026-10-10, from lesson proposal 02.

L-03: Verify Resource Arguments for Checks

Rule. Verify that the specific resource type used for an Element actually supports the configuration argument you specify in a Check. Remember that access policies and certain configurations often require entirely separate resources.

Why. If a Check specifies an argument that does not exist on the resource, it cannot be implemented, forcing an architectural revision.

Published 2026-10-10, from lesson proposal 03.

L-06: Do Not Mark Requirements as Not Applicable

Rule. Do not list Requirements in the not applicable field, as this field is strictly for Design Recommendations. Ensure every Requirement has at least one Check.

Why. The submission tool will reject the deliverable if a Requirement lacks a Check or is incorrectly marked as not applicable.

Published 2026-10-10, from lesson proposal 06.

L-07: Verify location constraints

Rule. When a requirement specifies where resources must be provisioned, such as a designated region or multi-zone placement, create a Check for the region or location argument on every applicable Element, naming the region the design uses. Do not write a Check about a property of the region that code cannot show, such as its carbon rating.

Why. Validation frequently catches missing location constraints. Without this Check, resources may be provisioned in default regions, violating location requirements. A Check about a region's carbon rating cannot be verified from code and sends the design back.

Published 2026-10-10, from lesson proposal 07.

L-08: Cloud SQL backup encryption

Rule. When writing a Check for CMEK encryption on a google_sql_database_instance, do not require an encryption_key_name argument for backup storage, as the instance-level encryption_key_name automatically encrypts backups as well.

Why. The database instance resource does not have a separate encryption key argument for backups. Asking for one causes validation to reject the Check as un-implementable.

Published 2026-10-10, from lesson proposal 08.

L-09: Backend Service capabilities

Rule. When writing Checks for a google_compute_backend_service, do not verify IAM roles inside the backend service or require health checks when it is configured with a Serverless NEG.

Why. Roles are verified via IAM bindings outside the backend service, and Serverless NEGs do not support health checks. Invalid Checks cause the design to be rejected during validation.

Published 2026-10-10, from lesson proposal 09.

L-10: Pub/Sub persistence regions

Rule. When a requirement dictates that a messaging queue or topic must replicate across zones or stay within a specific region, create a Check for the message_storage_policy.allowed_persistence_regions argument on the topic Element.

Why. Without this Check, topics might use default storage policies that violate geographical or high-availability requirements.

Published 2026-10-10, from lesson proposal 10.