External/BMAD-METHOD
1
0
Fork 0
mirror of https://github.com/bmadcode/BMAD-METHOD.git synced 2025-12-29 16:14:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

installer updates working with basic flow

Browse Source
This commit is contained in:
Brian Madison
2025-12-05 22:32:59 -06:00
parent e3f756488a
commit 228dfa28a5
92 changed files with 10643 additions and 960 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
src/modules/bmm/docs/README.md
View File

@@ -139,6 +139,9 @@ Comprehensive documentation for all BMM workflows organized by phase:
- Complete story lifecycle
- One-story-at-a-time discipline
<<<<<<< Updated upstream
<<<<<<< Updated upstream
- **[Testing & QA Workflows](./test-architecture.md)** - Comprehensive quality assurance (1,420 lines)
- Test strategy, automation, quality gates
- TEA agent and test healing
@@ -146,6 +149,14 @@ Comprehensive documentation for all BMM workflows organized by phase:
**Total: 34 workflows documented across all phases**
=======
> > > > > > > Stashed changes
=======
> > > > > > > Stashed changes
### Advanced Workflow References
For detailed technical documentation on specific complex workflows:
@@ -170,10 +181,21 @@ Quality assurance guidance:
<!-- Test Architect documentation to be added -->
<<<<<<< Updated upstream
<<<<<<< Updated upstream
- Test design workflows
- Quality gates
- Risk assessment
- NFR validation
- # NFR validation
=======
> > > > > > > Stashed changes
- Test design workflows
- Quality gates
- Risk assessment
- NFR validation
> > > > > > > Stashed changes
---

15
src/modules/bmm/docs/brownfield-guide.md
View File

@@ -725,6 +725,13 @@ flowchart TD
- **[Quick Start Guide](./quick-start.md)** - Getting started with BMM
- **[Glossary](./glossary.md)** - Key terminology
- **[FAQ](./faq.md)** - Common questions
<<<<<<< Updated upstream
=======
- **[Troubleshooting](./troubleshooting.md)** - Problem resolution
<<<<<<< Updated upstream
> > > > > > > # Stashed changes
> > > > > > >
> > > > > > > Stashed changes
- **[Workflow Documentation](./README.md#-workflow-guides)** - Complete workflow reference
---
@@ -739,7 +746,13 @@ flowchart TD
**Documentation:**
- [Test Architect Guide](./test-architecture.md) - Comprehensive testing strategy
<<<<<<< Updated upstream
<<<<<<< Updated upstream
- # [Test Architect Guide](./test-architecture.md) - Comprehensive testing strategy
> > > > > > > # Stashed changes
> > > > > > >
> > > > > > > Stashed changes
- [BMM Module README](../README.md) - Complete module and workflow reference
---

14
src/modules/bmm/docs/glossary.md
View File

@@ -95,6 +95,20 @@ Game development equivalent of PRD, created by Game Designer agent for game proj
## Workflow and Phases
<<<<<<< Updated upstream
# <<<<<<< Updated upstream
=======
> > > > > > > Stashed changes
### Phase 0: Documentation (Prerequisite)
**Conditional phase for brownfield projects.** Creates comprehensive codebase documentation before planning. Only required if existing documentation is insufficient for AI agents.
> > > > > > > Stashed changes
### Phase 1: Analysis (Optional)
Discovery and research phase including brainstorming, research workflows, and product brief creation. Optional for Quick Flow, recommended for BMad Method, required for Enterprise Method.

652
src/modules/bmm/docs/quick-spec-flow.md Normal file
View File

@@ -0,0 +1,652 @@
# BMad Quick Spec Flow
**Perfect for:** Bug fixes, small features, rapid prototyping, and quick enhancements
**Time to implementation:** Minutes, not hours
---
## What is Quick Spec Flow?
Quick Spec Flow is a **streamlined alternative** to the full BMad Method for Quick Flow track projects. Instead of going through Product Brief → PRD → Architecture, you go **straight to a context-aware technical specification** and start coding.
### When to Use Quick Spec Flow
✅ **Use Quick Flow track when:**
- Single bug fix or small enhancement
- Small feature with clear scope (typically 1-15 stories)
- Rapid prototyping or experimentation
- Adding to existing brownfield codebase
- You know exactly what you want to build
❌ **Use BMad Method or Enterprise tracks when:**
- Building new products or major features
- Need stakeholder alignment
- Complex multi-team coordination
- Requires extensive planning and architecture
💡 **Not sure?** Run `workflow-init` to get a recommendation based on your project's needs!
---
## Quick Spec Flow Overview
```mermaid
flowchart TD
START[Step 1: Run Tech-Spec Workflow]
DETECT[Detects project stack<br/>package.json, requirements.txt, etc.]
ANALYZE[Analyzes brownfield codebase<br/>if exists]
TEST[Detects test frameworks<br/>and conventions]
CONFIRM[Confirms conventions<br/>with you]
GENERATE[Generates context-rich<br/>tech-spec]
STORIES[Creates ready-to-implement<br/>stories]
OPTIONAL[Step 2: Optional<br/>Generate Story Context<br/>SM Agent<br/>For complex scenarios only]
IMPL[Step 3: Implement<br/>DEV Agent<br/>Code, test, commit]
DONE[DONE! 🚀]
START --> DETECT
DETECT --> ANALYZE
ANALYZE --> TEST
TEST --> CONFIRM
CONFIRM --> GENERATE
GENERATE --> STORIES
STORIES --> OPTIONAL
OPTIONAL -.->|Optional| IMPL
STORIES --> IMPL
IMPL --> DONE
style START fill:#bfb,stroke:#333,stroke-width:2px
style OPTIONAL fill:#ffb,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5
style IMPL fill:#bbf,stroke:#333,stroke-width:2px
style DONE fill:#f9f,stroke:#333,stroke-width:3px
```
---
## Single Atomic Change
**Best for:** Bug fixes, single file changes, isolated improvements
### What You Get
1. **tech-spec.md** - Comprehensive technical specification with:
- 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
2. **story-[slug].md** - Single user story ready for development
### Quick Spec Flow Commands
```bash
# Start Quick Spec Flow (no workflow-init needed!)
# Load PM agent and run tech-spec
# When complete, implement directly:
# Load DEV agent and run dev-story
```
### What Makes It Quick
- ✅ No Product Brief needed
- ✅ No PRD needed
- ✅ No Architecture doc needed
- ✅ Auto-detects your stack
- ✅ Auto-analyzes brownfield code
- ✅ Auto-validates quality
- ✅ Story context optional (tech-spec is comprehensive!)
### Example Single Change Scenarios
- "Fix the login validation bug"
- "Add email field to user registration form"
- "Update API endpoint to return additional field"
- "Improve error handling in payment processing"
---
## Coherent Small Feature
**Best for:** Small features with 2-3 related user stories
### What You Get
1. **tech-spec.md** - Same comprehensive spec as single change projects
2. **epics.md** - Epic organization with story breakdown
3. **story-[epic-slug]-1.md** - First story
4. **story-[epic-slug]-2.md** - Second story
5. **story-[epic-slug]-3.md** - Third story (if needed)
### Quick Spec Flow Commands
```bash
# Start Quick Spec Flow
# Load PM agent and run tech-spec
# Optional: Organize stories as a sprint
# Load SM agent and run sprint-planning
# Implement story-by-story:
# Load DEV agent and run dev-story for each story
```
### Story Sequencing
Stories are **automatically validated** to ensure proper sequence:
- ✅ No forward dependencies (Story 2 can't depend on Story 3)
- ✅ Clear dependency documentation
- ✅ Infrastructure → Features → Polish order
- ✅ Backend → Frontend flow
### Example Small Feature Scenarios
- "Add OAuth social login (Google, GitHub, Twitter)"
- "Build user profile page with avatar upload"
- "Implement basic search with filters"
- "Add dark mode toggle to application"
---
## Smart Context Discovery
Quick Spec Flow automatically discovers and uses:
### 1. Existing Documentation
- Product briefs (if they exist)
- Research documents
- `document-project` output (brownfield codebase map)
### 2. Project Stack
- **Node.js:** package.json → frameworks, dependencies, scripts, test framework
- **Python:** requirements.txt, pyproject.toml → packages, tools
- **Ruby:** Gemfile → gems and versions
- **Java:** pom.xml, build.gradle → Maven/Gradle dependencies
- **Go:** go.mod → modules
- **Rust:** Cargo.toml → crates
- **PHP:** composer.json → packages
### 3. Brownfield Code Patterns
- Directory structure and organization
- Existing code patterns (class-based, functional, MVC)
- Naming conventions (camelCase, snake_case, PascalCase)
- Test frameworks and patterns
- Code style (semicolons, quotes, indentation)
- Linter/formatter configs
- Error handling patterns
- Logging conventions
- Documentation style
### 4. Convention Confirmation
**IMPORTANT:** Quick Spec Flow detects your conventions and **asks for confirmation**:
```
I've detected these conventions in your codebase:
Code Style:
- ESLint with Airbnb config
- Prettier with single quotes, 2-space indent
- No semicolons
Test Patterns:
- Jest test framework
- .test.js file naming
- expect() assertion style
Should I follow these existing conventions? (yes/no)
```
**You decide:** Conform to existing patterns or establish new standards!
---
## Modern Best Practices via WebSearch
Quick Spec Flow stays current by using WebSearch when appropriate:
### For Greenfield Projects
- Searches for latest framework versions
- Recommends official starter templates
- Suggests modern best practices
### For Outdated Dependencies
- Detects if your dependencies are >2 years old
- Searches for migration guides
- Notes upgrade complexity
### Starter Template Recommendations
For greenfield projects, Quick Spec Flow recommends:
**React:**
- Vite (modern, fast)
- Next.js (full-stack)
**Python:**
- cookiecutter templates
- FastAPI starter
**Node.js:**
- NestJS CLI
- express-generator
**Benefits:**
- ✅ Modern best practices baked in
- ✅ Proper project structure
- ✅ Build tooling configured
- ✅ Testing framework set up
- ✅ Faster time to first feature
---
## UX/UI Considerations
For user-facing changes, Quick Spec Flow captures:
- UI components affected (create vs modify)
- UX flow changes (current vs new)
- Responsive design needs (mobile, tablet, desktop)
- Accessibility requirements:
- Keyboard navigation
- Screen reader compatibility
- ARIA labels
- Color contrast standards
- User feedback patterns:
- Loading states
- Error messages
- Success confirmations
- Progress indicators
---
## Auto-Validation and Quality Assurance
Quick Spec Flow **automatically validates** everything:
### Tech-Spec Validation (Always Runs)
Checks:
- ✅ Context gathering completeness
- ✅ Definitiveness (no "use X or Y" statements)
- ✅ Brownfield integration quality
- ✅ Stack alignment
- ✅ Implementation readiness
Generates scores:
```
✅ Validation Passed!
- Context Gathering: Comprehensive
- Definitiveness: All definitive
- Brownfield Integration: Excellent
- Stack Alignment: Perfect
- Implementation Readiness: ✅ Ready
```
### Story Validation (Multi-Story Features)
Checks:
- ✅ Story sequence (no forward dependencies!)
- ✅ Acceptance criteria quality (specific, testable)
- ✅ Completeness (all tech spec tasks covered)
- ✅ Clear dependency documentation
**Auto-fixes issues if found!**
---
## Complete User Journey
### Scenario 1: Bug Fix (Single Change)
**Goal:** Fix login validation bug
**Steps:**
1. **Start:** Load PM agent, say "I want to fix the login validation bug"
2. **PM runs tech-spec workflow:**
- Asks: "What problem are you solving?"
- You explain the validation issue
- Detects your Node.js stack (Express 4.18.2, Jest for testing)
- Analyzes existing UserService code patterns
- Asks: "Should I follow your existing conventions?" → You say yes
- Generates tech-spec.md with specific file paths and patterns
- Creates story-login-fix.md
3. **Implement:** Load DEV agent, run `dev-story`
- DEV reads tech-spec (has all context!)
- Implements fix following existing patterns
- Runs tests (following existing Jest patterns)
- Done!
**Total time:** 15-30 minutes (mostly implementation)
---
### Scenario 2: Small Feature (Multi-Story)
**Goal:** Add OAuth social login (Google, GitHub)
**Steps:**
1. **Start:** Load PM agent, say "I want to add OAuth social login"
2. **PM runs tech-spec workflow:**
- Asks about the feature scope
- You specify: Google and GitHub OAuth
- Detects your stack (Next.js 13.4, NextAuth.js already installed!)
- Analyzes existing auth patterns
- Confirms conventions with you
- 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)
3. **Optional Sprint Planning:** Load SM agent, run `sprint-planning`
4. **Implement Story 1:**
- Load DEV agent, run `dev-story` for story 1
- DEV implements backend OAuth
5. **Implement Story 2:**
- DEV agent, run `dev-story` for story 2
- DEV implements frontend
- Done!
**Total time:** 1-3 hours (mostly implementation)
---
## Integration with Phase 4 Workflows
Quick Spec Flow works seamlessly with all Phase 4 implementation workflows:
### story-context (SM Agent)
- ✅ Recognizes tech-spec.md as authoritative source
- ✅ Extracts context from tech-spec (replaces PRD)
- ✅ Generates XML context for complex scenarios
### create-story (SM Agent)
- ✅ Can work with tech-spec.md instead of PRD
- ✅ Uses epics.md from tech-spec workflow
- ✅ Creates additional stories if needed
### sprint-planning (SM Agent)
- ✅ Works with epics.md from tech-spec
- ✅ Organizes multi-story features for coordinated implementation
- ✅ Tracks progress through sprint-status.yaml
### dev-story (DEV Agent)
- ✅ Reads stories generated by tech-spec
- ✅ Uses tech-spec.md as comprehensive context
- ✅ Implements following detected conventions
---
## Comparison: Quick Spec vs Full BMM
| Aspect | Quick Flow Track | BMad Method/Enterprise Tracks |
| --------------------- | ---------------------------- | ---------------------------------- |
| **Setup** | None (standalone) | workflow-init recommended |
| **Planning Docs** | tech-spec.md only | Product Brief → PRD → Architecture |
| **Time to Code** | Minutes | Hours to days |
| **Best For** | Bug fixes, small features | New products, major features |
| **Context Discovery** | Automatic | Manual + guided |
| **Story Context** | Optional (tech-spec is rich) | Required (generated from PRD) |
| **Validation** | Auto-validates everything | Manual validation steps |
| **Brownfield** | Auto-analyzes and conforms | Manual documentation required |
| **Conventions** | Auto-detects and confirms | Document in PRD/Architecture |
---
## When to Graduate from Quick Flow to BMad Method
Start with Quick Flow, but switch to BMad Method when:
- ❌ Project grows beyond initial scope
- ❌ Multiple teams need coordination
- ❌ Stakeholders need formal documentation
- ❌ Product vision is unclear
- ❌ Architectural decisions need deep analysis
- ❌ Compliance/regulatory requirements exist
💡 **Tip:** You can always run `workflow-init` later to transition from Quick Flow to BMad Method!
---
## Quick Spec Flow - Key Benefits
### 🚀 **Speed**
- No Product Brief
- No PRD
- No Architecture doc
- Straight to implementation
### 🧠 **Intelligence**
- Auto-detects stack
- Auto-analyzes brownfield
- Auto-validates quality
- WebSearch for current info
### 📐 **Respect for Existing Code**
- Detects conventions
- Asks for confirmation
- Follows patterns
- Adapts vs. changes
### ✅ **Quality**
- Auto-validation
- Definitive decisions (no "or" statements)
- Comprehensive context
- Clear acceptance criteria
### 🎯 **Focus**
- Single atomic changes
- Coherent small features
- No scope creep
- Fast iteration
---
## Getting Started
### Prerequisites
- BMad Method installed (`npx bmad-method install`)
- Project directory with code (or empty for greenfield)
### Quick Start Commands
```bash
# For a quick bug fix or small change:
# 1. Load PM agent
# 2. Say: "I want to [describe your change]"
# 3. PM will ask if you want to run tech-spec
# 4. Answer questions about your change
# 5. Get tech-spec + story
# 6. Load DEV agent and implement!
# For a small feature with multiple stories:
# Same as above, but get epic + 2-3 stories
# Optionally use SM sprint-planning to organize
```
### No workflow-init Required!
Quick Spec Flow is **fully standalone**:
- Detects if it's a single change or multi-story feature
- Asks for greenfield vs brownfield
- Works without status file tracking
- Perfect for rapid prototyping
---
## FAQ
### Q: Can I use Quick Spec Flow on an existing project?
**A:** Yes! It's perfect for brownfield projects. It will analyze your existing code, detect patterns, and ask if you want to follow them.
### Q: What if I don't have a package.json or requirements.txt?
**A:** Quick Spec Flow will work in greenfield mode, recommend starter templates, and use WebSearch for modern best practices.
### Q: Do I need to run workflow-init first?
**A:** No! Quick Spec Flow is standalone. But if you want guidance on which flow to use, workflow-init can help.
### Q: Can I use this for frontend changes?
**A:** Absolutely! Quick Spec Flow captures UX/UI considerations, component changes, and accessibility requirements.
### Q: What if my Quick Flow project grows?
**A:** No problem! You can always transition to BMad Method by running workflow-init and create-prd. Your tech-spec becomes input for the PRD.
### Q: Do I need story-context for every story?
**A:** Usually no! Tech-spec is comprehensive enough for most Quick Flow projects. Only use story-context for complex edge cases.
### Q: Can I skip validation?
**A:** No, validation always runs automatically. But it's fast and catches issues early!
### Q: Will it work with my team's code style?
**A:** Yes! It detects your conventions and asks for confirmation. You control whether to follow existing patterns or establish new ones.
---
## Tips and Best Practices
### 1. **Be Specific in Discovery**
When describing your change, provide specifics:
- ✅ "Fix email validation in UserService to allow plus-addressing"
- ❌ "Fix validation bug"
### 2. **Trust the Convention Detection**
If it detects your patterns correctly, say yes! It's faster than establishing new conventions.
### 3. **Use WebSearch Recommendations for Greenfield**
Starter templates save hours of setup time. Let Quick Spec Flow find the best ones.
### 4. **Review the Auto-Validation**
When validation runs, read the scores. They tell you if your spec is production-ready.
### 5. **Story Context is Optional**
For single changes, try going directly to dev-story first. Only add story-context if you hit complexity.
### 6. **Keep Single Changes Truly Atomic**
If your "single change" needs 3+ files, it might be a multi-story feature. Let the workflow guide you.
### 7. **Validate Story Sequence for Multi-Story Features**
When you get multiple stories, check the dependency validation output. Proper sequence matters!
---
## Real-World Examples
### Example 1: Adding Logging (Single Change)
**Input:** "Add structured logging to payment processing"
**Tech-Spec Output:**
- Detected: winston 3.8.2 already in package.json
- Analyzed: Existing services use winston with JSON format
- Confirmed: Follow existing logging patterns
- Generated: Specific file paths, log levels, format example
- Story: Ready to implement in 1-2 hours
**Result:** Consistent logging added, following team patterns, no research needed.
---
### Example 2: Search Feature (Multi-Story)
**Input:** "Add search to product catalog with filters"
**Tech-Spec Output:**
- Detected: React 18.2.0, MUI component library, Express backend
- Analyzed: Existing ProductList component patterns
- Confirmed: Follow existing API and component structure
- Generated:
- Epic: Product Search Functionality
- Story 1: Backend search API with filters
- Story 2: Frontend search UI component
- Auto-validated: Story 1 → Story 2 sequence correct
**Result:** Search feature implemented in 4-6 hours with proper architecture.
---
## Summary
Quick Spec Flow is your **fast path from idea to implementation** for:
- 🐛 Bug fixes
- ✨ Small features
- 🚀 Rapid prototyping
- 🔧 Quick enhancements
**Key Features:**
- Auto-detects your stack
- Auto-analyzes brownfield code
- Auto-validates quality
- Respects existing conventions
- Uses WebSearch for modern practices
- Generates comprehensive tech-specs
- Creates implementation-ready stories
**Time to code:** Minutes, not hours.
**Ready to try it?** Load the PM agent and say what you want to build! 🚀
---
## Next Steps
- **Try it now:** Load PM agent and describe a small change
- **Learn more:** See the [BMM Workflow Guides](./README.md#-workflow-guides) for comprehensive workflow documentation
- **Need help deciding?** Run `workflow-init` to get a recommendation
- **Have questions?** Join us on Discord: https://discord.gg/gk8jAdXWmj
---
_Quick Spec Flow - Because not every change needs a Product Brief._

680
src/modules/bmm/docs/troubleshooting.md Normal file
View File

@@ -0,0 +1,680 @@
# BMM Troubleshooting Guide
Common issues and solutions for the BMad Method Module.
---
## Quick Diagnosis
**Use this flowchart to find your issue:**
```mermaid
flowchart TD
START{What's the problem?}
START -->|Can't get started| SETUP[Setup & Installation Issues]
START -->|Wrong level detected| LEVEL[Level Detection Problems]
START -->|Workflow not working| WORKFLOW[Workflow Issues]
START -->|Agent lacks context| CONTEXT[Context & Documentation Issues]
START -->|Implementation problems| IMPL[Implementation Issues]
START -->|Files/paths wrong| FILES[File & Path Issues]
style START fill:#ffb,stroke:#333,stroke-width:2px
style SETUP fill:#bfb,stroke:#333,stroke-width:2px
style LEVEL fill:#bbf,stroke:#333,stroke-width:2px
style WORKFLOW fill:#fbf,stroke:#333,stroke-width:2px
style CONTEXT fill:#f9f,stroke:#333,stroke-width:2px
```
---
## Table of Contents
- [Setup and Installation Issues](#setup-and-installation-issues)
- [Level Detection Problems](#level-detection-problems)
- [Workflow Issues](#workflow-issues)
- [Context and Documentation Issues](#context-and-documentation-issues)
- [Implementation Issues](#implementation-issues)
- [File and Path Issues](#file-and-path-issues)
- [Agent Behavior Issues](#agent-behavior-issues)
- [Integration Issues (Brownfield)](#integration-issues-brownfield)
---
## Setup and Installation Issues
### Problem: BMM not found after installation
**Symptoms:**
- `bmad` command not recognized
- Agent files not accessible
- Workflows don't load
**Solution:**
```bash
# Check if BMM is installed
ls bmad/
# If not present, run installer
npx bmad-method@alpha install
# For fresh install
npx bmad-method@alpha install --skip-version-prompt
```
### Problem: Agents don't have menu
**Symptoms:**
- Load agent file but no menu appears
- Agent doesn't respond to commands
**Solution:**
1. Ensure you're loading the correct agent file path: `bmad/bmm/agents/[agent-name].md`
2. Wait a few seconds for agent to initialize
3. Try asking "show menu" or "help"
4. Check IDE supports Markdown rendering with context
5. For Claude Code: Ensure agent file is open in chat context
### Problem: Workflows not found
**Symptoms:**
- Agent says workflow doesn't exist
- Menu shows workflow but won't run
**Solution:**
1. Check workflow exists: `ls bmad/bmm/workflows/`
2. Verify agent has access to workflow (check agent's workflow list)
3. Try using menu number instead of workflow name
4. Restart chat with agent in fresh session
---
## Level Detection Problems
### Problem: workflow-init suggests wrong level
**Symptoms:**
- Detects Level 3 but you only need Level 1
- Suggests Level 1 but project is actually Level 2
- Can't figure out appropriate level
**Solution:**
1. **Override the suggestion** - workflow-init always asks for confirmation, just say "no" and choose correct level
2. **Be specific in description** - Use level keywords when describing:
- "fix bug" → Level 0
- "add small feature" → Level 1
- "build dashboard" → Level 2
3. **Manual override** - You can always switch levels later if needed
**Example:**
```
workflow-init: "Level 3 project?"
You: "No, this is just adding OAuth login - Level 1"
workflow-init: "Got it, creating Level 1 workflow"
```
### Problem: Project level unclear
**Symptoms:**
- Between Level 1 and Level 2
- Not sure if architecture needed
- Story count uncertain
**Solution:**
**When in doubt, start smaller:**
- Choose Level 1 instead of Level 2
- You can always run `create-prd` later if needed
- Level 1 is faster, less overhead
- Easy to upgrade, hard to downgrade
**Decision criteria:**
- Single epic with related stories? → Level 1
- Multiple independent epics? → Level 2
- Need product-level planning? → Level 2
- Just need technical plan? → Level 1
### Problem: Old planning docs influencing level detection
**Symptoms:**
- Old Level 3 PRD in folder
- Working on new Level 0 bug fix
- workflow-init suggests Level 3
**Solution:**
workflow-init asks: "Is this work in progress or previous effort?"
- Answer: "Previous effort"
- Then describe your NEW work clearly
- System will detect level based on NEW work, not old artifacts
---
## Workflow Issues
### Problem: Workflow fails or hangs
**Symptoms:**
- Workflow starts but doesn't complete
- Agent stops responding mid-workflow
- Progress stalls
**Solution:**
1. **Check context limits** - Start fresh chat for complex workflows
2. **Verify prerequisites**:
- Phase 2 needs Phase 1 complete (if used)
- Phase 3 needs Phase 2 complete
- Phase 4 needs Phase 3 complete (if Level 3-4)
3. **Restart workflow** - Load agent in new chat and restart
4. **Check status file** - Verify `bmm-workflow-status.md` or `sprint-status.yaml` is present and valid
### Problem: Agent says "workflow not found"
**Symptoms:**
- Request workflow by name
- Agent doesn't recognize it
- Menu doesn't show workflow
**Solution:**
1. Check spelling/format - Use exact workflow name or menu shortcut (*prd not *PRD)
2. Verify agent has workflow:
- PM agent: prd, tech-spec
- Architect agent: create-architecture, validate-architecture
- SM agent: sprint-planning, create-story, story-context
3. Try menu number instead of name
4. Check you're using correct agent for workflow
### Problem: Sprint-planning workflow fails
**Symptoms:**
- Can't create sprint-status.yaml
- Epics not extracted from files
- Status file empty or incorrect
**Solution:**
1. **Verify epic files exist**:
- Level 1: tech-spec with epic
- Level 2-4: epics.md or sharded epic files
2. **Check file format**:
- Epic files should be valid Markdown
- Epic headers should be clear (## Epic Name)
3. **Run in Phase 4 only** - Ensure Phase 2/3 complete first
4. **Check file paths** - Epic files should be in correct output folder
### Problem: story-context generates empty or wrong context
**Symptoms:**
- Context file created but has no useful content
- Context doesn't reference existing code
- Missing technical guidance
**Solution:**
1. **Run epic-tech-context first** - story-context builds on epic context
2. **Check story file exists** - Verify story was created by create-story
3. **For brownfield**:
- Ensure document-project was run
- Verify docs/index.md exists with codebase context
4. **Try regenerating** - Sometimes needs fresh attempt with more specific story details
---
## Context and Documentation Issues
### Problem: AI agents lack codebase understanding (Brownfield)
**Symptoms:**
- Suggestions don't align with existing patterns
- Ignores available components
- Proposes approaches that conflict with architecture
- Doesn't reference existing code
**Solution:**
1. **Run document-project** - Critical for brownfield projects
```
Load Analyst agent → run document-project
Choose scan level: Deep (recommended for PRD prep)
```
2. **Verify docs/index.md exists** - This is master entry point for AI agents
3. **Check documentation completeness**:
- Review generated docs/index.md
- Ensure key systems are documented
4. **Run deep-dive on specific areas** if needed
### Problem: Have documentation but agents can't find it
**Symptoms:**
- README.md, ARCHITECTURE.md exist
- AI agents still ask questions answered in docs
- No docs/index.md file
**Solution:**
**Option 1: Quick fix (2-5min)**
Run `index-docs` task:
- Located at `bmad/core/tasks/index-docs.xml`
- Scans existing docs and generates index.md
- Lightweight, just creates navigation
**Option 2: Comprehensive (10-30min)**
Run document-project workflow:
- Discovers existing docs in Step 2
- Generates NEW AI-friendly documentation from codebase
- Creates index.md linking to BOTH existing and new docs
**Why this matters:** AI agents need structured entry point (index.md) to navigate docs efficiently.
### Problem: document-project takes too long
**Symptoms:**
- Exhaustive scan running for hours
- Impatient to start planning
**Solution:**
**Choose appropriate scan level:**
- **Quick (2-5min)** - Pattern analysis, no source reading - Good for initial overview
- **Deep (10-30min)** - Reads critical paths - **Recommended for most brownfield projects**
- **Exhaustive (30-120min)** - Reads all files - Only for migration planning or complete understanding
For most brownfield projects, **Deep scan is sufficient**.
---
## Implementation Issues
### Problem: Existing tests breaking (Brownfield)
**Symptoms:**
- Regression test failures
- Previously working functionality broken
- Integration tests failing
**Solution:**
1. **Review changes against existing patterns**:
- Check if new code follows existing conventions
- Verify API contracts unchanged (unless intentionally versioned)
2. **Run test-review workflow** (TEA agent):
- Analyzes test coverage
- Identifies regression risks
- Suggests fixes
3. **Add regression testing to DoD**:
- All existing tests must pass
- Add integration tests for new code
4. **Consider feature flags** for gradual rollout
### Problem: Story takes much longer than estimated
**Symptoms:**
- Story estimated 4 hours, took 12 hours
- Acceptance criteria harder than expected
- Hidden complexity discovered
**Solution:**
**This is normal!** Estimates are estimates. To handle:
1. **Continue until DoD met** - Don't compromise quality
2. **Document learnings in retrospective**:
- What caused the overrun?
- What should we watch for next time?
3. **Consider splitting story** if it's truly two stories
4. **Adjust future estimates** based on this data
**Don't stress about estimate accuracy** - use them for learning, not judgment.
### Problem: Integration points unclear
**Symptoms:**
- Not sure how to connect new code to existing
- Unsure which files to modify
- Multiple possible integration approaches
**Solution:**
1. **For brownfield**:
- Ensure document-project captured existing architecture
- Review architecture docs before implementing
2. **Check story-context** - Should document integration points
3. **In tech-spec/architecture** - Explicitly document:
- Which existing modules to modify
- What APIs/services to integrate with
- Data flow between new and existing code
4. **Run integration-planning workflow** (Level 3-4):
- Architect agent creates integration strategy
### Problem: Inconsistent patterns being introduced
**Symptoms:**
- New code style doesn't match existing
- Different architectural approach
- Not following team conventions
**Solution:**
1. **Check convention detection** (Quick Spec Flow):
- Should detect existing patterns
- Asks for confirmation before proceeding
2. **Review documentation** - Ensure document-project captured patterns
3. **Use story-context** - Injects pattern guidance per story
4. **Add to code-review checklist**:
- Pattern adherence
- Convention consistency
- Style matching
5. **Run retrospective** to identify pattern deviations early
---
## File and Path Issues
### Problem: Output files in wrong location
**Symptoms:**
- PRD created in wrong folder
- Story files not where expected
- Documentation scattered
**Solution:**
Check `bmad/bmm/config.yaml` for configured paths:
```yaml
output_folder: '{project-root}/docs'
dev_story_location: '{project-root}/docs/stories'
```
Default locations:
- Planning docs (PRD, epics, architecture): `{output_folder}/`
- Stories: `{dev_story_location}/`
- Status files: `{output_folder}/bmm-workflow-status.md`, `{output_folder}/sprint-status.yaml`
To change locations, edit config.yaml then re-run workflows.
### Problem: Can't find status file
**Symptoms:**
- workflow-status says no status file
- Can't track progress
- Lost place in workflow
**Solution:**
1. **Check default location**: `docs/bmm-workflow-status.md`
2. **If missing, reinitialize**:
```
Load Analyst agent → run workflow-init
```
3. **For Phase 4**: Look for `sprint-status.yaml` in same folder as PRD
4. **Search for it**:
```bash
find . -name "bmm-workflow-status.md"
find . -name "sprint-status.yaml"
```
### Problem: Sprint-status.yaml not updating
**Symptoms:**
- Workflows complete but status unchanged
- Stories stuck in old status
- Epic status not progressing
**Solution:**
1. **Manual update required** - Most status changes are manual:
```yaml
stories:
- id: epic-1-story-1
status: done # Change this manually
```
2. **Some workflows auto-update**:
- sprint-planning creates file
- epic-tech-context changes epic to "contexted"
- create-story changes story to "drafted"
- story-context changes to "ready-for-dev"
- dev-story may auto-update (check workflow)
3. **Re-run sprint-planning** to resync if needed
---
## Agent Behavior Issues
### Problem: Agent provides vague or generic responses
**Symptoms:**
- "Use appropriate framework"
- "Follow best practices"
- Generic advice without specifics
**Solution:**
1. **Provide more context** - Be specific in your description:
- "Add OAuth using passport.js to Express server"
- Not: "Add authentication"
2. **For brownfield**:
- Ensure document-project was run
- Agent needs codebase context for specific advice
3. **Reference existing docs**:
- "Based on the existing auth system in UserService..."
4. **Start fresh chat** - Context overload can cause generic responses
### Problem: Agent hallucinating or making up information
**Symptoms:**
- References files that don't exist
- Suggests APIs that aren't in your stack
- Creates imaginary requirements
**Solution:**
1. **Use fresh chat** - Context overflow main cause of hallucinations
2. **Provide concrete constraints**:
- "We use Express 4.18.2, not Next.js"
- "Our database is PostgreSQL, not MongoDB"
3. **For brownfield**:
- Document-project provides factual grounding
- Agent sees actual code, not assumptions
4. **Correct immediately**:
- "No, we don't have UserService, we have AuthenticationModule"
### Problem: Agent won't follow instructions
**Symptoms:**
- Ignores specific requests
- Does something different than asked
- Doesn't respect constraints
**Solution:**
1. **Be more explicit** - Agents respond to clear, specific instructions:
- "Use EXACTLY these three steps..."
- "Do NOT include database migrations in this story"
2. **Check agent capabilities** - Agent might not have access to requested workflow
3. **Try different phrasing** - Rephrase request to be more direct
4. **Use menu system** - Numbers are clearer than text commands
---
## Integration Issues (Brownfield)
### Problem: New code conflicts with existing architecture
**Symptoms:**
- Integration approach doesn't fit existing structure
- Would require major refactoring
- Conflicts with established patterns
**Solution:**
1. **Check if document-project was run** - Agents need architecture context
2. **Review existing architecture docs**:
- Read docs/architecture.md (from document-project)
- Understand current system design
3. **For Level 3-4**:
- Run validate-architecture workflow before planning
- Use integration-planning workflow
4. **Explicitly document integration strategy** in architecture:
- How new components fit existing structure
- What modifications needed to existing code
- Migration path if changing patterns
### Problem: Breaking changes to existing APIs
**Symptoms:**
- Changing API breaks consumers
- Downstream services affected
- Need backward compatibility
**Solution:**
1. **Identify all API consumers** (document-project should show this)
2. **Plan versioning strategy**:
- API v1 (existing) + v2 (new)
- Deprecation timeline
3. **Use feature flags** for gradual rollout
4. **Document migration guide** for API consumers
5. **Add to testing strategy**:
- Existing consumers still work (v1)
- New functionality works (v2)
### Problem: Data migration required
**Symptoms:**
- Schema changes needed
- Existing data needs transformation
- Risk of data loss
**Solution:**
1. **Create explicit migration strategy** in architecture:
- Forward migration (old → new schema)
- Rollback plan (new → old schema)
- Data validation approach
2. **Test migrations thoroughly**:
- On copy of production data
- Measure performance impact
3. **Plan rollout**:
- Staging environment first
- Gradual production rollout
- Monitoring for issues
4. **Document in tech-spec/architecture**:
- Migration scripts
- Rollback procedures
- Expected downtime
---
## Still Stuck?
### Getting More Help
If your issue isn't covered here:
1. **Check other documentation**:
- [FAQ](./faq.md) - Common questions
- [Glossary](./glossary.md) - Terminology
- [Quick Start](./quick-start.md) - Basic usage
- [Brownfield Guide](./brownfield-guide.md) - Existing codebases
- [Scale Adaptive System](./scale-adaptive-system.md) - Understanding levels
2. **Community support**:
- [Discord](https://discord.gg/gk8jAdXWmj) - #general-dev, #bugs-issues
- Active community, fast responses
- Share your specific situation
3. **Report bugs**:
- [GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)
- Include version, steps to reproduce, expected vs actual behavior
4. **Video tutorials**:
- [YouTube Channel](https://www.youtube.com/@BMadCode)
- Visual walkthroughs of common workflows
---
## Common Error Messages
### "No workflow status file found"
**Cause:** Haven't run workflow-init yet
**Fix:** Load Analyst agent → run workflow-init
### "Epic file not found"
**Cause:** PRD/epics not created, or wrong path
**Fix:** Verify PRD/epics exist in output folder, check config.yaml paths
### "Story not in sprint-status.yaml"
**Cause:** Sprint-planning not run, or story file not created
**Fix:** Run sprint-planning workflow, verify story files exist
### "Documentation insufficient for brownfield"
**Cause:** No docs/index.md or document-project not run
**Fix:** Run document-project workflow with Deep scan
### "Level detection failed"
**Cause:** Ambiguous project description
**Fix:** Be more specific, use level keywords (fix, feature, platform, etc.)
### "Context generation failed"
**Cause:** Missing prerequisites (epic context, story file, or docs)
**Fix:** Verify epic-tech-context run, story file exists, docs present
---
## Prevention Tips
**Avoid common issues before they happen:**
1. ✅ **Always run document-project for brownfield** - Saves hours of context issues later
2. ✅ **Use fresh chats for complex workflows** - Prevents hallucinations and context overflow
3. ✅ **Verify files exist before running workflows** - Check PRD, epics, stories are present
4. ✅ **Read agent menu before requesting workflows** - Confirm agent has the workflow
5. ✅ **Start with smaller level if unsure** - Easy to upgrade (Level 1 → 2), hard to downgrade
6. ✅ **Keep status files updated** - Manual updates when needed, don't let them drift
7. ✅ **Run retrospectives after epics** - Catch issues early, improve next epic
8. ✅ **Follow phase sequence** - Don't skip required phases (Phase 2 before 3, 3 before 4)
---
**Issue not listed?** Please [report it](https://github.com/bmad-code-org/BMAD-METHOD/issues) so we can add it to this guide!

139
src/modules/bmm/docs/workflows-implementation.md
View File

@@ -133,6 +133,7 @@ The `sprint-status.yaml` file is the single source of truth for all implementati
### (BMad Method / Enterprise)
```
<<<<<<< Updated upstream
PRD (PM) → Architecture (Architect)
→ create-epics-and-stories (PM) ← V6: After architecture!
→ implementation-readiness (Architect)
@@ -141,6 +142,144 @@ PRD (PM) → Architecture (Architect)
→ story loop (SM/DEV)
→ retrospective (SM)
→ [Next Epic]
=======
Current Phase: 4 (Implementation)
Current Epic: Epic 1 (Authentication)
Current Sprint: Sprint 1
Next Story: Story 1.3 (Email Verification)
Status: TODO
Dependencies: Story 1.2 (DONE) ✅
**Recommendation:** Run `create-story` to generate Story 1.3
After create-story:
1. Run story-context
2. Run dev-story
3. Run code-review
4. Run story-done
```
See: [workflow-status instructions](../workflows/workflow-status/instructions.md)
---
### document-project
**Purpose:** Analyze and document brownfield projects by scanning codebase, architecture, and patterns.
**Agent:** Analyst
**Duration:** 1-3 hours
**When to Use:** Brownfield projects without documentation
**How It Works:**
1. Scans codebase structure
2. Identifies architecture patterns
3. Documents technology stack
4. Creates reference documentation
5. Generates PRD-like document from existing code
**Output:** `project-documentation-{date}.md`
**When to Run:**
- Before starting work on legacy project
- When inheriting undocumented codebase
- Creating onboarding documentation
See: [document-project reference](./workflow-document-project-reference.md)
---
## Story Lifecycle Visualization
```
┌─────────────────────────────────────────────────────────────┐
│ PHASE 4: IMPLEMENTATION (Iterative Story Lifecycle) │
└─────────────────────────────────────────────────────────────┘
┌─────────────────┐
│ Sprint Planning │ → Creates sprint-status.yaml
└────────┬────────┘ Defines story queue
│
├──────────────────────────────────────────┐
│ │
▼ │
┌─────────────────────┐ │
│ Epic Tech Context │ → Optional per epic │
│ (Once per epic) │ Provides technical │
└─────────────────────┘ guidance │
│ │
▼ │
┌─────────────────────────────────────────────────┤
│ FOR EACH STORY IN QUEUE: │
├─────────────────────────────────────────────────┤
│ │
▼ │
┌─────────────────┐ │
│ Create Story │ → Generates story file │
│ (TODO → IN PROGRESS) │
└────────┬────────┘ │
│ │
▼ │
┌─────────────────┐ │
│ Story Context │ → Assembles focused context │
└────────┬────────┘ │
│ │
▼ │
┌─────────────────┐ │
│ Dev Story │ → Implements + tests │
│ (IN PROGRESS) │ │
└────────┬────────┘ │
│ │
▼ │
┌─────────────────┐ │
│ Code Review │ → Senior dev review │
│ (IN PROGRESS → │ │
│ READY FOR REVIEW) │
└────────┬────────┘ │
│ │
┌────┴────┐ │
│ Result? │ │
└────┬────┘ │
│ │
┌────┼────────────────────┐ │
│ │ │ │
▼ ▼ ▼ │
APPROVED APPROVED REQUEST │
WITH COMMENTS CHANGES │
│ │ │ │
└─────────┴───────────────────┘ │
│ │
▼ │
┌─────────────────┐ │
│ Story Done │ → READY FOR REVIEW → DONE│
└────────┬────────┘ │
│ │
├─────────────────────────────────────┘
│ More stories?
│
▼
┌────────────────┐
│ Epic Complete? │
└────────┬───────┘
│
┌────┼────┐
│ │
Yes No
│ └──> Continue to next story
│
▼
┌─────────────────┐
│ Retrospective │ → Review epic, lessons learned
└─────────────────┘
│
▼
All epics done?
│
Yes → PROJECT COMPLETE
>>>>>>> Stashed changes
```
---