bmad-architecture

Create, update, and validate architecture spine documents recording system design decisions.

1|Updated Sep 18, 2026
One-click install
npx skills add https://github.com/PastaSus/egg-defender --skill bmad-architecture-pastasus
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: bmad-architecture
Source: https://github.com/PastaSus/egg-defender/tree/main/.agents/skills/bmad-architecture
Command: npx skills add https://github.com/PastaSus/egg-defender --skill bmad-architecture-pastasus

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve? Teams building a system in separate parts drift apart on boundaries, state mutation, and shared data ownership. This Skill produces a terse architecture spine that fixes only the invariants keeping independently built units consistent, so downstream builders cannot diverge. ## Core Features & Use Cases - Architecture spine authoring: Create a decision-focused ARCHITECTURE-SPINE.md with stable AD-n entries (Binds/Prevents/Rule), a named design paradigm, a pinned stack table, and mermaid structural diagrams, working from a spec, a raw idea, or an existing codebase. - Coaching or fast drafting: Elicit decisions through open-ended coaching questions, or draft the full spine quickly with [ASSUMPTION] tags for review. - Deterministic review gate: Lint the spine for placeholders, duplicate AD IDs, missing fields, and unpinned versions, then run parallel reviewer subagents before handoff. - Use Case: Point it at a brownfield codebase and ask it to derive an architecture spine; it ratifies the conventions the code already shows, logs every decision to an append-only memlog, and distills a validated spine document. ## Quick Start Ask the assistant to create the technical architecture for your project from your spec or existing codebase, choosing the coaching path to work through the decisions together.

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 technical architecture document from a spec?

Invoke the skill with your spec package and it elicits the load-bearing decisions through coaching questions, logging each to a memlog. It then distills an ARCHITECTURE-SPINE.md with AD-n decision blocks, a pinned stack table, and mermaid diagrams.

How do I derive an architecture from an existing codebase?

Point the skill at the brownfield codebase and it investigates the real code to ratify existing conventions rather than inventing new ones. The resulting spine records only the invariants a future builder could not read off compliant code.

What is an architecture spine versus a full architecture document?

A spine fixes only the non-obvious decisions where two independent builders could diverge, such as boundaries, state mutation, and shared data ownership. Structural details like the full tree and data shapes are treated as seed owned by the code once it exists.

Can I validate an existing architecture document without changing it?

Yes, the Validate intent runs the reviewer gate against an existing spine without modifying it. It runs the lint_spine.py deterministic checks plus reviewer lenses and delivers a bespoke HTML report of findings.

What does the spine linter check for?

The lint_spine.py script checks for placeholder markers like TBD, duplicate or non-monotonic AD-n identifiers, AD blocks missing Binds/Prevents/Rule fields, and Stack table rows without pinned versions. Findings are reported as JSON with file line numbers.

When should I not use an architecture spine workflow?

If the real need is requirements, UX, a capability contract, or epic breakdown, the skill routes you to the appropriate PRD, UX, spec, or epic-creation skill instead. A spine only makes sense once there is enough input to decide invariants from.