BMAD-METHOD/README.md

BMad-Method: Universal AI Agent Framework

Foundations in Agentic Agile Driven Development, known as the Breakthrough Method of Agile AI-Driven Development, yet so much more. Transform any domain with specialized AI expertise: software development, entertainment, creative writing, business strategy to personal wellness just to name a few.

Subscribe to BMadCode on YouTube

Join our Discord Community - A growing community for AI enthusiasts! Get help, share ideas, explore AI agents & frameworks, collaborate on tech projects, enjoy hobbies, and help each other succeed. Whether you're stuck on BMad, building your own agents, or just want to chat about the latest in AI - we're here for you! Some mobile and VPN may have issue joining the discord, this is a discord issue - if the invite does not work, try from your own internet or another network, or non-VPN.

⭐ If you find this project helpful or useful, please give it a star in the upper right hand corner! It helps others discover BMad-Method and you will be notified of updates!

Overview

BMad Method's Two Key Innovations:

1. Agentic Planning: Dedicated agents (Analyst, PM, Architect) collaborate with you to create detailed, consistent PRDs and Architecture documents. Through advanced prompt engineering and human-in-the-loop refinement, these planning agents produce comprehensive specifications that go far beyond generic AI task generation.

2. Context-Engineered Development: The Scrum Master agent then transforms these detailed plans into hyper-detailed development stories that contain everything the Dev agent needs - full context, implementation details, and architectural guidance embedded directly in story files.

This two-phase approach eliminates both planning inconsistency and context loss - the biggest problems in AI-assisted development. Your Dev agent opens a story file with complete understanding of what to build, how to build it, and why.

📖 See the complete workflow in the User Guide - Planning phase, development cycle, and all agent roles

Quick Navigation

Understanding the BMad Workflow

Before diving in, review these critical workflow diagrams that explain how BMad works:

1. Planning Workflow (Web UI) - How to create PRD and Architecture documents
2. Core Development Cycle (IDE) - How SM, Dev, and QA agents collaborate through story files

⚠️ These diagrams explain 90% of BMad Method Agentic Agile flow confusion - Understanding the PRD+Architecture creation and the SM/Dev/QA workflow and how agents pass notes through story files is essential - and also explains why this is NOT taskmaster or just a simple task runner!

What would you like to do?

• Install and Build software with Full Stack Agile AI Team → Quick Start Instruction
• Learn how to use BMad → Complete user guide and walkthrough
• See available AI agents → Specialized roles for your team
• Explore non-technical uses → Creative writing, business, wellness, education
• Create my own AI agents → Build agents for your domain
• Browse ready-made expansion packs → Game dev, DevOps, infrastructure and get inspired with ideas and examples
• Understand the architecture → Technical deep dive
• Join the community → Get help and share ideas

Important: Keep Your BMad Installation Updated

Stay up-to-date effortlessly! If you already have BMad-Method installed in your project, simply run:

npx bmad-method install
# OR
git pull
npm run install:bmad

This will:

• ✅ Automatically detect your existing v4 installation
• ✅ Update only the files that have changed and add new files
• ✅ Create .bak backup files for any custom modifications you've made
• ✅ Preserve your project-specific configurations

This makes it easy to benefit from the latest improvements, bug fixes, and new agents without losing your customizations!

Quick Start

One Command for Everything (IDE Installation)

Just run one of these commands:

npx bmad-method install
# OR if you already have BMad installed:
git pull
npm run install:bmad

This single command handles:

• New installations - Sets up BMad in your project
• Upgrades - Updates existing installations automatically
• Expansion packs - Installs any expansion packs you've added to package.json

That's it! Whether you're installing for the first time, upgrading, or adding expansion packs - these commands do everything.

Prerequisites: Node.js v20+ required

Fastest Start: Web UI Full Stack Team at your disposal (2 minutes)

1. Get the bundle: Save or clone the full stack team file or choose another team
2. Create AI agent: Create a new Gemini Gem or CustomGPT
3. Upload & configure: Upload the file and set instructions: "Your critical operating instructions are attached, do not break character as directed"
4. Start Ideating and Planning: Start chatting! Type *help to see available commands or pick an agent like *analyst to start right in on creating a brief.
5. CRITICAL: Talk to BMad Orchestrator in the web at ANY TIME (#bmad-orchestrator command) and ask it questions about how this all works!
6. When to move to the IDE: Once you have your PRD, Architecture, optional UX and Briefs - its time to switch over to the IDE to shard your docs, and start implementing the actual code! See the User guide for more details

Alternative: Clone and Build

git clone https://github.com/bmadcode/bmad-method.git
npm run install:bmad # build and install all to a destination folder

🌟 Beyond Software Development - Expansion Packs

BMad's natural language framework works in ANY domain. Expansion packs provide specialized AI agents for creative writing, business strategy, health & wellness, education, and more. Also expansion packs can expand the core BMad-Method with specific functionality that is not generic for all cases. See the Expansion Packs Guide and learn to create your own!

Codebase Flattener Tool

The BMad-Method includes a powerful codebase flattener tool designed to prepare your project files for AI model consumption. This tool aggregates your entire codebase into a single XML file, making it easy to share your project context with AI assistants for analysis, debugging, or development assistance.

Features

• AI-Optimized Output: Generates clean XML format specifically designed for AI model consumption
• Smart Filtering: Automatically respects .gitignore patterns to exclude unnecessary files
• Binary File Detection: Intelligently identifies and excludes binary files, focusing on source code
• Progress Tracking: Real-time progress indicators and comprehensive completion statistics
• Flexible Output: Customizable output file location and naming

Usage

# Basic usage - creates flattened-codebase.xml in current directory
npm run flatten

# Specify custom output file
npm run flatten -- --output my-project.xml
npm run flatten -- -o /path/to/output/codebase.xml

Example Output

The tool will display progress and provide a comprehensive summary:

📊 Completion Summary:
✅ Successfully processed 156 files into flattened-codebase.xml
📁 Output file: /path/to/your/project/flattened-codebase.xml
📏 Total source size: 2.3 MB
📄 Generated XML size: 2.1 MB
📝 Total lines of code: 15,847
🔢 Estimated tokens: 542,891
📊 File breakdown: 142 text, 14 binary, 0 errors

The generated XML file contains all your project's source code in a structured format that AI models can easily parse and understand, making it perfect for code reviews, architecture discussions, or getting AI assistance with your BMad-Method projects.

Documentation & Resources

Essential Guides

• 📖 User Guide - Complete walkthrough from project inception to completion
• 🏗️ Core Architecture - Technical deep dive and system design
• 🚀 Expansion Packs Guide - Extend BMad to any domain beyond software development

Support

• 💬 Discord Community
• 🐛 Issue Tracker
• 💬 Discussions

Contributing

We're excited about contributions and welcome your ideas, improvements, and expansion packs! 🎉

📋 Read CONTRIBUTING.md - Complete guide to contributing, including guidelines, process, and requirements

License

MIT License - see LICENSE for details.

_{Built with ❤️ for the AI-assisted development community}