Skip to main content

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
This tutorial uses the BMad Method track (full PRD + Architecture). If you’re working on a simpler project, you can use the Quick Flow track instead.

Prerequisites

1

Complete Getting Started

Follow the Getting Started guide to install BMad Method
2

Create project directory

3

Install BMad Method

Select BMad Method module when prompted.

Phase 1: Analysis

Let’s start by clarifying our product concept through optional but valuable analysis workflows.

Create a Product Brief

1

Open your AI IDE

Launch Claude Code, Cursor, or your preferred AI IDE in the project directory.
2

Start a fresh chat

Create a new chat session to begin.
3

Load the Analyst agent

You’ll meet Mary, the Business Analyst agent.
4

Run the product brief workflow

Mary will guide you through questions about:
  • 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)
Example interaction:
Output: _bmad-output/planning-artifacts/product-brief.md
BMad-Help will automatically run at the end, telling you the recommended next step (creating your PRD).

Phase 2: Planning

Now let’s create our comprehensive Product Requirements Document.

Create the PRD

1

Start a fresh chat

Always start fresh chats for each workflow to avoid context limitations.
2

Load the PM agent

Meet John, your Product Manager agent who asks β€œWHY?” relentlessly.
3

Run the PRD creation workflow

John will facilitate a structured interview covering:
  • Product vision and goals
  • User personas and scenarios
  • Functional requirements
  • Non-functional requirements
  • Success metrics
The PRD workflow uses step-file architecture: John will guide you through steps sequentially:
  1. Initialization - Load context and understand your starting point
  2. Vision & Goals - Define the β€œwhy” behind your product
  3. User Research - Identify personas and scenarios
  4. Requirements Discovery - Functional and non-functional needs
  5. Success Metrics - How you’ll measure success
  6. Validation - Ensure completeness and cohesion
Example interaction:
Output: _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:
1

Start a fresh chat

2

Load the UX Designer agent

Meet Sally, who paints pictures with words and advocates for users.
3

Run the UX design workflow

Sally will guide you through:
  • User journey mapping
  • Visual foundation (colors, typography)
  • Component strategy
  • UX patterns and interactions
  • Responsive design considerations
Output: _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

1

Start a fresh chat

2

Load the Architect agent

Meet Winston, who speaks in calm, pragmatic tones and balances β€œwhat could be” with β€œwhat should be.”
3

Run the architecture workflow

Winston will guide you through:
  • Technology stack selection
  • System architecture patterns
  • Database design
  • API structure
  • Security approach
  • Deployment strategy
Example decisions for our Plant Care Tracker:
Output: _bmad-output/planning-artifacts/architecture.md

Create Epics and Stories

V6 Improvement: This workflow now runs after architecture, creating better quality stories informed by technical decisions.
1

Start a fresh chat

2

Load the PM agent

3

Run create epics and stories

John will analyze both your PRD and Architecture to create:
  • Logical epics grouping related functionality
  • Detailed user stories with acceptance criteria
  • Technically-informed implementation notes
Example output structure:
Output: _bmad-output/planning-artifacts/epics.md

Implementation Readiness Check

1

Start a fresh chat

2

Load the Architect agent

3

Run readiness check

Winston will validate:
  • PRD requirements are covered by stories
  • Architecture supports all story requirements
  • UX design aligns with functional requirements
  • No gaps or contradictions exist
Your planning phase is now complete! All documents are cohesive and ready for implementation.

Phase 4: Implementation

Now the exciting part β€” building the actual application!

Initialize Sprint Planning

1

Start a fresh chat

2

Load the Scrum Master agent

Meet Bob, your crisp and checklist-driven Scrum Master.
3

Run sprint planning

Bob will:
  • Load all epics and stories
  • Create sprint-status.yaml tracking file
  • Set initial status for all work items
Example sprint-status.yaml:

The Build Cycle: Story by Story

Let’s implement our first story: User Registration (1.1)

Step 1: Create Story File

1

Start a fresh chat

2

Load the Scrum Master agent

3

Run create-story

Bob will:
  • 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”
What’s in the story file:
Output: _bmad-output/implementation-artifacts/1-1-user-registration.md
Story file created! Bob updates sprint-status.yaml automatically:

Step 2: Develop the Story

1

Start a fresh chat

2

Load the Developer agent

Meet Amelia, who speaks in file paths and AC IDs with ultra-succinct precision.
3

Run dev-story

Amelia will:
  • 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
What happens during development:
Files created/modified:
Story implemented! Sprint status automatically updated:

Step 3: Code Review

For best results, use a different LLM for code review than the one that implemented the story. This provides fresh perspective.
1

Start a fresh chat (in different LLM if possible)

2

Load the Developer agent

3

Run code review

Amelia (now acting as senior reviewer) will:
  • 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
Example review output:
If review finds issues, re-run dev-story to address them. The Dev agent will automatically detect the review context and prioritize fixing review items.
Review complete! Once all items are addressed, manually update sprint-status:

Continue Building

Repeat the build cycle for each story:
  1. Create Story (SM agent + create-story)
  2. Develop Story (Dev agent + dev-story)
  3. Code Review (Dev agent + code-review)
Progress tracking:

Complete Epic 1

Once all stories in Epic 1 are done:
1

Start a fresh chat

2

Load the Scrum Master agent

3

Run retrospective

This launches Party Mode where multiple agent personas collaborate:
  • Bob (Scrum Master) facilitates
  • Amelia (Developer) shares technical insights
  • Winston (Architect) discusses patterns
  • John (PM) evaluates business value
  • You participate as project lead
Example Party Mode interaction:

What You’ve Built

Congratulations! You’ve completed your first BMad Method project cycle. You now have:

Complete Planning

Product brief, PRD, UX design, architecture, and epics

Working Authentication

Secure registration and login with JWT tokens

Comprehensive Tests

Unit and integration tests with 100% passing rate

Process Knowledge

Understanding of the full BMad workflow
Your project structure:

Key Learnings

1

Fresh chats are essential

Each workflow benefits from clean context to avoid limitations
2

BMad-Help is your guide

Always run /bmad-help when unsure what to do next
3

Planning pays off

The comprehensive story files prevent dev mistakes and omissions
4

TDD works with AI

Red-green-refactor cycle catches issues early
5

Code review adds quality

Using a different LLM for review provides valuable perspective
6

Party Mode enables collaboration

Multiple agent perspectives surface insights you might miss

Next Steps

Continue Building

Complete Epic 2 (Plant Inventory) and Epic 3 (Care Schedules)

Explore Advanced Features

Add Test Architect module for risk-based testing

Learn Agent Deep Dive

Understand agent personas and collaboration patterns

Read Best Practices

Discover optimization techniques and advanced workflows

Troubleshooting

  • 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
  • Verify sprint-status.yaml exists in _bmad-output/implementation-artifacts/
  • Check file permissions (must be writable)
  • Run sprint-planning again to regenerate
  • Manually update if needed (it’s just YAML)
  • Re-run create-story with fresh chat
  • Verify PRD and Architecture files exist and are complete
  • Check that project-context.md exists if you created one
  • Ensure previous story files are in the correct location
  • 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)

Community & Support

Discord Community

Share your progress and get help in #bmad-method-help

GitHub Discussions

Ask questions and share insights with the community
You’re now ready to build your own projects with BMad Method. Happy building! πŸš€