# bmad-code-org/bmad-method architecture

> Architecture diagram of the GitHub repository bmad-code-org/bmad-method, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bmad-code-org/bmad-method
- Repository: https://github.com/bmad-code-org/bmad-method

## Overview

BMad Method is a skill-based AI-assisted software delivery method: users invoke skills in a coding tool to clarify work, plan as needed, build, review, and learn. The repository also contains BMad setup/configuration scripts, skill-evaluation runners, and an Astro documentation site. The README documents the delivery workflow; source excerpts show selected script behavior and explicit imports. Several skill workflows are not represented in the supplied tree, so their implementation links are limited to existing directories and documented relationships.

Main entry points: [`docs-site/astro.config.mjs`](https://github.com/bmad-code-org/bmad-method/blob/main/docs-site/astro.config.mjs) (Site configuration), [`skills/bmad`](https://github.com/bmad-code-org/bmad-method/tree/main/skills/bmad) (Build and review), [`skills/bmad-architecture`](https://github.com/bmad-code-org/bmad-method/tree/main/skills/bmad-architecture) (Plan change), [`skills/bmad-brainstorming`](https://github.com/bmad-code-org/bmad-method/tree/main/skills/bmad-brainstorming) (Clarify work)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_delivery["Delivery method"]
  node_clarify["Clarify work"]
  node_existing["Recon codebase"]
  node_plan["Plan change"]
  node_build["Build and review"]
  node_learn["Retrospective"]
end

subgraph group_support["Setup and context"]
  node_render["Render skill snapshot<br/>[render_skill.py]"]
  node_setup["Project setup<br/>[setup.py]"]
  node_knowledge["Method knowledge<br/>[knowledge.py]"]
end

subgraph group_evaluation["Skill evaluation"]
  node_eval_runner["Case evaluator<br/>[run_evals.py]"]
  node_trigger_runner["Trigger evaluator<br/>[run_triggers.py]"]
  node_eval_common["Evaluation harness<br/>[eval_common.py]"]
end

subgraph group_docs["Documentation site"]
  node_astro["Site configuration<br/>[astro.config.mjs]"]
  node_inline["Inline diagrams"]
  node_diagram_cache["Diagram cache<br/>[diagrams.js]"]
  node_markdown_links["Markdown links"]
  node_base_paths["Base paths"]
  node_site_url["Site URL<br/>[site-url.mjs]"]
end

node_user(("Developer"))
node_software["Working software"]
node_docs_reader(("Documentation reader"))

node_user -->|"invokes when unclear"| node_clarify
node_user -->|"starts with existing code"| node_existing
node_user -->|"plans larger work"| node_plan
node_user -->|"invokes build"| node_build
node_user -->|"adjusts from learning"| node_learn
node_clarify -.->|"informs planning"| node_plan
node_plan -->|"guides implementation"| node_build
node_build -->|"delivers changes"| node_software
node_build -->|"feeds learning"| node_learn
node_user -->|"runs setup"| node_setup
node_setup -.->|"refreshes skill snapshot"| node_render
node_render -->|"uses configuration context"| node_knowledge
node_user -->|"runs case evaluations"| node_eval_runner
node_user -->|"runs trigger checks"| node_trigger_runner
node_eval_runner -->|"uses harness"| node_eval_common
node_trigger_runner -->|"uses harness"| node_eval_common
node_astro -->|"resolves site URL"| node_site_url
node_astro -->|"registers plugin"| node_inline
node_astro -->|"registers plugin"| node_markdown_links
node_astro -->|"registers plugin"| node_base_paths
node_astro -->|"registers integration"| node_diagram_cache
node_docs_reader -.->|"reads generated guidance"| node_astro

click node_clarify "https://github.com/bmad-code-org/bmad-method/tree/main/skills/bmad-brainstorming"
click node_existing "https://github.com/bmad-code-org/bmad-method/tree/main/skills/bmad-deep-recon"
click node_plan "https://github.com/bmad-code-org/bmad-method/tree/main/skills/bmad-architecture"
click node_build "https://github.com/bmad-code-org/bmad-method/tree/main/skills/bmad"
click node_learn "https://github.com/bmad-code-org/bmad-method/tree/main/skills/bmad-retrospective"
click node_render "https://github.com/bmad-code-org/bmad-method/blob/main/skills/bmad/scripts/render_skill.py"
click node_setup "https://github.com/bmad-code-org/bmad-method/blob/main/skills/bmad/scripts/setup.py"
click node_knowledge "https://github.com/bmad-code-org/bmad-method/blob/main/skills/bmad/scripts/knowledge.py"
click node_eval_runner "https://github.com/bmad-code-org/bmad-method/blob/main/skills/bmad-eval/scripts/run_evals.py"
click node_trigger_runner "https://github.com/bmad-code-org/bmad-method/blob/main/skills/bmad-eval/scripts/run_triggers.py"
click node_eval_common "https://github.com/bmad-code-org/bmad-method/blob/main/skills/bmad-eval/scripts/eval_common.py"
click node_astro "https://github.com/bmad-code-org/bmad-method/blob/main/docs-site/astro.config.mjs"
click node_inline "https://github.com/bmad-code-org/bmad-method/blob/main/docs-site/src/rehype-inline-diagrams.js"
click node_diagram_cache "https://github.com/bmad-code-org/bmad-method/blob/main/docs-site/src/integrations/diagrams.js"
click node_markdown_links "https://github.com/bmad-code-org/bmad-method/blob/main/docs-site/src/rehype-markdown-links.js"
click node_base_paths "https://github.com/bmad-code-org/bmad-method/blob/main/docs-site/src/rehype-base-paths.js"
click node_site_url "https://github.com/bmad-code-org/bmad-method/blob/main/docs-site/src/lib/site-url.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_clarify,node_existing,node_plan,node_build,node_learn toneBlue
class node_render,node_setup,node_knowledge toneAmber
class node_eval_runner,node_trigger_runner,node_eval_common toneMint
class node_astro,node_inline,node_diagram_cache,node_markdown_links,node_base_paths,node_site_url toneRose
class node_user,node_software,node_docs_reader toneIndigo
```

## Components

### Delivery method

- [Clarify work](https://github.com/bmad-code-org/bmad-method/tree/main/skills/bmad-brainstorming): `skills/bmad-brainstorming`
- [Recon codebase](https://github.com/bmad-code-org/bmad-method/tree/main/skills/bmad-deep-recon): `skills/bmad-deep-recon`
- [Plan change](https://github.com/bmad-code-org/bmad-method/tree/main/skills/bmad-architecture): `skills/bmad-architecture`
- [Build and review](https://github.com/bmad-code-org/bmad-method/tree/main/skills/bmad): `skills/bmad`
- [Retrospective](https://github.com/bmad-code-org/bmad-method/tree/main/skills/bmad-retrospective): `skills/bmad-retrospective`

### Setup and context

- [Render skill snapshot](https://github.com/bmad-code-org/bmad-method/blob/main/skills/bmad/scripts/render_skill.py): `skills/bmad/scripts/render_skill.py`
- [Project setup](https://github.com/bmad-code-org/bmad-method/blob/main/skills/bmad/scripts/setup.py): `skills/bmad/scripts/setup.py`
- [Method knowledge](https://github.com/bmad-code-org/bmad-method/blob/main/skills/bmad/scripts/knowledge.py): `skills/bmad/scripts/knowledge.py`

### Skill evaluation

- [Case evaluator](https://github.com/bmad-code-org/bmad-method/blob/main/skills/bmad-eval/scripts/run_evals.py): `skills/bmad-eval/scripts/run_evals.py`
- [Trigger evaluator](https://github.com/bmad-code-org/bmad-method/blob/main/skills/bmad-eval/scripts/run_triggers.py): `skills/bmad-eval/scripts/run_triggers.py`
- [Evaluation harness](https://github.com/bmad-code-org/bmad-method/blob/main/skills/bmad-eval/scripts/eval_common.py): `skills/bmad-eval/scripts/eval_common.py`

### Documentation site

- [Site configuration](https://github.com/bmad-code-org/bmad-method/blob/main/docs-site/astro.config.mjs): `docs-site/astro.config.mjs`
- [Inline diagrams](https://github.com/bmad-code-org/bmad-method/blob/main/docs-site/src/rehype-inline-diagrams.js): `docs-site/src/rehype-inline-diagrams.js`
- [Diagram cache](https://github.com/bmad-code-org/bmad-method/blob/main/docs-site/src/integrations/diagrams.js): `docs-site/src/integrations/diagrams.js`
- [Markdown links](https://github.com/bmad-code-org/bmad-method/blob/main/docs-site/src/rehype-markdown-links.js): `docs-site/src/rehype-markdown-links.js`
- [Base paths](https://github.com/bmad-code-org/bmad-method/blob/main/docs-site/src/rehype-base-paths.js): `docs-site/src/rehype-base-paths.js`
- [Site URL](https://github.com/bmad-code-org/bmad-method/blob/main/docs-site/src/lib/site-url.mjs): `docs-site/src/lib/site-url.mjs`

### Other components

- **Developer**
- **Working software**
- **Documentation reader**

## Connections

- Developer → Clarify work: invokes when unclear
- Developer → Recon codebase: starts with existing code
- Developer → Plan change: plans larger work
- Developer → Build and review: invokes build
- Developer → Retrospective: adjusts from learning
- Clarify work → Plan change: informs planning
- Plan change → Build and review: guides implementation
- Build and review → Working software: delivers changes
- Build and review → Retrospective: feeds learning
- Developer → Project setup: runs setup
- Project setup → Render skill snapshot: refreshes skill snapshot
- Render skill snapshot → Method knowledge: uses configuration context (evidence: `skills/bmad/scripts/render_skill.py`)
- Developer → Case evaluator: runs case evaluations (evidence: `skills/bmad-eval/scripts/run_evals.py`)
- Developer → Trigger evaluator: runs trigger checks (evidence: `skills/bmad-eval/scripts/run_triggers.py`)
- Case evaluator → Evaluation harness: uses harness (evidence: `skills/bmad-eval/scripts/run_evals.py`)
- Trigger evaluator → Evaluation harness: uses harness (evidence: `skills/bmad-eval/scripts/run_triggers.py`)
- Site configuration → Site URL: resolves site URL (evidence: `docs-site/astro.config.mjs`)
- Site configuration → Inline diagrams: registers plugin (evidence: `docs-site/astro.config.mjs`)
- Site configuration → Markdown links: registers plugin (evidence: `docs-site/astro.config.mjs`)
- Site configuration → Base paths: registers plugin (evidence: `docs-site/astro.config.mjs`)
- Site configuration → Diagram cache: registers integration (evidence: `docs-site/astro.config.mjs`)
- Documentation reader → Site configuration: reads generated guidance
