bmad-method 6.0.0-alpha.22 → 6.0.0-alpha.23

package/docs/how-to/workflows/create-architecture.md

@@ -0,0 +1,147 @@
+---
+title: "How to Create Architecture"
+description: How to create system architecture using the BMad Method
+---
+
+
+Use the `architecture` workflow to make technical decisions explicit and prevent agent conflicts during implementation.
+
+---
+
+## When to Use This
+
+- Multi-epic projects (BMad Method, Enterprise)
+- Cross-cutting technical concerns
+- Multiple agents implementing different parts
+- Integration complexity exists
+- Technology choices need alignment
+
+---
+
+## When to Skip This
+
+- Quick Flow (simple changes)
+- BMad Method Simple with straightforward tech stack
+- Single epic with clear technical approach
+
+---
+
+## Prerequisites
+
+- BMad Method installed
+- Architect agent available
+- PRD completed
+
+---
+
+## Steps
+
+### 1. Load the Architect Agent
+
+Start a fresh chat and load the Architect agent.
+
+### 2. Run the Architecture Workflow
+
+```
+*create-architecture
+```
+
+### 3. Engage in Discovery
+
+This is NOT a template filler. The architecture workflow:
+
+1. **Discovers** technical needs through conversation
+2. **Proposes** architectural options with trade-offs
+3. **Documents** decisions that prevent agent conflicts
+4. **Focuses** on decision points, not exhaustive documentation
+
+### 4. Document Key Decisions
+
+Work with the agent to create Architecture Decision Records (ADRs) for significant choices.
+
+### 5. Review the Architecture
+
+The agent produces a decision-focused architecture document.
+
+---
+
+## What You Get
+
+An `architecture.md` document containing:
+
+1. **Architecture Overview** - System context, principles, style
+2. **System Architecture** - High-level diagram, component interactions
+3. **Data Architecture** - Database design, state management, caching
+4. **API Architecture** - API style (REST/GraphQL/gRPC), auth, versioning
+5. **Frontend Architecture** - Framework, state management, components
+6. **Integration Architecture** - Third-party integrations, messaging
+7. **Security Architecture** - Auth/authorization, data protection
+8. **Deployment Architecture** - CI/CD, environments, monitoring
+9. **ADRs** - Key decisions with context, options, rationale
+10. **FR/NFR-Specific Guidance** - Technical approach per requirement
+11. **Standards and Conventions** - Directory structure, naming, testing
+
+---
+
+## ADR Format
+
+```markdown
+## ADR-001: Use GraphQL for All APIs
+
+**Status:** Accepted | **Date:** 2025-11-02
+
+**Context:** PRD requires flexible querying across multiple epics
+
+**Decision:** Use GraphQL for all client-server communication
+
+**Options Considered:**
+1. REST - Familiar but requires multiple endpoints
+2. GraphQL - Flexible querying, learning curve
+3. gRPC - High performance, poor browser support
+
+**Rationale:**
+- PRD requires flexible data fetching (Epic 1, 3)
+- Mobile app needs bandwidth optimization (Epic 2)
+- Team has GraphQL experience
+
+**Consequences:**
+- Positive: Flexible querying, reduced versioning
+- Negative: Caching complexity, N+1 query risk
+- Mitigation: Use DataLoader for batching
+```
+
+---
+
+## Example
+
+E-commerce platform produces:
+- Monolith + PostgreSQL + Redis + Next.js + GraphQL
+- ADRs explaining each choice
+- FR/NFR-specific implementation guidance
+
+---
+
+## Tips
+
+- Focus on decisions that prevent agent conflicts
+- Use ADRs for every significant technology choice
+- Keep it practical - don't over-architect
+- Architecture is living - update as you learn
+
+---
+
+## Next Steps
+
+After architecture:
+
+1. **Create Epics and Stories** - Work breakdown informed by architecture
+2. **Implementation Readiness** - Gate check before Phase 4
+
+---
+
+## Related
+
+- [Create PRD](/docs/how-to/workflows/create-prd.md) - Requirements before architecture
+- [Create Epics and Stories](/docs/how-to/workflows/create-epics-and-stories.md) - Next step
+- [Run Implementation Readiness](/docs/how-to/workflows/run-implementation-readiness.md) - Gate check
+- [Why Solutioning Matters](/docs/explanation/architecture/why-solutioning-matters.md)

package/docs/how-to/workflows/create-epics-and-stories.md

@@ -0,0 +1,136 @@
+---
+title: "How to Create Epics and Stories"
+description: How to break PRD requirements into epics and stories using BMad Method
+---
+
+
+Use the `create-epics-and-stories` workflow to transform PRD requirements into bite-sized stories organized into deliverable epics.
+
+---
+
+## When to Use This
+
+- After architecture workflow completes
+- When PRD contains FRs/NFRs ready for implementation breakdown
+- Before implementation-readiness gate check
+
+---
+
+## Prerequisites
+
+- BMad Method installed
+- PM agent available
+- PRD completed
+- Architecture completed
+
+---
+
+## Why After Architecture?
+
+This workflow runs AFTER architecture because:
+
+1. **Informed Story Sizing** - Architecture decisions affect story complexity
+2. **Dependency Awareness** - Architecture reveals technical dependencies
+3. **Technical Feasibility** - Stories can be properly scoped knowing the tech stack
+4. **Consistency** - All stories align with documented architectural patterns
+
+---
+
+## Steps
+
+### 1. Load the PM Agent
+
+Start a fresh chat and load the PM agent.
+
+### 2. Run the Workflow
+
+```
+*create-epics-and-stories
+```
+
+### 3. Provide Context
+
+Point the agent to:
+- Your PRD (FRs/NFRs)
+- Your architecture document
+- Optional: UX design artifacts
+
+### 4. Review Epic Breakdown
+
+The agent organizes requirements into logical epics with user stories.
+
+### 5. Validate Story Quality
+
+Ensure each story has:
+- Clear acceptance criteria
+- Appropriate priority
+- Identified dependencies
+- Technical notes from architecture
+
+---
+
+## What You Get
+
+Epic files (one per epic) containing:
+
+1. **Epic objective and scope**
+2. **User stories with acceptance criteria**
+3. **Story priorities** (P0/P1/P2/P3)
+4. **Dependencies between stories**
+5. **Technical notes** referencing architecture decisions
+
+---
+
+## Example
+
+E-commerce PRD with FR-001 (User Registration), FR-002 (Product Catalog) produces:
+
+- **Epic 1: User Management** (3 stories)
+  - Story 1.1: User registration form
+  - Story 1.2: Email verification
+  - Story 1.3: Login/logout
+
+- **Epic 2: Product Display** (4 stories)
+  - Story 2.1: Product listing page
+  - Story 2.2: Product detail page
+  - Story 2.3: Search functionality
+  - Story 2.4: Category filtering
+
+Each story references relevant ADRs from architecture.
+
+---
+
+## Story Priority Levels
+
+| Priority | Meaning |
+|----------|---------|
+| **P0** | Critical - Must have for MVP |
+| **P1** | High - Important for release |
+| **P2** | Medium - Nice to have |
+| **P3** | Low - Future consideration |
+
+---
+
+## Tips
+
+- Keep stories small enough to complete in a session
+- Ensure acceptance criteria are testable
+- Document dependencies clearly
+- Reference architecture decisions in technical notes
+
+---
+
+## Next Steps
+
+After creating epics and stories:
+
+1. **Implementation Readiness** - Validate alignment before Phase 4
+2. **Sprint Planning** - Organize work for implementation
+
+---
+
+## Related
+
+- [Create Architecture](/docs/how-to/workflows/create-architecture.md) - Do this first
+- [Run Implementation Readiness](/docs/how-to/workflows/run-implementation-readiness.md) - Gate check
+- [Run Sprint Planning](/docs/how-to/workflows/run-sprint-planning.md) - Start implementation

package/docs/how-to/workflows/create-prd.md

@@ -0,0 +1,130 @@
+---
+title: "How to Create a PRD"
+description: How to create a Product Requirements Document using the BMad Method
+---
+
+
+Use the `prd` workflow to create a strategic Product Requirements Document with Functional Requirements (FRs) and Non-Functional Requirements (NFRs).
+
+---
+
+## When to Use This
+
+- Medium to large feature sets
+- Multi-screen user experiences
+- Complex business logic
+- Multiple system integrations
+- Phased delivery required
+
+---
+
+## Prerequisites
+
+- BMad Method installed
+- PM agent available
+- Optional: Product brief from Phase 1
+
+---
+
+## Steps
+
+### 1. Load the PM Agent
+
+Start a fresh chat and load the PM agent.
+
+### 2. Run the PRD Workflow
+
+```
+*create-prd
+```
+
+### 3. Provide Context
+
+The workflow will:
+- Load any existing product brief
+- Ask about your project scope
+- Gather requirements through conversation
+
+### 4. Define Requirements
+
+Work with the agent to define:
+- Functional Requirements (FRs) - What the system should do
+- Non-Functional Requirements (NFRs) - How well it should do it
+
+### 5. Review the PRD
+
+The agent produces a comprehensive PRD scaled to your project.
+
+---
+
+## What You Get
+
+A `PRD.md` document containing:
+
+- Executive summary
+- Problem statement
+- User personas
+- Functional requirements (FRs)
+- Non-functional requirements (NFRs)
+- Success metrics
+- Risks and assumptions
+
+---
+
+## Scale-Adaptive Structure
+
+The PRD adapts to your project complexity:
+
+| Scale | Pages | Focus |
+|-------|-------|-------|
+| **Light** | 10-15 | Focused FRs/NFRs, simplified analysis |
+| **Standard** | 20-30 | Comprehensive FRs/NFRs, thorough analysis |
+| **Comprehensive** | 30-50+ | Extensive FRs/NFRs, multi-phase, stakeholder analysis |
+
+---
+
+## V6 Improvement
+
+In V6, the PRD focuses on **WHAT** to build (requirements). Epic and Stories are created **AFTER** architecture via the `create-epics-and-stories` workflow for better quality.
+
+---
+
+## Example
+
+E-commerce checkout → PRD with:
+- 15 FRs (user account, cart management, payment flow)
+- 8 NFRs (performance, security, scalability)
+
+---
+
+## Best Practices
+
+### 1. Do Product Brief First
+
+Run product-brief from Phase 1 to kickstart the PRD for better results.
+
+### 2. Focus on "What" Not "How"
+
+Planning defines **what** to build and **why**. Leave **how** (technical design) to Phase 3 (Solutioning).
+
+### 3. Document-Project First for Brownfield
+
+Always run `document-project` before planning brownfield projects. AI agents need existing codebase context.
+
+---
+
+## Next Steps
+
+After PRD:
+
+1. **Create UX Design** (optional) - If UX is critical
+2. **Create Architecture** - Technical design
+3. **Create Epics and Stories** - After architecture
+
+---
+
+## Related
+
+- [Create Product Brief](/docs/how-to/workflows/create-product-brief.md) - Input for PRD
+- [Create UX Design](/docs/how-to/workflows/create-ux-design.md) - Optional UX workflow
+- [Create Architecture](/docs/how-to/workflows/create-architecture.md) - Next step after PRD

package/docs/how-to/workflows/create-product-brief.md

@@ -0,0 +1,117 @@
+---
+title: "How to Create a Product Brief"
+description: How to create a product brief using the BMad Method
+---
+
+
+Use the `product-brief` workflow to define product vision and strategy through an interactive process.
+
+---
+
+## When to Use This
+
+- Starting new product or major feature initiative
+- Aligning stakeholders before detailed planning
+- Transitioning from exploration to strategy
+- Need executive-level product documentation
+
+---
+
+## Prerequisites
+
+- BMad Method installed
+- Analyst agent available
+- Optional: Research documents from previous workflows
+
+---
+
+## Steps
+
+### 1. Load the Analyst Agent
+
+Start a fresh chat and load the Analyst agent.
+
+### 2. Run the Product Brief Workflow
+
+```
+*product-brief
+```
+
+### 3. Answer the Interactive Questions
+
+The workflow guides you through strategic product vision definition:
+
+- What problem are you solving?
+- Who are your target users?
+- What makes this solution different?
+- What's the MVP scope?
+
+### 4. Review and Refine
+
+The agent will draft sections and let you refine them interactively.
+
+---
+
+## What You Get
+
+The `product-brief.md` document includes:
+
+- **Executive summary** - High-level overview
+- **Problem statement** - With evidence
+- **Proposed solution** - And differentiators
+- **Target users** - Segmented
+- **MVP scope** - Ruthlessly defined
+- **Financial impact** - And ROI
+- **Strategic alignment** - With business goals
+- **Risks and open questions** - Documented upfront
+
+---
+
+## Integration with Other Workflows
+
+The product brief feeds directly into the PRD workflow:
+
+| Analysis Output | Planning Input |
+|-----------------|----------------|
+| product-brief.md | **prd** workflow |
+| market-research.md | **prd** context |
+| technical-research.md | **architecture** (Phase 3) |
+
+Planning workflows automatically load the product brief if it exists.
+
+---
+
+## Common Patterns
+
+### Greenfield Software (Full Analysis)
+
+```
+1. brainstorm-project - explore approaches
+2. research (market/technical/domain) - validate viability
+3. product-brief - capture strategic vision
+4. → Phase 2: prd
+```
+
+### Skip Analysis (Clear Requirements)
+
+```
+→ Phase 2: prd or tech-spec directly
+```
+
+---
+
+## Tips
+
+- Be specific about the problem you're solving
+- Ruthlessly prioritize MVP scope
+- Document assumptions and risks
+- Use research findings as evidence
+- This is recommended for greenfield projects
+
+---
+
+## Related
+
+- [Run Brainstorming Session](/docs/how-to/workflows/run-brainstorming-session.md) - Explore ideas first
+- [Conduct Research](/docs/how-to/workflows/conduct-research.md) - Validate ideas
+- [Create PRD](/docs/how-to/workflows/create-prd.md) - Next step after product brief

package/docs/how-to/workflows/create-story.md

@@ -0,0 +1,119 @@
+---
+title: "How to Create a Story"
+description: How to create implementation-ready stories from epic backlog
+---
+
+
+Use the `create-story` workflow to prepare the next story from the epic backlog for implementation.
+
+---
+
+## When to Use This
+
+- Before implementing each story
+- When moving to the next story in an epic
+- After sprint-planning has been run
+
+---
+
+## Prerequisites
+
+- BMad Method installed
+- SM (Scrum Master) agent available
+- Sprint-status.yaml created by sprint-planning
+- Architecture and PRD available for context
+
+---
+
+## Steps
+
+### 1. Load the SM Agent
+
+Start a fresh chat and load the SM (Scrum Master) agent.
+
+### 2. Run the Workflow
+
+```
+*create-story
+```
+
+### 3. Specify the Story
+
+The agent will:
+- Read the sprint-status.yaml
+- Identify the next story to work on
+- Or let you specify a particular story
+
+### 4. Review the Story File
+
+The agent creates a comprehensive story file ready for development.
+
+---
+
+## What You Get
+
+A `story-[slug].md` file containing:
+
+- Story objective and scope
+- Acceptance criteria (specific, testable)
+- Technical implementation notes
+- References to architecture decisions
+- Dependencies on other stories
+- Definition of Done
+
+---
+
+## Story Content Sources
+
+The create-story workflow pulls from:
+
+- **PRD** - Requirements and acceptance criteria
+- **Architecture** - Technical approach and ADRs
+- **Epic file** - Story context and dependencies
+- **Existing code** - Patterns to follow (brownfield)
+
+---
+
+## Example Output
+
+```markdown
+
+## Objective
+Implement email verification flow for new user registrations.
+
+## Acceptance Criteria
+- [ ] User receives verification email within 30 seconds
+- [ ] Email contains unique verification link
+- [ ] Link expires after 24 hours
+- [ ] User can request new verification email
+
+## Technical Notes
+- Use SendGrid API per ADR-003
+- Store verification tokens in Redis per architecture
+- Follow existing email template patterns in /templates
+
+## Dependencies
+- Story 1.1 (User Registration) - DONE ✅
+
+## Definition of Done
+- All acceptance criteria pass
+- Tests written and passing
+- Code review approved
+```
+
+---
+
+## Tips
+
+- Complete one story before creating the next
+- Ensure dependencies are marked DONE before starting
+- Review technical notes for architecture alignment
+- Use the story file as context for dev-story
+
+---
+
+## Related
+
+- [Run Sprint Planning](/docs/how-to/workflows/run-sprint-planning.md) - Initialize tracking
+- [Implement Story](/docs/how-to/workflows/implement-story.md) - Next step
+- [Run Code Review](/docs/how-to/workflows/run-code-review.md) - After implementation