BMAD-METHOD/bmad-core/data/bmad-kb.md

BMAD Knowledge Base

Overview

BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework that combines AI agents with Agile development methodologies. The v4 system introduces a modular architecture with improved dependency management, bundle optimization, and support for both web and IDE environments.

Key Features

• Modular Agent System: Specialized AI agents for each Agile role
• Build System: Automated dependency resolution and optimization
• Dual Environment Support: Optimized for both web UIs and IDEs
• Reusable Resources: Portable templates, tasks, and checklists
• Slash Command Integration: Quick agent switching and control

When to Use BMAD

• New Projects (Greenfield): Complete end-to-end development
• Existing Projects (Brownfield): Feature additions and enhancements
• Team Collaboration: Multiple roles working together
• Quality Assurance: Structured testing and validation
• Documentation: Professional PRDs, architecture docs, user stories

Getting Started

Quick Start Options

Option 1: Web UI

Best for: ChatGPT, Claude, Gemini users who want to start immediately

1. Navigate to dist/teams/
2. Copy team-fullstack.txt content
3. Create new Gemini Gem or CustomGPT
4. Upload file with instructions: "Your critical operating instructions are attached, do not break character as directed"
5. Type /help to see available commands

Option 2: IDE Integration

Best for: Cursor, Claude Code, Windsurf, VS Code users

# Interactive installation (recommended)
npx bmad-method install

Installation Steps:

• Choose "Complete installation"
• Select your IDE (Cursor, Claude Code, Windsurf, or Roo Code)

Verify Installation:

• .bmad-core/ folder created with all agents
• IDE-specific integration files created
• All agent commands/rules/modes available

Environment Selection Guide

Use Web UI for:

• Initial planning and documentation (PRD, architecture)
• Cost-effective document creation (especially with Gemini)
• Brainstorming and analysis phases
• Multi-agent consultation and planning

Use IDE for:

• Active development and coding
• File operations and project integration
• Document sharding and story management
• Implementation workflow (SM/Dev cycles)

Cost-Saving Tip: Create large documents (PRDs, architecture) in web UI, then copy to docs/prd.md and docs/architecture.md in your project before switching to IDE for development.

Core Configuration (core-config.yml)

New in V4: The bmad-core/core-config.yml file is a critical innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.

What is core-config.yml?

This configuration file acts as a map for BMAD agents, telling them exactly where to find your project documents and how they're structured. It enables:

• Version Flexibility: Work with V3, V4, or custom document structures
• Custom Locations: Define where your documents and shards live
• Developer Context: Specify which files the dev agent should always load
• Debug Support: Built-in logging for troubleshooting

Key Configuration Areas

PRD Configuration

• prdVersion: Tells agents if PRD follows v3 or v4 conventions
• prdSharded: Whether epics are embedded (false) or in separate files (true)
• prdShardedLocation: Where to find sharded epic files
• epicFilePattern: Pattern for epic filenames (e.g., epic-{n}*.md)

Architecture Configuration

• architectureVersion: v3 (monolithic) or v4 (sharded)
• architectureSharded: Whether architecture is split into components
• architectureShardedLocation: Where sharded architecture files live

Developer Files

• devLoadAlwaysFiles: List of files the dev agent loads for every task
• devDebugLog: Where dev agent logs repeated failures
• agentCoreDump: Export location for chat conversations

Why It Matters

1. No Forced Migrations: Keep your existing document structure
2. Gradual Adoption: Start with V3 and migrate to V4 at your pace
3. Custom Workflows: Configure BMAD to match your team's process
4. Intelligent Agents: Agents automatically adapt to your configuration

Common Configurations

Legacy V3 Project:

prdVersion: v3
prdSharded: false
architectureVersion: v3
architectureSharded: false

V4 Optimized Project:

prdVersion: v4
prdSharded: true
prdShardedLocation: docs/prd
architectureVersion: v4
architectureSharded: true
architectureShardedLocation: docs/architecture

Core Philosophy

Vibe CEO'ing

You are the "Vibe CEO" - thinking like a CEO with unlimited resources and a singular vision. Your AI agents are your high-powered team, and your role is to:

• Direct: Provide clear instructions and objectives
• Refine: Iterate on outputs to achieve quality
• Oversee: Maintain strategic alignment across all agents

Core Principles

1. MAXIMIZE_AI_LEVERAGE: Push the AI to deliver more. Challenge outputs and iterate.
2. QUALITY_CONTROL: You are the ultimate arbiter of quality. Review all outputs.
3. STRATEGIC_OVERSIGHT: Maintain the high-level vision and ensure alignment.
4. ITERATIVE_REFINEMENT: Expect to revisit steps. This is not a linear process.
5. CLEAR_INSTRUCTIONS: Precise requests lead to better outputs.
6. DOCUMENTATION_IS_KEY: Good inputs (briefs, PRDs) lead to good outputs.
7. START_SMALL_SCALE_FAST: Test concepts, then expand.
8. EMBRACE_THE_CHAOS: Adapt and overcome challenges.

Key Workflow Principles

1. Agent Specialization: Each agent has specific expertise and responsibilities
2. Clean Handoffs: Always start fresh when switching between agents
3. Status Tracking: Maintain story statuses (Draft → Approved → InProgress → Done)
4. Iterative Development: Complete one story before starting the next
5. Documentation First: Always start with solid PRD and architecture

Agent System

Core Development Team

Agent	Role	Primary Functions	When to Use
analyst	Business Analyst	Market research, requirements gathering	Project planning, competitive analysis
pm	Product Manager	PRD creation, feature prioritization	Strategic planning, roadmaps
architect	Solution Architect	System design, technical architecture	Complex systems, scalability planning
dev	Developer	Code implementation, debugging	All development tasks
qa	QA Specialist	Test planning, quality assurance	Testing strategies, bug validation
ux-expert	UX Designer	UI/UX design, prototypes	User experience, interface design
po	Product Owner	Backlog management, story validation	Story refinement, acceptance criteria
sm	Scrum Master	Sprint planning, story creation	Project management, workflow

Meta Agents

Agent	Role	Primary Functions	When to Use
bmad-orchestrator	Team Coordinator	Multi-agent workflows, role switching	Complex multi-role tasks
bmad-master	Universal Expert	All capabilities without switching	Single-session comprehensive work

Agent Interaction Commands

IDE-Specific Syntax

Agent Loading by IDE:

• Claude Code: /agent-name (e.g., /bmad-master)
• Cursor: @agent-name (e.g., @bmad-master)
• Windsurf: @agent-name (e.g., @bmad-master)
• Roo Code: Select mode from mode selector (e.g., bmad-bmad-master)

Chat Management Guidelines:

• Claude Code, Cursor, Windsurf: Start new chats when switching agents
• Roo Code: Switch modes within the same conversation

Common Task Commands:

• *help - Show available commands
• *status - Show current context/progress
• *exit - Exit the agent mode
• *shard-doc docs/prd.md prd - Shard PRD into manageable pieces
• *shard-doc docs/architecture.md architecture - Shard architecture document
• *create - Run create-next-story task (SM agent)

In Web UI:

/pm create-doc prd
/architect review system design
/dev implement story 1.2
/help - Show available commands
/switch agent-name - Change active agent (if orchestrator available)

Team Configurations

Pre-Built Teams

Team All

• Includes: All 10 agents + orchestrator
• Use Case: Complete projects requiring all roles
• Bundle: team-all.txt

Team Fullstack

• Includes: PM, Architect, Developer, QA, UX Expert
• Use Case: End-to-end web/mobile development
• Bundle: team-fullstack.txt

Team No-UI

• Includes: PM, Architect, Developer, QA (no UX Expert)
• Use Case: Backend services, APIs, system development
• Bundle: team-no-ui.txt

Core Architecture

System Overview

The BMAD-Method is built around a modular architecture centered on the bmad-core directory, which serves as the brain of the entire system. This design enables the framework to operate effectively in both IDE environments (like Cursor, VS Code) and web-based AI interfaces (like ChatGPT, Gemini).

Key Architectural Components

1. Agents (bmad-core/agents/)

• Purpose: Each markdown file defines a specialized AI agent for a specific Agile role (PM, Dev, Architect, etc.)
• Structure: Contains YAML headers specifying the agent's persona, capabilities, and dependencies
• Dependencies: Lists of tasks, templates, checklists, and data files the agent can use
• Startup Instructions: Can load project-specific documentation for immediate context

2. Agent Teams (bmad-core/agent-teams/)

• Purpose: Define collections of agents bundled together for specific purposes
• Examples: team-all.yml (comprehensive bundle), team-fullstack.yml (full-stack development)
• Usage: Creates pre-packaged contexts for web UI environments

3. Workflows (bmad-core/workflows/)

• Purpose: YAML files defining prescribed sequences of steps for specific project types
• Types: Greenfield (new projects) and Brownfield (existing projects) for UI, service, and fullstack development
• Structure: Defines agent interactions, artifacts created, and transition conditions

4. Reusable Resources

• Templates (bmad-core/templates/): Markdown templates for PRDs, architecture specs, user stories
• Tasks (bmad-core/tasks/): Instructions for specific repeatable actions like "shard-doc" or "create-next-story"
• Checklists (bmad-core/checklists/): Quality assurance checklists for validation and review
• Data (bmad-core/data/): Core knowledge base and technical preferences

Dual Environment Architecture

IDE Environment

• Users interact directly with agent markdown files
• Agents can access all dependencies dynamically
• Supports real-time file operations and project integration
• Optimized for development workflow execution

Web UI Environment

• Uses pre-built bundles from dist/teams for stand alone 1 upload files for all agents and their assest with an orchestrating agent
• Single text files containing all agent dependencies are in dist/agents/ - these are unnecessary unless you want to create a web agent that is only a single agent and not a team
• Created by the web-builder tool for upload to web interfaces
• Provides complete context in one package

Template Processing System

BMAD employs a sophisticated template system with three key components:

1. Template Format (utils/template-format.md): Defines markup language for variable substitution and AI processing directives
2. Document Creation (tasks/create-doc.md): Orchestrates template selection and user interaction
3. Advanced Elicitation (tasks/advanced-elicitation.md): Provides interactive refinement through structured brainstorming

Template Features:

• Self-contained: Templates embed both output structure and processing instructions
• Variable Substitution: {{placeholders}} for dynamic content
• AI Processing Directives: [[LLM: instructions]] for AI-only processing
• Interactive Refinement: Built-in elicitation processes for quality improvement

Technical Preferences Integration

The technical-preferences.md file serves as a persistent technical profile that:

• Ensures consistency across all agents and projects
• Eliminates repetitive technology specification
• Provides personalized recommendations aligned with user preferences
• Evolves over time with lessons learned

Build and Delivery Process

The web-builder.js tool creates web-ready bundles by:

1. Reading agent or team definition files
2. Recursively resolving all dependencies
3. Concatenating content into single text files with clear separators
4. Outputting ready-to-upload bundles for web AI interfaces

This architecture enables seamless operation across environments while maintaining the rich, interconnected agent ecosystem that makes BMAD powerful.

Complete Development Workflow

Planning Phase (Web UI Recommended)

Ideal for cost efficiency, especially with Gemini:

1. Optional Analysis: /analyst - Market research, competitive analysis
2. Project Brief: Create foundation document (Analyst or user)
3. PRD Creation: /pm create-doc prd - Comprehensive product requirements
4. Architecture Design: /architect create-doc architecture - Technical foundation
5. Validation & Alignment: /po run master checklist to ensure document consistency
6. Document Preparation: Copy final documents to project as docs/prd.md and docs/architecture.md

Example Planning Prompts

For PRD Creation:

"I want to build a [type] application that [core purpose].
Help me brainstorm features and create a comprehensive PRD."

For Architecture Design:

"Based on this PRD, design a scalable technical architecture
that can handle [specific requirements]."

Critical Transition: Web UI to IDE

Once planning is complete, you MUST switch to IDE for development:

• Why: Development workflow requires file operations, real-time project integration, and document sharding
• Cost Benefit: Web UI is more cost-effective for large document creation; IDE is optimized for development tasks
• Required Files: Ensure docs/prd.md and docs/architecture.md exist in your project

IDE Development Workflow

Prerequisites: Planning documents must exist in docs/ folder

1. Document Sharding:

   • @bmad-master or @po shard docs/prd.md to docs/prd/ folder
   • If architecture exists, shard to docs/architecture/ folder
   • Results in multiple manageable documents and epic files

2. Verify Sharded Content:

   • At least one epic-n.md file in docs/prd/ with stories in development order
   • Source tree document and coding standards for dev agent reference
   • Sharded docs for SM agent story creation

Resulting Folder Structure:

• docs/prd/ - Broken down PRD sections
• docs/architecture/ - Broken down architecture sections
• docs/stories/ - Generated user stories

3. Development Cycle (Sequential, one story at a time):

   Step 1 - Story Creation: New chat window → @sm → *create

   • SM executes create-next-story task
   • Review generated story in docs/stories/
   • Update status from "Draft" to "Approved"

   Step 2 - Story Implementation: New chat window → @dev

   • Agent asks which story to implement
   • Include story file content to save dev agent lookup time
   • Dev follows tasks/subtasks, marking completion
   • Dev leaves notes for SM about any deviations
   • Update status to "Done"

   Step 3 - Repeat: Continue SM → Dev cycle until all epic stories complete

Important: Only 1 story in progress at a time, worked sequentially until all epic stories complete.

Status Tracking Workflow

Stories progress through defined statuses:

• Draft → Approved → InProgress → Done

Each status change requires user verification and approval before proceeding.

Workflow Types

Greenfield Development

• Business analysis and market research
• Product requirements and feature definition
• System architecture and design
• Development execution
• Testing and deployment

Brownfield Enhancement

• Current system analysis
• Enhancement planning
• Impact assessment
• Incremental development
• Integration testing

Document Creation Best Practices

Required File Naming for Framework Integration

• docs/prd.md - Product Requirements Document
• docs/architecture.md - System Architecture Document

Why These Names Matter:

• Agents automatically reference these files during development
• Sharding tasks expect these specific filenames
• Workflow automation depends on standard naming

Cost-Effective Document Creation Workflow

Recommended for Large Documents (PRD, Architecture):

1. Use Web UI: Create documents in web interface for cost efficiency
2. Copy Final Output: Save complete markdown to your project
3. Standard Names: Save as docs/prd.md and docs/architecture.md
4. Switch to IDE: Use IDE agents for development and smaller documents

Document Sharding

Templates with Level 2 headings (##) can be automatically sharded:

Original PRD:

## Goals and Background Context
## Requirements  
## User Interface Design Goals
## Success Metrics

After Sharding:

• docs/prd/goals-and-background-context.md
• docs/prd/requirements.md
• docs/prd/user-interface-design-goals.md
• docs/prd/success-metrics.md

Use the shard-doc task or @kayvan/markdown-tree-parser tool for automatic sharding.

Usage Patterns and Best Practices

Environment-Specific Usage

Web UI Best For:

• Initial planning and documentation phases
• Cost-effective large document creation
• Agent consultation and brainstorming
• Multi-agent workflows with orchestrator

IDE Best For:

• Active development and implementation
• File operations and project integration
• Story management and development cycles
• Code review and debugging

Quality Assurance

• Use appropriate agents for specialized tasks
• Follow Agile ceremonies and review processes
• Maintain document consistency with PO agent
• Regular validation with checklists and templates

Performance Optimization

• Use specific agents vs. bmad-master for focused tasks
• Choose appropriate team size for project needs
• Leverage technical preferences for consistency
• Regular context management and cache clearing

Success Tips

• Use Gemini for big picture planning - The team-fullstack bundle provides collaborative expertise
• Use bmad-master for document organization - Sharding creates manageable chunks
• Follow the SM → Dev cycle religiously - This ensures systematic progress
• Keep conversations focused - One agent, one task per conversation
• Review everything - Always review and approve before marking complete

Getting Help

• Commands: Use /help in any environment to see available commands
• Agent Switching: Use /switch agent-name with orchestrator for role changes
• Documentation: Check docs/ folder for project-specific context
• Community: Discord and GitHub resources available for support