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

package/docs/explanation/faq/planning-faq.md

@@ -0,0 +1,41 @@
+---
+title: "Planning Documents FAQ"
+description: Common questions about planning documents in the BMad Method
+---
+
+Quick answers to common questions about planning documents in the BMad Method.
+
+## Questions
+
+- [Why no tech-spec at Level 2+?](#why-no-tech-spec-at-level-2)
+- [Do I need a PRD for a bug fix?](#do-i-need-a-prd-for-a-bug-fix)
+- [Can I skip the product brief?](#can-i-skip-the-product-brief)
+
+### Why no tech-spec at Level 2+?
+
+Level 2+ projects need product-level planning (PRD) and system-level design (Architecture), which tech-spec doesn't provide. Tech-spec is too narrow for coordinating multiple features. Instead, Level 2-4 uses:
+
+- PRD (product vision, functional requirements, non-functional requirements)
+- Architecture (system design)
+- Epics+Stories (created AFTER architecture is complete)
+
+### Do I need a PRD for a bug fix?
+
+No! Bug fixes are typically Level 0 (single atomic change). Use Quick Spec Flow:
+
+- Load PM agent
+- Run tech-spec workflow
+- Implement immediately
+
+PRDs are for Level 2-4 projects with multiple features requiring product-level coordination.
+
+### Can I skip the product brief?
+
+Yes, product brief is always optional. It's most valuable for:
+
+- Level 3-4 projects needing strategic direction
+- Projects with stakeholders requiring alignment
+- Novel products needing market research
+- When you want to explore solution space before committing
+
+**Have a question not answered here?** Please [open an issue](https://github.com/bmad-code-org/BMAD-METHOD/issues) or ask in [Discord](https://discord.gg/gk8jAdXWmj) so we can add it!

package/docs/explanation/faq/tools-faq.md

@@ -0,0 +1,253 @@
+---
+title: "Tools and Advanced FAQ"
+description: Common questions about tools, IDEs, and advanced topics in the BMad Method
+---
+
+Quick answers to common questions about tools, IDEs, and advanced topics in the BMad Method.
+
+## Questions
+
+**Tools and Technical**
+
+- [Why are my Mermaid diagrams not rendering?](#why-are-my-mermaid-diagrams-not-rendering)
+- [Can I use BMM with GitHub Copilot / Cursor / other AI tools?](#can-i-use-bmm-with-github-copilot--cursor--other-ai-tools)
+- [What IDEs/tools support BMM?](#what-idestools-support-bmm)
+- [Can I customize agents?](#can-i-customize-agents)
+- [What happens to my planning docs after implementation?](#what-happens-to-my-planning-docs-after-implementation)
+- [Can I use BMM for non-software projects?](#can-i-use-bmm-for-non-software-projects)
+
+**Advanced**
+
+- [What if my project grows from Level 1 to Level 3?](#what-if-my-project-grows-from-level-1-to-level-3)
+- [Can I mix greenfield and brownfield approaches?](#can-i-mix-greenfield-and-brownfield-approaches)
+- [How do I handle urgent hotfixes during a sprint?](#how-do-i-handle-urgent-hotfixes-during-a-sprint)
+- [What if I disagree with the workflow's recommendations?](#what-if-i-disagree-with-the-workflows-recommendations)
+- [Can multiple developers work on the same BMM project?](#can-multiple-developers-work-on-the-same-bmm-project)
+- [What is party mode and when should I use it?](#what-is-party-mode-and-when-should-i-use-it)
+
+**Getting Help**
+
+- [Where do I get help if my question isn't answered here?](#where-do-i-get-help-if-my-question-isnt-answered-here)
+- [How do I report a bug or request a feature?](#how-do-i-report-a-bug-or-request-a-feature)
+
+## Tools and Technical
+
+### Why are my Mermaid diagrams not rendering?
+
+Common issues:
+
+1. Missing language tag: Use ` ```mermaid` not just ` ``` `
+2. Syntax errors in diagram (validate at mermaid.live)
+3. Tool doesn't support Mermaid (check your Markdown renderer)
+
+All BMM docs use valid Mermaid syntax that should render in GitHub, VS Code, and most IDEs.
+
+### Can I use BMM with GitHub Copilot / Cursor / other AI tools?
+
+Yes! BMM is complementary. BMM handles:
+
+- Project planning and structure
+- Workflow orchestration
+- Agent Personas and expertise
+- Documentation generation
+- Quality gates
+
+Your AI coding assistant handles:
+
+- Line-by-line code completion
+- Quick refactoring
+- Test generation
+
+Use them together for best results.
+
+### What IDEs/tools support BMM?
+
+BMM requires tools with **agent mode** and access to **high-quality LLM models** that can load and follow complex workflows, then properly implement code changes.
+
+**Recommended Tools:**
+
+- **Claude Code** — Best choice
+  - Sonnet 4.5 (excellent workflow following, coding, reasoning)
+  - Opus (maximum context, complex planning)
+  - Native agent mode designed for BMM workflows
+
+- **Cursor**
+  - Supports Anthropic (Claude) and OpenAI models
+  - Agent mode with composer
+  - Good for developers who prefer Cursor's UX
+
+- **Windsurf**
+  - Multi-model support
+  - Agent capabilities
+  - Suitable for BMM workflows
+
+**What Matters:**
+
+1. **Agent mode** — Can load long workflow instructions and maintain context
+2. **High-quality LLM** — Models ranked high on SWE-bench (coding benchmarks)
+3. **Model selection** — Access to Claude Sonnet 4.5, Opus, or GPT-4o class models
+4. **Context capacity** — Can handle large planning documents and codebases
+
+**Why model quality matters:** BMM workflows require LLMs that can follow multi-step processes, maintain context across phases, and implement code that adheres to specifications. Tools with weaker models will struggle with workflow adherence and code quality.
+
+### Can I customize agents?
+
+Yes! Agents are installed as markdown files with XML-style content (optimized for LLMs, readable by any model). Create customization files in `_bmad/_config/agents/[agent-name].customize.yaml` to override default behaviors while keeping core functionality intact. See agent documentation for customization options.
+
+**Note:** While source agents in this repo are YAML, they install as `.md` files with XML-style tags — a format any LLM can read and follow.
+
+### What happens to my planning docs after implementation?
+
+Keep them! They serve as:
+
+- Historical record of decisions
+- Onboarding material for new team members
+- Reference for future enhancements
+- Audit trail for compliance
+
+For enterprise projects (Level 4), consider archiving completed planning artifacts to keep workspace clean.
+
+### Can I use BMM for non-software projects?
+
+BMM is optimized for software development, but the methodology principles (scale-adaptive planning, just-in-time design, context injection) can apply to other complex project types. You'd need to adapt workflows and agents for your domain.
+
+## Advanced
+
+### What if my project grows from Level 1 to Level 3?
+
+Totally fine! When you realize scope has grown:
+
+1. Run create-prd to add product-level planning
+2. Run create-architecture for system design
+3. Use existing tech-spec as input for PRD
+4. Continue with updated level
+
+The system is flexible — growth is expected.
+
+### Can I mix greenfield and brownfield approaches?
+
+Yes! Common scenario: adding new greenfield feature to brownfield codebase. Approach:
+
+1. Run document-project for brownfield context
+2. Use greenfield workflows for new feature planning
+3. Explicitly document integration points between new and existing
+4. Test integration thoroughly
+
+### How do I handle urgent hotfixes during a sprint?
+
+Use correct-course workflow or just:
+
+1. Save your current work state
+2. Load PM agent → quick tech-spec for hotfix
+3. Implement hotfix (Level 0 flow)
+4. Deploy hotfix
+5. Return to original sprint work
+
+Level 0 Quick Spec Flow is perfect for urgent fixes.
+
+### What if I disagree with the workflow's recommendations?
+
+Workflows are guidance, not enforcement. If a workflow recommends something that doesn't make sense for your context:
+
+- Explain your reasoning to the agent
+- Ask for alternative approaches
+- Skip the recommendation if you're confident
+- Document why you deviated (for future reference)
+
+Trust your expertise — BMM supports your decisions.
+
+### Can multiple developers work on the same BMM project?
+
+Yes! But the paradigm is fundamentally different from traditional agile teams.
+
+**Key Difference:**
+
+- **Traditional** — Multiple devs work on stories within one epic (months)
+- **Agentic** — Each dev owns complete epics (days)
+
+**In traditional agile:** A team of 5 devs might spend 2-3 months on a single epic, with each dev owning different stories.
+
+**With BMM + AI agents:** A single dev can complete an entire epic in 1-3 days. What used to take months now takes days.
+
+**Team Work Distribution:**
+
+- **Recommended:** Split work by **epic** (not story)
+- Each developer owns complete epics end-to-end
+- Parallel work happens at epic level
+- Minimal coordination needed
+
+**For full-stack apps:**
+
+- Frontend and backend can be separate epics (unusual in traditional agile)
+- Frontend dev owns all frontend epics
+- Backend dev owns all backend epics
+- Works because delivery is so fast
+
+**Enterprise Considerations:**
+
+- Use **git submodules** for BMM installation (not .gitignore)
+- Allows personal configurations without polluting main repo
+- Teams may use different AI tools (Claude Code, Cursor, etc.)
+- Developers may follow different methods or create custom agents/workflows
+
+**Quick Tips:**
+
+- Share `sprint-status.yaml` (single source of truth)
+- Assign entire epics to developers (not individual stories)
+- Coordinate at epic boundaries, not story level
+- Use git submodules for BMM in enterprise settings
+
+### What is party mode and when should I use it?
+
+Party mode is a unique multi-agent collaboration feature where ALL your installed agents (19+ from BMM, CIS, BMB, custom modules) discuss your challenges together in real-time.
+
+**How it works:**
+
+1. Run `/bmad:core:workflows:party-mode` (or `*party-mode` from any agent)
+2. Introduce your topic
+3. BMad Master selects 2-3 most relevant agents per message
+4. Agents cross-talk, debate, and build on each other's ideas
+
+**Best for:**
+
+- Strategic decisions with trade-offs (architecture choices, tech stack, scope)
+- Creative brainstorming (game design, product innovation, UX ideation)
+- Cross-functional alignment (epic kickoffs, retrospectives, phase transitions)
+- Complex problem-solving (multi-faceted challenges, risk assessment)
+
+**Example parties:**
+
+- **Product Strategy** — PM + Innovation Strategist (CIS) + Analyst
+- **Technical Design** — Architect + Creative Problem Solver (CIS) + Game Architect
+- **User Experience** — UX Designer + Design Thinking Coach (CIS) + Storyteller (CIS)
+
+**Why it's powerful:**
+
+- Diverse perspectives (technical, creative, strategic)
+- Healthy debate reveals blind spots
+- Emergent insights from agent interaction
+- Natural collaboration across modules
+
+**For complete documentation:** See the [Party Mode Guide](/docs/explanation/features/party-mode.md)
+
+## Getting Help
+
+### Where do I get help if my question isn't answered here?
+
+1. Search [Complete Documentation](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/README.md) for related topics
+2. Ask in [Discord Community](https://discord.gg/gk8jAdXWmj) (#bmad-method-help)
+3. Open a [GitHub Issue](https://github.com/bmad-code-org/BMAD-METHOD/issues)
+4. Watch [YouTube Tutorials](https://www.youtube.com/@BMadCode)
+
+### How do I report a bug or request a feature?
+
+Open a GitHub issue at: <https://github.com/bmad-code-org/BMAD-METHOD/issues>
+
+Please include:
+
+- BMM version (check your installed version)
+- Steps to reproduce (for bugs)
+- Expected vs actual behavior
+- Relevant workflow or agent involved
+
+**Have a question not answered here?** Please [open an issue](https://github.com/bmad-code-org/BMAD-METHOD/issues) or ask in [Discord](https://discord.gg/gk8jAdXWmj) so we can add it!

package/docs/explanation/faq/workflows-faq.md

@@ -0,0 +1,61 @@
+---
+title: "Workflows FAQ"
+description: Common questions about BMad Method workflows and phases
+---
+
+Quick answers to common questions about BMad Method workflows and phases.
+
+## Questions
+
+- [What's the difference between workflow-status and workflow-init?](#whats-the-difference-between-workflow-status-and-workflow-init)
+- [Can I skip Phase 1 (Analysis)?](#can-i-skip-phase-1-analysis)
+- [When is Phase 3 (Architecture) required?](#when-is-phase-3-architecture-required)
+- [What happens if I skip a recommended workflow?](#what-happens-if-i-skip-a-recommended-workflow)
+- [How do I know when Phase 3 is complete?](#how-do-i-know-when-phase-3-is-complete)
+- [Can I run workflows in parallel?](#can-i-run-workflows-in-parallel)
+
+### What's the difference between workflow-status and workflow-init?
+
+- **workflow-status** — Checks existing status and tells you what's next (use when continuing work)
+- **workflow-init** — Creates new status file and sets up project (use when starting new project)
+
+If status file exists, use workflow-status. If not, use workflow-init.
+
+### Can I skip Phase 1 (Analysis)?
+
+Yes! Phase 1 is optional for all levels, though recommended for complex projects. Skip if:
+
+- Requirements are clear
+- No research needed
+- Time-sensitive work
+- Small changes (Level 0-1)
+
+### When is Phase 3 (Architecture) required?
+
+- **Level 0-1** — Never (skip entirely)
+- **Level 2** — Optional (only if system design needed)
+- **Level 3-4** — Required (comprehensive architecture mandatory)
+
+### What happens if I skip a recommended workflow?
+
+Nothing breaks! Workflows are guidance, not enforcement. However, skipping recommended workflows (like architecture for Level 3) may cause:
+
+- Integration issues during implementation
+- Rework due to poor planning
+- Conflicting design decisions
+- Longer development time overall
+
+### How do I know when Phase 3 is complete?
+
+For Level 3-4, run the implementation-readiness workflow. It validates PRD + Architecture + Epics + UX (optional) are aligned before implementation. Pass the gate check = ready for Phase 4.
+
+### Can I run workflows in parallel?
+
+Most workflows must be sequential within a phase:
+
+- **Phase 1** — brainstorm → research → product-brief (optional order)
+- **Phase 2** — PRD must complete before moving forward
+- **Phase 3** — architecture → epics+stories → implementation-readiness (sequential)
+- **Phase 4** — Stories within an epic should generally be sequential, but stories in different epics can be parallel if you have capacity
+
+**Have a question not answered here?** Please [open an issue](https://github.com/bmad-code-org/BMAD-METHOD/issues) or ask in [Discord](https://discord.gg/gk8jAdXWmj) so we can add it!

package/docs/{modules/core → explanation/features}/advanced-elicitation.md

@@ -1,4 +1,7 @@
-# Advanced Elicitation
+---
+title: "Advanced Elicitation"
+---
+
 
 **Push the LLM to rethink its work through 50+ reasoning methods—essentially, LLM brainstorming.**
 
@@ -39,7 +42,7 @@ Based on context, 5 methods are intelligently selected from a library of 50+ tec
 - Each method builds on previous enhancements
 
 ### 4. Party Mode Integration (Optional)
-If Party Mode is active, BMAD agents participate randomly in the elicitation process, adding their unique perspectives to the methods.
+If Party Mode is active, BMad agents participate randomly in the elicitation process, adding their unique perspectives to the methods.
 
 ---
 

package/docs/{modules/core/brainstorming.md → explanation/features/brainstorming-techniques.md}

@@ -1,4 +1,7 @@
-# Brainstorming
+---
+title: "Brainstorming"
+---
+
 
 **Facilitate structured creative sessions using 60+ proven ideation techniques.**
 

package/docs/{modules/bmm-bmad-method → explanation/features}/party-mode.md

@@ -1,4 +1,7 @@
-# Party Mode: Multi-Agent Collaboration
+---
+title: "Party Mode: Multi-Agent Collaboration"
+---
+
 
 **Get all your AI agents in one conversation**
 
@@ -36,20 +39,15 @@ Type `/bmad:core:workflows:party-mode` (or `*party-mode` from any agent or at ke
 ## Quick Start
 
 ```bash
-# Trigger party mode
 /bmad:core:workflows:party-mode
 
-# OR from any agent context
 *party-mode
 
-# Super Hack
 
 /bmad:core:workflows:party-mode and include also in the party Santa Clause and Einstein 
 
-# During party
 Ask questions, respond to agents, direct the conversation
 
-# Exit
 Type: exit
 ```
 
@@ -105,9 +103,9 @@ _(Multiple perspectives reveal the right answer)_
 
 ## Related Documentation
 
-- [Agents Guide](./agents-guide.md) - Complete agent reference
-- [Quick Start Guide](./quick-start.md) - Getting started with BMM
-- [FAQ](./faq.md) - Common questions
+- [Agents Reference](/docs/reference/agents/index.md) - Complete agent reference
+- [Quick Start Guide](/docs/tutorials/getting-started/getting-started-bmadv6.md) - Getting started with BMM
+- [Setup Party Mode](/docs/how-to/workflows/setup-party-mode.md) - How to use it
 
 ---
 

package/docs/explanation/features/quick-flow.md

@@ -0,0 +1,169 @@
+---
+title: "Quick Spec Flow"
+description: Understanding Quick Spec Flow for rapid development in BMad Method
+---
+
+
+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.
+
+**Perfect for:** Bug fixes, small features, rapid prototyping, and quick enhancements
+
+**Time to implementation:** Minutes, not hours
+
+---
+
+## When to Use Quick Flow
+
+### ✅ Use Quick Flow 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 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 Flow Overview
+
+```mermaid
+flowchart TD
+    START[Step 1: Run Tech-Spec Workflow]
+    DETECT[Detects project stack]
+    ANALYZE[Analyzes brownfield codebase]
+    TEST[Detects test frameworks]
+    CONFIRM[Confirms conventions]
+    GENERATE[Generates context-rich tech-spec]
+    STORIES[Creates ready-to-implement stories]
+    IMPL[Step 2: Implement with DEV Agent]
+    DONE[DONE!]
+
+    START --> DETECT
+    DETECT --> ANALYZE
+    ANALYZE --> TEST
+    TEST --> CONFIRM
+    CONFIRM --> GENERATE
+    GENERATE --> STORIES
+    STORIES --> IMPL
+    IMPL --> DONE
+
+    style START fill:#bfb,stroke:#333,stroke-width:2px
+    style IMPL fill:#bbf,stroke:#333,stroke-width:2px
+    style DONE fill:#f9f,stroke:#333,stroke-width:3px
+```
+
+---
+
+## 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!)
+
+---
+
+## Smart Context Discovery
+
+Quick Spec Flow automatically discovers and uses:
+
+### Existing Documentation
+- Product briefs (if they exist)
+- Research documents
+- `document-project` output (brownfield codebase map)
+
+### Project Stack
+- **Node.js:** package.json → frameworks, dependencies, scripts
+- **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
+
+### Brownfield Code Patterns
+- Directory structure and organization
+- Existing code patterns (class-based, functional, MVC)
+- Naming conventions
+- Test frameworks and patterns
+- Code style configurations
+
+### Convention Confirmation
+
+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
+
+Test Patterns:
+- Jest test framework
+- .test.js file naming
+
+Should I follow these existing conventions? (yes/no)
+```
+
+**You decide:** Conform to existing patterns or establish new standards!
+
+---
+
+## Auto-Validation
+
+Quick Spec Flow **automatically validates** everything:
+
+- ✅ Context gathering completeness
+- ✅ Definitiveness (no "use X or Y" statements)
+- ✅ Brownfield integration quality
+- ✅ Stack alignment
+- ✅ Implementation readiness
+
+---
+
+## Comparison: Quick Flow 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                    |
+| **Validation**        | Auto-validates everything    | Manual validation steps            |
+| **Brownfield**        | Auto-analyzes and conforms   | Manual documentation required      |
+
+---
+
+## When to Graduate 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!
+
+---
+
+## Related
+
+- [Quick Spec](/docs/how-to/workflows/quick-spec.md) - How to use Quick Flow
+- [Quick Start Guide](/docs/tutorials/getting-started/getting-started-bmadv6.md) - Getting started
+- [Four Phases](/docs/explanation/architecture/four-phases.md) - Understanding the full methodology