BMAD-METHOD/tools-faq.md at 2e16650067f0a12751a95ff22a4277f74b0c4f10

mirror of https://github.com/bmad-code-org/BMAD-METHOD.git synced 2026-01-30 04:32:02 +00:00

Files

Alex Verkhovsky 2e16650067 feat(docs): Diataxis restructure + Astro/Starlight migration (#1263 )

* 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>

2026-01-07 14:42:15 +08:00

8.7 KiB

Raw Blame History

title, description

title	description
Tools and Advanced FAQ	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:

Missing language tag: Use ```mermaid not just ```
Syntax errors in diagram (validate at mermaid.live)
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:

Agent mode - Can load long workflow instructions and maintain context
High-quality LLM - Models ranked high on SWE-bench (coding benchmarks)
Model selection - Access to Claude Sonnet 4.5, Opus, or GPT-4o class models
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:

Run create-prd to add product-level planning
Run create-architecture for system design
Use existing tech-spec as input for PRD
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:

Run document-project for brownfield context
Use greenfield workflows for new feature planning
Explicitly document integration points between new and existing
Test integration thoroughly

Q: How do I handle urgent hotfixes during a sprint?

A: Use correct-course workflow or just:

Save your current work state
Load PM agent → quick tech-spec for hotfix
Implement hotfix (Level 0 flow)
Deploy hotfix
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:

Run /bmad:core:workflows:party-mode (or *party-mode from any agent)
Introduce your topic
BMad Master selects 2-3 most relevant agents per message
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 - 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?

Search Complete Documentation for related topics
Ask in Discord Community (#general-dev)
Open a GitHub Issue
Watch YouTube Tutorials

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

Quick Start Guide - Get started with BMM
Glossary - Terminology reference

Have a question not answered here? Please open an issue or ask in Discord so we can add it!

8.7 KiB Raw Blame History