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

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

package/docs/how-to/workflows/create-ux-design.md

@@ -0,0 +1,117 @@
+---
+title: "How to Create a UX Design"
+description: How to create UX specifications using the BMad Method
+---
+
+
+Use the `create-ux-design` workflow to create UX specifications for projects where user experience is a primary differentiator.
+
+---
+
+## When to Use This
+
+- UX is primary competitive advantage
+- Complex user workflows needing design thinking
+- Innovative interaction patterns
+- Design system creation
+- Accessibility-critical experiences
+
+---
+
+## When to Skip This
+
+- Simple CRUD interfaces
+- Internal tools with standard patterns
+- Changes to existing screens you're happy with
+- Quick Flow projects
+
+---
+
+## Prerequisites
+
+- BMad Method installed
+- UX Designer agent available
+- PRD completed
+
+---
+
+## Steps
+
+### 1. Load the UX Designer Agent
+
+Start a fresh chat and load the UX Designer agent.
+
+### 2. Run the UX Design Workflow
+
+```
+*create-ux-design
+```
+
+### 3. Provide Context
+
+Point the agent to your PRD and describe:
+- Key user journeys
+- UX priorities
+- Any existing design patterns
+
+### 4. Collaborate on Design
+
+The workflow uses a collaborative approach:
+
+1. **Visual exploration** - Generate multiple options
+2. **Informed decisions** - Evaluate with user needs
+3. **Collaborative design** - Refine iteratively
+4. **Living documentation** - Evolves with project
+
+### 5. Review the UX Spec
+
+The agent produces comprehensive UX documentation.
+
+---
+
+## What You Get
+
+The `ux-spec.md` document includes:
+
+- User journeys
+- Wireframes and mockups
+- Interaction specifications
+- Design system (components, patterns, tokens)
+- Epic breakdown (UX stories)
+
+---
+
+## Example
+
+Dashboard redesign produces:
+- Card-based layout with split-pane toggle
+- 5 card components
+- 12 color tokens
+- Responsive grid
+- 3 epics (Layout, Visualization, Accessibility)
+
+---
+
+## Integration
+
+The UX spec feeds into:
+- PRD updates
+- Epic and story creation
+- Architecture decisions (Phase 3)
+
+---
+
+## Tips
+
+- Focus on user problems, not solutions first
+- Generate multiple options before deciding
+- Consider accessibility from the start
+- Document component reusability
+
+---
+
+## Related
+
+- [Create PRD](/docs/how-to/workflows/create-prd.md) - Create requirements first
+- [Create Architecture](/docs/how-to/workflows/create-architecture.md) - Technical design
+- [Create Epics and Stories](/docs/how-to/workflows/create-epics-and-stories.md) - Work breakdown

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

@@ -0,0 +1,127 @@
+---
+title: "How to Implement a Story"
+description: How to implement a story using the dev-story workflow
+---
+
+
+Use the `dev-story` workflow to implement a story with tests following the architecture and conventions.
+
+---
+
+## When to Use This
+
+- After create-story has prepared the story file
+- When ready to write code for a story
+- Story dependencies are marked DONE
+
+---
+
+## Prerequisites
+
+- BMad Method installed
+- DEV agent available
+- Story file created by create-story
+- Architecture and tech-spec available for context
+
+---
+
+## Steps
+
+### 1. Load the DEV Agent
+
+Start a fresh chat and load the DEV agent.
+
+### 2. Run the Workflow
+
+```
+*dev-story
+```
+
+### 3. Provide Story Context
+
+Point the agent to the story file created by create-story.
+
+### 4. Implement with Guidance
+
+The DEV agent:
+- Reads the story file and acceptance criteria
+- References architecture decisions
+- Follows existing code patterns
+- Implements with tests
+
+### 5. Complete Implementation
+
+Work with the agent until all acceptance criteria are met.
+
+---
+
+## What Happens
+
+The dev-story workflow:
+
+1. **Reads context** - Story file, architecture, existing patterns
+2. **Plans implementation** - Identifies files to create/modify
+3. **Writes code** - Following conventions and patterns
+4. **Writes tests** - Unit, integration, or E2E as appropriate
+5. **Validates** - Runs tests and checks acceptance criteria
+
+---
+
+## Key Principles
+
+### One Story at a Time
+
+Complete each story's full lifecycle before starting the next. This prevents context switching and ensures quality.
+
+### Follow Architecture
+
+The DEV agent references:
+- ADRs for technology decisions
+- Standards for naming and structure
+- Existing patterns in the codebase
+
+### Write Tests
+
+Every story includes appropriate tests:
+- Unit tests for business logic
+- Integration tests for API endpoints
+- E2E tests for critical flows
+
+---
+
+## After Implementation
+
+1. **Update sprint-status.yaml** - Mark story as READY FOR REVIEW
+2. **Run code-review** - Quality assurance
+3. **Address feedback** - If code review finds issues
+4. **Mark DONE** - After code review passes
+
+---
+
+## Tips
+
+- Keep the story file open for reference
+- Ask the agent to explain decisions
+- Run tests frequently during implementation
+- Don't skip tests for "simple" changes
+
+---
+
+## Troubleshooting
+
+**Q: Story needs significant changes mid-implementation?**
+A: Run `correct-course` to analyze impact and route appropriately.
+
+**Q: Can I work on multiple stories in parallel?**
+A: Not recommended. Complete one story's full lifecycle first.
+
+**Q: What if implementation reveals the story is too large?**
+A: Split the story and document the change.
+
+---
+
+## Related
+
+- [Create Story](/docs/how-to/workflows/create-story.md) - Prepare the story first
+- [Run Code Review](/docs/how-to/workflows/run-code-review.md) - After implementation
+- [Run Sprint Planning](/docs/how-to/workflows/run-sprint-planning.md) - Sprint organization