bmad-architecture

Produces an architecture spine of invariants and decisions distilled from a memlog.

Updated Sep 3, 2026
One-click install
npx skills add https://github.com/watchthelight/shatterfish --skill bmad-architecture-watchthelight
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: bmad-architecture
Source: https://github.com/watchthelight/shatterfish/tree/main/.claude/skills/bmad-architecture
Command: npx skills add https://github.com/watchthelight/shatterfish --skill bmad-architecture-watchthelight

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve? Architecture work often drifts into bloated documents or inconsistent decisions across independently built components. This Skill produces a lean architecture spine that fixes only the invariants keeping downstream units consistent, recorded as stable AD-n decisions with a full audit trail. ## Core Features & Use Cases - Architecture Spine Generation: Distills decisions into an ARCHITECTURE-SPINE.md with paradigm, AD-n blocks (Binds/Prevents/Rule), stack pins, and mermaid diagrams, at initiative, feature, or epic altitude. - Coaching or Fast Path: Elicits decisions through open-ended coaching by default, or drafts the full spine with [ASSUMPTION] tags when speed is requested. - Reviewer Gate: Runs a deterministic lint_spine.py pass plus parallel reviewer subagents against a good-spine checklist before handoff, with a Validate intent producing an HTML report. - Use Case: Point it at a spec package or brownfield codebase and ask for the architecture; it resumes prior runs from the memlog, inherits parent spine constraints, and hands off to spec and epic-breakdown workflows. ## Quick Start Ask the assistant to create the architecture for your project using the bmad-architecture skill, providing your spec or codebase path.

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 with this skill?

Invoke the skill with your spec package, PRD, or codebase path and choose the Coaching path for guided elicitation or the Fast path for a full draft with [ASSUMPTION] tags. The result is an ARCHITECTURE-SPINE.md distilled from a memlog of decisions.

What is an architecture spine versus a full architecture document?

A spine fixes only the invariants that keep independently built units consistent: paradigm, boundaries, state mutation rules, and shared data ownership. Structural details are minimal seed; fuller prose documents are optional renderings produced at finalize.

Can it validate an existing architecture without changing it?

Yes, the Validate intent runs the Reviewer Gate against an existing spine without modifying it. It executes lint_spine.py plus reviewer subagents and delivers a bespoke HTML report of findings.

Does it work on brownfield codebases?

Yes, it investigates the real code and project-context.md before deciding, ratifying conventions already present rather than inventing new ones. Decisions already settled by reality are tagged [ADOPTED].

How does it handle parent architecture spines at epic altitude?

It loads the parent ARCHITECTURE-SPINE.md and treats its ADs and conventions as binding read-only constraints listed under Inherited Invariants. New decisions that contradict inherited ones are surfaced as conflicts, not overrides.

What are the limitations of the lint_spine.py check?

The linter only catches mechanical issues: placeholders, duplicate or non-monotonic AD IDs, missing Binds/Prevents/Rule fields, and unpinned Stack versions. Semantic quality, such as whether a Rule is enforceable, is left to the reviewer subagents.