10 KiB
| title | description |
|---|---|
| Getting Started with the BMad Method | Install BMad and build your first project |
Upgrading from previous versions? See the Upgrade Guide instead.
Build software faster using AI-powered workflows with specialized agents that guide you through planning, architecture, and implementation.
What You'll Learn
- Install and initialize BMad Method for a new project
- Choose the right planning track for your project size
- Progress through phases from requirements to working code
- Use agents and workflows effectively
:::note[Prerequisites]
- Node.js 20+ — Required for the installer
- Git — Recommended for version control
- AI-powered IDE — Claude Code, Cursor, Windsurf, or similar
- A project idea — Even a simple one works for learning :::
:::tip[Quick Path]
Install → npx bmad-method@alpha install
Initialize → Load Analyst agent, run workflow-init
Plan → PM creates PRD, Architect creates architecture
Build → SM manages sprints, DEV implements stories
Always use fresh chats for each workflow to avoid context issues.
:::
Understanding BMad
BMad helps you build software through guided workflows with specialized AI agents. The process follows four phases:
| Phase | Name | What Happens |
|---|---|---|
| 1 | Analysis | Brainstorming, research, product brief (optional) |
| 2 | Planning | Create requirements (PRD or tech-spec) |
| 3 | Solutioning | Design architecture (BMad Method/Enterprise only) |
| 4 | Implementation | Build epic by epic, story by story |
Open the Interactive Workflow Guide to explore phases, agents, and outputs for your chosen track.
Based on your project's complexity, BMad offers three planning tracks:
| Track | Best For | Documents Created |
|---|---|---|
| Quick Flow | Bug fixes, simple features, clear scope (1-15 stories) | Tech-spec only |
| BMad Method | Products, platforms, complex features (10-50+ stories) | PRD + Architecture + UX |
| Enterprise | Compliance, multi-tenant systems (30+ stories) | PRD + Architecture + Security + DevOps |
:::note Story counts are guidance, not definitions. Choose your track based on planning needs, not story math. :::
Installation
Open a terminal in your project directory and run:
npx bmad-method@alpha install
The interactive installer guides you through setup and creates a _bmad/ folder with all agents and workflows.
Verify your installation:
your-project/
├── _bmad/
│ ├── bmm/ # Method module
│ │ ├── agents/ # Agent files
│ │ ├── workflows/ # Workflow files
│ │ └── config.yaml # Module config
│ └── core/ # Core utilities
├── _bmad-output/ # Generated artifacts (created later)
└── .claude/ # IDE configuration (if using Claude Code)
:::tip[Troubleshooting] Having issues? See Install BMad for common solutions. :::
Open your AI IDE in the project folder. From here, you can run /bmad-help anytime to see what to do next — or ask it a question like /bmad-help How should I build a web app for XYZ?
Step 1: Initialize Your Project
Load the Analyst agent in your IDE, wait for the menu, then run workflow-init.
:::note[How to Load Agents]
Type /<agent-name> in your IDE and use autocomplete. Not sure what's available? Start with /bmad to see all agents and workflows.
:::
The workflow asks you to describe your project, whether it's new or existing, and the general complexity. Based on your description, it recommends a planning track.
Once you confirm, the workflow creates bmm-workflow-status.yaml to track your progress through all phases.
:::caution[Fresh Chats] Always start a fresh chat for each workflow. This prevents context limitations from causing issues. :::
Step 2: Create Your Plan
After initialization, work through phases 1-3. Use fresh chats for each workflow.
:::tip[Check Your Status]
Unsure what's next? Load any agent and ask for workflow-status. It tells you the next recommended or required workflow.
:::
Phase 1: Analysis (Optional)
All workflows in this phase are optional:
- brainstorm-project — Guided ideation
- research — Market and technical research
- product-brief — Recommended foundation document
Phase 2: Planning (Required)
For BMad Method and Enterprise tracks:
- Load the PM agent in a new chat
- Run the PRD workflow:
*prd - Output:
PRD.md
For Quick Flow track:
- Use
tech-specinstead of PRD, then skip to implementation
:::note[UX Design (Optional)] If your project has a user interface, load the UX-Designer agent and run the UX design workflow after creating your PRD. :::
Phase 3: Solutioning (BMad Method/Enterprise)
Create Architecture
- Load the Architect agent in a new chat
- Run
create-architecture - Output: Architecture document with technical decisions
Create Epics and Stories
:::tip[V6 Improvement] Epics and stories are now created after architecture. This produces better quality stories because architecture decisions (database, API patterns, tech stack) directly affect how work should be broken down. :::
- Load the PM agent in a new chat
- Run
create-epics-and-stories - The workflow uses both PRD and Architecture to create technically-informed stories
Implementation Readiness Check (Highly Recommended)
- Load the Architect agent in a new chat
- Run
implementation-readiness - Validates cohesion across all planning documents
Step 3: Build Your Project
Once planning is complete, move to implementation. Each workflow should run in a fresh chat.
Initialize Sprint Planning
Load the SM agent and run sprint-planning. This creates sprint-status.yaml to track all epics and stories.
The Build Cycle
For each story, repeat this cycle with fresh chats:
| Step | Agent | Workflow | Purpose |
|---|---|---|---|
| 1 | SM | create-story |
Create story file from epic |
| 2 | DEV | dev-story |
Implement the story |
| 3 | TEA | automate |
Generate guardrail tests (optional) |
| 4 | DEV | code-review |
Quality validation (recommended) |
After completing all stories in an epic, load the SM agent and run retrospective.
What You've Accomplished
You've learned the foundation of building with BMad:
- Installed BMad and configured it for your IDE
- Initialized a project with your chosen planning track
- Created planning documents (PRD, Architecture, Epics & Stories)
- Understood the build cycle for implementation
Your project now has:
your-project/
├── _bmad/ # BMad configuration
├── _bmad-output/
│ ├── PRD.md # Your requirements document
│ ├── architecture.md # Technical decisions
│ ├── epics/ # Epic and story files
│ ├── bmm-workflow-status.yaml # Phase progress tracking
│ └── sprint-status.yaml # Sprint tracking
└── ...
Quick Reference
| Command | Agent | Purpose |
|---|---|---|
*workflow-init |
Analyst | Initialize a new project |
*workflow-status |
Any | Check progress and next steps |
*prd |
PM | Create Product Requirements Document |
*create-architecture |
Architect | Create architecture document |
*create-epics-and-stories |
PM | Break down PRD into epics |
*implementation-readiness |
Architect | Validate planning cohesion |
*sprint-planning |
SM | Initialize sprint tracking |
*create-story |
SM | Create a story file |
*dev-story |
DEV | Implement a story |
*code-review |
DEV | Review implemented code |
Common Questions
Do I always need architecture? Only for BMad Method and Enterprise tracks. Quick Flow skips from tech-spec to implementation.
Can I change my plan later?
Yes. The SM agent has a correct-course workflow for handling scope changes.
What if I want to brainstorm first?
Load the Analyst agent and run brainstorm-project before workflow-init.
Can I skip workflow-init and workflow-status? Yes, once you learn the flow. Use the Quick Reference to go directly to needed workflows.
Getting Help
- During workflows — Agents guide you with questions and explanations
- Community — Discord (#bmad-method-help, #report-bugs-and-issues)
- Documentation — BMM Workflow Reference
- Video tutorials — BMad Code YouTube
Key Takeaways
:::tip[Remember These]
- Always use fresh chats — Load agents in new chats for each workflow
- Let workflow-status guide you — Ask any agent for status when unsure
- Track matters — Quick Flow uses tech-spec; Method/Enterprise need PRD and architecture
- Tracking is automatic — Status files update themselves
- Agents are flexible — Use menu numbers, shortcuts (
*prd), or natural language :::
Ready to start? Install BMad, load the Analyst, run workflow-init, and let the agents guide you.