17 - BMAD Method: AI-Driven Agile Development

bmad-agent/
├── agents/                     # 21 specialized agents
│   ├── pm-agent.md             # Product Manager
│   ├── architect-agent.md      # System Architect
│   ├── developer-agent.md      # Developer
│   ├── ux-agent.md             # UX Designer
│   ├── sm-agent.md             # Scrum Master
│   ├── qa-agent.md             # Quality Assurance
│   ├── devops-agent.md         # DevOps Engineer
│   ├── data-agent.md           # Data Engineer
│   ├── security-agent.md       # Security Specialist
│   ├── tech-writer-agent.md    # Technical Writer
│   ├── analyst-agent.md        # Business Analyst
│   ├── design-agent.md         # System Designer
│   ├── frontend-agent.md       # Frontend Specialist
│   ├── backend-agent.md        # Backend Specialist
│   ├── mobile-agent.md         # Mobile Developer
│   ├── ml-agent.md             # ML Engineer
│   ├── performance-agent.md    # Performance Engineer
│   ├── migration-agent.md      # Migration Specialist
│   ├── review-agent.md         # Code Reviewer
│   ├── release-agent.md        # Release Manager
│   └── orchestrator-agent.md   # Agent Orchestrator
│
├── tasks/                      # 50+ guided workflows
│   ├── analysis/
│   │   ├── gather-requirements.md
│   │   ├── competitive-analysis.md
│   │   ├── user-persona-creation.md
│   │   └── risk-assessment.md
│   ├── planning/
│   │   ├── create-roadmap.md
│   │   ├── sprint-planning.md
│   │   ├── resource-allocation.md
│   │   └── milestone-definition.md
│   ├── architecture/
│   │   ├── system-design.md
│   │   ├── api-contract.md
│   │   ├── database-schema.md
│   │   └── integration-patterns.md
│   ├── implementation/
│   │   ├── feature-implementation.md
│   │   ├── code-generation.md
│   │   ├── refactoring-guide.md
│   │   └── testing-strategy.md
│   └── delivery/
│       ├── deployment-plan.md
│       ├── release-checklist.md
│       ├── monitoring-setup.md
│       └── post-mortem.md
│
├── templates/                  # Reusable templates
│   ├── prd-template.md         # Product Requirements Document
│   ├── adr-template.md         # Architecture Decision Record
│   ├── epic-template.md        # Epic/Feature template
│   ├── story-template.md       # User Story template
│   └── test-plan-template.md   # Test Plan template
│
├── personas/                   # Persona configurations
│   ├── startup-mode.md         # Lean startup mode
│   ├── enterprise-mode.md      # Rigorous enterprise mode
│   └── solo-dev-mode.md        # Single developer mode
│
└── checklists/                 # Quality checklists
    ├── code-review.md
    ├── security-audit.md
    ├── accessibility.md
    └── performance.md

# API Shard: Create Booking

## Endpoint
POST /api/v1/bookings

## Description
Creates a new booking for a registered user.

## Authentication
Bearer JWT Token (roles: USER, ADMIN)

## Input Schema
{
  "roomId": "string (UUID, required)",
  "checkIn": "string (ISO 8601, required)",
  "checkOut": "string (ISO 8601, required)",
  "guests": "number (1-10, required)",
  "notes": "string (max 500 char, optional)"
}

## Validations
1. checkOut must be after checkIn
2. Minimum duration is 1 night
3. Maximum duration is 30 nights
4. The room must exist and be available for the period
5. The user must not have overlapping bookings

## Responses
- 201 Created: booking created successfully
- 400 Bad Request: validation failed
- 401 Unauthorized: missing or invalid token
- 404 Not Found: room not found
- 409 Conflict: room not available for the period

## Dependencies
- Shard: room-availability-service
- Shard: user-validation-middleware
- Shard: booking-entity-schema

## Required Tests
- Happy path with valid data
- Date validation (checkOut before checkIn)
- Room not available (conflict)
- Unauthenticated user
- Overlapping booking

# PM Agent - Product Manager

## Identity
You are an experienced Product Manager with 15+ years of experience in B2B
and B2C software products. You excel at requirements gathering, stakeholder
needs analysis, and strategic roadmap definition.

## Specific Competencies
- Requirements elicitation techniques (interviews, workshops, surveys)
- Prioritization frameworks (MoSCoW, RICE, Kano)
- Product Requirements Document (PRD) creation
- Success metrics definition (KPI, OKR)
- Competitive analysis and positioning

## Available Workflows
1. gather-requirements: Structured requirements gathering
2. competitive-analysis: Competitive landscape analysis
3. user-persona-creation: Detailed user persona creation
4. prd-creation: Product Requirements Document drafting
5. roadmap-planning: Product roadmap planning

## Templates
- prd-template.md: Requirements document template
- epic-template.md: Epic/feature template
- story-template.md: User stories template

## Interaction Rules
1. Always ask clarifying questions before proceeding
2. Quantify requirements when possible (numbers, metrics, SLA)
3. Identify and document risks for each critical requirement
4. Always distinguish between MUST, SHOULD, COULD and WON'T (MoSCoW)
5. Produce artifacts in shard format for consumption by other agents

# Architect Agent - System Architect

## Identity
You are a senior System Architect with experience in distributed architectures,
microservices, event-driven and serverless. You balance pragmatism and technical
rigor in architectural decisions.

## Specific Competencies
- Scalable architecture design (vertical and horizontal)
- Architectural patterns (DDD, CQRS, Event Sourcing, Hexagonal)
- API Design (REST, GraphQL, gRPC)
- Database selection (SQL vs NoSQL vs NewSQL)
- Trade-off analysis (CAP theorem, performance vs consistency)
- Security by design

## Expected Output
For each architectural decision, produce:
1. ADR (Architecture Decision Record) in shard format
2. Component diagram (textual description for mermaid)
3. API contract shard for each interface
4. Database schema shard
5. List of constraints and assumptions

## Rules
1. Every decision must have an ADR with alternatives considered
2. Prefer simple solutions over elegant solutions
3. Document trade-offs explicitly
4. Define interfaces before implementations
5. Always consider scalability, security, and maintainability

# Developer Agent - Full-Stack Developer

## Identity
You are an experienced full-stack developer with mastery of TypeScript,
Java, Python and Go. You write clean, testable and maintainable code.
You follow community best practices and SOLID principles.

## Specific Competencies
- TypeScript/JavaScript (Node.js, Angular, React, Next.js)
- Java (Spring Boot, Hibernate)
- Python (FastAPI, Django)
- Database (PostgreSQL, MongoDB, Redis)
- Testing (Jest, JUnit, pytest)
- Clean Code and Design Patterns

## Workflow
1. Read the shard for the feature/endpoint to implement
2. Read the relevant architecture shard
3. Implement the code following project conventions
4. Write unit tests with coverage > 80%
5. Run lint and type check
6. Update the module STATUS.md

## Rules
1. Never use `any` in TypeScript without a justification comment
2. Every public function must have JSDoc/JavaDoc
3. Explicit error handling, never empty catches
4. Follow the naming convention defined in CLAUDE.md
5. Respect the interfaces defined by the Architect Agent

# Workflow: Structured Requirements Gathering

## Prerequisites
- Access to the client/stakeholder (or brief document)
- PRD template (prd-template.md)
- Standard questions checklist

## Steps

### Step 1: Context Understanding
- What problem does the product solve?
- Who are the target users?
- What are the business constraints (budget, timeline, compliance)?
- Are there legacy systems to integrate?

### Step 2: Functional Elicitation
For each identified macro-feature:
1. Define the main use case (happy path)
2. Identify edge cases
3. Define acceptance criteria (Given/When/Then)
4. Classify priority (MoSCoW)
5. Estimate relative complexity (S/M/L/XL)

### Step 3: Non-Functional Requirements
- Performance: expected response times (p50, p95, p99)
- Scalability: expected concurrent users (now, 6 months, 1 year)
- Availability: target SLA (99.9%? 99.99%?)
- Security: compliance requirements (GDPR, SOC2, PCI-DSS)
- Accessibility: target WCAG level (A, AA, AAA)

### Step 4: Artifact Production
Generate the following shards:
1. shard-prd-overview.md (project overview)
2. shard-personas.md (user personas)
3. shard-requirements-functional.md (functional requirements)
4. shard-requirements-nonfunctional.md (non-functional requirements)
5. shard-constraints.md (constraints and assumptions)
6. shard-risks.md (identified risks)

### Step 5: Validation
- Review each shard for completeness
- Verify that every requirement is testable
- Confirm priorities with the stakeholder

# Workflow: System Design

## Required Input
- shard-prd-overview.md
- shard-requirements-functional.md
- shard-requirements-nonfunctional.md
- shard-constraints.md

## Steps

### Step 1: Component Identification
Read the functional requirements and identify:
- Bounded contexts (DDD)
- Main services
- External integrations
- Persistence layers

### Step 2: Architectural Pattern Selection
Evaluate and document in ADR:
- Monolith vs Microservices vs Modular Monolith
- Sync vs Async communication
- SQL vs NoSQL for each bounded context
- Hosting: Cloud vs On-premise vs Hybrid

### Step 3: Interface Design
For each service/module:
1. Define API contract (OpenAPI/Protobuf)
2. Define event schema (for async communication)
3. Define database schema
4. Document in separate shards

### Step 4: Security Design
- Authentication: method and flow
- Authorization: model (RBAC, ABAC, ReBAC)
- Encryption: at rest and in transit
- Threat model (STRIDE)

### Step 5: Architectural Shard Production
1. shard-architecture-overview.md
2. shard-adr-{decision}.md (one per decision)
3. shard-api-{service}.md (one per API)
4. shard-db-{context}.md (schema per bounded context)
5. shard-security-model.md

# Workflow: Feature Implementation

## Required Input
- shard-api-{endpoint}.md (endpoint contract)
- shard-db-{context}.md (database schema)
- shard-architecture-overview.md (architectural constraints)

## Steps

### Step 1: Shard Analysis
1. Read the shard for the endpoint/feature to implement
2. Identify dependencies on other shards
3. Verify that all interfaces are defined

### Step 2: Scaffolding
1. Create the necessary files following the project structure
2. Define TypeScript/Java interfaces for the types
3. Create stubs for the main methods

### Step 3: TDD Implementation
For each feature in the shard:
1. Write the test that verifies expected behavior
2. Implement the minimum code to pass the test
3. Refactor while keeping tests green
4. Repeat for the next feature

### Step 4: Integration
1. Verify compatibility with defined interfaces
2. Run integration tests
3. Verify compliance with the architecture shard

### Step 5: Quality
1. Run linter and type checker
2. Verify coverage > 80%
3. Document API with JSDoc/JavaDoc
4. Update STATUS.md

# BMAD Solo Developer Mode

## Active Agents
1. PM Agent (lightweight): only user stories and acceptance criteria
2. Developer Agent: implementation + testing
3. DevOps Agent: only deployment configuration

## Simplified Workflow
1. Define the problem in 1 paragraph
2. List the main features (max 10)
3. For each feature, write 1 user story with acceptance criteria
4. Implement with TDD
5. Deploy

## Minimum Shards
- overview.md: what the project does, for whom, why
- features.md: feature list with priorities
- tech-stack.md: chosen technologies with rationale
- For each feature: 1 shard with interface + test criteria

## Rules
- No formal ADRs for obvious decisions
- Unit tests only for complex business logic
- Inline documentation (JSDoc) instead of separate documents
- Continuous deployment without formal releases

┌─────────────────────────────────────────────────────────────────┐
│                      PHASE 1: ANALYSIS                          │
│  PM Agent ──→ Analyst Agent ──→ UX Agent                        │
│  Output: PRD shards, Personas, Requirements, Risks              │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                     PHASE 2: PLANNING                           │
│  SM Agent ──→ PM Agent                                          │
│  Output: Roadmap, Sprint Backlog, Milestones                    │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                   PHASE 3: ARCHITECTURE                         │
│  Architect Agent ──→ Designer Agent ──→ Security Agent          │
│  Output: ADR shards, API contracts, DB schemas, Security model  │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                 PHASE 4: IMPLEMENTATION                          │
│  Developer ──→ QA ──→ DevOps ──→ Tech Writer                   │
│  Output: Code, Tests, Pipeline, Documentation                   │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                           ▼
                    ┌──────────────┐
                    │   DELIVERY   │
                    │  Release +   │
                    │  Monitoring  │
                    └──────────────┘

# Clone the BMAD template
git clone https://github.com/bmad-method/bmad-agent.git .bmad

# Create the base structure in the project
mkdir -p .bmad/{agents,tasks,templates,shards}

# Copy the agents needed for the chosen scale level
# Example: "Small" level (6 agents)
cp .bmad/agents/{pm-agent,architect-agent,developer-agent,qa-agent,devops-agent,tech-writer-agent}.md \
   .bmad/agents/

# Copy the relevant workflows
cp -r .bmad/tasks/{analysis,architecture,implementation} .bmad/tasks/

# Configure CLAUDE.md to integrate BMAD
cat >> CLAUDE.md << 'EOF'

## BMAD Configuration
- Agents directory: .bmad/agents/
- Tasks directory: .bmad/tasks/
- Shards directory: .bmad/shards/
- Active scale: Small (6 agents)

When starting a new task, always:
1. Check which shard is relevant in .bmad/shards/
2. Follow the appropriate workflow in .bmad/tasks/
3. Produce output as new shards when generating documentation
EOF

# .bmad/shards/project-overview.md

# Project Overview Shard

## Project Name
BookingAPI - Online Booking System

## Problem
Small hotels and B&Bs lack a modern, affordable, and easily
embeddable booking system for their websites.

## Solution
REST API + Embeddable widget for booking management with
availability calendar, payments, and notifications.

## Technology Stack
- Backend: Node.js + Express + TypeScript
- Database: PostgreSQL
- Cache: Redis
- Auth: JWT + OAuth2
- Deploy: Docker + Railway

## Target Users
1. Small hotel/B&B owners (admin)
2. Guests who book (end user)
3. Developers who integrate the widget (developer)

## Constraints
- Budget: $0 infrastructure (free tier)
- Timeline: MVP in 2 weeks
- Compliance: GDPR for user data
- Accessibility: WCAG 2.1 AA

## Related Shards
- shard-personas.md
- shard-requirements-functional.md
- shard-architecture-overview.md

# Method 1: Direct prompt with agent context
claude "Read .bmad/agents/architect-agent.md to assume the architect role.
Then read .bmad/shards/project-overview.md and .bmad/shards/requirements-functional.md.
Follow the workflow in .bmad/tasks/architecture/system-design.md to produce
the architectural design. Save each output as a separate shard in .bmad/shards/"

# Method 2: Custom slash command
# In .claude/commands/bmad-architect.md:
# Assume the Architect Agent role from .bmad/agents/architect-agent.md
# Read relevant shards and produce architecture design shards

/bmad-architect "Booking system design"

# Method 3: Combination with Ralph Wiggum
# PROMPT.md with BMAD instructions + autonomous loop
cat PROMPT.md | claude --print --dangerously-skip-permissions

# CLAUDE.md

## Project
BookingAPI - Online Booking System

## BMAD Configuration
Scale: Small (6 agents active)

### Directory Structure
- `.bmad/agents/` - Agent configurations
- `.bmad/tasks/` - Guided workflows
- `.bmad/shards/` - Project documentation shards
- `.bmad/templates/` - Reusable templates

### Active Agents
1. PM Agent: requirements and product decisions
2. Architect Agent: system design and ADRs
3. Developer Agent: code implementation
4. QA Agent: testing strategy and execution
5. DevOps Agent: deployment and infrastructure
6. Tech Writer Agent: documentation

### Conventions
- Every new feature must start with a shard
- Every architecture decision needs an ADR shard
- Implementation follows TDD within BMAD workflows
- Shards are updated when implementation diverges

### Current Sprint
Read `.bmad/shards/sprint-current.md` for active tasks

## Development Commands
- `npm run dev` - Start development server
- `npm test` - Run test suite
- `npm run build` - Production build
- `npm run lint` - Lint check

# .claude/commands/bmad-pm.md
# Assume the PM Agent role from .bmad/agents/pm-agent.md
# Gather requirements and produce shards

Read .bmad/agents/pm-agent.md to understand your role.
Then follow the workflow in .bmad/tasks/analysis/gather-requirements.md.
Save all outputs as shards in .bmad/shards/.
Ask clarifying questions before proceeding.

---

# .claude/commands/bmad-architect.md
# Assume the Architect Agent role from .bmad/agents/architect-agent.md
# Design system architecture based on requirement shards

Read .bmad/agents/architect-agent.md to understand your role.
Read all shards in .bmad/shards/ that start with "requirements-".
Follow the workflow in .bmad/tasks/architecture/system-design.md.
Produce architecture shards and ADRs.

---

# .claude/commands/bmad-implement.md
# Assume the Developer Agent role from .bmad/agents/developer-agent.md
# Implement the next feature based on architecture shards

Read .bmad/agents/developer-agent.md to understand your role.
Read .bmad/shards/sprint-current.md to identify the next task.
Read the relevant API and architecture shards.
Follow the workflow in .bmad/tasks/implementation/feature-implementation.md.
Use TDD: write tests first, then implement.

// src/bookings/booking.service.ts
// Generated by the Developer Agent following the api-bookings.md shard

import { Injectable, ConflictException, NotFoundException } from '@nestjs/common';
import { BookingRepository } from './booking.repository';
import { RoomService } from '../rooms/room.service';
import { CreateBookingDto, BookingResponse } from './booking.dto';

@Injectable()
export class BookingService {
  constructor(
    private readonly bookingRepo: BookingRepository,
    private readonly roomService: RoomService,
  ) {}

  /**
   * Creates a new booking after verifying availability.
   * @shard api-bookings.md - POST /api/v1/bookings
   */
  async createBooking(
    userId: string,
    dto: CreateBookingDto,
  ): Promise<BookingResponse> {
    // Verify room existence
    const room = await this.roomService.findById(dto.roomId);
    if (!room) {
      throw new NotFoundException('Room not found');
    }

    // Verify availability for the period
    const isAvailable = await this.roomService.checkAvailability(
      dto.roomId,
      dto.checkIn,
      dto.checkOut,
    );
    if (!isAvailable) {
      throw new ConflictException('Room not available for the requested period');
    }

    // Create booking
    const booking = await this.bookingRepo.create({
      userId,
      roomId: dto.roomId,
      checkIn: dto.checkIn,
      checkOut: dto.checkOut,
      guests: dto.guests,
      notes: dto.notes,
      status: 'CONFIRMED',
    });

    return this.toResponse(booking);
  }

  private toResponse(booking: any): BookingResponse {
    return {
      id: booking.id,
      roomId: booking.roomId,
      checkIn: booking.checkIn,
      checkOut: booking.checkOut,
      guests: booking.guests,
      status: booking.status,
      createdAt: booking.createdAt,
    };
  }
}