BMAD Tutorial

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#

/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 displayed

Step 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:                                  ║
║     /bmad:review --persona architect --retry                   ║
║                                                                ║
╚════════════════════════════════════════════════════════════════╝

Step 2: Check Feedback#

# Check current status
/bmad:status --phase solutioning

Output:

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 /bmad:review --persona architect --retry

Step 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#

/bmad:review --persona architect --retry

Output:

╔════════════════════════════════════════════════════════════════╗
║  🏗️ 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#

/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#

/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 displayed

AC 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