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

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

package/docs/how-to/workflows/run-implementation-readiness.md

@@ -0,0 +1,162 @@
+---
+title: "How to Run Implementation Readiness"
+description: How to validate planning and solutioning before implementation
+---
+
+
+Use the `implementation-readiness` workflow to validate that planning and solutioning are complete and aligned before Phase 4 implementation.
+
+---
+
+## When to Use This
+
+- **Always** before Phase 4 for BMad Method and Enterprise projects
+- After create-epics-and-stories workflow completes
+- Before sprint-planning workflow
+- When stakeholders request readiness check
+
+---
+
+## When to Skip This
+
+- Quick Flow (no solutioning phase)
+- BMad Method Simple (no gate check required)
+
+---
+
+## Prerequisites
+
+- BMad Method installed
+- Architect agent available
+- PRD, Architecture, and Epics completed
+
+---
+
+## Steps
+
+### 1. Load the Architect Agent
+
+Start a fresh chat and load the Architect agent.
+
+### 2. Run the Workflow
+
+```
+*implementation-readiness
+```
+
+### 3. Let the Agent Validate
+
+The workflow systematically checks:
+- PRD completeness
+- Architecture completeness
+- Epic/Story completeness
+- Alignment between all documents
+
+### 4. Review the Gate Decision
+
+The agent produces a gate decision with rationale.
+
+---
+
+## Gate Decision Outcomes
+
+### ✅ PASS
+
+- All critical criteria met
+- Minor gaps acceptable with documented plan
+- **Action:** Proceed to Phase 4
+
+### ⚠️ CONCERNS
+
+- Some criteria not met but not blockers
+- Gaps identified with clear resolution path
+- **Action:** Proceed with caution, address gaps in parallel
+
+### ❌ FAIL
+
+- Critical gaps or contradictions
+- Architecture missing key decisions
+- Epics conflict with PRD/architecture
+- **Action:** BLOCK Phase 4, resolve issues first
+
+---
+
+## What Gets Checked
+
+### PRD/GDD Completeness
+- Problem statement clear and evidence-based
+- Success metrics defined
+- User personas identified
+- Functional requirements (FRs) complete
+- Non-functional requirements (NFRs) specified
+- Risks and assumptions documented
+
+### Architecture Completeness
+- System architecture defined
+- Data architecture specified
+- API architecture decided
+- Key ADRs documented
+- Security architecture addressed
+- FR/NFR-specific guidance provided
+- Standards and conventions defined
+
+### Epic/Story Completeness
+- All PRD features mapped to stories
+- Stories have acceptance criteria
+- Stories prioritized (P0/P1/P2/P3)
+- Dependencies identified
+- Story sequencing logical
+
+### Alignment Checks
+- Architecture addresses all PRD FRs/NFRs
+- Epics align with architecture decisions
+- No contradictions between epics
+- NFRs have technical approach
+- Integration points clear
+
+---
+
+## What You Get
+
+An `implementation-readiness.md` document containing:
+
+1. **Executive Summary** (PASS/CONCERNS/FAIL)
+2. **Completeness Assessment** (scores for PRD, Architecture, Epics)
+3. **Alignment Assessment** (PRD↔Architecture, Architecture↔Epics)
+4. **Quality Assessment** (story quality, dependencies, risks)
+5. **Gaps and Recommendations** (critical/minor gaps, remediation)
+6. **Gate Decision** with rationale
+7. **Next Steps**
+
+---
+
+## Example
+
+E-commerce platform → CONCERNS ⚠️
+
+**Gaps identified:**
+- Missing security architecture section
+- Undefined payment gateway
+
+**Recommendation:**
+- Complete security section
+- Add payment gateway ADR
+
+**Action:** Proceed with caution, address before payment epic.
+
+---
+
+## Tips
+
+- Run this before every Phase 4 start
+- Take FAIL decisions seriously - fix issues first
+- Use CONCERNS as a checklist for parallel work
+- Document why you proceed despite concerns
+
+---
+
+## Related
+
+- [Create Architecture](/docs/how-to/workflows/create-architecture.md) - Architecture workflow
+- [Create Epics and Stories](/docs/how-to/workflows/create-epics-and-stories.md) - Work breakdown
+- [Run Sprint Planning](/docs/how-to/workflows/run-sprint-planning.md) - Start implementation

package/docs/how-to/workflows/run-sprint-planning.md

@@ -0,0 +1,111 @@
+---
+title: "How to Run Sprint Planning"
+description: How to initialize sprint tracking for implementation
+---
+
+
+Use the `sprint-planning` workflow to initialize the sprint tracking file and organize work for implementation.
+
+---
+
+## When to Use This
+
+- Once at the start of Phase 4 (Implementation)
+- After implementation-readiness gate passes
+- When starting a new sprint cycle
+
+---
+
+## Prerequisites
+
+- BMad Method installed
+- SM (Scrum Master) agent available
+- Epic files created from `create-epics-and-stories`
+- Implementation-readiness passed (for BMad Method/Enterprise)
+
+---
+
+## Steps
+
+### 1. Load the SM Agent
+
+Start a fresh chat and load the SM (Scrum Master) agent.
+
+### 2. Run the Workflow
+
+```
+*sprint-planning
+```
+
+### 3. Provide Context
+
+Point the agent to your epic files created during Phase 3.
+
+### 4. Review Sprint Organization
+
+The agent organizes stories into the sprint tracking file.
+
+---
+
+## What You Get
+
+A `sprint-status.yaml` file containing:
+
+- All epics with their stories
+- Story status tracking (TODO, IN PROGRESS, READY FOR REVIEW, DONE)
+- Dependencies between stories
+- Priority ordering
+
+---
+
+## Story Lifecycle States
+
+Stories move through these states in the sprint status file:
+
+| State | Description |
+|-------|-------------|
+| **TODO** | Story identified but not started |
+| **IN PROGRESS** | Story being implemented |
+| **READY FOR REVIEW** | Implementation complete, awaiting code review |
+| **DONE** | Accepted and complete |
+
+---
+
+## Typical Sprint Flow
+
+### Sprint 0 (Planning Phase)
+- Complete Phases 1-3
+- PRD/GDD + Architecture complete
+- Epics+Stories created via create-epics-and-stories
+
+### Sprint 1+ (Implementation Phase)
+
+**Start of Phase 4:**
+1. SM runs `sprint-planning` (once)
+
+**Per Story (repeat until epic complete):**
+1. SM runs `create-story`
+2. DEV runs `dev-story`
+3. DEV runs `code-review`
+4. Update sprint-status.yaml
+
+**After Epic Complete:**
+- SM runs `retrospective`
+- Move to next epic
+
+---
+
+## Tips
+
+- Run sprint-planning only once at Phase 4 start
+- Use `sprint-status` during Phase 4 to check current state
+- Keep the sprint-status.yaml file as single source of truth
+- Update story status after each stage
+
+---
+
+## Related
+
+- [Create Story](/docs/how-to/workflows/create-story.md) - Prepare stories for implementation
+- [Implement Story](/docs/how-to/workflows/implement-story.md) - Dev workflow
+- [Run Code Review](/docs/how-to/workflows/run-code-review.md) - Quality assurance