mirror of
https://github.com/bmad-code-org/BMAD-METHOD.git
synced 2026-01-30 04:32:02 +00:00
2e16650067
* feat(docs): add Diataxis folder structure and update sidebar styling - Create tutorials, how-to, explanation, reference directories with subdirectories - Add index.md files for each main Diataxis section - Update homepage with Diataxis card navigation layout - Implement clean React Native-inspired sidebar styling - Convert sidebar to autogenerated for both Diataxis and legacy sections - Update docusaurus config with dark mode default and navbar changes 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * feat(docs): migrate Phase 1 files to Diataxis structure Move 21 files to new locations: - Tutorials: quick-start guides, agent creation guide - How-To: installation, customization, workflows - Explanation: core concepts, features, game-dev, builder - Reference: merged glossary from BMM and BMGD Also: - Copy images to new locations - Update internal links via migration script (73 links updated) - Build verified successfully 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(docs): add category labels for sidebar folders Add _category_.json files to control display labels and position for autogenerated sidebar categories. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * style(docs): improve welcome page and visual styling - Rewrite index.md with React Native-inspired welcoming layout - Add Diataxis section cards with descriptions - Remove sidebar separator, add spacing instead - Increase navbar padding with responsive breakpoints - Add rounded admonitions without left border bar - Use system font stack for better readability - Add lighter chevron styling in sidebar - Constrain max-width to 1600px for wide viewports 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix: use baseUrl in meta tag paths for correct deployment URLs * feat(docs): complete Phase 2 - split files and fix broken links Phase 2 of Diataxis migration: - Split 16 large legacy files into 42+ focused documents - Created FAQ section with 7 topic-specific files - Created brownfield how-to guides (3 files) - Created workflow how-to guides (15+ files) - Created architecture explanation files (3 files) - Created TEA/testing explanation files - Moved remaining legacy module files to proper Diataxis locations Link fixes: - Fixed ~50 broken internal links across documentation - Updated relative paths for new file locations - Created missing index files for installation, advanced tutorials - Simplified TOC anchors to fix Docusaurus warnings Cleanup: - Removed legacy sidebar entries for deleted folders - Deleted duplicate and empty placeholder files - Moved workflow diagram assets to tutorials/images 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(build): use file glob instead of sidebar parsing for llms-full.txt Replace brittle sidebar.js regex parsing with recursive file glob. The old approach captured non-file strings like 'autogenerated' and category labels, resulting in only 5 files being processed. Now correctly processes all 86+ markdown files (~95k tokens). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(seo): use absolute URLs in AI meta tags for agent discoverability AI web-browsing agents couldn't follow relative paths in meta tags due to URL security restrictions. Changed llms-full.txt and llms.txt meta tag URLs from relative (baseUrl) to absolute (urlParts.origin + baseUrl). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * refactor(docs): recategorize misplaced files per Diataxis analysis Phase 2.5 categorization fixes based on post-migration analysis: Moved to correct Diataxis categories: - tutorials/installation.md → deleted (duplicate of how-to/install-bmad.md) - tutorials/brownfield-onboarding.md → how-to/brownfield/index.md - reference/faq/* (8 files) → explanation/faq/ - reference/agents/barry-quick-flow.md → explanation/agents/ - reference/agents/bmgd-agents.md → explanation/game-dev/agents.md Created: - explanation/agents/index.md Fixed all broken internal links (14 total) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * feat(docs): add Getting Started tutorial and simplify build script - Add comprehensive Getting Started tutorial with installation as Step 1 - Simplify build-docs.js to read directly from docs/ (no consolidation) - Remove backup/restore dance that could corrupt docs folder on build failure - Remove ~150 lines of unused consolidation code 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(css): use fixed width layout to prevent content shifting Apply React Native docs approach: set both width and max-width at largest breakpoint (1400px) so content area maintains consistent size regardless of content length. Switches to fluid 100% below 1416px breakpoint. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * refactor(docs): restructure tutorials with renamed entry point - Rename index.md to bmad-tutorial.md for clearer navigation - Remove redundant tutorials/index.md - Update sidebar and config references 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * feat(docs): add tutorial style guide and AI agent announcement bar - Add docs/_contributing/ with tutorial style guide - Reformat quick-start-bmm.md and bmad-tutorial.md per style guide - Remove horizontal separators, add strategic admonitions - Add persistent announcement bar for AI agents directing to llms-full.txt - Fix footer broken link to tutorials 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * feat(docs): add markdown demo page and UI refinements - Add comprehensive markdown-demo.md for style testing - Remove doc category links from navbar (use sidebar instead) - Remove card buttons from welcome page - Add dark mode styling for announcement bar - Clean up index.md card layout 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * feat(docs): apply unified tutorial style and update references - Reformat create-custom-agent.md to follow tutorial style guide - Update tutorial-style.md with complete unified structure - Update all internal references to renamed tutorial files - Remove obsolete advanced/index.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * refactor(docs): migrate from Docusaurus to Astro+Starlight Replace Docusaurus with Astro and the Starlight documentation theme for improved performance, better customization, and modern tooling. Build pipeline changes: - New build-docs.js orchestrates link checking, artifact generation, and Astro build in sequence - Add check-doc-links.js for validating internal links and anchors - Generate llms.txt and llms-full.txt for LLM-friendly documentation - Create downloadable source bundles (bmad-sources.zip, bmad-prompts.zip) - Suppress MODULE_TYPELESS_PACKAGE_JSON warning in Astro build - Output directly to build/site for cleaner deployment Website architecture: - Add rehype-markdown-links.js plugin to transform .md links to routes - Add site-url.js helper for GitHub Pages URL resolution with strict validation (throws on invalid GITHUB_REPOSITORY format) - Custom Astro components: Banner, Header, MobileMenuFooter - Symlink docs/ into website/src/content/docs for Starlight Documentation cleanup: - Remove Docusaurus _category_.json files (Starlight uses frontmatter) - Convert all docs to use YAML frontmatter with title field - Move downloads.md from website/src/pages to docs/ - Consolidate style guide and workflow diagram docs - Add 404.md and tutorials/index.md --------- Co-authored-by: forcetrainer <bryan@inagaki.us> Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
249 lines
8.7 KiB
Markdown
249 lines
8.7 KiB
Markdown
---
|
|
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.
|
|
|
|
---
|
|
|
|
## Tools and Technical
|
|
|
|
### Q: Why are my Mermaid diagrams not rendering?
|
|
|
|
**A:** 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.
|
|
|
|
### Q: Can I use BMM with GitHub Copilot / Cursor / other AI tools?
|
|
|
|
**A:** 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.
|
|
|
|
### Q: 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.
|
|
|
|
**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.
|
|
|
|
### Q: 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.
|
|
|
|
**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?
|
|
|
|
**A:** 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.
|
|
|
|
### Q: 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.
|
|
|
|
---
|
|
|
|
## Advanced Questions
|
|
|
|
### Q: What if my project grows from Level 1 to Level 3?
|
|
|
|
**A:** 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.
|
|
|
|
### Q: Can I mix greenfield and brownfield approaches?
|
|
|
|
**A:** 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?
|
|
|
|
**A:** 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.
|
|
|
|
### Q: 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:
|
|
|
|
- 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.
|
|
|
|
### Q: Can multiple developers work on the same BMM project?
|
|
|
|
**A:** 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
|
|
|
|
### Q: 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.
|
|
|
|
**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:**
|
|
|
|
👉 **[Party Mode Guide](../../explanation/features/party-mode.md)** - How it works, when to use it, example compositions, best practices
|
|
|
|
---
|
|
|
|
## Getting Help
|
|
|
|
### Q: Where do I get help if my question isn't answered here?
|
|
|
|
**A:**
|
|
|
|
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) (#general-dev)
|
|
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?
|
|
|
|
**A:** 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
|
|
|
|
---
|
|
|
|
## Related Documentation
|
|
|
|
- [Quick Start Guide](../../tutorials/getting-started/getting-started-bmadv6.md) - Get started with BMM
|
|
- [Glossary](../../reference/glossary/index.md) - 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!
|