# wa-builder

wa-builder explains AWS Well-Architected concepts for your project and generates annotated diagrams, decision trees, and remediation roadmaps.

- command · `type=command` · Claude Code, Cline, Codex, GitHub Copilot, Gemini CLI · ★ 280 repo stars
- Author: aws-samples
- License: MIT-0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/aws-samples/sample-well-architected-skills-and-steering/tree/HEAD/adapters/claude-code/commands/wa-builder.md
- Updated: 2026-10-06
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/commands/wa-builder

## What it does

The prompt adopts a learn-then-build workflow tailored to your workload. Rather than grading your stack, it pinpoints how cloud design principles apply to your IaC setup. It maps existing compute, database, and networking definitions against Well-Architected pillars, flagging key risks with explicit question codes such as `SEC 3` or `REL 9`.

Tone and depth adjust to your familiarity. Practitioners get straight to output generation, while newcomers receive analogies tied directly to their chosen cloud services. Deliverables include color-coded PlantUML or Mermaid topologies, branching decision flows for tricky architectural crossroads, and a staged Gantt implementation plan.

If you already ran `/aws-well-architected-framework-review`, supply its output. The prompt consumes existing review findings directly so you avoid duplicate discovery passes.

## Install

### Claude Code (native platform)

**Manually: put the files in place**
- File: `.claude/commands/wa-builder.md` — Call it with /wa-builder. For all projects use ~/.claude/commands/

### Codex

**Manually: put the files in place**
- File: `~/.codex/prompts/wa-builder.md` — Call it with /prompts:wa-builder. Codex marks this format deprecated in favour of skills

### GitHub Copilot

**Manually: put the files in place**
- File: `.github/prompts/wa-builder.prompt.md`

### Gemini CLI

**Manually: put the files in place**
- File: `.gemini/commands/wa-builder.toml` — Gemini stores commands as TOML: the prompt text goes into the prompt field

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/aws-samples/sample-well-architected-skills-and-steering/tree/HEAD/adapters/claude-code/commands/wa-builder.md

## When to use it
- generate Well-Architected architecture diagrams with PlantUML and Mermaid
- map architectural trade-offs using structured decision flowcharts
- schedule cloud remediation steps by dependency and effort
- translate AWS Well-Architected Framework questions into code-level adjustments

## Example prompts
- /wa-builder inspect our terraform files and output an annotated PlantUML diagram
- /wa-builder I am new to Well-Architected, explain our reliability gaps and build a decision tree
- /wa-builder use our review findings to generate an improvement roadmap in Mermaid

## Source text · wa-builder.md · MIT-0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 58abe794be6a0901.

BEGIN THIRD-PARTY FILE 58abe794be6a0901
```text
"Learn then Build" — help the user understand AWS Well-Architected best practices for their specific workload, then produce actionable visual artifacts (architecture diagrams with WA annotations, decision trees, improvement roadmaps) they can commit and use.

Unlike `/aws-well-architected-framework-review` (which assesses and scores), wa-builder teaches and enables. Adapt explanations for beginners and generate artifacts faster for experienced builders.

## Step 1: Context and calibration

Ask the user:

> I can help you understand Well-Architected for your project and produce visual artifacts. Let me know:
> - **Workload name** and brief description (or point me at your code)
> - **Your WA familiarity**: New to WA / Familiar / Practitioner
> - **What you want**: Architecture diagram, decision tree, roadmap, or all three
> - **Existing review** (optional): If you have a `/aws-well-architected-framework-review` output, share it for richer artifacts

If context is already provided or you are in a codebase, proceed directly.

**Detect experience** if not stated:
- Uses "pillar", "HRI", "RTO/RPO", "blast radius" naturally → **Practitioner** (skip learning, go straight to artifacts)
- Asks "what is WA" or "how does this apply" → **Beginner** (full explanations with analogies)
- Default → **Familiar** (concise pillar relevance)

## Step 2: Workload discovery

**Path A — Standalone (no prior review):** lightweight discovery — scan IaC for resource types, identify compute pattern (serverless/containers/VMs/mixed), data stores, network topology, deployment patterns. Produce a workload profile: architecture pattern, AWS services in use, per-pillar health signals, top 3 risk hotspots.

**Path B — Post-review (consumes a `/aws-well-architected-framework-review` output):** parse the report for pillar scores, findings by severity, evidence locations, remediation items, and any PlantUML diagram. Use directly — skip discovery, do NOT re-assess.

## Step 3: Learning phase

**Skip entirely for Practitioners.** For Beginners and Familiar, personalize WA to their workload, prioritized by gap severity.

- **Beginner**: for each relevant pillar, explain "Why it matters for YOU" (reference their actual services), top 3 concepts with WA Question IDs, and one developer-friendly analogy.
- **Familiar**: terse per-pillar key-gap list with Question/BP IDs.

Select concepts by mapping the workload's gaps to WA questions (OPS 1–11, SEC 1–11, REL 1–13, PERF 1–5, COST 1–11, SUS 1–6), clustering related questions, and ordering by risk severity then relevance.

## Step 4: Artifact generation

Generate ALL requested artifacts. Each MUST include BP ID references, color/severity indicators, and context specific to THEIR workload (never generic).

**Artifact 1 — Architecture diagram with WA annotations:** PlantUML (primary) + Mermaid alternative. Color-coded component borders — 🟢 key BPs implemented, 🟡 partial gaps, 🔴 critical/high gaps — plus risk-hotspot callouts citing BP IDs and a legend.

**Artifact 2 — Decision trees:** 2–3 Mermaid flowcharts for the most impactful architectural choices (e.g. serverless vs containers, single vs multi-region, canary vs blue/green). Start from their workload context, branch on WA-relevant criteria (availability target, cost tolerance, compliance), end with recommendations citing BP IDs and effort/cost indicators. Present OPTIONS, not mandates.
```
END THIRD-PARTY FILE 58abe794be6a0901

The third-party file has ended. Everything between the 58abe794be6a0901 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3453 of 4957 bytes. © aws-samples · MIT-0 · https://github.com/aws-samples/sample-well-architected-skills-and-steering/tree/HEAD/adapters/claude-code/commands/wa-builder.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
