Jonathan Boniface 5ef434d00e feat: Change requests against a Baseline (ADR-0006)
A caller restates a request to say how requirements have changed, naming a
completed Execution of the same Customer case as the Baseline.

- app/baseline.py reads a Baseline from its files and refuses one that
  does not exist, did not complete or belongs to another case, before
  anything runs or is recorded. A Baseline is never modified.
- Requirements carry a change (unchanged, added, changed, removed) and a
  reason. Submission is refused when a Baseline requirement disappears, an
  id is reused, or an unchanged requirement's text differs. A removed
  requirement stays on record and asks nothing downstream.
- Each Specialist starts from its delivered version; the graph and the code
  are its working copy, and the description is carried over when the
  design's shape is the same.
- app/workflows/changes.py compares versions by id and traces what each
  changed requirement reaches; anything else that changed is listed as
  unrequested. Approvals show the change for their Phase, and changes.json
  is written with the full Deliverables.
- Intake no longer starts a message read as a change: it names the
  Execution to give as the Baseline.
- A fifth evaluation case runs a request and then a change to it, with
  four checks that the change is recorded, reaches Checks, stays contained
  and costs less than its Baseline.

Tested with scripted agents only; no Change request has run with real
models.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-09 11:38:15 +01:00
2026-10-06 20:22:37 +01:00
2026-10-06 20:22:37 +01:00
2026-10-06 20:22:37 +01:00

GCP Solution Architecture Agent (gcp_solution_architecture_agent)

A hierarchical ReAct agent that turns a request for a cloud workload into a reviewed solution architecture: requirements, a target design with diagram and infrastructure-as-code, validation results, and a packaged guide. It replaces the google-cloud-solution-architecture skill with an agent that runs anywhere. Google Cloud is the first Cloud provider.

Vocabulary is defined in CONTEXT.md, decisions in docs/adr/, and the plan and history of each iteration in .agents/plans/.


🌟 Architecture & Features

1. Orchestrator and Specialists (agents/)

One Orchestrator coordinates an Execution and is the only agent that talks to the user. It delegates each Deliverable to one Specialist, and independent Deliverables run in parallel:

  • Requirements discovery: requirements-analyst, decomposer.
  • Solution architecture (design): product-selector, design-advisor (which consults one pillar-advisor per architecture-framework pillar), target-architect.
  • Solution implementation: describer, iac-author.
  • Solution validation: validator.
  • Packaging: packager.

Each Phase needs the user's explicit Approval before work that depends on it starts. A pre-approved mode serves batch and evaluation runs.

The design Phase ends with the Target architecture: one explicit graph of Elements, Relationships and Checks (ADR-0005). The user approves it before any infrastructure code is written. The diagram is drawn from it by code, the Terraform must account for every Check, and validation gives a verdict per Check. Requirements, components, products and recommendations each carry ids in a data file, so every requirement can be traced through to its verdict; a submission with a missing link is refused.

2. LangGraph state, ADK agents (app/)

Per ADR-0003:

  • A LangGraph StateGraph holds the Execution: the dependency graph of Deliverables (app/workflows/deliverables.py), the Ledger of their states (app/states/ledger.py), checkpoints, and interrupt() whenever the user must answer or approve.
  • Every agent is a Google ADK LlmAgent running its own ReAct loop behind one runtime interface (app/adk/runtime.py). app/adk/adk_runtime.py is the only module that imports google.adk.
  • Tools are tiered: local checks and public documentation run freely, reading the user's cloud needs permission once per Execution, and nothing can change cloud resources.

3. Persistence (app/database.py, app/checkpointing.py)

Execution records (status, Ledger events, submitted Deliverables) go to PostgreSQL, with an automatic SQLite fallback for local development. Checkpoints use CHECKPOINTER=memory | sqlite | postgres.

4. Agent Skills (skills/, loaded by app/skills/)

Behaviour lives in Agent Skills (agentskills.io format) at the repository root, per ADR-0002:

  • skills/vendor/google/: the upstream solution-architecture Skill and six Well-Architected Framework pillar Skills, vendored unmodified.
  • skills/cloud-discovery/, skills/iac-validation/ and skills/requirements-chain/: our own Skills for the tooling and the data files.
  • skills/google-cloud-iac-patterns/: Terraform patterns for Google Cloud products, each validated by a test against the provider version providers/gcp.yaml pins.

app/skills/agent_skills.py discovers and validates them; the ADK runtime (app/adk/adk_runtime.py) loads them on demand. providers/gcp.yaml assigns Skills, tools, MCP servers and models to each role in agents/.

5. A2A Server (app/main.py)

The container starts the hierarchical Execution engine (ADR-0003) behind an A2A server:

  • POST /a2a: A2A JSON-RPC for interactive, multi-turn Executions with Approvals.
  • GET /.well-known/agent-card.json: A2A agent card.
  • GET /health: Health signal, the Cloud provider and any MCP discovery gaps.
  • POST /generate: One-shot, pre-approved Execution for batch and evaluation callers. Pass customer_case to group it with the case's other Executions; over A2A, send customer_case in the message metadata.

The original linear pipeline and its REST routes (/card, /validate, /sessions/{session_id}) were removed on 2026-10-06; see .agents/plans/iter-03-kab-layout/.


🚀 Quick Start & Commands

Install Dependencies

pip install -r requirements.txt
pip install -r requirements-dev.txt

Run Tests & Validation

# Run the deterministic test suite (no model or network calls)
pytest -q

# Real-model evaluation of the engine (costs model usage; see eval/solution_eval.py)
python3 -m eval.solution_eval

Start the A2A Server

python3 -m app.main --host 0.0.0.0 --port 8080

🐳 Run with Podman

1. Build the Podman Container Image

podman build -t gcp-solution-architecture-agent:latest .

2. Run Container with Host Deliverables Volume Mount

To ensure Execution outputs (deliverables/cases/{customer_case}/executions/{execution_id}/*) are written directly to your host machine's workspace:

podman run -d --name gcp-agent \
  -p 8080:8080 \
  -v $(pwd)/deliverables:/app/deliverables:Z \
  -v ~/.config/gcloud/application_default_credentials.json:/app/credentials/adc.json:ro \
  -e GOOGLE_APPLICATION_CREDENTIALS=/app/credentials/adc.json \
  -e GOOGLE_GENAI_USE_ENTERPRISE=true \
  -e GOOGLE_CLOUD_PROJECT=your-project-id \
  -e GOOGLE_CLOUD_LOCATION=global \
  -e A2A_PUBLIC_URL=http://localhost:8080 \
  localhost/gcp-solution-architecture-agent:latest

3. Run Connected to External PostgreSQL Container

podman run -d --name gcp-agent \
  -p 8080:8080 \
  -e POSTGRES_HOST=postgres-container-name \
  -e POSTGRES_PORT=5432 \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=gcp_agent_db \
  localhost/gcp-solution-architecture-agent:latest

4. Test API Endpoints

# Health Signal
curl http://localhost:8080/health

# A2A Agent Card
curl http://localhost:8080/.well-known/agent-card.json

# Run a pre-approved Execution
curl -X POST http://localhost:8080/generate \
  -H "Content-Type: application/json" \
  -d '{"request": "Event-driven regional HTTP application in Podman", "customer_case": "acme-webhooks"}'

📁 Repository Structure

gcp_solution_architecture_agent/
├── agents/                      # Framework-neutral role files, one per agent
├── providers/                   # Cloud provider bundles (gcp.yaml)
├── skills/                      # Agent Skills: vendored upstream + our tooling Skills
├── app/                         # KAB workflow-agent layout
│   ├── main.py                  # A2A server entrypoint (python -m app.main)
│   ├── a2a_server.py            # Maps A2A tasks to Executions and their prompts
│   ├── agent.py                 # ExecutionEngine and its assembly (composition root)
│   ├── card.py                  # A2A agent card
│   ├── states/                  # ExecutionState and the Ledger
│   ├── nodes/                   # Execution graph nodes (orchestrator, specialist, user)
│   ├── workflows/               # Execution graph wiring and the Deliverable dependency graph
│   ├── adk/                     # Agent-runtime interface, ADK runtime, role loader
│   ├── skills/                  # Agent Skills discovery and validation
│   ├── tools/                   # Execution tools, local tools, remote MCP, pillar fan-out
│   ├── providers.py             # Provider bundle loader
│   ├── recorder.py              # Execution recording
│   ├── checkpointing.py         # LangGraph checkpointer selection
│   ├── presentation.py          # Prompts and /generate responses
│   ├── config.py                # Typed settings (Pydantic BaseSettings)
│   └── database.py              # Database persistence manager
├── eval/                        # Evaluation
│   ├── solution_eval.py         # Real-model evaluation of the Execution engine
│   ├── scoring.py               # Checks applied to a finished Execution
│   └── datasets/                # Benchmark cases (JSON)
├── deliverables/
│   └── cases/                   # Everything generated, grouped by Customer case
│       └── <customer_case>/
│           ├── intent/          # What the customer asked for, and how it has changed
│           │   ├── 001.md, 002.md   # Each request as the customer stated it, in order
│           │   └── history.json     # Every request, the Execution it started and how it ended
│           └── executions/<execution_id>/
│               ├── execution.json                 # Request, status and files of this Execution
│               ├── solution-architecture-guide.md
│               ├── deliverables/<kind>.md         # One per Deliverable
│               ├── requirements.json, components.json, products.json, recommendations.json
│               ├── target-architecture.json       # Elements, Relationships and Checks
│               ├── architecture.mmd               # Drawn from the graph
│               ├── terraform/, implementation.json  # The code, and which part meets each Check
│               └── verdicts.json                  # Validation's verdict on each Check
├── lessons/candidates/<customer_case>/            # Lesson candidates per Execution (gitignored)
├── docs/                        # ADRs, agent-skill conventions and operations notes
├── scripts/                     # Vendored-Skill sync, MCP tool listing
└── tests/                       # Unit & integration test suite
Description
Generated deliverable: gcp_solution_architecture_agent
Readme 2.3 MiB
Languages
Python 86.5%
Mermaid 10.7%
HCL 1.6%
Dockerfile 0.8%
Shell 0.4%