Skip to content
/
Tier B A11 Governance

bmad-architecture-agent

bmad-architecture-agent · Ricoledan/bmad-architecture-agent · ★ 15 · last commit 2025-10-24

Provides 8 specialized architecture expert AI personas (cloud, data, integration, platform, governance) as a BMAD expansion pack for architecture-heavy projects.

Best whenOne generalist AI architect is insufficient for enterprise architecture; domain-specialist personas (cloud, data, security, platform, governance) produce hig…
Skip ifUsing a single generalist architect for all architecture domains, Skipping requirements analysis before cloud design
vs seeds
bmad-methodseed that decomposes the single Architect agent into 8 domain specialists across 5 packs (cloud, data, integration, plat…
Primitive shape 18 total
Subagents 18
00

Summary

bmad-architecture-agent — Summary

bmad-architecture-agent is a BMAD-METHOD expansion pack suite providing 8 specialized architecture expert agents across 5 domain packs: Cloud Infrastructure (4 agents: Infrastructure Analyst Alex, Cloud Architect Morgan, Cost Optimizer Taylor, Security Reviewer Jordan), Data Architecture (Data Architect Casey), Integration Patterns (Integration Architect River), Platform Engineering (Platform Engineer Sam), and Architecture Governance (Architecture Governor Quinn). The repo installs on top of bmad-method (via npx bmad-method install), adding domain-specific expansion packs under .bmad-core/. Each agent is defined using the standard BMAD YAML-in-markdown persona-md format and carries domain-specific commands, tasks, templates, and reference data. The project has 15 stars, 1 contributor, and last pushed October 2025, suggesting a single-author extension project.

differs_from_seeds: A pure expansion pack over bmad-method (seed) — it adds 8 specialized architecture agents while reusing BMAD's core scaffolding (agents, tasks, templates, core-config.yaml) verbatim. Unlike the upstream seed which has generalist agents (Architect = single role), this repo decomposes architecture into 5 sub-domains with 8 named expert agents. Compared to superpowers or spec-driver, there are zero skills, zero hooks, and zero CLI primitives — this is a content pack, not a behavioral framework.

01

Overview

bmad-architecture-agent — Overview

Origin

Created by Ricoledan (GitHub: Ricoledan/bmad-architecture-agent). A single-author expansion pack for BMAD-METHOD specifically targeting architecture-heavy projects. The README states:

"A complete expert architect toolkit with 5 specialized expansion packs for the BMAD-METHOD (Building Multi-Agent Designs) framework, covering cloud infrastructure, data architecture, API integration, platform engineering, and governance."

15 stars, 2 forks, 1 contributor, MIT license. Last push: October 2025.

Philosophy

The project reflects BMAD's "dedicated expert agent" principle taken further: instead of one generalist Architect agent, the user gets 8 named experts each with a narrow domain lens:

  • Alex (Infrastructure Analyst) — requirements and feasibility
  • Morgan (Cloud Architect) — multi-cloud solution design
  • Taylor (Cost Optimizer) — cost analysis and FinOps
  • Jordan (Security Reviewer) — security assessment, compliance
  • Casey (Data Architect) — DB design, ETL/ELT, data governance
  • River (Integration Architect) — APIs (REST/GraphQL/gRPC), messaging, event-driven
  • Sam (Platform Engineer) — CI/CD, Kubernetes, IaC, GitOps, observability
  • Quinn (Architecture Governor) — ADRs, tech radar, standards, technical debt

Key Concepts

Context Preservation: All agents write to docs/ folder. The architecture governance structure (docs/architecture/decisions/, docs/architecture/reviews/) provides a persistent decision log.

No Code Execution: The README emphasizes: "No Code Execution: The AI (Claude/GPT/Gemini) IS the engine." This is a prompt-only framework.

Expansion Pack Pattern: The repo follows BMAD's expansion-pack pattern — each pack has its own agents/, tasks/, templates/, and data/ subdirectories, and a pack-config.yaml that declares dependencies on the BMAD core.

Target Audience

Teams doing serious architecture work (cloud migrations, microservices design, data platform design) who want specialized expert personas rather than a single generalist AI architect.

02

Architecture

bmad-architecture-agent — Architecture

Distribution

  • Type: standalone-repo (BMAD expansion pack)
  • Install: npx bmad-method install (requires bmad-method npm package)
  • Runtime: None (content-only; agents are markdown files)
  • License: MIT

Directory Structure

bmad-architecture-agent/
├── .bmad-core/                    # BMAD core framework (installed via npm)
│   ├── agents/                    # Core BMAD agents (analyst, pm, architect, dev, qa, sm, ux-expert, bmad-master, bmad-orchestrator, po)
│   ├── tasks/                     # Core tasks (create-doc, create-next-story, etc.)
│   ├── templates/                 # Core templates
│   ├── checklists/                # Core checklists
│   ├── workflows/                 # Workflow definitions
│   ├── commands/                  # Core commands
│   └── core-config.yaml           # Project configuration
│
├── expansion-packs/
│   ├── cloud-architecture/        # Cloud Infrastructure Pack
│   │   ├── agents/                # Alex, Morgan, Taylor, Jordan
│   │   ├── tasks/
│   │   ├── templates/
│   │   ├── data/
│   │   └── pack-config.yaml
│   ├── data-architecture/         # Data Architecture Pack
│   │   ├── agents/                # Casey
│   │   └── ...
│   ├── integration-patterns/      # Integration Pack
│   │   ├── agents/                # River
│   │   └── ...
│   ├── platform-engineering/      # Platform Engineering Pack
│   │   ├── agents/                # Sam
│   │   └── ...
│   ├── architecture-governance/   # Governance Pack
│   │   ├── agents/                # Quinn
│   │   └── ...
│   ├── ai-nlp/                    # AI/NLP Pack
│   ├── document-processing/       # Document Processing Pack
│   └── report-generation/         # Report Generation Pack
│
├── .claude/                       # Claude Code agent config
├── docs/                          # Generated architecture artifacts
│   ├── requirements.md
│   ├── architecture.md
│   ├── data-architecture.md
│   ├── integration.md
│   ├── platform.md
│   ├── cost-analysis.md
│   ├── security-assessment.md
│   ├── governance.md
│   └── architecture/
│       ├── decisions/             # ADRs
│       ├── tech-radar.md
│       ├── standards/
│       └── reviews/
└── package.json                   # BMAD dependency

Target AI Tools

  • Claude Code (.claude/ directory present)
  • Claude.ai, Gemini, ChatGPT (model-agnostic markdown agents)

No Runtime Required

All agents are pure markdown + YAML persona definitions. No Node.js hooks, no MCP servers, no shell scripts.

03

Components

bmad-architecture-agent — Components

Core BMAD Agents (10 — inherited, in .bmad-core/agents/)

analyst, architect, bmad-master, bmad-orchestrator, dev, pm, po, qa, sm, ux-expert

Expansion Pack Agents (8 — new)

Cloud Infrastructure Pack (expansion-packs/cloud-architecture/agents/)

Agent Persona Name Specialization
infrastructure-analyst.md Alex Requirements gathering, feasibility, capacity planning
cloud-architect.md Morgan Multi-cloud solution design (AWS/Azure/GCP)
cost-optimizer.md Taylor FinOps, cost analysis, right-sizing
security-reviewer.md Jordan Security assessment, compliance, IAM

Data Architecture Pack (expansion-packs/data-architecture/agents/)

Agent Persona Name Specialization
data-architect.md Casey DB design, data modeling, ETL/ELT, governance

Integration Patterns Pack (expansion-packs/integration-patterns/agents/)

Agent Persona Name Specialization
integration-architect.md River REST/GraphQL/gRPC, messaging, event-driven

Platform Engineering Pack (expansion-packs/platform-engineering/agents/)

Agent Persona Name Specialization
platform-engineer.md Sam CI/CD, Kubernetes, IaC, GitOps, observability

Architecture Governance Pack (expansion-packs/architecture-governance/agents/)

Agent Persona Name Specialization
architecture-governor.md Quinn ADRs, tech radar, standards, technical debt

Additional Expansion Packs

3 more expansion packs with agents (ai-nlp, document-processing, report-generation) — agents not individually listed in README.

Templates (examples)

  • Cloud: infrastructure requirements, cost analysis, cloud architecture document, security assessment
  • Data: ERD, data dictionary, pipeline specification
  • Integration: API specification, event schema
  • Platform: CI/CD pipeline, Kubernetes manifest, IaC module
  • Governance: ADR, architecture review report, standards document

No Hooks, No Skills, No CLI

Zero hooks, zero skills (Claude Code skills format), zero CLI binaries. Pure content pack.

05

Prompts

bmad-architecture-agent — Prompts

Excerpt 1 — Cloud Architect (Morgan) Activation

From expansion-packs/cloud-architecture/agents/cloud-architect.md:

agent:
  name: Morgan
  id: cloud-architect
  title: Cloud Solutions Architect
  icon: ☁️
  whenToUse: Use for cloud solution design, service selection, architecture patterns, API design, and deployment strategies
  customization: null
persona:
  role: Multi-Cloud Solutions Architect & Platform Expert
  style: Pragmatic, platform-aware, best-practices focused, solution-oriented
  identity: Expert in designing cloud-native architectures across AWS, Azure, and GCP
  focus: Solution architecture, service selection, patterns, scalability, reliability, deployment
  core_principles:
    - Cloud-Native Design - Leverage managed services and platform capabilities
    - Right Tool for Job - Select services based on requirements, not preferences
    - Multi-Cloud Awareness - Understand service equivalents across platforms
    - Scalability by Design - Build systems that scale horizontally
    - Reliability Patterns - Implement resilience and fault tolerance
    - Cost-Conscious Architecture - Balance features with operational costs
    - Security in Depth - Layer security controls throughout architecture
    - Observability First - Design for monitoring and troubleshooting
    - Infrastructure as Code - Everything should be reproducible
    - Well-Architected Principles - Follow platform best practices
commands:
  - help: Show numbered list of the following commands
  - design: Execute architecture design using design-architecture task
  - select-services: Run cloud service selection for requirements
  - create-architecture-doc: Use create-doc with architecture-template

Prompting technique: Same BMAD YAML-in-markdown persona-md pattern with 10 explicit core_principles as instructional constraints. The whenToUse field gives Claude Code (and the Orchestrator) a routing hint.

Excerpt 2 — Activation Instructions (from cloud-architect.md)

activation-instructions:
  - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
  - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
  - STEP 3: Load and read `.bmad-core/core-config.yaml` before any greeting
  - STEP 4: Greet user with your name/role and immediately run `*help`
  - DO NOT: Load any other agent files during activation
  - CRITICAL: On activation, ONLY greet user, auto-run `*help`, and then HALT

Prompting technique: Numbered activation sequence with explicit DON'T rules and a mandatory HALT after greeting. This prevents the model from "helpfully" starting tasks before the user asks — a common problem with unbounded LLM agents.

09

Uniqueness

bmad-architecture-agent — Uniqueness & Positioning

differs_from_seeds

This is an expansion pack over the bmad-method seed that decomposes the generalist "Architect" agent role into 8 domain-specialist agents across 5 packs. The upstream seed has one architect.md (Winston); this repo replaces that with Morgan (cloud), Casey (data), River (integration), Sam (platform), Jordan (security), Taylor (cost), Alex (infra analyst), and Quinn (governance). The pattern is identical to BMAD's expansion pack system — the value is entirely in the content of the persona prompts, not in any new infrastructure primitive. Compared to superpowers (behavioral skills, auto-activation), this is a passive content pack: zero hooks, zero skills, zero CLI.

Key Positioning

  • Niche use case: teams doing architecture-heavy work (cloud migrations, multi-domain system design) who need specialized expert perspectives.
  • The governance pack (Quinn, ADRs, tech radar) is the most distinctive element not present in other BMAD ports or the seed.
  • Expansion pack pattern is well-documented, making it a good template for creating domain-specific BMAD packs.

Observable Failure Modes

  1. Single contributor, low stars: 15 stars, 1 contributor — effectively a solo personal project. Likely to become stale.
  2. No inter-agent coordination: Agents write to overlapping files (docs/architecture.md) — if two agents are active, they can clobber each other's output.
  3. BMAD dependency drift: If bmad-method releases a breaking change to the agent definition format, all 8 expansion pack agents will need manual updates.
  4. No task templates for expansion packs: Only agents are provided for some packs (ai-nlp, document-processing, report-generation lack fully populated tasks/templates).
  5. Documentation-only governance: Quinn writes ADRs but there is no enforcement mechanism — humans could ignore them without any system-level consequence.
04

Workflow

bmad-architecture-agent — Workflow

Overall Pattern

Inherits BMAD's 4-phase agile workflow (Analysis → Planning → Solutioning → Implementation) and extends the Solutioning phase with specialist architecture agents.

Architecture-Focused Sub-Workflow

  1. Requirements → Alex (Infrastructure Analyst) creates docs/requirements.md
  2. Cloud Design → Morgan (Cloud Architect) creates docs/architecture.md
  3. Cost Analysis → Taylor (Cost Optimizer) creates docs/cost-analysis.md
  4. Security Review → Jordan (Security Reviewer) creates docs/security-assessment.md
  5. Data Architecture → Casey creates docs/data-architecture.md
  6. Integration Design → River creates docs/integration.md
  7. Platform Engineering → Sam creates docs/platform.md
  8. Governance → Quinn maintains docs/architecture/decisions/, docs/architecture/tech-radar.md

Governance Artifacts

Artifact Location Owner
ADRs docs/architecture/decisions/ Quinn
Tech Radar docs/architecture/tech-radar.md Quinn
Standards docs/architecture/standards/ Quinn
Review Reports docs/architecture/reviews/ Quinn

Approval Gates (inherited from BMAD)

  • User must explicitly activate each specialist agent via *agent <name> or natural language routing.
  • Each agent presents findings and pauses for user input before generating final document.
  • BMAD step-file sequence: user selects Continue at each sub-step.

Artifacts Map

Phase Artifact
Requirements docs/requirements.md
Cloud Architecture docs/architecture.md
Cost Analysis docs/cost-analysis.md
Security docs/security-assessment.md
Data Architecture docs/data-architecture.md
Integration docs/integration.md
Platform docs/platform.md
Governance docs/governance.md, ADRs, tech-radar
06

Memory Context

bmad-architecture-agent — Memory & Context

Storage Pattern

File-based, project-scoped. All agent-generated artifacts land in docs/:

  • docs/requirements.md
  • docs/architecture.md
  • docs/cost-analysis.md
  • docs/security-assessment.md
  • docs/data-architecture.md
  • docs/integration.md
  • docs/platform.md
  • docs/governance.md
  • docs/architecture/decisions/ (ADRs)
  • docs/architecture/tech-radar.md

Context Injection

The BMAD core-config.yaml is loaded by each agent on activation (STEP 3: Load and read .bmad-core/core-config.yaml). This provides the project name, stack, and configuration to each specialist agent without requiring the user to re-state it.

Cross-Agent Continuity

Agents read each other's output files. For example:

  • Morgan (Cloud Architect) reads Alex's docs/requirements.md before designing the architecture.
  • Jordan (Security Reviewer) reads Morgan's docs/architecture.md to assess attack surfaces.
  • Quinn (Governance) reads all architecture docs to maintain the ADR register.

No Active Memory System

No SQLite, no vector DB, no Neo4j, no session state files. Memory = the docs/ directory. This is the BMAD Archetype 1 / Archetype 4 pattern: markdown files as the sole memory substrate.

Compaction Handling

Inherited from BMAD — agents load only their specific task file when executing a command, avoiding context overload. The NEVER load PRD/architecture/other docs unless explicitly directed rule from the dev agent applies here too.

07

Orchestration

bmad-architecture-agent — Orchestration

Multi-Agent Pattern

Yes — 8 specialized expansion pack agents + 10 BMAD core agents = 18 total agents.

Pattern: Sequential, human-directed handoffs. The user explicitly switches to each specialist for their domain. No automatic routing or orchestration beyond the BMAD Orchestrator's general *agent <name> command.

Subagent definition format: persona-md — each agent is a markdown file with embedded YAML persona definition (the BMAD standard).

Spawn mechanism: User invokes via *agent morgan or natural language. The BMAD Orchestrator interprets intent and switches context.

Isolation

None — all agents write to the same docs/ folder. No worktree, no container. Concurrent editing by multiple agents in the same session is not coordinated (no locking).

Multi-Model

No — single model, no per-role routing.

Execution Mode

interactive-loop — user drives each step. No autonomous background execution.

Consensus

None — single agent active at a time. Architecture reviews (Quinn) produce a review report for human judgment, not automated consensus.

Prompt Chaining

Yes — architect agents read each other's outputs:

  • Requirements → Cloud Design → Cost Analysis → Security Review is an explicit artifact chain.
  • Quinn's governance outputs (ADRs) reference all prior architecture docs.
08

Ui Cli Surface

bmad-architecture-agent — UI / CLI Surface

CLI Binary

None beyond npx bmad-method install (upstream BMAD installer). No dedicated binary for this expansion pack.

Local UI

None — terminal/chat only.

IDE Integration

.claude/ directory is present in the repo, suggesting Claude Code configuration files. No separate IDE extension.

Agent Invocation

All agents invoked via *agent <name> in any AI chat interface that has loaded the agent files. Supports:

  • Claude Code (.claude/ directory)
  • Claude.ai (paste the agent markdown)
  • Gemini (upload to Gem)
  • ChatGPT (Custom GPT with file upload)

Cross-Tool Portability

High — the agent definitions are plain markdown with YAML. Any AI assistant that can read markdown can use these agents. The only Claude Code–specific feature is the .claude/ directory config.

Observability

docs/architecture/decisions/ (ADR register) functions as a lightweight audit trail of architecture decisions. No structured log format; human-readable markdown only.

Related frameworks

same archetype · same primary tool · same memory type

OpenHarness ★ 13k
A11 Governance

Open-source Python agent runtime providing complete harness infrastructure: tools, memory, governance, swarm coordination, and…

Trae Agent ★ 12k
A11 Governance

Research-friendly open-source CLI coding agent by ByteDance, designed for academic ablation studies and modular LLM provider…

Sweep AI ★ 7.7k
A11 Governance

Autonomous GitHub bot that converts issues to pull requests using a sequential multi-agent pipeline.

Agent Governance Toolkit (microsoft) ★ 2.3k
A11 Governance

Enterprise-grade AI agent governance: YAML policy enforcement, 12-vector prompt injection defense, zero-trust identity,…

TDD Guard ★ 2.1k
A11 Governance

Mechanically enforces the Red-Green-Refactor TDD cycle by blocking file writes that violate TDD principles via a PreToolUse hook…

Agentic Coding Flywheel Setup (ACFS) ★ 1.5k
A11 Governance

Take a complete beginner from laptop to three AI coding agents running on a VPS in 30 minutes via an idempotent manifest-driven…