diff --git a/docs/_STYLE_GUIDE.md b/docs/_STYLE_GUIDE.md index 168237e7..592d1148 100644 --- a/docs/_STYLE_GUIDE.md +++ b/docs/_STYLE_GUIDE.md @@ -244,16 +244,33 @@ Instead, break into separate sections or use an admonition for context. ## FAQ Sections -Format as bold question followed by answer paragraph: +Use a TOC with jump links, `###` headers for questions, and direct answers: ```md -**Do I always need architecture?** +## Questions + +- [Do I always need architecture?](#do-i-always-need-architecture) +- [Can I change my plan later?](#can-i-change-my-plan-later) + +### Do I always need architecture? + Only for BMad Method and Enterprise tracks. Quick Flow skips to implementation. -**Can I change my plan later?** +### Can I change my plan later? + Yes. The SM agent has a `correct-course` workflow for handling scope changes. + +**Have a question not answered here?** Please [open an issue](...) or ask in [Discord](...) so we can add it! ``` +### FAQ Guidelines + +- **TOC at top** — Jump links under `## Questions` for quick navigation +- **`###` headers** — Questions are scannable and linkable (no `Q:` prefix) +- **Direct answers** — No `**A:**` prefix, just the answer +- **No "Related Documentation"** — Sidebar handles navigation; avoid repetitive links +- **End with CTA** — "Have a question not answered here?" with issue/Discord links + ## Folder Structure Blocks Show project structure in "What You've Accomplished": diff --git a/docs/explanation/faq/brownfield-faq.md b/docs/explanation/faq/brownfield-faq.md index 5c15cb5e..79e192b2 100644 --- a/docs/explanation/faq/brownfield-faq.md +++ b/docs/explanation/faq/brownfield-faq.md @@ -2,22 +2,25 @@ 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 -Quick answers to common questions about brownfield (existing codebase) development in the BMad Method. +- [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? -## Q: What is brownfield vs greenfield? +- **Greenfield** — New project, starting from scratch, clean slate +- **Brownfield** — Existing project, working with established codebase and patterns -**A:** +### Do I have to run document-project for brownfield? -- **Greenfield:** New project, starting from scratch, clean slate -- **Brownfield:** Existing project, working with established codebase and patterns - -## Q: Do I have to run document-project for brownfield? - -**A:** Highly recommended, especially if: +Highly recommended, especially if: - No existing documentation - Documentation is outdated @@ -26,9 +29,9 @@ Quick answers to common questions about brownfield (existing codebase) developme You can skip it if you have comprehensive, up-to-date documentation including `docs/index.md`. -## Q: What if I forget to run document-project on brownfield? +### What if I forget to run document-project? -**A:** Workflows will lack context about existing code. You may get: +Workflows will lack context about existing code. You may get: - Suggestions that don't match existing patterns - Integration approaches that miss existing APIs @@ -36,9 +39,9 @@ You can skip it if you have comprehensive, up-to-date documentation including `d Run document-project and restart planning with proper context. -## Q: Can I use Quick Spec Flow for brownfield projects? +### Can I use Quick Spec Flow for brownfield projects? -**A:** Yes! Quick Spec Flow works great for brownfield. It will: +Yes! Quick Spec Flow works great for brownfield. It will: - Auto-detect your existing stack - Analyze brownfield code patterns @@ -47,34 +50,24 @@ Run document-project and restart planning with proper context. Perfect for bug fixes and small features in existing codebases. -## Q: How does workflow-init handle brownfield with old planning docs? +### How does workflow-init handle old planning docs? -**A:** workflow-init asks about YOUR current work first, then uses old artifacts as context: +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 new Level 0 bug fix. +This prevents old Level 3 PRDs from forcing Level 3 workflow for a new Level 0 bug fix. -## Q: What if my existing code doesn't follow best practices? +### What if my existing code doesn't follow best practices? -**A:** Quick Spec Flow detects your conventions and asks: "Should I follow these existing conventions?" You decide: +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. - ---- - -## Related Documentation - -- [Quick Start Guide](/tutorials/getting-started/getting-started-bmadv6/) - Get started with BMM -- [Brownfield Guide](/how-to/brownfield/) - Existing codebase workflows -- [Glossary](/reference/glossary/) - Terminology reference - ---- +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! diff --git a/docs/explanation/faq/getting-started-faq.md b/docs/explanation/faq/getting-started-faq.md index 49ccda48..f8428e47 100644 --- a/docs/explanation/faq/getting-started-faq.md +++ b/docs/explanation/faq/getting-started-faq.md @@ -3,14 +3,19 @@ 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 -## Q: Do I always need to run workflow-init? +- [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) -**A:** No, once you learn the flow you can go directly to workflows. However, workflow-init is helpful because it: +### 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 @@ -18,9 +23,9 @@ Quick answers to common questions about getting started with the BMad Method. For experienced users: use the [Quick Start Guide](/tutorials/getting-started/getting-started-bmadv6/) to go directly to the right agent/workflow. -## Q: Why do I need fresh chats for each workflow? +### Why do I need fresh chats for each workflow? -**A:** 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: +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) @@ -28,39 +33,30 @@ For experienced users: use the [Quick Start Guide](/tutorials/getting-started/ge Quick workflows like status checks can reuse chats safely. -## Q: Can I skip workflow-status and just start working? +### Can I skip workflow-status and just start working? -**A:** Yes, if you already know your project level and which workflow comes next. workflow-status is mainly useful for: +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 -## Q: What's the minimum I need to get started? +### What's the minimum I need to get started? -**A:** For the fastest path: +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 -## Q: How do I know if I'm in Phase 1, 2, 3, or 4? +### How do I know if I'm in Phase 1, 2, 3, or 4? -**A:** 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: +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 - ---- - -## Related Documentation - -- [Quick Start Guide](/tutorials/getting-started/getting-started-bmadv6/) - Get started with BMM -- [Glossary](/reference/glossary/) - Terminology reference - ---- +- **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! diff --git a/docs/explanation/faq/implementation-faq.md b/docs/explanation/faq/implementation-faq.md index 795529b9..fe4f64cb 100644 --- a/docs/explanation/faq/implementation-faq.md +++ b/docs/explanation/faq/implementation-faq.md @@ -3,54 +3,50 @@ title: "Implementation FAQ" description: Common questions about implementation in the BMad Method --- - Quick answers to common questions about implementation in the BMad Method. ---- +## Questions -## Q: Does create-story include implementation context? +- [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) -**A:** 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. +### Does create-story include implementation context? -## Q: How do I mark a story as done? +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. -**A:** After dev-story completes and code-review passes: +### 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 -## Q: Can I work on multiple stories at once? +### Can I work on multiple stories at once? -**A:** 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. +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. -## Q: What if my story takes longer than estimated? +### What if my story takes longer than estimated? -**A:** That's normal! Stories are estimates. If implementation reveals more complexity: +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 -## Q: When should I run retrospective? +### When should I run retrospective? -**A:** After completing all stories in an epic (when epic is done). Retrospectives capture: +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. - ---- - -## Related Documentation - -- [Quick Start Guide](/tutorials/getting-started/getting-started-bmadv6/) - Get started with BMM -- [Glossary](/reference/glossary/) - Terminology reference - ---- +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! diff --git a/docs/explanation/faq/index.md b/docs/explanation/faq/index.md deleted file mode 100644 index 47a0806e..00000000 --- a/docs/explanation/faq/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -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](/explanation/faq/getting-started-faq/) - Questions about starting with BMM -- [Levels & Tracks](/explanation/faq/levels-and-tracks-faq/) - Choosing the right level -- [Workflows](/explanation/faq/workflows-faq/) - Workflow and phase questions -- [Planning](/explanation/faq/planning-faq/) - Planning document questions -- [Implementation](/explanation/faq/implementation-faq/) - Implementation questions -- [Brownfield](/explanation/faq/brownfield-faq/) - Existing codebase questions -- [Tools & Advanced](/explanation/faq/tools-faq/) - Tools, IDEs, and advanced topics diff --git a/docs/explanation/faq/levels-and-tracks-faq.md b/docs/explanation/faq/levels-and-tracks-faq.md index 29decf82..acce6ae1 100644 --- a/docs/explanation/faq/levels-and-tracks-faq.md +++ b/docs/explanation/faq/levels-and-tracks-faq.md @@ -3,41 +3,44 @@ 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 -## Q: How do I know which level my project is? +- [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) -**A:** Use workflow-init for automatic detection, or self-assess using these keywords: +### How do I know which level my project is? -- **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 +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. -## Q: Can I change levels mid-project? +### Can I change levels mid-project? -**A:** 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. +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. -## Q: What if workflow-init suggests the wrong level? +### What if workflow-init suggests the wrong level? -**A:** 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. +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. -## Q: Do I always need architecture for Level 2? +### Do I always need architecture for Level 2? -**A:** 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. +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. -## Q: What's the difference between Level 1 and Level 2? +### What's the difference between Level 1 and Level 2? -**A:** - -- **Level 1:** 1-10 stories, uses tech-spec (simpler, faster), no architecture -- **Level 2:** 5-15 stories, uses PRD (product-focused), optional architecture +- **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: @@ -46,13 +49,4 @@ The overlap (5-10 stories) is intentional. Choose based on: - Multiple epics? → Level 2 - Single epic? → Level 1 ---- - -## Related Documentation - -- [Quick Start Guide](/tutorials/getting-started/getting-started-bmadv6/) - Get started with BMM -- [Glossary](/reference/glossary/) - Terminology reference - ---- - **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! diff --git a/docs/explanation/faq/planning-faq.md b/docs/explanation/faq/planning-faq.md index 07f02459..c6ab49fe 100644 --- a/docs/explanation/faq/planning-faq.md +++ b/docs/explanation/faq/planning-faq.md @@ -3,22 +3,25 @@ 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 -## Q: Why no tech-spec at Level 2+? +- [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) -**A:** 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: +### 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) -## Q: Do I need a PRD for a bug fix? +### Do I need a PRD for a bug fix? -**A:** No! Bug fixes are typically Level 0 (single atomic change). Use Quick Spec Flow: +No! Bug fixes are typically Level 0 (single atomic change). Use Quick Spec Flow: - Load PM agent - Run tech-spec workflow @@ -26,22 +29,13 @@ Quick answers to common questions about planning documents in the BMad Method. PRDs are for Level 2-4 projects with multiple features requiring product-level coordination. -## Q: Can I skip the product brief? +### Can I skip the product brief? -**A:** Yes, product brief is always optional. It's most valuable for: +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 ---- - -## Related Documentation - -- [Quick Start Guide](/tutorials/getting-started/getting-started-bmadv6/) - Get started with BMM -- [Glossary](/reference/glossary/) - Terminology reference - ---- - **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! diff --git a/docs/explanation/faq/tools-faq.md b/docs/explanation/faq/tools-faq.md index 3dcb8532..ac72d228 100644 --- a/docs/explanation/faq/tools-faq.md +++ b/docs/explanation/faq/tools-faq.md @@ -3,16 +3,38 @@ 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 -### Q: Why are my Mermaid diagrams not rendering? +### Why are my Mermaid diagrams not rendering? -**A:** Common issues: +Common issues: 1. Missing language tag: Use ` ```mermaid` not just ` ``` ` 2. Syntax errors in diagram (validate at mermaid.live) @@ -20,9 +42,9 @@ Quick answers to common questions about tools, IDEs, and advanced topics in the All BMM docs use valid Mermaid syntax that should render in GitHub, VS Code, and most IDEs. -### Q: Can I use BMM with GitHub Copilot / Cursor / other AI tools? +### Can I use BMM with GitHub Copilot / Cursor / other AI tools? -**A:** Yes! BMM is complementary. BMM handles: +Yes! BMM is complementary. BMM handles: - Project planning and structure - Workflow orchestration @@ -38,13 +60,13 @@ Your AI coding assistant handles: Use them together for best results. -### Q: What IDEs/tools support BMM? +### What IDEs/tools support BMM? -**A:** 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. +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 +- **Claude Code** — Best choice - Sonnet 4.5 (excellent workflow following, coding, reasoning) - Opus (maximum context, complex planning) - Native agent mode designed for BMM workflows @@ -61,22 +83,22 @@ Use them together for best results. **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 +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. -### Q: Can I customize agents? +### Can I customize agents? -**A:** 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. +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. +**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. -### Q: What happens to my planning docs after implementation? +### What happens to my planning docs after implementation? -**A:** Keep them! They serve as: +Keep them! They serve as: - Historical record of decisions - Onboarding material for new team members @@ -85,37 +107,35 @@ Use them together for best results. For enterprise projects (Level 4), consider archiving completed planning artifacts to keep workspace clean. -### Q: Can I use BMM for non-software projects? +### Can I use BMM for non-software projects? -**A:** 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. +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 -## Advanced Questions +### What if my project grows from Level 1 to Level 3? -### Q: What if my project grows from Level 1 to Level 3? - -**A:** Totally fine! When you realize scope has grown: +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. +The system is flexible — growth is expected. -### Q: Can I mix greenfield and brownfield approaches? +### Can I mix greenfield and brownfield approaches? -**A:** Yes! Common scenario: adding new greenfield feature to brownfield codebase. Approach: +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 -### Q: How do I handle urgent hotfixes during a sprint? +### How do I handle urgent hotfixes during a sprint? -**A:** Use correct-course workflow or just: +Use correct-course workflow or just: 1. Save your current work state 2. Load PM agent → quick tech-spec for hotfix @@ -125,25 +145,25 @@ The system is flexible - growth is expected. Level 0 Quick Spec Flow is perfect for urgent fixes. -### Q: What if I disagree with the workflow's recommendations? +### What if I disagree with the workflow's recommendations? -**A:** Workflows are guidance, not enforcement. If a workflow recommends something that doesn't make sense for your context: +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. +Trust your expertise — BMM supports your decisions. -### Q: Can multiple developers work on the same BMM project? +### Can multiple developers work on the same BMM project? -**A:** Yes! But the paradigm is fundamentally different from traditional agile teams. +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) +- **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. @@ -177,9 +197,9 @@ Trust your expertise - BMM supports your decisions. - Coordinate at epic boundaries, not story level - Use git submodules for BMM in enterprise settings -### Q: What is party mode and when should I use it? +### What is party mode and when should I use it? -**A:** 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. +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:** @@ -197,9 +217,9 @@ Trust your expertise - BMM supports your decisions. **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) +- **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:** @@ -208,26 +228,20 @@ Trust your expertise - BMM supports your decisions. - Emergent insights from agent interaction - Natural collaboration across modules -**For complete documentation:** - -👉 **[Party Mode Guide](/explanation/features/party-mode/)** - How it works, when to use it, example compositions, best practices - ---- +**For complete documentation:** See the [Party Mode Guide](/explanation/features/party-mode/) ## Getting Help -### Q: Where do I get help if my question isn't answered here? - -**A:** +### 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) -### Q: How do I report a bug or request a feature? +### How do I report a bug or request a feature? -**A:** Open a GitHub issue at: +Open a GitHub issue at: Please include: @@ -236,13 +250,4 @@ Please include: - Expected vs actual behavior - Relevant workflow or agent involved ---- - -## Related Documentation - -- [Quick Start Guide](/tutorials/getting-started/getting-started-bmadv6/) - Get started with BMM -- [Glossary](/reference/glossary/) - Terminology reference - ---- - **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! diff --git a/docs/explanation/faq/workflows-faq.md b/docs/explanation/faq/workflows-faq.md index dc4d9bc2..9e92121f 100644 --- a/docs/explanation/faq/workflows-faq.md +++ b/docs/explanation/faq/workflows-faq.md @@ -3,66 +3,59 @@ title: "Workflows FAQ" description: Common questions about BMad Method workflows and phases --- - Quick answers to common questions about BMad Method workflows and phases. ---- +## Questions -## Q: What's the difference between workflow-status and workflow-init? +- [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) -**A:** +### 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) +- **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. -## Q: Can I skip Phase 1 (Analysis)? +### Can I skip Phase 1 (Analysis)? -**A:** Yes! Phase 1 is optional for all levels, though recommended for complex projects. Skip if: +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) -## Q: When is Phase 3 (Architecture) required? +### When is Phase 3 (Architecture) required? -**A:** +- **Level 0-1** — Never (skip entirely) +- **Level 2** — Optional (only if system design needed) +- **Level 3-4** — Required (comprehensive architecture mandatory) -- **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? -## Q: What happens if I skip a recommended workflow? - -**A:** Nothing breaks! Workflows are guidance, not enforcement. However, skipping recommended workflows (like architecture for Level 3) may cause: +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 -## Q: How do I know when Phase 3 is complete and I can start Phase 4? +### How do I know when Phase 3 is complete? -**A:** 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. +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. -## Q: Can I run workflows in parallel or do they have to be sequential? +### Can I run workflows in parallel? -**A:** Most workflows must be sequential within a phase: +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 - ---- - -## Related Documentation - -- [Quick Start Guide](/tutorials/getting-started/getting-started-bmadv6/) - Get started with BMM -- [Glossary](/reference/glossary/) - Terminology reference - ---- +- **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!