Skip to content

Home

Jump to bottom
wiki-sync[bot] edited this page Jul 23, 2026 · 1 revision

Nightly Well-Architected Framework (NWAF) Agent

An autonomous nightly pipeline that reviews a workload's Terraform (declared state) and live AWS account (actual state) against the AWS Well-Architected Framework, classifies configuration drift, keeps a Well-Architected Tool posture current, and reports risk to the team — with human accountability preserved throughout.

Guiding principle: deterministic where determinism exists; the LLM only for the reasoning nothing else can do. Mature scanners detect; a bounded LLM reconciles their output. Orchestration is code, not a model.

NWAF Agent — High-Level Design

Reading order

  1. docs/hld.md — what the architecture is: components, the nightly sequence, data flows, trust boundaries.
  2. The diagram — docs/diagrams/nwaf-agent-hld.drawio (editable) / .png (v2.3).
  3. ADRs — why each decision was made (table below).
  4. docs/governance.md — framework mapping, the consolidated trade-off register, and the AI-governance controls.
  5. docs/business-case.md — problem, cost of the status quo, ROI, risks, KPIs.

Decision records

Every material choice is an Architecture Decision Record (house style: Status · Context · Decision · Consequences · Alternatives · Revisit trigger · References). Each records the honest counter-argument as an explicit revisit trigger.

ADR Decision Choice
0001 Agent runtime compute AWS CodeBuild (deterministic pipeline)
0002 LLM provider Portability layer, Bedrock default, per-run selectable
0003 Detection & orchestration Deterministic pipeline + bounded-LLM reconciliation
0004 Detection tooling Per-pillar scanner portfolio + judgment boundary
0005 RAG store Bundled versioned WA reference — no vector DB
0006 WA Tool write-back Scoped, dedicated automation workload
0007 Least-privilege IAM Per-stage roles, read-only in reviewed account
0008 Human-in-the-loop / remediation report_only | advisory_pr, selectable
0009 Delivery SNS hub → Slack · Jira · Email adapters

Deferred (documented as revisit triggers, not gaps): runtime provider fallback (0002), scheduling formalisation (settled in 0001).

The pipeline in one line

trigger → ① scan (live + code) → ② reconcile (LLM) → ③ score / write-back → ④ deliver
  • ① Scan — Prowler · Steampipe/Powerpipe · Compute Optimizer (live) + Checkov · Infracost (code) → normalised findings.
  • ② Reconcile — Claude (via provider layer) correlates live-vs-code, classifies drift, maps to WA pillars, prioritises, drafts remediation.
  • ③ Score — writes scanner-backed answers + a milestone to a dedicated WA-Tool workload; judgment items proposed, not written.
  • ④ Deliver — full report to S3; thin notification via SNS → Slack / Jira / Email.

Repository layout

nwaf-agent/
├── README.md                 ← you are here
└── docs/
    ├── hld.md                narrative high-level design
    ├── governance.md         frameworks · trade-off register · AI controls
    ├── business-case.md      problem · cost · ROI · risks · KPIs
    ├── adr/                  0001–0009 decision records
    └── diagrams/             nwaf-agent-hld.drawio / .png (v2.3)

Status

  • Decision set: complete (ADR-0001 … 0009).
  • Diagram: v2.3.
  • Known gap (tracked): no run-failure alerting yet — a failed nightly run is silent until the next success (see governance.md §4). Candidate follow-on ADR.
  • Frameworks considered: ISO/IEC 42010 & 25010 · TOGAF ADM · AWS Well-Architected + Cloud Adoption Framework · responsible-AI / model-risk governance (see governance.md).

NWAF Agent repository · generated from docs/ — do not edit wiki pages directly.

Home

Design

Decision Records

Clone this wiki locally