Building Your First Project with BMad Method
This tutorial walks you through creating a complete project using BMad Method, from initial concept to working code. Youβll experience the full workflow: analysis, planning, architecture, and implementation.Tutorial Project: Plant Care Tracker
Weβll build a simple web application that helps users track their houseplants and care schedules. This project is complex enough to showcase BMadβs capabilities while remaining approachable for learning. Features weβll implement:- User authentication
- Plant inventory management
- Care schedule tracking
- Watering reminders
Prerequisites
Complete Getting Started
Create project directory
Install BMad Method
Phase 1: Analysis
Letβs start by clarifying our product concept through optional but valuable analysis workflows.Create a Product Brief
Open your AI IDE
Start a fresh chat
Load the Analyst agent
Run the product brief workflow
- Your target users (plant owners who struggle with care schedules)
- Core problem (forgetting to water plants, over/under watering)
- Key features (inventory, schedules, reminders)
- Success metrics (user retention, plants saved)
View example output
View example output
_bmad-output/planning-artifacts/product-brief.md
Phase 2: Planning
Now letβs create our comprehensive Product Requirements Document.Create the PRD
Start a fresh chat
Load the PM agent
Run the PRD creation workflow
- Product vision and goals
- User personas and scenarios
- Functional requirements
- Non-functional requirements
- Success metrics
- Initialization - Load context and understand your starting point
- Vision & Goals - Define the βwhyβ behind your product
- User Research - Identify personas and scenarios
- Requirements Discovery - Functional and non-functional needs
- Success Metrics - How youβll measure success
- Validation - Ensure completeness and cohesion
View example PRD structure
View example PRD structure
_bmad-output/planning-artifacts/PRD.md
Optional: Create UX Design
If your project has a user interface (like ours does), create a UX design document:Start a fresh chat
Load the UX Designer agent
Run the UX design workflow
- User journey mapping
- Visual foundation (colors, typography)
- Component strategy
- UX patterns and interactions
- Responsive design considerations
_bmad-output/planning-artifacts/ux-design.md
Phase 3: Solutioning
Now weβll make technical decisions and break down the work into actionable stories.Create Architecture
Start a fresh chat
Load the Architect agent
Run the architecture workflow
- Technology stack selection
- System architecture patterns
- Database design
- API structure
- Security approach
- Deployment strategy
_bmad-output/planning-artifacts/architecture.md
Create Epics and Stories
Start a fresh chat
Load the PM agent
Run create epics and stories
- Logical epics grouping related functionality
- Detailed user stories with acceptance criteria
- Technically-informed implementation notes
View example epics and stories
View example epics and stories
_bmad-output/planning-artifacts/epics.md
Implementation Readiness Check
Start a fresh chat
Load the Architect agent
Run readiness check
- PRD requirements are covered by stories
- Architecture supports all story requirements
- UX design aligns with functional requirements
- No gaps or contradictions exist
Phase 4: Implementation
Now the exciting part β building the actual application!Initialize Sprint Planning
Start a fresh chat
Load the Scrum Master agent
Run sprint planning
- Load all epics and stories
- Create
sprint-status.yamltracking file - Set initial status for all work items
The Build Cycle: Story by Story
Letβs implement our first story: User Registration (1.1)Step 1: Create Story File
Start a fresh chat
Load the Scrum Master agent
Run create-story
- Find the first βbacklogβ story from sprint-status
- Load comprehensive context (PRD, Architecture, previous stories)
- Create detailed story file with tasks/subtasks
- Include dev notes with architecture requirements
- Mark story as βready-for-devβ
View example story file
View example story file
_bmad-output/implementation-artifacts/1-1-user-registration.md
Step 2: Develop the Story
Start a fresh chat
Load the Developer agent
Run dev-story
- Load the story file and all context
- Execute tasks sequentially following red-green-refactor
- Write failing tests first, then implementation
- Mark each task complete only when tests pass
- Update File List with all changes
- Mark story as βreviewβ when complete
View example dev execution
View example dev execution
Step 3: Code Review
Start a fresh chat (in different LLM if possible)
Load the Developer agent
Run code review
- Load the story and review all changed files
- Analyze code quality, patterns, security
- Check test coverage and quality
- Validate architecture compliance
- Create action items for any issues found
View example code review
View example code review
dev-story to address them. The Dev agent will automatically detect the review context and prioritize fixing review items.
Continue Building
Repeat the build cycle for each story:- Create Story (SM agent +
create-story) - Develop Story (Dev agent +
dev-story) - Code Review (Dev agent +
code-review)
Complete Epic 1
Once all stories in Epic 1 are done:Start a fresh chat
Load the Scrum Master agent
Run retrospective
- Bob (Scrum Master) facilitates
- Amelia (Developer) shares technical insights
- Winston (Architect) discusses patterns
- John (PM) evaluates business value
- You participate as project lead
What Youβve Built
Congratulations! Youβve completed your first BMad Method project cycle. You now have:Complete Planning
Working Authentication
Comprehensive Tests
Process Knowledge
Key Learnings
Fresh chats are essential
BMad-Help is your guide
/bmad-help when unsure what to do nextPlanning pays off
TDD works with AI
Code review adds quality
Party Mode enables collaboration
Next Steps
Continue Building
Explore Advanced Features
Learn Agent Deep Dive
Read Best Practices
Troubleshooting
Agent doesn't follow instructions
Agent doesn't follow instructions
- Start a fresh chat to reset context
- Verify you loaded the correct agent with the slash command
- Check that youβre running the intended workflow
- Ensure your IDE is properly configured for agent support
Sprint status not updating
Sprint status not updating
- Verify
sprint-status.yamlexists in_bmad-output/implementation-artifacts/ - Check file permissions (must be writable)
- Run
sprint-planningagain to regenerate - Manually update if needed (itβs just YAML)
Story file missing context
Story file missing context
- Re-run
create-storywith fresh chat - Verify PRD and Architecture files exist and are complete
- Check that
project-context.mdexists if you created one - Ensure previous story files are in the correct location
Tests failing during dev-story
Tests failing during dev-story
- Dev agent should stop and fix before continuing
- If it doesnβt, explicitly tell it to fix failing tests
- Check that all dependencies are installed
- Verify database is running (for integration tests)
