24 KiB

Raw Blame History

BMAD-METHOD Best Practices Summary

Learned from Analyzing the BMAD-METHOD Repository

This document summarizes key best practices and patterns discovered in the BMAD-METHOD codebase that you can apply to your own projects and AI collaboration workflows.

1. Agent Design Patterns

Persona-Driven Agents

Every BMAD agent has a well-defined persona with:

persona:
  role: "Specific role + expertise area"
  identity: "Years of experience + domain expertise"
  communication_style: "How they interact"
  principles: "Core beliefs that guide decisions"

Why this works:

Creates consistent agent behavior
Sets clear expectations for users
Makes agents feel like real experts
Guides decision-making through principles

Apply to your agents:

## Agent: Security Auditor

**Role:** Application Security Expert + Penetration Tester
**Identity:** 10+ years securing enterprise applications, CISSP certified
**Style:** Paranoid but practical. Questions everything. Risk-focused.
**Principles:**
- Trust nothing, verify everything
- Defense in depth
- Fail securely
- Security is everyone's job

BMAD agents present numbered menus of available workflows:

Welcome! I'm John, your Product Manager.

Available workflows:
1. *workflow-init - Start a new project
2. *create-prd - Create PRD
3. *create-epics-and-stories - Break down into stories
4. *party-mode - Multi-agent collaboration

Type a number, shortcut (*prd), or ask naturally.

Why this works:

Discoverability - users see all capabilities
Multiple interaction modes (number, shortcut, natural language)
Reduces cognitive load - clear options
Self-documenting - menu IS the documentation

Apply to your agents:

Always start with a menu introduction
Use consistent trigger patterns (*workflow-name)
Support natural language AND shortcuts
Include descriptions for each option

Critical Actions Pattern

Agents execute "critical actions" on load:

critical_actions:
  - auto_load_config
  - check_workflow_status
  - set_context_from_project_files
  - remember_user_preferences

Why this works:

Agents are immediately context-aware
Reduces repetitive prompting
Ensures consistency across sessions
Loads just-in-time information

Apply to your agents:

## Critical Actions (Execute on Load)

1. Load user configuration (name, skill level, preferences)
2. Scan project directory for existing artifacts
3. Determine current project phase
4. Set appropriate context
5. Present relevant menu based on phase

2. Workflow Architecture

Structured Workflow Files

Each workflow has a clear structure:

workflow/
├── workflow.yaml          # Workflow definition
├── instructions.md        # Step-by-step guide for agent
├── template.md            # Output document template
├── checklist.md           # Validation checklist
└── data/
    └── reference-data.csv # Data-driven behavior

Why this works:

Separation of concerns (config, logic, output, validation)
Reusable templates
Data-driven customization
Quality assurance built-in

Apply to your workflows:

Define workflow (inputs, outputs, steps)
Create instructions (how agent should execute)
Design template (consistent output format)
Add validation (checklist to verify quality)

Scale-Adaptive Workflows

BMAD workflows adapt to project complexity:

scale_adaptive:
  level_0_1: quick_flow      # Bug fixes, small features
  level_2: bmad_method       # Products, platforms
  level_3_4: enterprise      # Large-scale systems

Decision matrix:

Complexity	Users	Timeline	Documentation	Test Strategy
0-1	1-100	Days	Tech spec	Basic
2	100-10K	Weeks	PRD + Arch	Standard
3-4	10K+	Months	Full suite	Comprehensive

Why this works:

Prevents over-planning simple tasks
Ensures thoroughness for complex projects
Saves time and tokens
Automatic adjustment based on assessment

Apply to your workflows:

## Workflow: Security Review

**Quick (Level 0-1):**
- Basic OWASP checklist
- Automated scan only

**Standard (Level 2):**
- Threat modeling
- Manual code review
- Penetration testing

**Enterprise (Level 3-4):**
- Full threat modeling (STRIDE)
- Security architecture review
- Compliance audit (SOC2, ISO27001)
- Penetration testing + red team

Four-Phase Methodology

BMAD organizes workflows into phases:

Phase 1: Analysis (Optional)
├── brainstorming
├── research
└── product-brief

Phase 2: Planning (Required)
├── PRD or tech-spec
└── epic/story breakdown

Phase 3: Solutioning (Track-dependent)
├── architecture
├── UX design
└── test strategy

Phase 4: Implementation (Iterative)
├── story development
├── code review
└── testing

Why this works:

Clear progression (left-to-right workflow)
Prevents jumping to implementation prematurely
Artifacts from each phase feed the next
Allows checkpoints and course corrections

Apply to your domains:

Marketing Campaign:

Research (market analysis, competitor review)
Planning (campaign brief, messaging)
Creation (copy, creative, landing pages)
Execution (launch, monitor, optimize)

Data Science Project:

Discovery (problem definition, data exploration)
Planning (hypothesis, metrics, approach)
Modeling (feature engineering, model building)
Deployment (productionize, monitor, iterate)

3. Collaboration Patterns

Sequential Handoffs

Agents work in sequence, each producing artifacts for the next:

PM → PRD.md
  ↓
Architect → architecture.md (reads PRD)
  ↓
UX Designer → ux-design.md (reads PRD)
  ↓
Developer → code (reads PRD + Architecture + UX)

Why this works:

Clear dependencies
Artifacts are contracts between agents
Each agent adds their expertise layer
Prevents rework from missing context

Apply to your agent workflows:

Define artifact formats (templates)
Specify what each agent consumes vs. produces
Version artifacts (PRD v1 → PRD v2)
Track dependencies in workflow status

Party Mode (Multi-Agent Collaboration)

All agents collaborate on complex decisions:

party_mode:
  participants:
    - PM (facilitator)
    - Architect (technical feasibility)
    - Developer (implementation complexity)
    - UX Designer (user impact)
    - Security Expert (risk assessment)

  process:
    1. PM presents problem
    2. Each agent shares perspective
    3. Agents debate trade-offs
    4. Human makes final decision

Why this works:

Diverse perspectives on complex problems
Uncovers issues single agents miss
More creative solutions
Human retains decision authority

Apply to your workflows:

Example: Choosing a tech stack

Architect: "I recommend microservices for scalability"
Developer: "Team is small, monolith is faster to start"
Security: "Microservices increase attack surface"
PM: "MVP timeline is 3 months, complexity is a risk"
Decision: Start with modular monolith, extract services later

Just-In-Time Context Loading

BMAD loads context only when needed:

# Anti-pattern: Load everything
context = load_entire_prd() + load_all_stories() + load_full_architecture()
# → 50K tokens, most irrelevant

# BMAD pattern: Load just-in-time
current_story = load_story("story-12")
relevant_prd_section = load_prd_section("user-management")
relevant_arch = load_architecture_component("auth-service")
# → 2K tokens, all relevant

Why this works:

90%+ token savings
Faster processing
More focused responses
Lower costs

Apply to your workflows:

## Context Loading Strategy

**Phase 2 (Planning):** Load full context
- All research
- All market data
- All user feedback

**Phase 4 (Implementation):** Load relevant context only
- Current story
- Related PRD section
- Relevant architecture component
- Affected code files only

4. Configuration Management

Update-Safe Customization

BMAD separates core files from user customizations:

.bmad/
├── bmm/agents/pm.agent.yaml          # Core (never edit)
└── _cfg/
    └── agents/pm.customize.yaml      # Your changes

Customization file:

agent:
  metadata:
    name: "Sarah"  # Override default "John"

  persona:
    additional_expertise: "SaaS products, B2B sales"

  memory:
    - "User prefers Agile over Waterfall"
    - "Project uses TypeScript + React"

Why this works:

Updates don't break your customizations
Clear separation of concerns
Easy to version control your changes
Can reset to defaults easily

Apply to your agents:

Base template (version controlled, shared)
User overrides (gitignored or per-user)
Project-specific config (per-project folder)

Layered Configuration

BMAD has 4 configuration levels:

1. Global defaults (framework level)
   ↓
2. Module defaults (bmm, bmb, cis)
   ↓
3. Project config (per-project settings)
   ↓
4. Agent customization (per-agent overrides)

Priority: Agent > Project > Module > Global

Why this works:

Sensible defaults out-of-the-box
Customize per-project or per-agent
Override only what you need
Clear precedence rules

Apply to your systems:

# global-config.yaml
output_language: "English"
skill_level: "Intermediate"

# project-config.yaml
output_language: "Spanish"  # Override global

# agent-config/pm.yaml
communication_style: "Casual"  # Override for this agent

Multi-Language Support

BMAD separates communication from output:

config:
  communication_language: "Spanish"       # Agent talks to me in Spanish
  document_output_language: "English"     # But generates docs in English

Why this works:

International teams with English docs
Personal comfort vs. team standards
Separate concerns (interaction vs. artifacts)

Apply to your agents:

## Language Configuration

**Communication:** The language I use to talk with you
**Output:** The language I generate documents in

Examples:
- Communicate in German, output in English (EU team, English docs)
- Communicate in English, output in Japanese (offshore team)
- Both in Spanish (Spanish-language product)

5. Document Management

Document Sharding

For large documents, BMAD splits by headings:

Whole PRD (50K tokens):

PRD.md
├── Executive Summary
├── User Stories
├── Epic: User Management (5K tokens)
├── Epic: Task Management (8K tokens)
├── Epic: Collaboration (7K tokens)
└── ... (10 more sections)

Sharded PRD (load only what you need):

docs/
├── PRD.md                          # Main file with links
└── PRD/
    ├── epic-user-management.md     # 5K tokens
    ├── epic-task-management.md     # 8K tokens
    └── epic-collaboration.md       # 7K tokens

Workflow loads only relevant shard:

Story: "Add password reset"
→ Load: epic-user-management.md (5K tokens)
→ Skip: epic-task-management.md (8K tokens saved)

Why this works:

90%+ token savings in implementation
Faster loading
Lower costs
Maintains full document for reference

Apply to your documents:

Generate full document in planning phase
Split by logical sections (epics, components, modules)
Load only relevant sections during implementation
Keep full document for reviews/updates

Input Pattern Abstraction

BMAD workflows auto-detect whole vs. sharded documents:

inputs:
  - name: prd
    pattern:
      whole: "{output_folder}/PRD.md"
      sharded: "{output_folder}/PRD/epic-*.md"

    load_strategy:
      - try: whole
        if_exists: load_entire_file
      - try: sharded
        if_exists: load_matching_shard_for_current_story
      - else: ask_user_for_prd_location

Why this works:

Workflows work with either format
No manual configuration needed
Backward compatible
Graceful fallbacks

Apply to your workflows:

## Document Loading Strategy

**Step 1:** Try to load whole document
- If exists: Use it
- If not: Continue to Step 2

**Step 2:** Try to load sharded documents
- If exists: Load relevant shard only
- If not: Continue to Step 3

**Step 3:** Ask user
- "I couldn't find the PRD. Please provide the path."

6. Quality Assurance

Validation Checklists

Every major workflow has a validation checklist:

PRD Validation Checklist:

## Completeness
- [ ] Executive Summary (1 paragraph)
- [ ] Problem Statement (clear, measurable)
- [ ] User Personas (3-5, detailed)
- [ ] Success Metrics (quantified)
- [ ] Functional Requirements (granular, testable)

## Quality
- [ ] Requirements are specific (not vague)
- [ ] Acceptance criteria are testable
- [ ] Risks are identified
- [ ] Timeline is realistic

## Alignment
- [ ] Aligns with business goals
- [ ] User needs are addressed
- [ ] Technical constraints considered

Why this works:

Catches gaps before implementation
Ensures consistency across projects
Teachable moments (users learn what "good" looks like)
Reduces rework

Apply to your workflows:

Create checklist for each deliverable
Run validation workflow before moving to next phase
Use checklist as a teaching tool
Update checklist based on lessons learned

Schema Validation

BMAD validates agent definitions against schemas:

// Agent schema validation
const agentSchema = {
  metadata: { required: ['id', 'name', 'title', 'module'] },
  persona: { required: ['role', 'identity', 'communication_style', 'principles'] },
  menu: {
    type: 'array',
    items: {
      required: ['trigger', 'description'],
      oneOf: ['workflow', 'exec', 'tmpl', 'data', 'action']
    }
  }
};

validateAgent(agentFile, agentSchema);

Why this works:

Catches errors before runtime
Ensures consistency across agents
Documentation through types
Easy to onboard new contributors

Apply to your systems:

Define schemas for agents, workflows, templates
Validate before deployment
Use TypeScript/JSON Schema for type safety
Run validation in CI/CD

7. Developer Experience

Comprehensive Testing

BMAD has multiple test layers:

# Schema validation
npm run test:schemas          # Validate YAML against schemas

# Installation tests
npm run test:install          # Test compilation process

# Integration tests
npm run validate:bundles      # Verify web bundles work

# Code quality
npm run lint                  # ESLint + YAML lint
npm run format:check          # Prettier

# All checks
npm test                      # Run everything

Why this works:

Catch issues before users hit them
Fast feedback loop
Multiple validation layers
Automated quality gates

Apply to your projects:

Schema validation (structure)
Unit tests (logic)
Integration tests (workflows end-to-end)
Linting (code quality)
Pre-commit hooks (prevent bad commits)

Self-Documenting Code

BMAD uses YAML for agent definitions (human-readable):

# Anti-pattern: Opaque code
agent = Agent(
  "pm",
  "John",
  lambda x: x.role == "PM",
  [Workflow("prd", "Create PRD", prd_handler)]
)

# BMAD pattern: Self-documenting YAML
agent:
  metadata:
    name: John
    title: Product Manager

  menu:
    - trigger: create-prd
      workflow: "path/to/prd/workflow.yaml"
      description: "Create Product Requirements Document"

Why this works:

Non-developers can read and modify
Version control friendly (clear diffs)
Self-documenting (structure = documentation)
Easy to generate/validate

Apply to your systems:

Use YAML/JSON for configuration
Clear naming conventions
Comments for complex logic only
Structure reflects intent

Modular Architecture

BMAD is organized into clear modules:

src/
├── core/                    # Framework (agents, workflows, tasks)
│   ├── agents/              # BMad Master orchestrator
│   ├── workflows/           # Core workflows (party-mode)
│   └── tasks/               # Reusable task units
│
├── modules/
│   ├── bmm/                 # Software development
│   ├── bmb/                 # Agent builder
│   ├── cis/                 # Creative intelligence
│   └── custom/              # User-created modules
│
├── utility/                 # Shared utilities
│   ├── models/fragments/    # XML components
│   └── templates/           # Reusable templates
│
└── tools/
    ├── cli/                 # Installation CLI
    └── bundlers/            # Web bundle generation

Why this works:

Clear boundaries (core vs. modules vs. tools)
Modules can be installed independently
Easy to add new modules
Shared utilities reduce duplication

Apply to your projects:

your-project/
├── core/               # Framework, base classes
├── modules/            # Domain-specific functionality
│   ├── module-a/
│   ├── module-b/
│   └── module-c/
├── shared/             # Shared utilities
└── tools/              # CLI tools, scripts

8. Deployment Strategies

Multi-Target Compilation

BMAD compiles agents for different targets:

// Single agent definition (YAML)
const agent = loadAgentYaml('pm.agent.yaml');

// Compile for different targets
compileForIDE(agent, 'claude-code');    // → .md with filesystem handlers
compileForIDE(agent, 'cursor');         // → .md with Cursor-specific syntax
compileForWeb(agent, 'gemini');         // → .xml for Gemini Gems
compileForWeb(agent, 'chatgpt');        // → Custom GPT format

Why this works:

Write once, deploy anywhere
Target-specific optimizations
Maintain single source of truth
Easy to add new targets

Apply to your agents:

Define agents in platform-agnostic format (YAML)
Create target-specific compilers
Generate optimized artifacts per platform
Automate compilation in build process

Dependency Resolution

BMAD automatically resolves cross-module dependencies:

# Workflow in BMM module references CIS module
workflow:
  dependencies:
    - module: cis
      workflow: brainstorming

Bundler resolves:

Scan all workflows
Identify cross-module references
Vendor (copy) dependencies into bundle
Embed inline to create self-contained artifact

Why this works:

Self-contained bundles (no external deps)
Automatic detection (no manual tracking)
Works across modules
No broken links

Apply to your build system:

Parse all workflow/agent files
Build dependency graph
Resolve and bundle dependencies
Validate no missing dependencies
Generate self-contained artifacts

Web Bundle Strategy

BMAD creates dual deployment modes:

IDE Installation (Filesystem-aware):

Agents load files from project folder
Read/write workflows
Customization via _cfg/ folder
Full functionality

Web Bundles (Self-contained):

Everything embedded inline
No file system access
Dependencies bundled
Limited but portable

Trade-offs:

Feature	IDE	Web Bundle
File access	✅ Yes	❌ No
Customization	✅ Easy	❌ Manual
Multi-agent	✅ Yes	⚠️ Limited
Cost	$
Setup	Complex	Easy

Why this works:

Best tool for the job
Planning in web (cheaper)
Implementation in IDE (full power)
Users choose based on needs

Apply to your deployment:

Identify use cases (planning vs. implementation)
Create appropriate deployment modes
Guide users to right mode
Allow hybrid workflows (web planning → IDE implementation)

9. Community & Contribution

Clear Contribution Guidelines

BMAD has comprehensive contribution docs:

CONTRIBUTING.md includes:

Code style guide
PR size limits (200-400 lines ideal, 800 max)
Commit message conventions (feat:, fix:, docs:)
Testing requirements
Documentation standards

Why this works:

Consistent codebase
Easy code reviews
Faster merges
Better collaboration

Apply to your projects:

Document coding standards
Set PR size expectations
Require tests for new features
Enforce via CI/CD
Provide templates (PR, issue)

Atomic Commits

BMAD uses conventional commits:

# Good commits
feat(bmm): add course-correction workflow
fix(bundler): resolve cross-module dependencies correctly
docs(readme): update installation instructions

# Bad commits
update stuff
fixes
WIP

Why this works:

Clear history (what changed, why)
Easier to review
Can generate changelogs automatically
Easy to revert specific changes

Apply to your workflow:

One logical change per commit
Use conventional commit format
Write clear commit messages
Small, frequent commits
Use tools like commitlint

10. Key Takeaways

Top 10 Best Practices

Persona-Driven Agents - Give agents identity, principles, and communication style
Menu-Driven UX - Let users discover capabilities through menus
Scale-Adaptive - Adjust complexity based on project needs
Just-In-Time Context - Load only relevant information
Update-Safe Customization - Separate core from user configs
Validation Checklists - Ensure quality before moving forward
Multi-Target Compilation - Write once, deploy anywhere
Modular Architecture - Clear boundaries, independent modules
Comprehensive Testing - Multiple validation layers
Human Amplification - AI augments, doesn't replace human decisions

Anti-Patterns to Avoid

❌ Monolithic agents - One agent trying to do everything ✅ Specialized agents - Each agent has a clear domain

❌ Loading full context always - Wasting tokens ✅ Just-in-time loading - Load only what's needed

❌ Hardcoded instructions - Difficult to maintain ✅ YAML-based config - Easy to read and modify

❌ No validation - Quality issues slip through ✅ Built-in checklists - Validate before proceeding

❌ Manual artifact handoffs - Prone to errors ✅ Structured file formats - Automatic detection

❌ All-or-nothing planning - Overkill for small tasks ✅ Scale-adaptive - Right level of planning per project

❌ Editing core files - Breaks on updates ✅ Customization layer - Survives updates

❌ One deployment target - Locked in ✅ Multi-target compilation - Deploy anywhere

❌ Vague commit messages - Hard to understand history ✅ Conventional commits - Clear, structured history

❌ Large, infrequent commits - Hard to review ✅ Small, atomic commits - Easy to review and revert

Next Steps

Apply These Practices:

Review your agents - Do they have clear personas and principles?
Check your workflows - Are they scale-adaptive?
Audit context loading - Are you loading too much?
Add validation - Create checklists for deliverables
Separate customizations - Set up update-safe config
Improve testing - Add schema validation, linting
Modularize - Break monoliths into clear modules
Document - Make code self-documenting
Optimize deployment - Create target-specific bundles
Contribute - Share your learnings with the community

Resources

BMAD-METHOD Repo: https://github.com/bmad-code-org/BMAD-METHOD
Example Agents: src/modules/bmm/agents/
Example Workflows: src/modules/bmm/workflows/
Bundler Source: tools/cli/bundlers/
Discord Community: https://discord.gg/gk8jAdXWmj

These best practices are derived from analyzing the BMAD-METHOD v6-alpha codebase. Apply them to build better AI collaboration systems!

24 KiB Raw Blame History

BMAD-METHOD Best Practices Summary

Learned from Analyzing the BMAD-METHOD Repository

1. Agent Design Patterns

Persona-Driven Agents

Menu-Driven Interaction

Critical Actions Pattern

2. Workflow Architecture

Structured Workflow Files

Scale-Adaptive Workflows

Four-Phase Methodology

3. Collaboration Patterns

Sequential Handoffs

Party Mode (Multi-Agent Collaboration)

Just-In-Time Context Loading

4. Configuration Management

Update-Safe Customization

Layered Configuration

Multi-Language Support

5. Document Management

Document Sharding

Input Pattern Abstraction

6. Quality Assurance

Validation Checklists

Schema Validation

7. Developer Experience

Comprehensive Testing

Self-Documenting Code

Modular Architecture

8. Deployment Strategies

Multi-Target Compilation

Dependency Resolution

Web Bundle Strategy

9. Community & Contribution

Clear Contribution Guidelines

Atomic Commits

10. Key Takeaways

Top 10 Best Practices

Anti-Patterns to Avoid

Next Steps

Apply These Practices:

Resources

24 KiB

Raw Blame History