Quick Start Guide

Get started with BMad Method in 5 minutes. This guide walks you through installation and your first workflow.

Prerequisites

• Node.js >= 20.10.0
• npm (comes with Node.js)
• Project directory
• Either a web AI platform (ChatGPT/Claude/Gemini) or desktop IDE (Cursor/Claude Code/Windsurf)

Installation

Step 1: Install BMad Method

# Navigate to your project directory
cd your-project

# Run interactive installer
npx bmad-method install

Step 2: Answer Installation Prompts

The installer will ask:

1. Installation directory: Press Enter to use current directory
2. Package selection: Select "BMad Agile Core System" (default)
3. Document sharding: Select "Yes" for both PRD and architecture (default)
4. IDE configuration: Select your IDE(s) using Spacebar, press Enter
5. Web bundles (optional): Select "Yes" if using web platforms

Step 3: Verify Installation

npx bmad-method status

You should see:

• BMad core version installed
• Configured IDEs listed
• Installation directory confirmed

Your First Greenfield Project

Phase 1: Planning (Web Platform - 1-2 hours)

Platform: ChatGPT, Claude, or Gemini

Step 1: Load the planning team

• Copy web-bundles/teams/team-fullstack.txt contents
• Paste into your web AI platform

Step 2: Start the workflow

*help
*workflow-guidance

Follow the orchestrator's guidance:

1. Select "New project" → "Full-stack application"
2. Recommended workflow: greenfield-fullstack

Step 3: Create project brief

*agent analyst
*create-project-brief

Answer questions about your project. Output: docs/project-brief.md

Step 4: Create PRD

*agent pm
*create-prd

Interactive elicitation creates comprehensive PRD. Output: docs/prd.md

Step 5: Create frontend spec (if UI needed)

*agent ux-expert
*create-frontend-spec

Output: docs/front-end-spec.md

Step 6: Create architecture

*agent architect
*create-architecture

Output: docs/fullstack-architecture.md

Step 7: Shard documents

*agent po
*shard-doc

Splits PRD and architecture into manageable chunks. Output: docs/prd/ and docs/architecture/ directories

Phase 2: Development (IDE - ongoing)

Platform: Cursor, Claude Code, or Windsurf

Step 1: Load development agents in your IDE

• Reference .bmad-core/agents/ in your IDE configuration
• Or load team-ide-minimal if your IDE supports team loading

Step 2: Create first story

*agent sm
*draft

SM creates story with complete context. Output: docs/stories/1.1.{story-name}.md

Step 3: Implement story

*agent dev
*develop-story

Dev reads story (contains ALL context) and implements sequentially.

Step 4: QA review

*agent qa
*review
*gate

QA makes gate decision (PASS/CONCERNS/FAIL/WAIVED).

Step 5: If needed, address QA feedback

*agent dev
*review-qa

Dev addresses issues and updates story.

Step 6: Repeat for remaining stories Continue with *agent sm → *draft for next story.

Your First Brownfield Enhancement

Phase 1: Document Existing Project

Step 1: Flatten codebase

npx bmad-method flatten -i . -o project.xml

This creates an XML file with your entire codebase for AI context.

Phase 2: Planning (Web Platform - 30 min to 1 hour)

Step 1: Load planning team

• Copy web-bundles/teams/team-fullstack.txt or team-no-ui.txt
• Paste into web AI platform

Step 2: Create brownfield PRD

*agent pm
*create-prd

PM uses brownfield template and references project.xml for context.

Step 3: Create brownfield architecture

*agent architect
*create-architecture

Documents changes and integration points.

Step 4: Shard documents

*agent po
*shard-doc

Phase 3: Development (IDE - ongoing)

Same as greenfield development phase above.

Common Commands

Agent Commands

*help                      # Show available commands
*agent <name>              # Transform to specific agent
*workflow <name>           # Start specific workflow

CLI Commands

npx bmad-method status                    # Check installation
npx bmad-method list:agents               # List all agents
npx bmad-method list:expansions           # List expansion packs
npx bmad-method update                    # Update installation
npx bmad-method flatten -i ./src -o src.xml  # Flatten directory

Quick Troubleshooting

Problem: Agent doesn't recognize commands Solution: Ensure you're using * prefix for all agent commands

Problem: Can't find PRD or architecture Solution: Check core-config.yaml for correct file paths

Problem: Story creation fails Solution: Ensure PRD and architecture are sharded (*agent po → *shard-doc)

Problem: Agent asks for files that don't exist Solution: Complete planning phase first (PRD, architecture, sharding)

Next Steps

• Learn More: Read Planning Phase Guide for detailed planning workflow
• Development: Read Development Phase Guide for detailed development workflow
• Brownfield: Read Brownfield Guide for working with existing codebases
• Advanced: Explore Agent Reference for complete agent capabilities

Getting Help

• Check *help command in any agent
• Review Error Recovery Guide
• Consult Agent Reference for specific agent capabilities
• Check CLI Reference for installation and management commands