- Remove duplicate H1 header (frontmatter provides title)
- Remove horizontal rules throughout
- Convert Prerequisites to admonition
- Add Quick Path TL;DR admonition
- Convert Key Takeaway to tip admonition
- Convert TEA Workflows list to Quick Reference table
- Convert Troubleshooting to Common Questions FAQ format
- Rename Need Help to Getting Help section
- Remove redundant Feedback section
Also adds missing @clack/prompts dependency from upstream merge.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: optimize style guide for LLM readers
Restructure documentation style guide with dependency-first ordering
and LLM-optimized content based on editorial-review-structure analysis.
Key changes:
- Add Universal Formatting Rules section at top (consolidated anti-patterns)
- Move Visual Hierarchy and formatting rules before document types
- Add Document Types decision table for type selection
- Move Before/After example to follow Visual Hierarchy
- Merge Links/Images into single Assets table
- Move tutorial-specific checklist into Tutorial Structure section
- Move Validation Steps to end (submission workflow)
- Cut abstract Quick Principles (no execution value for LLMs)
- Remove emotional/orientation language throughout
- Condense FAQ Sections structure
Result: ~35% reduction (539 deletions, 383 insertions) with improved
parseability for AI agents writing documentation.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: clarify explanation checklist admonition limit
Disambiguate 2-3 admonitions max to explicitly show it is a per-document
limit that still respects the universal per-section rule.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: clarify header budget vs structure template relationship
Add note explaining that structure templates show content flow, not 1:1
header mapping. Admonitions and inline elements are within sections.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: remove horizontal rules to follow own guidelines
Remove all --- section separators to comply with Universal Formatting
Rules. The ## headers provide sufficient visual separation.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: address PR review findings for style guide
- Fix forward reference in Header Budget section
- Clarify descriptions rule scope (tables and 5+ item lists)
- Restore realistic FAQ examples
- Add qualifier to admonition content length guideline
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: further optimize style guide as delta-only document
- Add opener declaring adherence to Google Style Guide and Diataxis
- Remove generic Google style guide sections (Visual Hierarchy patterns,
Tables constraints, Code Blocks, Lists, Assets)
- Remove Diataxis explainer content (Document Types table, "X documents
do Y" explanatory sentences, Before/After example)
- Keep all project-specific structure templates and checklists
- Consolidate rules into single Project-Specific Rules table
Result: 367 lines (down from 597), pure delta document assuming
LLM training knowledge of baseline standards.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
- Add "Why does BMad use so many tokens?" FAQ explaining design tradeoff
(decision quality over code velocity)
- Fix stale anchor #adversarial-review-general → #adversarial-review
- Remove link to archived customize-workflows.md
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: expand TEA documentation with cheat sheets, MCP enhancements, and API testing patterns
* docs: update TEA fragment counts and fix playwright-utils code examples
* docs: addressed PR review concerns
* docs: update TEA MCP configuration link to point to documentation site
* feat: add link auditor tools and fix broken docs links
- Add audit-doc-links.js to scan docs for broken links with auto-resolution
- Add fix-doc-links.js to apply suggested fixes (dry-run by default)
- Remove stale "Back to Core Concepts" breadcrumb links
- Update BMad acronym to "Breakthrough Method of Agile AI Driven Development"
- Update README links to docs.bmad-method.org
- Simplify upgrade callout in getting-started tutorial
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: reorganize docs structure and archive v4 tutorial
- Remove unused section index files (tutorials, how-to, explanation, reference)
- Move getting-started-bmadv4.md to _archive
- Update quick-start-bmgd.md to remove archived file reference
- Update upgrade-to-v6.md
- Update astro.config.mjs for new structure
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: ignore underscore directories in link checker
Update check-doc-links.js to skip _archive, _planning, and other
underscore-prefixed directories when validating links.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: add v4 users section to README
Add links to v4 documentation archive and upgrade guide for users
migrating from previous versions.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat: convert docs to site-relative links and add validation tools
- Convert all relative links (./ ../) to site-relative paths (/path/)
- Strip .md extensions and use trailing slashes for Astro/Starlight
- Add fix-doc-links.js to convert relative links to site-relative
- Add validate-doc-links.js to check links point to existing files
- Remove old audit-doc-links.js and check-doc-links.js
- Update build-docs.js to use new validation script
- Add npm scripts: docs:fix-links, docs:validate-links
- Update style guide with validation steps
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: standardize acronym to BMad across documentation
Replace incorrect "BMAD" with correct "BMad" in text and frontmatter
while preserving "BMAD-METHOD" in GitHub URLs.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: fix BMad acronym and remove draft README
- Correct acronym to "Breakthrough Method of Agile AI Driven Development"
- Remove unused README-draft.md
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: standardize BMad acronym in README
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: standardize FAQ format across all FAQ pages
- Add TOC with jump links under "## Questions"
- Use ### headers for questions (no Q: prefix)
- Direct answers without **A:** prefix
- Remove horizontal rules and "Related Documentation" sections
- End each FAQ with issue/Discord CTA
- Update style guide with new FAQ guidelines
- Delete redundant faq/index.md (sidebar handles navigation)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: use repo-relative links with .md for GitHub compatibility
Convert all documentation links to repo-relative format (/docs/path/file.md)
so they work when browsing on GitHub. The rehype plugin strips /docs/ prefix
and converts .md to trailing slash at build time for Astro/Starlight.
- Update rehype-markdown-links.js to strip /docs/ prefix from absolute paths
- Update fix-doc-links.js to generate /docs/ prefixed paths with .md extension
- Convert 217 links across 64 files to new format
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: handle /docs/ prefix in link validator
Update resolveLink to strip /docs/ prefix from repo-relative links
before checking if files exist.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: restore FAQ index page
Re-add the FAQ index page that was accidentally deleted, with
updated repo-relative link format.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Alex Verkhovsky <alexey.verkhovsky@gmail.com>
* 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>
* fix(docs): align sidebar with actual docs structure and fix image path
Sidebar referenced non-existent paths (modules/bmm/, getting-started/, etc.)
while actual docs live in different locations (modules/bmm-bmad-method/,
bmad-core-concepts/, etc.). Updated sidebar to match reality so Docusaurus
can build successfully.
Also fixed broken image reference in workflows-guide.md that used an
incorrect relative path.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix(docs): update build script to include docs/modules directory
The build script was excluding the modules folder when copying from docs/,
but module docs now live in docs/modules/ instead of src/modules/*/docs/.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix(docs): correct broken internal links
Fixed relative paths that were pointing to non-existent locations:
- bmgd index: ../../bmm/docs/index.md → ../bmm/index.md
- cis index: ../../bmm/docs/index.md → ../bmm/index.md
- bmm faq: ./README.md → GitHub URL
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
* docs: chose your tea engagement
* docs: addressed PR comments
* docs: made refiements to the mermaid diagram
* docs: wired in test architect discoverability nudges
---------
Co-authored-by: Brian <bmadcode@gmail.com>
* feat: add documentation website with Docusaurus build pipeline
* feat(docs): add AI discovery meta tags for llms.txt files
- Add global headTags with ai-terms, llms, llms-full meta tags
- Update landing page link to clarify AI context purpose
* fix(docs): restore accidentally deleted faq.md and glossary.md
Files were removed in 12dd97fe during path restructuring.
* fix(docs): update broken project-readme links to GitHub URL
* feat(schema): add compound trigger format validation
forcetrainer
Murat K Ozcan
Alex Verkhovsky
Brian Madison
forcetrainer
Wendy Smoak