playbooks

home / skills / bacoco / bmad-skills / bmad-architecture-design

bmad-architecture-design skill

/.claude/skills/bmad-architecture-design

This skill converts approved product requirements into a decision architecture outlining components, tech choices, and rationale for implementation teams.

npx playbooks add skill bacoco/bmad-skills --skill bmad-architecture-design

Review the files below or copy the command above to add this skill to your agents.

Files (6)
SKILL.md
3.3 KB
---
name: bmad-architecture-design
description: Creates technical architecture and system design.
allowed-tools: ["Read", "Write", "Grep"]
metadata:
  auto-invoke: true
  triggers:
    patterns:
      - "how should we build"
      - "what's the architecture"
      - "tech stack"
      - "system design"
      - "how to build this"
    keywords:
      - architecture
      - design
      - system
      - build
      - technical
      - structure
      - stack
  capabilities:
    - architecture-design
    - tech-stack-selection
    - system-design
    - decision-documentation
  prerequisites:
    - product-requirements-document
  outputs:
    - architecture-decisions
    - system-design-doc
    - tech-stack-rationale
---

# Architecture Design Skill

## When to Invoke

**Automatically activate when user:**
- Says "How should we build this?", "What's the architecture?"
- Asks "Tech stack?", "System design?", "How to architect?"
- Mentions "architecture", "technical decisions", "stack"
- PRD and epics are approved (Phase 3)
- Uses words like: architecture, tech stack, design, system, build, technical

**Specific trigger phrases:**
- "How should we build this?"
- "What's the architecture?"
- "Choose tech stack"
- "System design for [project]"
- "Technical architecture"
- "How to architect [feature]"

**Prerequisites:**
- PRD exists and approved
- Epics defined

**Do NOT invoke when:**
- PRD not ready (use bmad-product-planning first)
- Already have architecture (skip to stories)
- Simple Level 0-1 project (may not need formal architecture)

## Mission
Convert approved product requirements into a Decision Architecture that communicates component structure, technology choices, and rationale for implementation teams.

## Inputs Required
- prd: latest PRD plus epic roadmap from product-requirements skill
- constraints: non-functional requirements, compliance rules, and integrations
- existing_assets: repositories, current architecture diagrams, or technology standards
- project_level: BMAD level sizing to guide depth of design

Missing inputs must be escalated to the orchestrator or originating skill before work proceeds.

## Outputs
- `ARCHITECTURE.md` written using `assets/decision-architecture-template.md.template`
- Updated risk and decision log entries summarized for stakeholders

Deliverables should highlight decisions, rejected options, and implementation guardrails.

## Process
1. Validate prerequisites via `CHECKLIST.md` and confirm planning artifacts are approved.
2. Identify architecture drivers (quality attributes, constraints, integrations).
3. Design component topology, data flows, and technology selections with traceability to requirements.
4. Record key decisions, alternatives, and mitigation strategies.
5. Generate or update architecture artifact using `scripts/generate_architecture.py` if structured data is available.
6. Review the quality checklist and publish summary plus follow-up actions for delivery-planning and development-execution skills.

## Quality Gates
Follow `CHECKLIST.md` to ensure completeness, feasibility, and stakeholder alignment. Stop if guardrails fail.

## Error Handling
When contradictions or gaps exist:
- Cite the specific requirement or assumption causing the conflict.
- Request clarifications from product-requirements, UX, or discovery-analysis skills.
- Recommend holding implementation until resolution is documented.

Overview

This skill converts approved product requirements and epics into a clear, actionable technical architecture and system design. It produces a decision-focused architecture artifact, documents key decisions and risks, and provides implementation guardrails for delivery teams. The output is traceable to requirements and highlights selected technologies, rejected alternatives, and next steps for execution.

How this skill works

The skill validates prerequisites (approved PRD and epics) and gathers constraints, existing assets, and project level to identify architecture drivers. It designs component topology, data flows, and technology selections, records decisions and alternatives, and generates a structured ARCHITECTURE.md plus a summarized risk and decision log. If inputs are incomplete or contradictory, it escalates for clarification and pauses until issues are resolved.

When to use it

  • You have an approved PRD and defined epics and need a decision-level architecture.
  • You need a traceable technology selection and component topology for implementation teams.
  • Preparing for Phase 3 delivery planning or wanting to handoff to engineering with clear guardrails.
  • Evaluating architecture trade-offs under constraints like compliance, performance, or integrations.
  • When existing architecture is outdated and requires a documented redesign.

Best practices

  • Ensure the PRD, epics, and non-functional requirements are final before starting.
  • Provide existing assets (repos, diagrams, standards) to avoid redundant analysis.
  • Capture architecture drivers up front: quality attributes, constraints, and integrations.
  • Document rejected options and rationale to prevent rework and support audits.
  • Run the architecture through the quality checklist and get stakeholder signoff before implementation.

Example use cases

  • Design microservice topology, API boundaries, and data flow for a new SaaS product.
  • Choose a cloud-native stack and deployment model with cost, scalability, and compliance trade-offs.
  • Translate integration and compliance constraints into concrete middleware and security controls.
  • Produce a decision architecture for a platform consolidation or migration project.
  • Create implementation guardrails and a risk log for a cross-team rollout.

FAQ

What inputs are required to start?

An approved PRD, epic roadmap, non-functional requirements, and available existing assets (repos, diagrams, standards). Missing inputs will be escalated.

What if requirements conflict?

The skill will cite the conflicting requirement or assumption, request clarification from the responsible stakeholder, and recommend pausing implementation until resolved.