BMAD Tutorial
Learn BMAD workflows step by step through practical examples.
Learn BMAD workflows step by step through practical examples.
Tutorial 1: First BMAD Workflow#
Scenario#
We will use BMAD to "add an author list screen to the console app".
Step 1: Start BMAD Workflow#
/cc-product:bmad "Add console author list screen"Step 2: Analysis Phase (automatic)#
Analyst analyzes requirements and writes AC:
╔════════════════════════════════════════════════════════════════╗
║ 🔍 Analyst Review: APPROVED ║
╠════════════════════════════════════════════════════════════════╣
║ ║
║ ✅ Requirements clarity: PASS ║
║ - Console app, author list screen ║
║ - Scope: feature/console module ║
║ ║
║ ✅ AC BDD Gherkin format: PASS ║
║ - @happy-path: 2 ║
║ - @error-handling: 1 ║
║ ║
╚════════════════════════════════════════════════════════════════╝
📋 Acceptance Criteria:
Feature: Console author list screen
As a publisher admin
I want to view the author list
So that I can manage author information
@happy-path
Scenario: View author list
Given I am logged in as a publisher admin
When I click the author management menu
Then the author list screen is displayed
And the registered authors are shown in a table
@happy-path
Scenario: Search authors
Given I am on the author list screen
And the author "Hong Gildong" is registered
When I enter "Hong Gildong" in the search field
Then the search results include "Hong Gildong"
@error-handling
Scenario: List loading failure
Given the server connection is unstable
When I navigate to the author list screen
Then the message "Unable to load data" is displayed
And a retry button is displayedStep 3: Planning Phase (automatic)#
Product Manager creates the issue:
╔════════════════════════════════════════════════════════════════╗
║ 📝 PM Review: APPROVED ║
╠════════════════════════════════════════════════════════════════╣
║ ║
║ 📋 Issue created: #1810 ║
║ Title: [feat] Add console author list screen ║
║ Labels: feature, console, author ║
║ Story Point: 5 ║
║ ║
║ 📊 Complexity analysis: ║
║ - Screen type: List (pagination, search) ║
║ - Layers: Presentation + Domain + Data ║
║ - Expected files: 15-20 ║
║ ║
╚════════════════════════════════════════════════════════════════╝Step 4: Solutioning Phase (parallel)#
Architect and UX Designer review simultaneously:
╔════════════════════════════════════════════════════════════════╗
║ Phase 3: SOLUTIONING (parallel execution) ║
╠════════════════════════════════════════════════════════════════╣
║ ║
║ 🏗️ Architect review: ✅ APPROVED ║
║ ├── ✅ Clean Architecture ║
║ │ └── AuthorListBloC → GetAuthorsUseCase → IAuthorRepo ║
║ ├── ✅ Dependency wiring ║
║ │ └── Pure DI, BlocProvider direct creation verified ║
║ └── ✅ API design ║
║ └── Uses existing AuthorEndpoint ║
║ ║
║ 🎨 UX Designer review: ✅ APPROVED ║
║ ├── ✅ CoUI compliance ║
║ │ └── DataTable, TextField, Button used ║
║ ├── ✅ Layout ║
║ │ └── Standard console layout (Scaffold + headers) ║
║ └── ✅ Accessibility ║
║ └── Keyboard navigation supported ║
║ ║
╚════════════════════════════════════════════════════════════════╝Step 5: Implementation Phase#
Flutter Developer starts implementation:
╔════════════════════════════════════════════════════════════════╗
║ Phase 4: IMPLEMENTATION ║
╠════════════════════════════════════════════════════════════════╣
║ ║
║ 🌿 Branch created: feature/1810-author-list ║
║ ║
║ 📁 Created files: ║
║ feature/console/console_author/ ║
║ ├── lib/src/ ║
║ │ ├── data/ ║
║ │ │ └── repository/author_repository_impl.dart ║
║ │ ├── domain/ ║
║ │ │ ├── entity/author.dart ║
║ │ │ ├── repository/i_author_repository.dart ║
║ │ │ └── usecase/get_authors_usecase.dart ║
║ │ ├── presentation/ ║
║ │ │ ├── bloc/author_list_bloc.dart ║
║ │ │ ├── page/author_list_page.dart ║
║ │ │ └── widget/author_table.dart ║
║ │ └── route/route.dart ║
║ └── test/ ║
║ ├── bloc/author_list_bloc_test.dart ║
║ └── bdd/author_list_test.dart ║
║ ║
║ ✅ melos run analyze: PASS ║
║ ✅ Tests: 12/12 passed ║
║ ✅ PR #1815 created ║
║ ✅ Code review: APPROVED ║
║ ║
╚════════════════════════════════════════════════════════════════╝Step 6: Complete#
╔════════════════════════════════════════════════════════════════╗
║ 🎉 BMAD Workflow Complete ║
╠════════════════════════════════════════════════════════════════╣
║ ║
║ ✅ Phase 1: ANALYSIS - Approved (3 AC confirmed) ║
║ ✅ Phase 2: PLANNING - Issue #1810 created ║
║ ✅ Phase 3: SOLUTIONING - Design approved ║
║ ✅ Phase 4: IMPLEMENTATION - PR #1815 merged ║
║ ║
║ 📊 Summary: ║
║ - Reviews passed: 7/7 personas ║
║ - Gates passed: 4/4 phases ║
║ - Retries: 0 ║
║ - Total files: 18 ║
║ ║
║ 🧹 Cleanup complete: ║
║ - Branch deleted: feature/1810-author-list ║
║ - Issue closed: #1810 ║
║ - Pipeline: Done ║
║ ║
╚════════════════════════════════════════════════════════════════╝Tutorial 2: Gate Failure and Re-review#
Scenario#
Covers the case when Architect review fails in the Solutioning phase.
Step 1: Gate Failure Occurs#
╔════════════════════════════════════════════════════════════════╗
║ Phase 3: SOLUTIONING Gate ❌ FAILED ║
╠════════════════════════════════════════════════════════════════╣
║ ║
║ 🏗️ Architect review: ❌ REJECTED ║
║ ├── ✅ Clean Architecture: PASS ║
║ ├── ❌ Dependency wiring: FAIL ║
║ │ └── getIt<Bloc>() usage found - BlocProvider direct creation required ║
║ └── ✅ API design: PASS ║
║ ║
║ 🎨 UX Designer review: ✅ APPROVED ║
║ ║
║ ──────────────────────────────────────────────────────────── ║
║ Required actions: ║
║ ──────────────────────────────────────────────────────────── ║
║ 1. Change to direct creation in BlocProvider: ║
║ create: (_) => AuthorBloc() ║
║ ║
║ ⚠️ Re-review required after completing fixes: ║
║ /cc-product:review --persona architect --retry ║
║ ║
╚════════════════════════════════════════════════════════════════╝Step 2: Check Feedback#
# Check current status
/cc-product:bmad-status --phase solutioningOutput:
Phase: Solutioning
Status: ❌ BLOCKED (Architect review failed)
Architect feedback:
- getIt<Bloc>() usage prohibited - BlocProvider direct creation required
- File: lib/src/presentation/page/console_author_page.dart
- Required change: create: (_) => AuthorBloc()
UX Designer: ✅ APPROVED
Next action: Apply feedback then /cc-product:review --persona architect --retryStep 3: Fix Code#
// console_author_page.dart (before fix)
class ConsoleAuthorPage extends StatelessWidget {
@override
Widget build(BuildContext context) {
return BlocProvider(
create: (_) => getIt<AuthorBloc>() // ❌ getIt usage
..add(const AuthorEvent.load()),
child: const _ConsoleAuthorView(),
);
}
}
// console_author_page.dart (after fix)
class ConsoleAuthorPage extends StatelessWidget {
@override
Widget build(BuildContext context) {
return BlocProvider(
create: (_) => AuthorBloc() // ✅ Direct creation
..add(const AuthorEvent.load()),
child: const _ConsoleAuthorView(),
);
}
}
Step 4: Request Re-review#
/cc-product:review --persona architect --retryOutput:
╔════════════════════════════════════════════════════════════════╗
║ 🏗️ Architect Review (re-review): ✅ APPROVED ║
╠════════════════════════════════════════════════════════════════╣
║ ║
║ ✅ Clean Architecture: PASS ║
║ ✅ Dependency wiring: PASS ║
║ └── Pure DI pattern compliance, BlocProvider direct creation verified ✓ ║
║ ✅ API design: N/A ║
║ ║
║ Phase 3 Gate: ✅ PASSED ║
║ → Proceeding to Phase 4 (Implementation) ║
║ ║
╚════════════════════════════════════════════════════════════════╝Tutorial 3: Emergency Mode Usage#
Scenario#
A payment bug has occurred in production and an emergency fix is needed.
Step 1: Start Emergency Mode#
/cc-product:bmad --emergency "emergency fix for payment amount calculation error"Step 2: Approval Request#
╔════════════════════════════════════════════════════════════════╗
║ ⚠️ Emergency Mode Approval Request ║
╠════════════════════════════════════════════════════════════════╣
║ ║
║ Emergency mode streamlines the following gates: ║
║ - Analysis: Skipped ║
║ - Planning: Skipped ║
║ - Solutioning: Streamlined (core review only) ║
║ ║
║ ⚠️ Implementation gate is still mandatory: ║
║ - melos run analyze pass ║
║ - Basic tests pass ║
║ ║
║ ⚠️ Post-review is required within 48 hours of completion. ║
║ ║
║ [Yes, approved] [No, proceed in normal mode] ║
║ ║
╚════════════════════════════════════════════════════════════════╝User selects "Yes, approved".
Step 3: Streamlined Workflow#
╔════════════════════════════════════════════════════════════════╗
║ 🚨 Emergency Mode: Emergency fix for payment amount calculation error ║
╠════════════════════════════════════════════════════════════════╣
║ ║
║ ⏭️ Phase 1: ANALYSIS - Skipped (emergency mode) ║
║ ⏭️ Phase 2: PLANNING - Skipped (emergency mode) ║
║ 🔄 Phase 3: SOLUTIONING - Streamlined review in progress ║
║ ⏳ Phase 4: IMPLEMENTATION - Waiting ║
║ ║
╚════════════════════════════════════════════════════════════════╝Step 4: Completion and Post-Review Notification#
╔════════════════════════════════════════════════════════════════╗
║ 🚨 Emergency Workflow Complete ║
╠════════════════════════════════════════════════════════════════╣
║ ║
║ ✅ Emergency fix complete: PR #1820 merged ║
║ ║
║ ⚠️ Post-review required: ║
║ - Deadline: Within 48 hours (until 2025-01-26 15:30) ║
║ - Reviewers: Architect, Product Manager ║
║ - Issue: #1821 (auto-created) ║
║ ║
║ Post-review items: ║
║ - [ ] Review impact of fix on architecture ║
║ - [ ] Check if additional tests are needed ║
║ - [ ] Check if documentation is needed ║
║ - [ ] Plan preventive measures ║
║ ║
╚════════════════════════════════════════════════════════════════╝Tutorial 4: Skip Specific Persona#
Scenario#
Backend-only task where UX Designer review is not needed.
Step 1: Use Persona Skip Option#
/cc-product:bmad --skip-persona ux-designer "Add Serverpod migration endpoint"Step 2: Solutioning Phase#
╔════════════════════════════════════════════════════════════════╗
║ Phase 3: SOLUTIONING ║
╠════════════════════════════════════════════════════════════════╣
║ ║
║ 🏗️ Architect review: ✅ APPROVED ║
║ ├── ✅ Clean Architecture ║
║ ├── ✅ API design ║
║ └── ✅ DB migration review ║
║ ║
║ 🎨 UX Designer review: ⏭️ Skipped (--skip-persona) ║
║ ║
║ Phase 3 Gate: ✅ PASSED ║
║ ║
╚════════════════════════════════════════════════════════════════╝Tutorial 5: AC (Acceptance Criteria) Writing Guide#
BDD Gherkin Format Required#
In the Analysis phase, the Analyst must write all AC in BDD Gherkin format.
Basic Structure#
Feature: {feature name}
As a {user role}
I want to {desired capability}
So that {expected benefit}
Background:
Given {common precondition}
@happy-path
Scenario: {normal case}
Given {precondition}
When {action}
Then {verifiable result}
@error-handling
Scenario: {error case}
Given {precondition}
When {error-inducing action}
Then {error handling result}
@edge-case
Scenario: {boundary case}
Given {special condition}
When {action}
Then {result}Required Tags#
| Tag | Required | Minimum Count |
|---|---|---|
@happy-path | ✅ | 1 or more |
@error-handling | ✅ | 1 or more |
@edge-case | Recommended | - |
Example: Form Screen#
Feature: Author registration form
As a publisher admin
I want to register a new author
So that I can manage author information
Background:
Given I am logged in as a publisher admin
And I am on the author registration screen
@happy-path
Scenario: Register author with valid information
Given all required fields are empty
When I enter "Hong Gildong" in the name field
And I enter "hong@example.com" in the email field
And I click the save button
Then the author is registered successfully
And I am navigated to the author list screen
And a success toast is displayed
@error-handling
Scenario: Required field missing
Given the name field is empty
When I click the save button
Then the error "Name is required" is displayed
And the form is not submitted
@error-handling
Scenario: Invalid email format
Given I enter "invalid-email" in the email field
When I click the save button
Then the error "Please enter a valid email" is displayed
@edge-case
Scenario: Duplicate email
Given the email "hong@example.com" is already registered
When I enter "hong@example.com" in the email field
And I click the save button
Then the error "This email is already registered" is displayedAC Verification Failure Example#
╔════════════════════════════════════════════════════════════════╗
║ 🔍 Analyst Review: ❌ REJECTED ║
╠════════════════════════════════════════════════════════════════╣
║ ║
║ ❌ AC BDD Gherkin format: FAIL ║
║ - @error-handling scenario is missing ║
║ ║
║ Required actions: ║
║ 1. Add at least 1 error handling scenario ║
║ ║
║ Example: ║
║ @error-handling ║
║ Scenario: Display error on server failure ║
║ Given the server connection is unstable ║
║ When I click the save button ║
║ Then the error "Save failed" is displayed ║
║ And a retry button is displayed ║
║ ║
╚════════════════════════════════════════════════════════════════╝Next Steps#
- BMAD_GUIDE.md - Full guide
- BMAD_QUICKREF.md - Quick reference
- PERSONA_MATRIX.md - Persona matrix