Automating AWS Well-Architected Reviews with Kiro CLI

Level 300

As cloud architects and consultants, we've all been there: conducting Well-Architected Framework Reviews (WAFR) that take weeks of manual effort—collecting data, interviewing stakeholders, cross-referencing AWS documentation, and producing reports that often arrive too late to drive meaningful change. The community has responded with great tools: WA-Gen-AI analyzes IaC templates against best practices in minutes, the Well-Architected IaC Analyzer brings that to production scale, and the WA GenAI Workshop teaches prompt engineering patterns for reviews.

But after leading multiple WAFR engagements for financial services clients at GFT, I noticed a gap these tools don't cover: what happens when what clients claim in the WA Tool doesn't match what's actually running in their accounts? And how do you scale that verification across 6 pillars, multiple clients, and regulatory frameworks like DORA—without rebuilding the wheel every time?

The answer came from combining specialized AI agents with Kiro CLI's native subagent orchestration, automated gap analysis that cross-references claims with live account data, and a reusable scaffold that any consultant can clone and configure in minutes.

You're invited to explore how I built this approach—standing on the shoulders of existing tools while adding the verification and multi-client acceleration layer that was missing.

The Problem: Manual Assessments Don't Scale

Traditional WAFR assessments follow a predictable pattern:

1. Schedule workshops with multiple teams (2-3 weeks of calendar time)
2. Walk through 50+ questions per pillar manually
3. Trust that answers reflect reality (spoiler: they often don't)
4. Produce a report that's outdated by the time it's delivered
5. Repeat everything for the next client from scratch

Yes, the WA Tool supports custom lenses—you can upload your own compliance frameworks (DORA, SOX, internal standards) and evaluate workloads against them. This is powerful for structuring the questions. But the fundamental issue remains: the answers are self-reported. Custom lenses tell you what to ask, not whether the answers are true.

For regulated industries like banking (DORA, SOX compliance), this gap between stated practices and actual implementation goes undetected until an audit finds them—regardless of how well-crafted your custom lens is.

The Ecosystem: Tools That Accelerate WAFR Today

Before building this scaffold, I evaluated the existing tools. Each solves a piece of the puzzle:

Tool	What It Does	Strength
WA-Gen-AI / IaC Analyzer	Analyzes CloudFormation/Terraform templates against WA best practices using Bedrock	Answers ~50% of WA questions from IaC alone. Showcased at re:Invent 2024 with Commonwealth Bank
AWS Well-Architected Tool	Native console for structured reviews—questionnaires, milestones, improvement plans	Source of truth for formal WA reviews, custom lens support, Trusted Advisor integration
WA GenAI Workshop	AWS workshop on applying GenAI to accelerate reviews	Prompt engineering patterns, Bedrock integration

These are excellent—and complementary to what we're building. Here's the gap:

Capability	WA-Gen-AI / IaC Analyzer	WA Tool	This Scaffold
IaC template analysis	✅	❌	✅ (via MCP)
Structured questionnaire	❌	✅	✅ (agent prompts)
Live account verification	❌	❌	✅
Gap analysis (claims vs. reality)	❌	❌	✅
Trusted Advisor correlation	❌	✅ (native)	✅ (three-way validation)
Multi-client isolation	❌	Per-workload	✅
Parallel pillar execution	❌	Manual	✅ (subagents)
Compliance frameworks (DORA/SOX)	❌	Custom lenses	✅ (built-in)
Reusable scaffold/template	❌	❌	✅
Consultant workflow	❌	❌	✅

WA-Gen-AI analyzes what you intend to deploy (IaC). Our scaffold verifies what's actually running and compares it with what you claimed in the WA Tool. Together, they cover the full spectrum—design-time analysis AND runtime verification.

The ideal combined workflow:

1. WA-Gen-AI → Analyze IaC templates before deployment (shift-left)
2. WA Tool → Conduct formal review with structured questionnaires and custom lenses
3. This Scaffold → Verify claims against live accounts, correlate with Trusted Advisor, run parallel pillar assessments, produce evidence-based reports

The Solution: WAFR Assessment Scaffold

I created a scaffold project that provides the complete structure, AI agent configurations, and automation tooling to conduct comprehensive WAFR assessments. Think of it as a "quick start" for any new assessment engagement—clone it, configure it for your client, and let the agents do the heavy lifting.

Architecture Overview

well-architected-assessment-scaffold/
├── .kiro/
│   ├── agents/          # 7 specialized AI agents (one per pillar + general)
│   ├── prompts/         # Deep knowledge prompts for each assessment domain
│   └── steering/        # Project context (product, tech, structure)
├── clients/
│   └── {client-name}/   # Isolated client environments
│       ├── inputs/      # Client documentation & architecture
│       ├── data/        # Automated collection results
│       ├── config/      # Client-specific settings
│       └── outputs/     # Generated reports & dashboards
├── tools/
│   └── kiro-extensions/          # Utilities and helpers
├── config/
│   └── assessment/
│       └── pillars.yaml          # Pillar weights & priorities
└── docs/                          # Methodology, compliance, guidelines

The key design principle is client isolation with shared intelligence—every client gets their own data space, but all assessments leverage the same expert agents and proven methodology.

Prerequisites: AWS CLI Profile Configuration

Before running any assessment, you need a configured AWS CLI profile with read-only access to the target account. There are two ways to tell agents which profile to use:

Option 1: Specify in the prompt (recommended)

The simplest approach — tell the agent which profile to use when you invoke it:

kiro-cli chat --agent aws-wafr-expert "Conduct a full WAFR assessment for acme-corp. \
  Use AWS profile 'acme-corp-readonly' for all AWS operations. \
  Region: us-east-1."

The aws tool accepts a profile_name parameter on every call, so the agent will use it for all AWS CLI interactions throughout the session.

Option 2: Set in MCP server environment

For MCP servers that connect directly to AWS (CloudWatch, IAM, etc.), set the profile in the agent config:

"env": {
  "AWS_PROFILE": "acme-corp-readonly",
  "AWS_REGION": "us-east-1"
}

Client profile documentation

The scaffold provides a location to document each client's AWS access:

clients/acme-corp/config/aws/
└── profiles.ini          # Client AWS profile name, role ARN, region

Minimum IAM permissions required

The assessment role needs read-only access:

• ReadOnlyAccess managed policy (broad coverage)
• support:DescribeTrustedAdvisor* (Trusted Advisor — requires Business Support)
• wellarchitected:Get*, wellarchitected:List* (WA Tool API)
• ce:GetCost*, ce:GetDimensionValues, ce:GetTags (Cost Explorer)

Security note: Never use admin credentials for assessments. Create a dedicated read-only role. The agents only need to read account state, not modify it.

Hands On

Let's get into the code. 👽

Setting Up the Scaffold

velez94 / aws_well_architected_assement_scaffold

Well Architected Assement Scaffold Project with AI and Human on the loop

Well-Architected Assessment Scaffold

This is a scaffold/template project for AWS Well-Architected Framework Reviews (WAFR). It contains the essential Kiro AI configuration and a sample client structure to help you quickly start new assessment projects.

What's Included

.kiro/ - Kiro AI Configuration

Contains all the AI agent configurations and prompts for conducting Well-Architected assessments:

• agents/ - Specialized AI agents for each pillar:

  • aws-wafr-expert.json - General WAFR expert
  • aws-cost-exp.json - Cost Optimization pillar
  • aws-security-expert.json - Security pillar
  • aws-reliability-expert.json - Reliability pillar
  • aws-performance-expert.json - Performance Efficiency pillar
  • aws-opex-expert.json - Operational Excellence pillar
  • aws-sustainability-expert.json - Sustainability pillar

• prompts/ - Review prompts for each pillar:

  • general-wafr-review.md
  • cost-optimization-review.md
  • security-pillar-review.md
  • reliability-pillar-review.md
  • performance-pillar-review.md
  • operational-excellence-review.md
  • sustainability-pillar-review.md

• steering/ - Project guidance documents:

  • product.md - Product requirements
  • structure.md - Project structure guidelines
  • tech.md - Technical specifications

config/ - Project Configuration

• assessment/ - Assessment configuration files:
  • pillars.yaml - Well-Architected pillar definitions

docs/ - Documentation

Comprehensive documentation for the assessment framework:

• wafr/ -…

View on GitHub

Start by cloning and configuring for your client:

git clone https://github.com/velez94/aws_well_architected_assement_scaffold.git my-client-assessment
cd my-client-assessment
mv clients/acme-retail clients/acme-corp

The Agent Architecture

Each WAFR pillar has a dedicated Kiro CLI agent with specialized knowledge and MCP integrations. Here's the security expert configuration:

{
  "name": "aws-security-expert",
  "description": "AWS WAFR Security Pillar Expert",
  "prompt": "file://../prompts/security-pillar-review.md",
  "tools": ["read", "write", "shell", "aws"],
  "mcpServers": {
    "aws-documentation": {
      "command": "uvx",
      "args": ["awslabs.aws-documentation-mcp-server@latest"]
    },
    "iam": {
      "command": "uvx",
      "args": ["awslabs.iam-mcp-server@latest"]
    },
    "well-architected-security": {
      "command": "uvx",
      "args": ["awslabs.well-architected-security-mcp-server@latest"]
    },
    "cloudwatch": {
      "command": "uvx",
      "args": ["awslabs.cloudwatch-mcp-server@latest"]
    }
  }
}

Each agent connects to specific AWS MCP servers that give it real-time access to documentation, IAM analysis, security findings, and monitoring data—no hallucinations, just facts.

The full agent roster:

Agent	Pillar	Weight	MCP Integrations
aws-security-expert	Security	25%	IAM, WA Security, CloudWatch, Docs
aws-reliability-expert	Reliability	20%	AWS Support (Trusted Advisor), CloudWatch, Docs
aws-cost-exp	Cost Optimization	20%	Billing & Cost Management, Docs
aws-performance-expert	Performance	15%	CloudWatch, Docs
aws-opex-expert	Operational Excellence	15%	CloudTrail, CloudWatch, Docs
aws-sustainability-expert	Sustainability	5%	Billing & Cost Management, CloudWatch, Docs
aws-wafr-expert	General/Orchestration	—	All of the above + AWS Support, CloudTrail

Native Orchestration with Kiro Subagents

Here's where Kiro CLI shines. The built-in subagent system provides DAG-based pipeline execution with parallel stages, dependencies, and consolidated results. Each pillar agent runs as an independent stage, and a final consolidation stage merges everything:

# All 6 pillar assessments run IN PARALLEL, then consolidate
kiro-cli chat --agent aws-wafr-expert "Conduct a full WAFR assessment for acme-corp across all pillars. Use the client inputs in clients/acme-corp/inputs/ and cross-reference with actual AWS account findings. Produce a consolidated report with gap analysis, risk ratings, and prioritized remediation roadmap."

Under the hood, Kiro's subagent pipeline coordinates this as a DAG:

Stage	Agent	Execution
Security assessment	aws-security-expert	Parallel
Reliability assessment	aws-reliability-expert	Parallel
Cost assessment	aws-cost-exp	Parallel
Performance assessment	aws-performance-expert	Parallel
Operational Excellence	aws-opex-expert	Parallel
Sustainability	aws-sustainability-expert	Parallel
Consolidation	aws-wafr-expert	After all above

Why this matters: Traditional approaches require you to build and maintain orchestration code, handle failures, manage state, and coordinate outputs. With Kiro subagents, the infrastructure is the orchestrator. You focus on the assessment logic in your prompts and agent configurations, not on plumbing.

How Subagents Get Triggered

You don't need to manually define the pipeline in your prompt. The aws-wafr-expert agent has access to the subagent tool and understands from its prompt (the 4-phase methodology) that multi-pillar assessments should be delegated. When you give it a task like "assess all 6 pillars," it internally constructs the DAG:

{
  "task": "Full WAFR assessment for acme-corp",
  "stages": [
    {"name": "security", "role": "aws-security-expert", 
     "prompt_template": "Conduct security pillar assessment for {task}"},
    {"name": "reliability", "role": "aws-reliability-expert", 
     "prompt_template": "Conduct reliability pillar assessment for {task}"},
    {"name": "cost", "role": "aws-cost-exp", 
     "prompt_template": "Conduct cost optimization assessment for {task}"},
    {"name": "consolidation", "role": "aws-wafr-expert",
     "prompt_template": "Consolidate all findings into unified report for {task}",
     "depends_on": ["security", "reliability", "cost"]}
  ]
}

Each subagent:

• Loads its own agent config (own MCP servers, own tools, own prompt)
• Runs in an isolated session (no cross-contamination between pillars)
• Reports results back via the summary tool when done
• Can be monitored live with Ctrl+G in the TUI

You can also be explicit: "Use subagents to run security, reliability, and cost in parallel, then consolidate." But in most cases, the agent figures it out from the task scope and its methodology prompt.

Important: The orchestrating agent (aws-wafr-expert) must have "subagent" in its tools array — as documented here. Subagents cannot spawn sub-subagents — only the parent agent can orchestrate. Each subagent loads its own MCP servers independently, so pillar agents don't inherit the parent's connections.

To avoid approval prompts for each pillar agent spawn, configure trustedAgents in the orchestrator:

{
  "tools": ["read", "write", "shell", "aws", "subagent"],
  "toolsSettings": {
    "subagent": {
      "availableAgents": ["aws-security-expert", "aws-reliability-expert", 
        "aws-performance-expert", "aws-cost-exp", "aws-opex-expert", 
        "aws-sustainability-expert"],
      "trustedAgents": ["aws-*"]
    }
  }
}

This allows all aws-* pillar agents to be spawned without user confirmation — essential for unattended parallel execution.

The 4-Phase Assessment Flow

The assessment follows 4 logical phases, expressed through agent interactions:

Phase 1 - Data Collection: The aws-wafr-expert agent extracts WA Tool workload data, queries Trusted Advisor (when Business/Enterprise Support is available), and triggers automated account discovery via MCP integrations (Cost Explorer, CloudWatch, IAM).

Phase 2 - Gap Analysis: The same agent performs a three-way validation—comparing WA Tool responses vs. Trusted Advisor detections vs. actual account state. Discrepancies become the highest-priority inputs for pillar agents.

Phase 3 - Pillar Assessments: All 6 specialized agents run in parallel, each receiving the gap analysis context and performing deep-dive evaluation of their domain.

Phase 4 - Consolidation: The aws-wafr-expert merges all pillar results into a unified report with prioritized recommendations, risk ratings, and remediation roadmaps.

Pillar Configuration with Weights

The pillars.yaml defines assessment priorities—critical for financial services where security and reliability outweigh other concerns:

pillars:
  security:
    weight: 25
    priority: high
    focus_areas:
      - identity_access_management
      - data_protection
      - infrastructure_protection
      - detective_controls
      - incident_response

  reliability:
    weight: 20
    priority: high
    focus_areas:
      - foundations
      - workload_architecture
      - change_management
      - failure_management

  cost:
    weight: 20
    priority: high
    focus_areas:
      - practice_cloud_financial_management
      - expenditure_awareness
      - cost_effective_resources

Customize these weights per industry. Banking needs Security at 25%+; a startup might weight Cost Optimization higher. The agents use these weights to prioritize findings in the consolidated report.

Running a Pillar Assessment with Kiro CLI

Once your client inputs are in place, invoke a specialized agent:

# Run security pillar assessment
kiro-cli chat --agent aws-security-expert "Conduct a comprehensive security   assessment for acme-corp. Analyze the inputs in clients/acme-corp/inputs/security/  and cross-reference with actual AWS account findings."

# Run cost optimization review
kiro-cli chat --agent aws-cost-exp "Perform cost optimization analysis for 
  acme-corp workloads. Compare WA Tool responses with actual Cost Explorer data and Trusted Advisor cost findings."

The agents produce structured findings with evidence, risk ratings, and specific remediation steps—ready for executive or technical audiences.

Multi-Client Scalability

The scaffold supports multiple concurrent assessments with complete isolation:

clients/
├── acme-corp/        # Banking client (DORA + SOX)
│   ├── inputs/
│   ├── data/
│   └── outputs/
├── healthco/         # Healthcare client (HIPAA)
│   ├── inputs/
│   ├── data/
│   └── outputs/
└── retailx/          # Retail client (PCI-DSS)
    ├── inputs/
    ├── data/
    └── outputs/

Each client inherits the same expert agents and methodology but maintains completely separate data, configurations, and deliverables. This is critical for consulting firms managing multiple engagements—no cross-contamination, clean audit trails.

---

Integrating with the WA Tool API: Start Fresh or Continue an Existing Review

A key feature of this scaffold is its direct integration with the AWS Well-Architected Tool API. You can either start a new assessment from scratch or pull an existing review to contrast and continue the work:

# Option 1: Start from an existing workload assessment
kiro-cli chat --agent aws-wafr-expert "Pull workload assessment data from WA Tool workload ID abc12345-def6-7890-ghij-klmnopqrstuv. Extract all lens reviews,  answers, and milestones. Use this as baseline for gap analysis against the live account."

# Option 2: Start a fresh assessment (no prior WA Tool data)
kiro-cli chat --agent aws-wafr-expert "Create a new WAFR assessment for acme-corp.  No prior WA Tool review exists. Perform full account discovery and evaluate  against all 6 pillars from scratch."

The aws-wafr-expert agent uses the WA Tool API through its AWS tool integration to:

API Operation	Purpose
ListWorkloads	Discover existing workload assessments in the account
GetWorkload	Retrieve workload metadata and configuration
GetLensReview	Pull pillar-level review summaries and risk counts
ListAnswers	Extract all question responses for a given lens/pillar
ListMilestones	Track assessment history and improvement over time
ListLensReviewImprovements	Get AWS-recommended improvement items

When a prior review exists, the agent uses those answers as the "claims" side of the gap analysis—then verifies each claim against live account data and Trusted Advisor findings. This is where the real value emerges: you're not starting from zero, you're validating and extending work that was already done.

Two workflows, one scaffold:

This means the scaffold fits into any point of the assessment lifecycle—whether the client has been doing WA reviews for years or is starting their first one today.

---

Leveraging Trusted Advisor Integration

When the client has Business or Enterprise Support, the WA Tool automatically integrates with AWS Trusted Advisor—surfacing real-time checks across cost optimization, performance, security, fault tolerance, and service limits directly into the review. This is a powerful data source that many teams underutilize.

Our scaffold takes full advantage of this:

Trusted Advisor Category	How Kiro Agents Use It
Cost Optimization	aws-cost-exp cross-references TA findings (idle resources, underutilized instances) with Cost Explorer data for validated savings estimates
Security	aws-security-expert correlates TA security checks (open ports, IAM issues, MFA gaps) with Security Hub findings for comprehensive posture assessment
Fault Tolerance	aws-reliability-expert uses TA availability checks (multi-AZ, backup coverage, RDS redundancy) to validate reliability claims
Performance	aws-performance-expert leverages TA performance checks (overutilized instances, CloudFront optimization) alongside CloudWatch metrics
Service Limits	All agents flag service quota risks that could impact scalability or availability

With Business Support, Trusted Advisor provides full check access—over 100 checks that become automated evidence for the gap analysis. Without it, you're limited to core checks. This is why we recommend clients activate Business Support before starting the assessment.

The aws-wafr-expert agent queries Trusted Advisor findings via the AWS Support API and feeds them as context to each pillar agent. Combined with the WA Tool's native TA integration, this creates a three-way validation: what the client claimed (WA Tool answers) vs. what Trusted Advisor detected vs. what the account actually shows (live resource analysis via MCP).

---

The Gap Analysis: Claims vs. Reality

This is the differentiator. Traditional WAFR assessments trust the answers. Our approach verifies them.

Example findings from a real engagement:

WA Tool Claim	Trusted Advisor	Actual Finding	Risk
"MFA enabled for all users"	⚠️ IAM users without MFA detected	3 IAM users without MFA, root account MFA not hardware-based	HIGH
"Encryption at rest for all data"	— (not covered by TA)	2 S3 buckets with default encryption disabled, 1 RDS instance unencrypted	HIGH
"Automated backups configured"	⚠️ RDS backup retention < 7 days	Backup retention set to 1 day on production databases	MEDIUM
"Cost monitoring in place"	⚠️ No budget alerts	No budget alerts configured, no anomaly detection	MEDIUM

This evidence-based approach transforms the assessment from an opinion exercise into a factual audit—exactly what regulated industries need for DORA and SOX compliance.

---

Compliance Integration

The scaffold includes built-in support for regulatory frameworks commonly required in financial services, healthcare, and enterprise environments:

docs/compliance/
├── dora/     # Digital Operational Resilience Act (EU financial services)
├── hipaa/    # Health Insurance Portability (US healthcare)
└── sox/      # Sarbanes-Oxley (US financial reporting)

The security agent prompt includes specific DORA focus areas:

Financial Services Security (DORA Compliance): ICT risk management, operational resilience, third-party risk, Zero-Trust Architecture, Multi-Account Security

This means every security assessment automatically evaluates DORA readiness—no separate engagement needed. The compliance documentation provides the agents with regulatory context so their recommendations map directly to compliance requirements.

---

GenAI Patterns Applied

This scaffold implements several established GenAI patterns that ensure quality, safety, and reliability in an enterprise context. Understanding these patterns is important for anyone building AI-assisted workflows in regulated environments:

Human-in-the-Loop (HITL)

The most critical pattern here. AI agents collect data, analyze gaps, and generate recommendations—but a human architect validates and approves before anything reaches the client. This is non-negotiable for regulated industries.

Where HITL applies:

• Review agent findings before consolidation into the final report
• Validate risk ratings—the agent may flag something as HIGH that context makes MEDIUM
• Approve remediation recommendations—ensure feasibility given client constraints
• Sign-off on executive summaries—tone, framing, and business impact require human judgment

Retrieval-Augmented Generation (RAG)

Agents don't rely on training data alone. Through MCP integrations, they retrieve real-time data from:

• AWS documentation (always current)
• Live account state (IAM, CloudWatch, Cost Explorer)
• WA Tool API (actual assessment responses)
• Trusted Advisor (automated checks with Business/Enterprise Support)

This eliminates hallucinations about the client's actual environment.

Agentic Orchestration (Fan-out / Fan-in)

The subagent DAG implements a classic fan-out/fan-in pattern:

• Fan-out: 6 specialized agents execute in parallel, each with domain expertise
• Fan-in: The consolidation agent merges results into a unified deliverable

This reduces wall-clock time from sequential (6× pillar duration) to parallel (1× longest pillar duration).

Tool-Augmented Generation

Agents don't just generate text—they execute tools to gather evidence:

• aws CLI calls for account interrogation and Trusted Advisor queries
• MCP servers for structured data retrieval
• File system reads for client documentation and architecture inputs

Every recommendation is backed by data the agent actually retrieved, not inferred.

Supervised Autonomy

The operating model is supervised autonomy:

• Autonomous: Data collection, TA queries, resource inventory, metric gathering
• Supervised: Gap analysis interpretation, risk prioritization, client-facing recommendations
• Human-only: Final report approval, client presentation, remediation prioritization with stakeholders

This isn't fully autonomous AI replacing the architect. It's AI handling the 80% of toil (data collection, cross-referencing, formatting) so the architect focuses on the 20% that requires judgment, context, and client relationships.

---

Skills: Deep Knowledge On-Demand

One challenge with AI agents is context window management. If you load every possible best practice, compliance requirement, and remediation pattern into the agent prompt, you burn through context before the assessment even starts. But if you keep prompts lean, the agent lacks depth when it encounters specific scenarios.

Kiro CLI solves this with Skills—resources whose metadata (name + description) is loaded at startup, but whose full content is only pulled on-demand when the agent determines it's relevant.

How It Works

A skill is a Markdown file with YAML frontmatter:

---
name: dora-compliance-requirements
description: DORA regulatory requirements for ICT risk management, 
  operational resilience, and third-party risk. Use when assessing 
  financial services workloads for DORA compliance.
---

# DORA Compliance Requirements
## Key Articles for WAFR Assessment
### Article 5-16: ICT Risk Management
- Establish and maintain resilient ICT systems...
(detailed content only loaded when needed)

Referenced in agent config via skill:// URI:

{
  "resources": [
    "file://README.md",
    "skill://.kiro/skills/**/SKILL.md"
  ]
}

Skills vs. Prompts — When to Use Each

	Agent Prompt	Skill
Loaded	Always — full content in context	On-demand — only metadata at start
Purpose	Defines who the agent is (methodology, output format)	Provides deep reference knowledge for specific scenarios
Analogy	The architect's expertise	The reference books pulled from the shelf when needed
Size	Keep lean (< 5K tokens)	Can be large (2-20K tokens of detailed guidance)

The Scaffold's Skill Library

.kiro/skills/
├── compliance/
│   └── dora/SKILL.md              # DORA articles, AWS mapping, risk criteria
├── pillars/
│   ├── security/
│   │   └── iam-best-practices/SKILL.md    # IAM checks, common findings, evidence commands
│   ├── cost/
│   │   └── rightsizing-guide/SKILL.md     # Rightsizing analysis, savings estimation
│   └── reliability/
│       └── disaster-recovery/SKILL.md     # DR strategies by RTO/RPO, assessment checklist
└── remediation/
    └── quick-wins/SKILL.md                # 0-30 day low-effort high-impact actions

The security agent sees: "dora-compliance-requirements — Use when assessing financial services workloads". When it encounters a banking client, it pulls the full DORA skill with article-by-article AWS mappings. For a retail client, it never loads it—saving context for what matters.

Each pillar agent references only the skills relevant to its domain:

// aws-security-expert.json
"resources": [
  "file://README.md",
  "skill://.kiro/skills/pillars/security/**/SKILL.md",
  "skill://.kiro/skills/compliance/**/SKILL.md",
  "skill://.kiro/skills/remediation/**/SKILL.md"
]

This means you can grow the skill library indefinitely—adding new compliance frameworks, service-specific patterns, industry guidance—without impacting agent performance. The agents stay fast and focused, pulling depth only when the assessment requires it.

Knowledge Bases: Searching Through Client Data

Skills solve the "deep reference knowledge" problem. But what about the client's own documentation—architecture diagrams, runbooks, security policies, infrastructure configs? These can be 50+ files that are too large to load into context but need to be searchable during the assessment.

Kiro CLI's Knowledge Base feature provides persistent semantic search across sessions. You index client inputs once, and agents can search through them on-demand using natural language queries.

How It Works

Define a knowledge base in the agent config with auto-sync:

{
  "resources": [
    "file://README.md",
    "skill://.kiro/skills/**/SKILL.md",
    {
      "type": "knowledgeBase",
      "source": "file://./clients",
      "name": "Client Inputs & Architecture",
      "indexType": "best",
      "include": ["**/*.md", "**/*.yaml", "**/*.json", "**/*.txt"],
      "exclude": ["**/outputs/**", "**/draft/**"],
      "autoUpdate": true
    }
  ]
}

When the agent starts, all client documentation gets indexed semantically. The agent then searches it during the assessment—pulling only the relevant snippets into context when needed.

The Three-Layer Context Strategy

Layer	Mechanism	When Loaded	Best For
Prompts	file://../prompts/	Always (full content)	Agent identity, methodology, output format
Skills	skill://.kiro/skills/	On-demand (by description match)	Deep reference knowledge, compliance frameworks
Knowledge Bases	knowledgeBase resource	Searchable (semantic query)	Large client documentation, architecture inputs

Prompts tell the agent how to assess. Skills give it what to look for. Knowledge Bases let it find relevant client context without loading everything into memory.

This layered approach means an agent can handle a client with 100+ input documents without ever hitting context limits—it searches, retrieves the relevant 2-3 snippets, and uses them to produce evidence-based findings.

---

Best Practices and Lessons Learned

After multiple engagements using this scaffold, here are the patterns that consistently deliver the best results:

• Start with steering files: Clear product, tech, and structure documentation in .kiro/steering/ gives agents the context they need to produce relevant findings instead of generic advice. Invest time here—it pays dividends across every assessment.

• Limit MCP tools per agent (~50 max): Each tool definition consumes ~400 tokens of context window. At 100+ tools, you're burning 40K+ tokens before any work begins. The aws-wafr-expert orchestrator needs only 4 servers (~26 tools) for coordination—leave the heavy toolsets (IAM 29 tools, Billing 33 tools, CloudWatch 19 tools) to the specialized pillar agents that actually use them.

• Gap analysis is non-negotiable: The comparison between WA Tool answers and actual account state consistently reveals the highest-value findings. Never skip this phase—it's where the scaffold earns its keep.

• Pillar weights matter: Customize pillars.yaml per industry. Banking needs Security at 25%+; a startup might weight Cost Optimization higher. These weights drive prioritization in the consolidated report.

• Client isolation is a feature, not overhead: Each client assessment gets its own scaffold project—clone the scaffold, configure it, and you have a completely independent repository with its own git history, access controls, and lifecycle. No shared state, no cross-contamination. For consulting firms, this means clean handoffs, simple access management per engagement, and compliance with data handling requirements out of the box.

• Activate Business Support first: Recommend clients enable Business or Enterprise Support before the assessment. The full Trusted Advisor check access (100+ checks) dramatically improves evidence quality.

• Use Kiro CLI for parallel assessments: While one agent analyzes security, another can simultaneously evaluate cost optimization. The subagent system coordinates everything—leverage it.

• Keep inputs clean and structured: The quality of agent output directly correlates with the quality of client documentation in inputs/. Garbage in, garbage out still applies—even with AI.

• Supervised execution for critical findings: Let agents run autonomously for data collection, but review and validate high-risk recommendations before presenting to clients. The human-in-the-loop pattern is your quality gate.

• Iterate on prompts: The prompts in .kiro/prompts/ are living documents. After each engagement, refine them based on what worked and what produced noise. This is how the scaffold gets smarter over time.

---

The scaffold is open for the community to use, extend, and improve. Whether you're a solo consultant or part of a large practice, the goal is the same: deliver better assessments, faster, with evidence.

---

Thank you for your time and support. Please remember to follow us for additional updates.

✨ Alejandro Velez, Platform Engineering Latam Lead @ GFT | AWS Ambassador

---

References:

• AWS Well-Architected Framework
• AWS Well-Architected Tool API
• WA-Gen-AI by Ebrahim Khiyami
• Well-Architected IaC Analyzer (AWS Sample)
• Well-Architected GenAI Workshop
• AWS Trusted Advisor
• Custom Lenses in WA Tool
• Kiro CLI Documentation
• AWS MCP Servers