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 — . 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:

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:

—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:

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:

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

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

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 MCP Servers