CLOUD.md

Cloud — A.T.O.M & @allen

Design and operate real AWS infrastructure by talking to it.

You say "@allen deploy this CDK repo to dev". A Cloud Architect agent clones the repo, synthesizes the templates, reads your governance policy, drafts a plan, pauses for your approval, deploys the stack, captures its outputs to SSM — and the new resources render as live nodes in a dependency graph you can see, audit, and reconcile. No console clicking. No drift you don't know about. The estate is the source of truth, and the agent works inside it.

This is the cloud half of the circular loop: humans set the boundaries → @allen does the provisioning → A.T.O.M renders the result as live truth → humans observe and adjust.

---

A.T.O.M — the live truth of your cloud estate

A.T.O.M (Agentic Temporal Operating Model) is the single pane of glass over everything that exists in AWS. It is not a static diagram you maintain by hand — it is a live projection of the real estate, organized in three layers:

Layer	Question it answers	Source of truth
Discovery	What exists in this account — including things we didn't build?	AWS Resource Groups Tagging API
Inventory	What is actually running, right now?	Live resource enumeration
Dependencies	What depends on what?	The live CloudFormation stack → resource dependency DAG

A.T.O.M's live estate landing — Discovery, Inventory, and Dependencies over the real account.

Two directions of truth

A.T.O.M is bidirectional. Infrastructure flows into the graph from both ends:

graph LR
    subgraph EXTERNAL["Built outside CortexObserver"]
        X["Existing AWS resources<br/>(consoles, Terraform, other teams)"]
    end
    subgraph CORTEX["Built by CortexObserver"]
        A["@allen deploys<br/>a CDK / CFN stack"]
    end
    subgraph ATOM["A.T.O.M — single pane"]
        D["Discovery<br/>(Tagging API)"]
        I["Inventory<br/>(running resources)"]
        G["Dependencies<br/>(live CFN DAG)"]
    end

    X -->|DISCOVER · absorb + flag drift| D
    A -->|DEPLOY · render as live nodes| G
    D --> I --> G

    style EXTERNAL fill:#3d1d1d,stroke:#5a3a3a,color:#fff
    style CORTEX fill:#1e3a5f,stroke:#2d5a8e,color:#fff
    style ATOM fill:#1d2d1d,stroke:#3a4a3a,color:#fff

Loading

• DISCOVER — A.T.O.M absorbs infrastructure built outside CortexObserver. The Resource Groups Tagging API sweeps the account, pulls in resources nobody provisioned through here, and flags drift between what the estate believes and what AWS actually reports. You inherit a brownfield account without re-modeling it by hand.
• DEPLOY — when @allen provisions a stack, its resources appear as live nodes in the dependency graph. The act of deploying is the act of updating the model. There is no second system to keep in sync.

The dependency DAG

The Dependencies layer is the payoff: a real CloudFormation stack → resource dependency graph, derived from the templates that were actually deployed — not a hand-drawn approximation.

The live dependency DAG — edges introspected from deployed CloudFormation templates.

Edges are extracted by cfn_introspect.py, which reads each deployed template and derives a resource's dependencies from:

• Explicit DependsOn declarations, and
• Implicit intrinsic references — Ref, Fn::GetAtt, and Fn::Sub inside a resource's Properties.

References to template Parameters, pseudo-parameters, or external cross-stack exports are ignored — only edges between two resources declared in the same template become DAG edges. CDK's JSON synth output is already in long-form intrinsics; CloudFormation-flavored YAML (!Ref, !GetAtt, !Sub) is normalized first via parse_template. The extractor is pure and side-effect-free, so it is unit-testable without ever touching AWS. On a real deploy, the BootstrapEngine maps the returned LogicalResourceIds to the asset UUIDs it just created and calls gateway.project_edge — turning a deployed template into rendered edges.

---

@allen — the Cloud Architect

@allen is a single LangGraph StateGraph (agents/allen/graph.py) reasoning on Claude Sonnet. He runs a 7-node, plan-based deployment flow with a hard human-in-the-loop gate before anything consequential happens:

graph TD
    START([command]) --> S[synthesize_repo]
    S --> A[analyze_request]
    A --> P[read_policy]
    P --> C[create_plan]
    C -->|needs approval| W{await_approval}
    C -->|no approval needed| E[execute_plan]
    W -->|approved| E
    W -->|rejected| SUM[summarize]
    E --> SUM
    SUM --> DONE([END])

    style W fill:#3d2d1d,stroke:#c08a3a,color:#fff,stroke-width:2px
    style E fill:#1e3a5f,stroke:#2d5a8e,color:#fff

Loading

@allen's deploy graph — the amber node is the human-in-the-loop approval gate.

#	Node	What happens
1	synthesize_repo	If the request names a CDK repo, clone it and run cdk synth via the allen-worker sidecar, storing the synthesized template. A no-op for plain "deploy <template>" asks.
2	analyze_request	LLM node — parse intent, identify the target templates and the existing infrastructure to deploy against.
3	read_policy	Pull the governing policy context so the plan — and the approval — reflect the org's standards before a human ever sees them.
4	create_plan	LLM node — build an ordered, multi-step plan (e.g. VPC → capture outputs → Hello World → capture). Decides whether the plan requires_approval.
5	await_approval	Human-in-the-loop gate. A real LangGraph interrupt() for any DEPLOY / DELETE action — the run pauses, the command becomes awaiting_clarification, and a human approves or rejects with the plan summary and policy refs in hand.
6	execute_plan	Walk the approved plan task-by-task, deploying each stack via the Bootstrap deploy_stack tooling.
7	summarize	LLM node — report what was deployed (or why it was rejected).

Routing is explicit: create_plan branches to await_approval or straight to execute_plan (no-approval path); await_approval branches to execute_plan (approved) or summarize (rejected). The pause is a first-class outcome — when the graph interrupts, @allen surfaces paused=True with an allen.deploy_approval payload, mirroring the same HITL contract @bishop uses. A deploy never runs unseen.

After the deploy — outputs captured, dependencies rendered

When execute_plan finishes, two things close the loop back to A.T.O.M:

1. Outputs → SSM Parameter Store. A stack's outputs (VPC IDs, subnet IDs, endpoint URLs) are captured as SSM parameters under a derived prefix /cortex/{environment}/{stack_name}/{OutputKey} — e.g. /cortex/dev/cortex-vpc-dev/VpcId. Each is tagged source=bootstrap with the originating execution_id. Downstream stacks then resolve those values dynamically via AWS::SSM::Parameter::Value<String> — zero hardcoded values across a multi-stack deploy.
2. Dependencies → the DAG. The deployed CloudFormation template is introspected into edges (above) and those edges render in the live dependency graph.

sequenceDiagram
    participant H as Human
    participant Allen as @allen
    participant Worker as allen-worker
    participant AWS as AWS CloudFormation
    participant SSM as SSM Parameter Store
    participant ATOM as A.T.O.M DAG

    H->>Allen: "deploy this CDK repo to dev"
    Allen->>Worker: cdk.synth (clone + cdk synth)
    Worker-->>Allen: synthesized template
    Allen->>Allen: analyze · read_policy · create_plan
    Allen-->>H: ⏸ approval required (plan + policy refs)
    H->>Allen: approve
    Allen->>AWS: deploy_stack
    AWS-->>Allen: stack outputs
    Allen->>SSM: capture_outputs → /cortex/dev/.../VpcId
    Allen->>ATOM: introspect template → project edges
    ATOM-->>H: new resources render as live nodes

Loading

---

The allen-worker sidecar

@allen reasons in Python, but cdk synth needs Node and the AWS CDK toolchain. That work runs in a dedicated allen-worker sidecar so the backend never shells out to an untrusted toolchain:

Property	Detail
Runtime	Node + aws-cdk
Auth	HMAC-signed requests between backend and worker
AWS profile	--profile cdk — an isolated credential profile for synth/deploy
Launched by	./scripts/start.sh with --profile cdk (the optional CDK worker sidecar)

The worker is reached through two orchestration tools:

Tool	What it does
cdk.synth	Clone a CDK repo and run cdk synth in the sidecar, returning the synthesized CloudFormation template(s) for synthesize_repo to store.
iac.create_template	Persist a synthesized or authored template into the IaC template store, where it becomes deployable and linkable to SSM parameters.

Because synth is isolated behind an HMAC-signed boundary on its own AWS profile, @allen can ingest an arbitrary CDK repo and turn it into a governed, deployable, graph-rendered stack — without ever running foreign Node code inside the control plane.

---

Why this matters

A traditional IaC workflow is write template → run CLI → hope the diagram is current → discover drift in an incident. A.T.O.M and @allen collapse that into one governed loop:

• One source of truth — discovery, deployment, and the dependency graph are the same model.
• Brownfield-native — the Tagging API absorbs what you already have and flags where reality diverges.
• Governed by construction — policy is read before the plan, and every deploy/delete stops at a human gate.
• Self-wiring — outputs flow to SSM, downstream stacks resolve them dynamically, and dependencies render themselves.

Humans set the rules. @allen does the work. A.T.O.M shows you the truth. The loop closes.

---

Related

• Architecture — the circular loop, Humans/Agents/Farms, A.T.O.M, time as the universal index
• Agents — the repeatable agent pattern and the full roster
• Governance — Policies/Procedures/Standards, risk budgets, and human approval gates