bmad-architecture

Produces an architecture spine of invariants and decisions distilled from specs, codebases, or raw ideas.

Updated Jul 2, 2026
One-click install
npx skills add https://github.com/tuanpa-nhg-eng/nhg-ipms --skill bmad-architecture-tuanpa-nhg-eng
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: bmad-architecture
Source: https://github.com/tuanpa-nhg-eng/nhg-ipms/tree/main/.claude/skills/bmad-architecture
Command: npx skills add https://github.com/tuanpa-nhg-eng/nhg-ipms --skill bmad-architecture-tuanpa-nhg-eng

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve? Software projects drift when independently built components make incompatible choices about boundaries, state mutation, data ownership, and stack versions. This Skill produces an architecture spine — a lean consistency contract that fixes only the non-obvious invariants, keeping everything built from it coherent without bloated documentation. ## Core Features & Use Cases - Architecture Spine Generation: Distills decisions into stable AD-n blocks (Binds/Prevents/Rule), a named design paradigm, consistency conventions, a pinned stack table, and mermaid structural diagrams, with an append-only memlog as working memory. - Coaching or Fast Path: Elicits decisions from the user through open-ended coaching by default, or drafts the full spine with [ASSUMPTION] tags for fast review. - Brownfield & Inherited Spines: Ratifies conventions from an existing codebase, or inherits a parent spine's ADs as read-only constraints when working at epic altitude. - Reviewer Gate: Runs a deterministic lint_spine.py pass plus parallel reviewer subagents against a good-spine checklist before handoff, with a standalone Validate intent producing an HTML report. - Use Case: Given a SPEC.md for a new feature, produce ARCHITECTURE-SPINE.md that fixes the paradigm, boundary rules, and pinned stack so multiple developers or agents build compatible modules. ## Quick Start Ask the assistant to create the architecture for your project or spec, and choose the Coaching path when prompted.

Frequently Asked Questions about bmad-architecture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a software architecture document from a spec?

Invoke the skill with your SPEC.md as input and it distills an ARCHITECTURE-SPINE.md containing a named paradigm, AD-n decision blocks, conventions, and a pinned stack table. Decisions are logged to an append-only memlog and the spine is distilled at finalize.

What is an architecture spine versus a full architecture document?

A spine fixes only the invariants that independently built units could diverge on — boundaries, state mutation, data ownership — while structural details stay as minimal seed. A fuller prose document is an optional rendering produced only when the audience needs it.

Can this skill derive architecture from an existing codebase?

Yes. For brownfield projects it reads the real code and project-context.md to ratify conventions already present rather than inventing new ones. The resulting spine documents what the code already shows plus the decisions it leaves open.

How does the Reviewer Gate validate an architecture spine?

The gate runs lint_spine.py for mechanical checks like duplicate AD IDs, missing Binds/Prevents/Rule fields, and unpinned stack versions, then dispatches parallel reviewer subagents against a good-spine checklist. Under the Validate intent it delivers a bespoke HTML report without changing the spine.

When should I not use bmad-architecture?

If the real ask is requirements, UX, a capability contract, or epic breakdown, the skill redirects to bmad-prd, bmad-ux, bmad-spec, or bmad-create-epics-and-stories instead. It also suggests running bmad-spec first when the input is too thin to build on.