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

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

package/docs/how-to/workflows/quick-spec.md

@@ -0,0 +1,159 @@
+---
+title: "How to Use Quick Spec"
+description: How to create a technical specification using Quick Spec workflow
+---
+
+
+Use the `tech-spec` workflow for Quick Flow projects to go directly from idea to implementation-ready specification.
+
+---
+
+## When to Use This
+
+- Bug fixes and small enhancements
+- Small features with clear scope (1-15 stories)
+- Rapid prototyping
+- Adding to existing brownfield codebase
+- Quick Flow track projects
+
+---
+
+## Prerequisites
+
+- BMad Method installed
+- PM agent or Quick Flow Solo Dev agent available
+- Project directory (can be empty for greenfield)
+
+---
+
+## Steps
+
+### 1. Load the PM Agent
+
+Start a fresh chat and load the PM agent (or Quick Flow Solo Dev agent).
+
+### 2. Run the Tech Spec Workflow
+
+```
+*quick-spec
+```
+
+Or simply describe what you want to build:
+
+```
+I want to fix the login validation bug
+```
+
+### 3. Answer Discovery Questions
+
+The workflow will ask:
+- What problem are you solving?
+- What's the scope of the change?
+- Any specific constraints?
+
+### 4. Review Detected Context
+
+For brownfield projects, the agent will:
+- Detect your project stack
+- Analyze existing code patterns
+- Detect test frameworks
+- Ask: "Should I follow these existing conventions?"
+
+### 5. Get Your Tech Spec
+
+The agent generates a comprehensive tech-spec with ready-to-implement stories.
+
+---
+
+## What You Get
+
+### tech-spec.md
+
+- Problem statement and solution
+- Detected framework versions and dependencies
+- Brownfield code patterns (if applicable)
+- Existing test patterns to follow
+- Specific file paths to modify
+- Complete implementation guidance
+
+### Story Files
+
+For single changes:
+- `story-[slug].md` - Single user story ready for development
+
+For small features:
+- `epics.md` - Epic organization
+- `story-[epic-slug]-1.md`, `story-[epic-slug]-2.md`, etc.
+
+---
+
+## Example: Bug Fix (Single Change)
+
+**You:** "I want to fix the login validation bug that allows empty passwords"
+
+**Agent:**
+1. Asks clarifying questions about the issue
+2. Detects your Node.js stack (Express 4.18.2, Jest for testing)
+3. Analyzes existing UserService code patterns
+4. Asks: "Should I follow your existing conventions?" → Yes
+5. Generates tech-spec.md with specific file paths
+6. Creates story-login-fix.md
+
+**Total time:** 15-30 minutes (mostly implementation)
+
+---
+
+## Example: Small Feature (Multi-Story)
+
+**You:** "I want to add OAuth social login (Google, GitHub)"
+
+**Agent:**
+1. Asks about feature scope
+2. Detects your stack (Next.js 13.4, NextAuth.js already installed!)
+3. Analyzes existing auth patterns
+4. Confirms conventions
+5. Generates:
+   - tech-spec.md (comprehensive implementation guide)
+   - epics.md (OAuth Integration epic)
+   - story-oauth-1.md (Backend OAuth setup)
+   - story-oauth-2.md (Frontend login buttons)
+
+**Total time:** 1-3 hours (mostly implementation)
+
+---
+
+## Implementing After Tech Spec
+
+```bash
+# Single change:
+# Load DEV agent and run dev-story
+
+# Multi-story feature:
+# Optional: Load SM agent and run sprint-planning
+# Then: Load DEV agent and run dev-story for each story
+```
+
+---
+
+## Tips
+
+### Be Specific in Discovery
+
+- ✅ "Fix email validation in UserService to allow plus-addressing"
+- ❌ "Fix validation bug"
+
+### Trust Convention Detection
+
+If it detects your patterns correctly, say yes! It's faster than establishing new conventions.
+
+### Keep Single Changes Atomic
+
+If your "single change" needs 3+ files, it might be a multi-story feature. Let the workflow guide you.
+
+---
+
+## Related
+
+- [Quick Flow](/docs/explanation/features/quick-flow.md) - Understanding Quick Spec Flow
+- [Implement Story](/docs/how-to/workflows/implement-story.md) - After tech spec
+- [Create PRD](/docs/how-to/workflows/create-prd.md) - For larger projects needing full BMad Method

package/docs/how-to/workflows/run-brainstorming-session.md

@@ -0,0 +1,94 @@
+---
+title: "How to Run a Brainstorming Session"
+description: How to run a brainstorming session using the BMad Method
+---
+
+
+Use the `brainstorm-project` workflow to explore solution approaches through parallel ideation tracks.
+
+---
+
+## When to Use This
+
+- Very vague or seed kernel of an idea that needs exploration
+- Consider alternatives or enhancements to an idea
+- See your idea from different angles and viewpoints
+- No idea what you want to build, but want to find some inspiration
+
+---
+
+## Prerequisites
+
+- BMad Method installed
+- Analyst agent available
+
+---
+
+## Steps
+
+### 1. Load the Analyst Agent
+
+Start a fresh chat and load the Analyst agent.
+
+### 2. Run the Brainstorm Workflow
+
+```
+*brainstorm-project
+```
+
+### 3. Describe Your Idea
+
+Tell the agent about your project idea, even if it's vague:
+
+- "I want to build something that helps developers manage their context"
+- "I have a game idea about resource management"
+- "I need a tool for my team but I'm not sure what exactly"
+
+### 4. Explore the Tracks
+
+The workflow generates solution approaches through parallel ideation tracks:
+
+- **Architecture track** - Technical approaches and patterns
+- **UX track** - User experience possibilities
+- **Integration track** - How it connects with other systems
+- **Value track** - Business value and differentiation
+
+### 5. Evaluate Options
+
+Review the generated options with rationale for each approach.
+
+---
+
+## What You Get
+
+- Multiple solution approaches with trade-offs
+- Different architectural options
+- UX and integration considerations
+- Clear rationale for each direction
+
+---
+
+## Next Steps
+
+After brainstorming:
+
+1. **Research** - Validate ideas with market/technical research
+2. **Product Brief** - Capture strategic vision
+3. **PRD** - Move to formal planning
+
+---
+
+## Tips
+
+- Don't worry about having a fully formed idea
+- Let the agent guide the exploration
+- Consider multiple tracks before deciding
+- Use outputs as input for product-brief workflow
+
+---
+
+## Related
+
+- [Conduct Research](/docs/how-to/workflows/conduct-research.md) - Validate your ideas
+- [Create Product Brief](/docs/how-to/workflows/create-product-brief.md) - Capture strategic vision
+- [Create PRD](/docs/how-to/workflows/create-prd.md) - Move to formal planning

package/docs/how-to/workflows/run-code-review.md

@@ -0,0 +1,141 @@
+---
+title: "How to Run Code Review"
+description: How to run code review for quality assurance
+---
+
+
+Use the `code-review` workflow to perform a thorough quality review of implemented code.
+
+---
+
+## When to Use This
+
+- After dev-story completes implementation
+- Before marking a story as DONE
+- Every story goes through code review - no exceptions
+
+---
+
+## Prerequisites
+
+- BMad Method installed
+- DEV agent available
+- Story implementation complete
+- Tests written and passing
+
+---
+
+## Steps
+
+### 1. Load the DEV Agent
+
+Start a fresh chat (or continue from dev-story) and load the DEV agent.
+
+### 2. Run the Workflow
+
+```
+*code-review
+```
+
+### 3. Provide Context
+
+Point the agent to:
+- The story file
+- Files changed during implementation
+- Test files
+
+### 4. Review Findings
+
+The agent performs a senior developer code review and reports findings.
+
+### 5. Address Issues
+
+If issues are found:
+1. Fix issues using dev-story
+2. Re-run tests
+3. Run code-review again
+
+---
+
+## What Gets Reviewed
+
+The code review checks:
+
+### Code Quality
+- Clean, readable code
+- Appropriate abstractions
+- No code smells
+- Proper error handling
+
+### Architecture Alignment
+- Follows ADRs and architecture decisions
+- Consistent with existing patterns
+- Proper separation of concerns
+
+### Testing
+- Adequate test coverage
+- Tests are meaningful (not just for coverage)
+- Edge cases handled
+- Tests follow project patterns
+
+### Security
+- No hardcoded secrets
+- Input validation
+- Authentication/authorization proper
+- No common vulnerabilities
+
+### Performance
+- No obvious performance issues
+- Appropriate data structures
+- Efficient queries
+
+---
+
+## Review Outcomes
+
+### ✅ Approved
+
+- Code meets quality standards
+- Tests pass
+- **Action:** Mark story as DONE in sprint-status.yaml
+
+### 🔧 Changes Requested
+
+- Issues identified that need fixing
+- **Action:** Fix issues in dev-story, then re-run code-review
+
+---
+
+## Quality Gates
+
+Every story goes through code-review before being marked done. This ensures:
+
+- Consistent code quality
+- Architecture adherence
+- Test coverage
+- Security review
+
+---
+
+## Tips
+
+- Don't skip code review for "simple" changes
+- Address all findings, not just critical ones
+- Use findings as learning opportunities
+- Re-run review after fixes
+
+---
+
+## After Code Review
+
+1. **If approved:** Update sprint-status.yaml to mark story DONE
+2. **If changes requested:** Fix issues and re-run review
+3. **Move to next story:** Run create-story for the next item
+
+---
+
+## Related
+
+- [Implement Story](/docs/how-to/workflows/implement-story.md) - Before code review
+- [Create Story](/docs/how-to/workflows/create-story.md) - Move to next story
+- [Run Sprint Planning](/docs/how-to/workflows/run-sprint-planning.md) - Sprint organization