Diagram-Based Workflow (dbw)

A diagram-first documentation and architecture-planning module for the BMad Method.

diagram-based-workflow makes the diagram the primary medium of communication between engineers and AI coding agents. System understanding, feature planning, and codebase modifications happen visually through Mermaid diagrams organized by the C4 model, paired with concise text for rationale, trade-offs, and cost drivers.

              DIAGRAM FIRST
                   │
        ┌──────────┴──────────┐
        ↓                     ↓
 DOCUMENTATION         PLANNING-WORKFLOW
 (Understand system)   (Design new changes)
        │                     │
        └──────────┬──────────┘
                   ↓
               ARCHITECT
       (Map design ↔ code)
                   ↓
             CODING AGENT
          (Implement code)
                   ↓
        Verify & Update Docs

---

Installation via GitHub

To install this module directly into your BMad project from GitHub:

# In your project root
npx bmad install https://github.com/Glitch_guy0/diagram-based-workflow

Or run the setup skill within your AI assistant / IDE:

/dbw-setup

---

Core Philosophy

1. Diagram is the Primary Medium

• Diagram → WHAT / WHERE / CONNECTIONS / FLOW
• Text → WHY / RULES / CONSTRAINTS / TRADE-OFFS / COST
• Code → ACTUAL IMPLEMENTATION

2. Three Fundamental Questions

Every project documented with this module answers three questions:

1. How does the system work? (System Context, Containers, Sequence, Flows, States)
2. How is the code structured & integrated? (Components, Code, Integrations, Adapters)
3. What decisions were made and why? (ADRs, trade-offs, cost drivers)

3. Separation of Planning vs Approved Documentation

• {planning_artifacts}/ (default: _bmad-output/planning-artifacts/): Work-in-progress drafts, proposed diagrams, iterative plans.
• {project_knowledge}/ (default: docs/): Authoritative, approved, and verified system documentation structured by C4 hierarchy.

---

Skills in this Module

Skill	Menu Code	Description
dbw-setup	[SU]	Configures module paths (docs/, _bmad-output/planning-artifacts/, docs/decisions/) and registers capabilities in BMad.
dbw-documentation	[DS]	Work Sequence A: Maps existing systems into C4 diagrams, behavioral flows, and linked ADRs.
dbw-documentation	[VS]	Verifies synchronization between Mermaid diagrams and active source code to detect drift.
dbw-planning-workflow	[PW]	Work Sequence B: Guides diagram-first planning with Architect impact analysis, cost evaluations, and implementation plans in {planning_artifacts}/.
dbw-planning-workflow	[PD]	Promotes verified planning diagrams and decisions from {planning_artifacts}/ into docs/.

---

C4 Documentation Structure

Approved project documentation follows the standard C4 hierarchy:

docs/
├── c4/
│   ├── system-context.mmd       # Level 1: System Context (Actors, Systems, Boundaries)
│   ├── containers.mmd           # Level 2: Containers (Deployable units, services, DBs, queues)
│   ├── components/              # Level 3: Components (Scoped per container)
│   │   └── <container>.mmd
│   └── code/                    # Level 4: Code (Selective domain/module structures)
│       └── <subject>.mmd
│
├── flows/                       # Behavioral diagrams
│   ├── sequence-<flow>.mmd      # Chronological interactions
│   ├── flowchart-<flow>.mmd     # Decision branching & process logic
│   └── state-<object>.mmd       # Lifecycle state transitions
│
├── integrations/                # Third-party integrations & boundary adapters
│   └── <integration>.mmd
│
├── decisions/                   # Architecture Decision Records (ADRs)
│   └── ADR-<number>-<title>.md  # Linked to diagram nodes
│
└── indexes/
    └── diagram-index.md         # Master catalog & source-of-truth matrix

---

Workflows

Sequence A: Documenting an Existing System ([DS])

1. Inspect codebase and existing documentation.
2. Select diagram type using One Diagram = One Question rule.
3. Author canonical .mmd diagram in docs/.
4. Document significant decisions in docs/decisions/ADR-xxx.md.
5. Update docs/indexes/diagram-index.md.

Sequence B: Planning Architectural Changes ([PW])

1. Create or edit diagram in {planning_artifacts}/ (e.g. _bmad-output/planning-artifacts/).
2. Architect analyzes diagram diff against current codebase.
3. Architect maps affected C4 levels, flows, and boundaries.
4. Evaluate cost drivers (infrastructure, vendor, operations).
5. Generate step-by-step Implementation Plan.
6. User reviews and approves.
7. Coding agent implements changes.
8. Promote approved diagrams into docs/ ([PD]).

---

Role Coordination

The module coordinates two core BMad capabilities:

• architect (Diana / Winston): Owns architectural reasoning, system decomposition, boundary rules, code mapping, impact analysis, and cost/trade-off identification.
• technical-writer: Maintains concise supporting documentation, ADRs, indexes, and source-of-truth references.

Customization via _bmad/custom/

You can customize DBW behaviors and agents:

• Module & Agent Overrides: Edit _bmad/custom/config.toml (e.g. under [modules.dbw] or [agents.dbw-agent-architect]).
• Skill Overrides: Create _bmad/custom/dbw-documentation.toml, _bmad/custom/dbw-planning-workflow.toml, or _bmad/custom/dbw-setup.toml (personal overrides use .user.toml).

---

License & Contributing

Part of the BMad ecosystem. Open source and customizable via _bmad/custom/.