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

package/docs/explanation/core-concepts/what-are-workflows.md

@@ -0,0 +1,217 @@
+---
+title: "Workflows"
+---
+
+
+Workflows are like prompts on steroids. They harness the untapped power and control of LLMs through progressive disclosure—breaking complex tasks into focused steps that execute sequentially. Instead of random AI slop where you hope for the best, workflows give you repeatable, reliable, high-quality outputs.
+
+This guide explains what workflows are, why they're powerful, and how to think about designing them.
+
+---
+
+## What Is a Workflow?
+
+A workflow is a structured process where the AI executes steps sequentially to accomplish a task. Each step has a specific purpose, and the AI moves through them methodically—whether that involves extensive collaboration or minimal user interaction.
+
+Think of it this way: instead of asking "help me build a nutrition plan" and getting a generic response, a workflow guides you (or runs automatically) through discovery, assessment, strategy, shopping lists, and prep schedules—each step building on the last, nothing missed, no shortcuts taken.
+
+## How do workflows differ from skills?
+
+Actually they really do not - a workflow can be a skill, and a skill can be a workflow. The main thing with a BMad workflow is the suggestion to follow certain conventions, which actually are also skill best practices. A skill has a few optional and required fields to add as the main file workflow and get stored in a specific location depending on your tool choice for automatic invocation by the llm - whereas workflows are generally intentionally launched, with from another process calling them, or a user invoking via a slash command. In the near future, workflows will optionally be installable as skills also - but if you like, you can add front matter to your custom workflows based on the skill spec from Anthropic, and put them in the proper location your tool dictates.
+
+### The Power of Progressive Disclosure
+
+Here's why workflows work so well: the AI only sees the current step. It doesn't know about step 5 when it's on step 2. It can't get ahead of itself, skip steps, or lose focus. Each step gets the AI's full attention, completing fully before the next step loads.
+
+This is the opposite of a giant prompt that tries to handle everything at once and inevitably misses details or loses coherence.
+
+Workflows exist on a spectrum:
+
+- **Interactive workflows** guide users through complex decisions via collaboration and facilitation
+- **Automated workflows** run with minimal user input, processing documents or executing tasks
+- **Hybrid workflows** combine both—some steps need user input, others run automatically
+
+### Real-World Workflow Examples
+
+**Tax Organizer Workflow**
+
+A tax preparation workflow that helps users organize financial documents for tax filing. Runs in a single session, follows prescriptive IRS categories, produces a checklist of required documents with missing-item alerts. Sequential and compliance-focused.
+
+**Meal Planning Workflow**
+
+Creates personalized weekly meal plans through collaborative nutrition planning. Users can stop mid-session and return later because the workflow tracks progress. Intent-based conversation helps discover preferences rather than following a script. Multi-session, creative, and highly interactive.
+
+**Course Creator Workflow**
+
+Helps instructors design course syllabi. Branches based on course type—academic courses need accreditation sections, vocational courses need certification prep, self-paced courses need different structures entirely.
+
+**Therapy Intake Workflow**
+
+Guides mental health professionals through structured client intake sessions. Highly sensitive and confidential, uses intent-based questioning to build rapport while ensuring all required clinical information is collected. Continuable across multiple sessions.
+
+**Software Architecture Workflow** (BMM Module)
+
+Part of a larger software development pipeline. Runs after product requirements and UX design are complete, takes those documents as input, then collaboratively walks through technical decisions: system components, data flows, technology choices, architectural patterns. Produces an architecture document that implementation teams use to build consistently.
+
+**Shard Document Workflow**
+
+Nearly hands-off automated workflow. Takes a large document as input, uses a custom npx tool to split it into smaller files, deletes the original, then augments an index with content details so the LLM can efficiently find and reference specific sections later. Minimal user interaction—just specify the input document.
+
+These examples show the range: from collaborative creative processes to automated batch jobs, workflows ensure completeness and consistency whether the work involves deep collaboration or minimal human oversight.
+
+### The Facilitative Philosophy
+
+When workflows involve users, they should be **facilitative, not directive**. The AI treats users as partners and domain experts, not as passive recipients of generated content.
+
+**Collaborative dialogue, not command-response**: The AI and user work together throughout. The AI brings structured thinking, methodology, and technical knowledge. The user brings domain expertise, context, and judgment. Together they produce something better than either could alone.
+
+**The user is the expert in their domain**: A nutrition planning workflow doesn't dictate meal plans—it guides users through discovering what works for their lifestyle. An architecture workflow doesn't tell architects what to build—it facilitates systematic decision-making so choices are explicit and consistent.
+
+**Intent-based facilitation**: Workflows should describe goals and approaches, not scripts. Instead of "Ask: What is your age? Then ask: What is your goal weight?" use "Guide the user through understanding their health profile. Ask 1-2 questions at a time. Think about their responses before asking follow-ups. Probe to understand their actual needs."
+
+The AI figures out exact wording and question order based on conversation context. This makes interactions feel natural and responsive rather than robotic and interrogative.
+
+**When to be prescriptive**: Some workflows require exact scripts—medical intake, legal compliance, safety-critical procedures. But these are the exception, not the rule. Default to facilitative intent-based approaches unless compliance or regulation demands otherwise.
+
+---
+
+## Why Workflows Matter
+
+Workflows solve three fundamental problems with AI interactions:
+
+**Focus**: Each step contains only instructions for that phase. The AI sees one step at a time, preventing it from getting ahead of itself or losing focus.
+
+**Continuity**: Workflows can span multiple sessions. Stop mid-workflow and return later without losing progress—something free-form prompts can't do.
+
+**Quality**: Sequential enforcement prevents shortcuts. The AI must complete each step fully before moving on, ensuring thorough, complete outputs instead of rushed, half-baked results.
+
+---
+
+## How Workflows Work
+
+### The Basic Structure
+
+Workflows consist of multiple markdown files, each representing one step:
+
+```
+my-workflow/
+├── workflow.md              # Entry point and configuration
+├── steps/                   # Step files (steps-c/ for create, steps-e/ for edit, steps-v/ for validate)
+│   ├── step-01-init.md
+│   ├── step-02-profile.md
+│   └── step-N-final.md
+├── data/                    # Reference materials, CSVs, examples
+└── templates/               # Output document templates
+```
+
+The `workflow.md` file is minimal—it contains the workflow name, description, goal, the AI's role, and how to start. Importantly, it does not list all steps or detail what each does. This is progressive disclosure in action.
+
+### Sequential Execution
+
+Workflows execute in strict sequence: `step-01 → step-02 → step-03 → ... → step-N`
+
+The AI cannot skip steps or optimize the sequence. It must complete each step fully before loading the next. This ensures thoroughness and prevents shortcuts that compromise quality.
+
+### Continuable Workflows
+
+Some workflows are complex enough that users might need multiple sessions. These "continuable workflows" track which steps are complete in the output document's frontmatter, so users can stop and resume later without losing progress.
+
+Use continuable workflows when:
+- The workflow produces large documents
+- Multiple sessions are likely
+- Complex decisions benefit from reflection
+- The workflow has many steps (8+)
+
+Keep it simple (single-session) when tasks are quick, focused, and can be completed in one sitting.
+
+### Workflow Chaining
+
+Workflows can be chained together where outputs become inputs. The BMM module pipeline is a perfect example:
+
+```
+brainstorming → research → brief → PRD → UX → architecture → epics → sprint-planning
+                                                        ↓
+                                            implement-story → review → repeat
+```
+
+Each workflow checks for required inputs from prior workflows, validates they're complete, and produces output for the next workflow. This creates powerful end-to-end pipelines for complex processes.
+
+### The Tri-Modal Pattern
+
+For critical workflows that produce important artifacts, BMad uses a tri-modal structure: Create, Validate, and Edit. Each mode is a separate workflow path that can run independently or flow into the others.
+
+**Create mode** builds new artifacts from scratch. But here's where it gets interesting: create mode can also function as a conversion tool. Feed it a non-compliant document—something that doesn't follow BMad standards—and it will extract the essential content and rebuild it as a compliant artifact. This means you can bring in existing work and automatically upgrade it to follow proper patterns.
+
+**Validate mode** runs standalone and checks artifacts against standards. Because it's separate, you can run validation whenever you want—immediately after creation, weeks later when things have changed, or even using a different LLM entirely. It's like having a quality assurance checkpoint that's always available but never forced.
+
+**Edit mode** modifies existing artifacts while enforcing standards. As you update documents to reflect changing requirements or new understanding, edit mode ensures you don't accidentally drift away from the patterns that make the artifacts useful. It checks compliance as you work and can route back to create mode if it detects something that needs full conversion.
+
+All BMad planning workflows and the BMB module (will) use this tri-modal pattern. The pristine example is the workflow workflow in BMB—it creates workflow specifications, validates them against standards, and lets you edit them while maintaining compliance. You can study that workflow to see the pattern in action.
+
+This tri-modal approach gives you the best of both worlds: the creativity and flexibility to build what you need, the quality assurance of validation that can run anytime, and the ability to iterate while staying true to standards that make the artifacts valuable across sessions and team members.
+
+---
+
+## Design Decisions
+
+Before building a workflow, answer these questions:
+
+**Module affiliation**: Is this standalone or part of a module? Module-based workflows can access module-specific variables and reference other workflow outputs. Also when part of a module, generally they will be associated to an agent.
+
+**Continuable or single-session?**: Will users need multiple sessions, or can this be completed in one sitting?
+
+**Edit/Validate support?**: Do you need Create/Edit/Validate modes (tri-modal structure)? Use tri-modal for complex, critical workflows requiring quality assurance. Use create-only for simple, one-off workflows.
+
+**Document output?**: Does this produce a persistent file, or perform actions without output?
+
+**Intent or prescriptive?**: Is this intent-based facilitation (most workflows) or prescriptive compliance (medical, legal, regulated)?
+
+---
+
+## Learning from Examples
+
+The best way to understand workflows is to study real examples. Look at the official BMad modules:
+
+- **BMB (Module Builder)**: Workflow and agent creation workflows
+- **BMM (Business Method Module)**: Complete software development pipeline from brainstorming through sprint planning
+- **BMGD (Game Development Module)**: Game design briefs, narratives, architecture
+- **CIS (Creativity, Innovation, Strategy)**: Brainstorming, design thinking, storytelling, innovation strategy
+
+Study the workflow.md files to understand how each workflow starts. Examine step files to see how instructions are structured. Notice the frontmatter variables, menu handling, and how steps chain together.
+
+Copy patterns that work. Adapt them to your domain. The structure is consistent across all workflows—the content and steps change, but the architecture stays the same.
+
+---
+
+## When to Use Workflows
+
+Use workflows when:
+
+- **Tasks are multi-step and complex**: Break down complexity into manageable pieces
+- **Quality and completeness matter**: Sequential enforcement ensures nothing gets missed
+- **Repeatability is important**: Get consistent results every time
+- **Tasks span multiple sessions**: Continuable workflows preserve progress
+- **You need to chain processes**: Output of one workflow becomes input of another
+- **Compliance or standards matter**: Enforce required steps and documentation
+
+Don't use workflows when:
+
+- **Tasks are simple and one-off**: A single prompt works fine for quick questions
+- **Flexibility trumps structure**: Free-form conversation is better for exploration
+
+Modified BMad Workflows
+
+- **Tasks are truly one-step**
+
+If there's only one thing to do and it can be explained in under about 300 lines - don't bother with step files. Instead, you can still have
+a short single file workflow.md file.
+
+---
+
+## The Bottom Line
+
+Workflows transform AI from a tool that gives variable, unpredictable results into a reliable system for complex, multi-step processes. Through progressive disclosure, sequential execution, guided facilitation, and thoughtful design, workflows give you control and repeatability that ad-hoc prompting alone can't match.
+
+They're not just for software development. You can create workflows for any guided process - meal planning, course design, therapy intake, tax preparation, document processing, creative writing, event planning—any complex task that benefits from structure and thoroughness.
+
+Start simple. Study examples. Build workflows for your own domain. You'll wonder how you ever got by with just prompts.

package/docs/{modules/cis-creative-intelligence-suite → explanation/creative-intelligence}/index.md

@@ -1,20 +1,19 @@
-# CIS - Creative Intelligence Suite
+---
+title: "Creative Intelligence Suite (CIS)"
+description: AI-powered creative facilitation with the Creative Intelligence Suite
+---
 
-AI-powered creative facilitation transforming strategic thinking through expert coaching across five specialized domains.
 
-## Table of Contents
+AI-powered creative facilitation transforming strategic thinking through expert coaching across five specialized domains.
 
-- [Core Capabilities](#core-capabilities)
-- [Specialized Agents](#specialized-agents)
-- [Interactive Workflows](#interactive-workflows)
-- [Quick Start](#quick-start)
-- [Key Differentiators](#key-differentiators)
-- [Configuration](#configuration)
+---
 
 ## Core Capabilities
 
 CIS provides structured creative methodologies through distinctive agent personas who act as master facilitators, drawing out insights through strategic questioning rather than generating solutions directly.
 
+---
+
 ## Specialized Agents
 
 - **Carson** - Brainstorming Specialist (energetic facilitator)
@@ -23,74 +22,69 @@ CIS provides structured creative methodologies through distinctive agent persona
 - **Victor** - Innovation Oracle (bold strategic precision)
 - **Sophia** - Master Storyteller (whimsical narrator)
 
-## Interactive Workflows
+---
 
-[View all workflows →](../workflows/README.md)
+## Interactive Workflows
 
 **5 Workflows** with **150+ Creative Techniques:**
 
 ### Brainstorming
 
-36 techniques across 7 categories for ideation
-
+36 techniques across 7 categories for ideation:
 - Divergent/convergent thinking
 - Lateral connections
 - Forced associations
 
 ### Design Thinking
 
-Complete 5-phase human-centered process
-
+Complete 5-phase human-centered process:
 - Empathize → Define → Ideate → Prototype → Test
 - User journey mapping
 - Rapid iteration
 
 ### Problem Solving
 
-Systematic root cause analysis
-
+Systematic root cause analysis:
 - 5 Whys, Fishbone diagrams
 - Solution generation
 - Impact assessment
 
 ### Innovation Strategy
 
-Business model disruption
-
+Business model disruption:
 - Blue Ocean Strategy
 - Jobs-to-be-Done
 - Disruptive innovation patterns
 
 ### Storytelling
 
-25 narrative frameworks
-
+25 narrative frameworks:
 - Hero's Journey
 - Story circles
 - Compelling pitch structures
 
+---
+
 ## Quick Start
 
 ### Direct Workflow
 
 ```bash
-# Start interactive session
 workflow brainstorming
 
-# With context document
 workflow design-thinking --data /path/to/context.md
 ```
 
 ### Agent-Facilitated
 
 ```bash
-# Load agent
 agent cis/brainstorming-coach
 
-# Start workflow
 > *brainstorm
 ```
 
+---
+
 ## Key Differentiators
 
 - **Facilitation Over Generation** - Guides discovery through questions
@@ -99,30 +93,7 @@ agent cis/brainstorming-coach
 - **Persona-Driven** - Unique communication styles
 - **Rich Method Libraries** - 150+ proven techniques
 
-## Configuration
-
-Edit `/_bmad/cis/config.yaml`:
-
-```yaml
-output_folder: ./creative-outputs
-user_name: Your Name
-communication_language: english
-```
-
-## Module Structure
-
-```
-cis/
-├── agents/              # 5 specialized facilitators
-├── workflows/           # 5 interactive processes
-│   ├── brainstorming/
-│   ├── design-thinking/
-│   ├── innovation-strategy/
-│   ├── problem-solving/
-│   └── storytelling/
-├── tasks/              # Supporting operations
-└── teams/              # Agent collaborations
-```
+---
 
 ## Integration Points
 
@@ -132,6 +103,8 @@ CIS workflows integrate with:
 - **BMB** - Creative module design
 - **Custom Modules** - Shared creative resource
 
+---
+
 ## Best Practices
 
 1. **Set clear objectives** before starting sessions
@@ -140,10 +113,9 @@ CIS workflows integrate with:
 4. **Take breaks** when energy flags
 5. **Document insights** as they emerge
 
-## Related Documentation
-
-- **[BMM Documentation](../../bmm/docs/index.md)** - Core BMad Method documentation
-
 ---
 
-Part of BMad Method v6.0 - Transform creative potential through expert AI facilitation.
+## Related
+
+- [Facilitation Over Generation](/docs/explanation/philosophy/facilitation-over-generation.md) - Core philosophy
+- [Brainstorming Techniques](/docs/explanation/features/brainstorming-techniques.md) - Technique reference

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

@@ -0,0 +1,73 @@
+---
+title: "Brownfield Development FAQ"
+description: Common questions about brownfield development in the BMad Method
+---
+Quick answers to common questions about brownfield (existing codebase) development in the BMad Method (BMM).
+
+## Questions
+
+- [What is brownfield vs greenfield?](#what-is-brownfield-vs-greenfield)
+- [Do I have to run document-project for brownfield?](#do-i-have-to-run-document-project-for-brownfield)
+- [What if I forget to run document-project?](#what-if-i-forget-to-run-document-project)
+- [Can I use Quick Spec Flow for brownfield projects?](#can-i-use-quick-spec-flow-for-brownfield-projects)
+- [How does workflow-init handle old planning docs?](#how-does-workflow-init-handle-old-planning-docs)
+- [What if my existing code doesn't follow best practices?](#what-if-my-existing-code-doesnt-follow-best-practices)
+
+### What is brownfield vs greenfield?
+
+- **Greenfield** — New project, starting from scratch, clean slate
+- **Brownfield** — Existing project, working with established codebase and patterns
+
+### Do I have to run document-project for brownfield?
+
+Highly recommended, especially if:
+
+- No existing documentation
+- Documentation is outdated
+- AI agents need context about existing code
+- Level 2-4 complexity
+
+You can skip it if you have comprehensive, up-to-date documentation including `docs/index.md`.
+
+### What if I forget to run document-project?
+
+Workflows will lack context about existing code. You may get:
+
+- Suggestions that don't match existing patterns
+- Integration approaches that miss existing APIs
+- Architecture that conflicts with current structure
+
+Run document-project and restart planning with proper context.
+
+### Can I use Quick Spec Flow for brownfield projects?
+
+Yes! Quick Spec Flow works great for brownfield. It will:
+
+- Auto-detect your existing stack
+- Analyze brownfield code patterns
+- Detect conventions and ask for confirmation
+- Generate context-rich tech-spec that respects existing code
+
+Perfect for bug fixes and small features in existing codebases.
+
+### How does workflow-init handle old planning docs?
+
+workflow-init asks about YOUR current work first, then uses old artifacts as context:
+
+1. Shows what it found (old PRD, epics, etc.)
+2. Asks: "Is this work in progress, previous effort, or proposed work?"
+3. If previous effort: Asks you to describe your NEW work
+4. Determines level based on YOUR work, not old artifacts
+
+This prevents old Level 3 PRDs from forcing Level 3 workflow for a new Level 0 bug fix.
+
+### What if my existing code doesn't follow best practices?
+
+Quick Spec Flow detects your conventions and asks: "Should I follow these existing conventions?" You decide:
+
+- **Yes** → Maintain consistency with current codebase
+- **No** → Establish new standards (document why in tech-spec)
+
+BMM respects your choice — it won't force modernization, but it will offer it.
+
+**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/getting-started-faq.md

@@ -0,0 +1,62 @@
+---
+title: "Getting Started FAQ"
+description: Common questions about getting started with the BMad Method
+---
+
+Quick answers to common questions about getting started with the BMad Method.
+
+## Questions
+
+- [Do I always need to run workflow-init?](#do-i-always-need-to-run-workflow-init)
+- [Why do I need fresh chats for each workflow?](#why-do-i-need-fresh-chats-for-each-workflow)
+- [Can I skip workflow-status and just start working?](#can-i-skip-workflow-status-and-just-start-working)
+- [What's the minimum I need to get started?](#whats-the-minimum-i-need-to-get-started)
+- [How do I know if I'm in Phase 1, 2, 3, or 4?](#how-do-i-know-if-im-in-phase-1-2-3-or-4)
+
+### Do I always need to run workflow-init?
+
+No, once you learn the flow you can go directly to workflows. However, workflow-init is helpful because it:
+
+- Determines your project's appropriate level automatically
+- Creates the tracking status file
+- Routes you to the correct starting workflow
+
+For experienced users: use the [Quick Start Guide](/docs/tutorials/getting-started/getting-started-bmadv6.md) to go directly to the right agent/workflow.
+
+### Why do I need fresh chats for each workflow?
+
+Context-intensive workflows (like brainstorming, PRD creation, architecture design) can cause AI hallucinations if run in sequence within the same chat. Starting fresh ensures the agent has maximum context capacity for each workflow. This is particularly important for:
+
+- Planning workflows (PRD, architecture)
+- Analysis workflows (brainstorming, research)
+- Complex story implementation
+
+Quick workflows like status checks can reuse chats safely.
+
+### Can I skip workflow-status and just start working?
+
+Yes, if you already know your project level and which workflow comes next. workflow-status is mainly useful for:
+
+- New projects (guides initial setup)
+- When you're unsure what to do next
+- After breaks in work (reminds you where you left off)
+- Checking overall progress
+
+### What's the minimum I need to get started?
+
+For the fastest path:
+
+1. Install BMad Method: `npx bmad-method@alpha install`
+2. For small changes: Load PM agent → run tech-spec → implement
+3. For larger projects: Load PM agent → run prd → architect → implement
+
+### How do I know if I'm in Phase 1, 2, 3, or 4?
+
+Check your `bmm-workflow-status.md` file (created by workflow-init). It shows your current phase and progress. If you don't have this file, you can also tell by what you're working on:
+
+- **Phase 1** — Brainstorming, research, product brief (optional)
+- **Phase 2** — Creating either a PRD or tech-spec (always required)
+- **Phase 3** — Architecture design (Level 2-4 only)
+- **Phase 4** — Actually writing code, implementing stories
+
+**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/implementation-faq.md

@@ -0,0 +1,52 @@
+---
+title: "Implementation FAQ"
+description: Common questions about implementation in the BMad Method
+---
+
+Quick answers to common questions about implementation in the BMad Method.
+
+## Questions
+
+- [Does create-story include implementation context?](#does-create-story-include-implementation-context)
+- [How do I mark a story as done?](#how-do-i-mark-a-story-as-done)
+- [Can I work on multiple stories at once?](#can-i-work-on-multiple-stories-at-once)
+- [What if my story takes longer than estimated?](#what-if-my-story-takes-longer-than-estimated)
+- [When should I run retrospective?](#when-should-i-run-retrospective)
+
+### Does create-story include implementation context?
+
+Yes! The create-story workflow generates story files that include implementation-specific guidance, references existing patterns from your documentation, and provides technical context. The workflow loads your architecture, PRD, and existing project documentation to create comprehensive stories. For Quick Flow projects using tech-spec, the tech-spec itself is already comprehensive, so stories can be simpler.
+
+### How do I mark a story as done?
+
+After dev-story completes and code-review passes:
+
+1. Open `sprint-status.yaml` (created by sprint-planning)
+2. Change the story status from `review` to `done`
+3. Save the file
+
+### Can I work on multiple stories at once?
+
+Yes, if you have capacity! Stories within different epics can be worked in parallel. However, stories within the same epic are usually sequential because they build on each other.
+
+### What if my story takes longer than estimated?
+
+That's normal! Stories are estimates. If implementation reveals more complexity:
+
+1. Continue working until DoD is met
+2. Consider if story should be split
+3. Document learnings in retrospective
+4. Adjust future estimates based on this learning
+
+### When should I run retrospective?
+
+After completing all stories in an epic (when epic is done). Retrospectives capture:
+
+- What went well
+- What could improve
+- Technical insights
+- Learnings for future epics
+
+Don't wait until project end — run after each epic for continuous improvement.
+
+**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/index.md

@@ -0,0 +1,16 @@
+---
+title: "Frequently Asked Questions"
+description: Frequently asked questions about the BMad Method
+---
+
+Quick answers to common questions about the BMad Method, organized by topic.
+
+## Topics
+
+- [Getting Started](/docs/explanation/faq/getting-started-faq.md) - Questions about starting with BMad
+- [Levels & Tracks](/docs/explanation/faq/levels-and-tracks-faq.md) - Choosing the right level
+- [Workflows](/docs/explanation/faq/workflows-faq.md) - Workflow and phase questions
+- [Planning](/docs/explanation/faq/planning-faq.md) - Planning document questions
+- [Implementation](/docs/explanation/faq/implementation-faq.md) - Implementation questions
+- [Brownfield](/docs/explanation/faq/brownfield-faq.md) - Existing codebase questions
+- [Tools & Advanced](/docs/explanation/faq/tools-faq.md) - Tools, IDEs, and advanced topics

package/docs/explanation/faq/levels-and-tracks-faq.md

@@ -0,0 +1,52 @@
+---
+title: "Levels and Tracks FAQ"
+description: Common questions about choosing the right level for your project
+---
+
+Quick answers to common questions about choosing the right level for your BMad Method project.
+
+## Questions
+
+- [How do I know which level my project is?](#how-do-i-know-which-level-my-project-is)
+- [Can I change levels mid-project?](#can-i-change-levels-mid-project)
+- [What if workflow-init suggests the wrong level?](#what-if-workflow-init-suggests-the-wrong-level)
+- [Do I always need architecture for Level 2?](#do-i-always-need-architecture-for-level-2)
+- [What's the difference between Level 1 and Level 2?](#whats-the-difference-between-level-1-and-level-2)
+
+### How do I know which level my project is?
+
+Use workflow-init for automatic detection, or self-assess using these keywords:
+
+- **Level 0** — "fix", "bug", "typo", "small change", "patch" → 1 story
+- **Level 1** — "simple", "basic", "small feature", "add" → 1-10 stories
+- **Level 2** — "dashboard", "several features", "admin panel" → 5-15 stories
+- **Level 3** — "platform", "integration", "complex", "system" → 12-40 stories
+- **Level 4** — "enterprise", "multi-tenant", "multiple products" → 40+ stories
+
+When in doubt, start smaller. You can always run create-prd later if needed.
+
+### Can I change levels mid-project?
+
+Yes! If you started at Level 1 but realize it's Level 2, you can run create-prd to add proper planning docs. The system is flexible — your initial level choice isn't permanent.
+
+### What if workflow-init suggests the wrong level?
+
+You can override it! workflow-init suggests a level but always asks for confirmation. If you disagree, just say so and choose the level you think is appropriate. Trust your judgment.
+
+### Do I always need architecture for Level 2?
+
+No, architecture is **optional** for Level 2. Only create architecture if you need system-level design. Many Level 2 projects work fine with just PRD created during planning.
+
+### What's the difference between Level 1 and Level 2?
+
+- **Level 1** — 1-10 stories, uses tech-spec (simpler, faster), no architecture
+- **Level 2** — 5-15 stories, uses PRD (product-focused), optional architecture
+
+The overlap (5-10 stories) is intentional. Choose based on:
+
+- Need product-level planning? → Level 2
+- Just need technical plan? → Level 1
+- Multiple epics? → Level 2
+- Single epic? → Level 1
+
+**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!