Agent-first evolution #

Adage remains a configuration-driven AWS deployment framework. The agent model extends its architecture with specifications, deterministic checks, scoped observation, and reviewable evidence.

Architecture first, agent fit later #

The May 2025 documentation already describes separate configuration and infrastructure repositories, reusable components, SSM dependency resolution, and Git-controlled changes. The motivation was understandable, composable cloud infrastructure. The current agent use case emerged from those choices; it did not originate them.

Original choice	Agent engineering benefit
Declarative desired state	Compare intended instances with observed resources.
Configuration separate from implementation	Change intent without duplicating infrastructure code; inspect both sides independently.
Reusable components and predictable interfaces	Bound a change by component and nickname; test implementation independently.
Explicit environment/account boundaries	Make targets reviewable and verify identity before planning.
Git history and review	Trace intent and prepare auditable changes.
SSM discovery and runtime metadata	Follow dependencies without sharing Terraform state between components.
Minimal hidden coupling	Reduce assumptions and expose missing evidence.

These properties support safe reasoning. SSM can contain stale or manually edited values; a nickname does not prove an environment; configuration presence does not enforce Git approval. IAM and execution controls must enforce authority separately.

Roles and workflow #

Adage defines the infrastructure control model. aws-config defines intent and environment bindings; aws-iac implements reusable Terraform/Terragrunt components. SSM bridges published inputs and runtime discovery. Karma is the workload on which this model is tested.

The agent business solution template complements Adage with a general workflow: ambiguous objective → specification → agent work → deterministic verification → evidence → human release decision. It does not replace Terraform or grant AWS permissions.

An infrastructure task should record its objective, accounts/regions, component instances, acceptance criteria, permitted observations, and prohibited mutations. The agent inspects both repositories and history, proposes changes, runs checks, and prepares a plan and risk report. A human reviews evidence and separately authorizes consequential execution. Read-only post-change checks verify the outcome; operational observation tests whether expected savings and health actually follow.

Authority is enforced, not inferred #

Agents may inspect code and AWS read-only, develop components, modify local configuration, validate, plan, analyze cost/drift, and prepare pull requests. They must not self-authorize apply/destroy, SSM publishing, environment rebinding, data deletion, sensitive IAM/security changes, or irreversible operations.

Use restricted observation/planning credentials and a separately authorized execution path. Planning must not silently bootstrap or change a remote backend. Saved plans and raw evidence may contain sensitive values; public reports should redact account identifiers, configuration values, and secrets.

Implemented safeguards are under review in aws-iac PR #1 and aws-config PR #1, rather than on main. They include agent instructions, target preflight, mutation guards, verification tools, and evidence guidance. Read their current limitations and check CI before relying on them. Legacy deployment commands remain mutating interfaces; an approval acknowledgement is not permission for an agent to grant itself authority.

Architecture and approval boundary #

The infrastructure paths are established. The agent evidence loop and approval process describe the evolving workflow.

flowchart TD
    objective["Business / engineering objective"] --> agent["Agent: reason, build, verify"]
    agent --> config["aws-config: desired state"]
    agent --> iac["aws-iac: Terraform / Terragrunt"]
    config -->|"Published configuration"| ssm["SSM: configuration and runtime bridge"]
    ssm -->|"Inputs and dependencies"| iac
    iac -->|"Plans and checks"| evidence["Verification: plans, cost, health, risk"]
    aws["AWS: actual resources"] -->|"Read-only observations"| evidence
    evidence --> approval["Human approval boundary"]
    approval --> execution["Separately authorized execution"]
    execution --> aws
    execution -->|"Publish runtime metadata"| ssm
    evidence -->|"Findings and revised objectives"| agent

SSM stores /iac/environment, /iac/<component>/<nickname>/config, and /iac/<component>/<nickname>/runtime by convention. IAC_PREFIX can change the prefix. It does not replace Terraform state or live AWS inventory.

See the original system diagram and the cost proof for supporting detail.