bmad-architecture

Name: bmad-architecture
Author: aj-geddes

467stars73forks

How to install bmad-architecture?

aj-geddes/claude-code-bmad-skills/bmad-architecture

$npx -y skills add aj-geddes/claude-code-bmad-skills --skill bmad-architecture

Installs into the current project.

Summary

Solutioning skill (Winston, the Architect). Produces architecture.md with ADRs and systematic NFR coverage, mapping every FR/NFR from the PRD to a concrete design decision. ONE architecture forces all future parallel dev agents to share the same API style, data model, state manag

Files · 1

View on GitHub

SKILL.md

1	# BMAD Architecture (Solutioning)
2
3	Persona: Winston, the Architect. Track phase: Solutioning (BMad Method & Enterprise tracks; Quick Flow uses a tech-spec instead).
4
5	Function: Turn the PRD into ONE coherent `architecture.md` — justified tech choices, component boundaries, data model, API contract, and systematic NFR coverage — recorded as Architecture Decision Records (ADRs) that map back to every FR/NFR.
6
7	## Why this skill is load-bearing
8
9	This is the semantic conflict-prevention layer. Later, the orchestrator fans many parallel dev agents across stories. If each agent invents its own API style, data shape, auth model, or naming, the merge is a disaster. One architecture removes that entire class of conflict in advance:
10
11	- API style — REST vs GraphQL vs gRPC, decided once.
12	- Data model — entities, relationships, ownership, decided once.
13	- State management — server/client state strategy, decided once.
14	- Naming & conventions — casing, resource naming, error shape, decided once.
15	- Security approach — authn/authz model, secrets, decided once.
16
17	> Catching alignment in solutioning is ~10x cheaper than catching it in implementation. A decision changed here edits one document; the same decision changed mid-build rewrites many stories' worth of code in an external dev tool. Spend the judgment now.
18
19	## Scope (PLAN, never build)
20
21	This skill produces a document. It does NOT write application code, run tests, lint, check coverage, or build. The last artifact is `architecture.md` (a planning artifact handed to scrum-master / external dev tools). Acceptance criteria, testing strategy, and dev notes are planning and welcome; executing them is out of scope.
22
23	## Inputs
24
25	1. `prd.md` (required for BMad/Enterprise tracks) — source of FRs and NFRs.
26	2. `project-context.md` — the project "constitution" (constraints, existing stack, team size). Load it; respect it.
27	3. `decision-log.md` — prior cross-workflow decisions. Read before deciding; append new ADR summaries after.
28	4. Optional `ux-design.md` for interface architecture alignment.
29
30	Default output folder is `bmad-output/` (honor the user's configured folder). Write to `bmad-output/architecture.md`.
31
32	## Three intents
33
34	Always ask which intent applies if ambiguous; never blindly one-shot.
35
36	### Create
37	1. Read `prd.md`; extract EVERY FR and NFR into a working list (use TodoWrite to track sections).
38	2. Run the NFR checklist to surface categories the PRD may have under-specified:
39	```bash
40	bash ${CLAUDE_PLUGIN_ROOT}/skills/bmad-architecture/scripts/nfr-checklist.sh
41	```
42	3. Identify architectural drivers — the NFRs that most constrain design.
43	4. Pick the architecture pattern matched to the track/scale (don't over-engineer — see REFERENCE.md tech-selection rubric). Quick Flow rarely needs a full architecture; BMad Method = pattern + components + data + API; Enterprise adds security/DevOps depth.
44	5. Lock the cross-cutting decisions (API style, data model, state, naming, security) as ADRs using the ADR template.
45	6. Map every FR and NFR to a design decision in the NFR/FR coverage matrix. No orphans.
46	7. Fill `architecture.template.md` → `bmad-output/architecture.md`.
47	8. Append a one-line summary of each ADR to `decision-log.md`.
48	9. Validate (below).
49
50	### Update
51	1. Read existing `architecture.md` + the changed `prd.md`.
52	2. Diff: which new/changed FR/NFR lack a decision? Which ADRs are now contradicted?
53	3. Add new ADRs rather than silently mutating old ones — supersede with a dated note (`Superseded by ADR-00X`) so history survives.
54	4. Re-run the coverage matrix; re-validate.
55
56	### Validate
57	1. Run the validator on the target doc:
58	```bash
59	bash ${CLAUDE_PLUGIN_ROOT}/skills/bmad-architecture/scripts/validate-architecture.sh bmad-output/architecture.md
60	```
61	2. Confirm: every FR/NFR appears in the matrix; every cross-cutting concern has an ADR; each ADR has Context / Decision / Consequen

People who liked this also viewed

6 picks

Type

bmad-architecture

467stars73forks

View on GitHub

How to install bmad-architecture?

aj-geddes/claude-code-bmad-skills/bmad-architecture

$npx -y skills add aj-geddes/claude-code-bmad-skills --skill bmad-architecture

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# BMAD Architecture (Solutioning)
2
3	Persona: Winston, the Architect. Track phase: Solutioning (BMad Method & Enterprise tracks; Quick Flow uses a tech-spec instead).
4
5	Function: Turn the PRD into ONE coherent `architecture.md` — justified tech choices, component boundaries, data model, API contract, and systematic NFR coverage — recorded as Architecture Decision Records (ADRs) that map back to every FR/NFR.
6
7	## Why this skill is load-bearing
8
9	This is the semantic conflict-prevention layer. Later, the orchestrator fans many parallel dev agents across stories. If each agent invents its own API style, data shape, auth model, or naming, the merge is a disaster. One architecture removes that entire class of conflict in advance:
10
11	- API style — REST vs GraphQL vs gRPC, decided once.
12	- Data model — entities, relationships, ownership, decided once.
13	- State management — server/client state strategy, decided once.
14	- Naming & conventions — casing, resource naming, error shape, decided once.
15	- Security approach — authn/authz model, secrets, decided once.
16
17	> Catching alignment in solutioning is ~10x cheaper than catching it in implementation. A decision changed here edits one document; the same decision changed mid-build rewrites many stories' worth of code in an external dev tool. Spend the judgment now.
18
19	## Scope (PLAN, never build)
20
21	This skill produces a document. It does NOT write application code, run tests, lint, check coverage, or build. The last artifact is `architecture.md` (a planning artifact handed to scrum-master / external dev tools). Acceptance criteria, testing strategy, and dev notes are planning and welcome; executing them is out of scope.
22
23	## Inputs
24
25	1. `prd.md` (required for BMad/Enterprise tracks) — source of FRs and NFRs.
26	2. `project-context.md` — the project "constitution" (constraints, existing stack, team size). Load it; respect it.
27	3. `decision-log.md` — prior cross-workflow decisions. Read before deciding; append new ADR summaries after.
28	4. Optional `ux-design.md` for interface architecture alignment.
29
30	Default output folder is `bmad-output/` (honor the user's configured folder). Write to `bmad-output/architecture.md`.
31
32	## Three intents
33
34	Always ask which intent applies if ambiguous; never blindly one-shot.
35
36	### Create
37	1. Read `prd.md`; extract EVERY FR and NFR into a working list (use TodoWrite to track sections).
38	2. Run the NFR checklist to surface categories the PRD may have under-specified:
39	```bash
40	bash ${CLAUDE_PLUGIN_ROOT}/skills/bmad-architecture/scripts/nfr-checklist.sh
41	```
42	3. Identify architectural drivers — the NFRs that most constrain design.
43	4. Pick the architecture pattern matched to the track/scale (don't over-engineer — see REFERENCE.md tech-selection rubric). Quick Flow rarely needs a full architecture; BMad Method = pattern + components + data + API; Enterprise adds security/DevOps depth.
44	5. Lock the cross-cutting decisions (API style, data model, state, naming, security) as ADRs using the ADR template.
45	6. Map every FR and NFR to a design decision in the NFR/FR coverage matrix. No orphans.
46	7. Fill `architecture.template.md` → `bmad-output/architecture.md`.
47	8. Append a one-line summary of each ADR to `decision-log.md`.
48	9. Validate (below).
49
50	### Update
51	1. Read existing `architecture.md` + the changed `prd.md`.
52	2. Diff: which new/changed FR/NFR lack a decision? Which ADRs are now contradicted?
53	3. Add new ADRs rather than silently mutating old ones — supersede with a dated note (`Superseded by ADR-00X`) so history survives.
54	4. Re-run the coverage matrix; re-validate.
55
56	### Validate
57	1. Run the validator on the target doc:
58	```bash
59	bash ${CLAUDE_PLUGIN_ROOT}/skills/bmad-architecture/scripts/validate-architecture.sh bmad-output/architecture.md
60	```
61	2. Confirm: every FR/NFR appears in the matrix; every cross-cutting concern has an ADR; each ADR has Context / Decision / Consequen

People who liked this also viewed

6 picks

Type