* 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>
Integrates the bmad-guide skill into BMAD installation process to help
Claude stay on track with BMAD methodology.
Features:
- Phase navigation and workflow selection guidance
- Project level detection (0-4) for routing to correct workflows
- Common mistakes prevention (skipping phases, manual coding)
- Emergency recovery procedures when off track
- Quick reference tables and troubleshooting
Implementation:
- Created resources/skills/ directory with bmad-guide.md (428 lines)
- Added installBmadGuideSkill() to ClaudeCodeSetup class
- Skill auto-installs to ~/.claude/skills/ during setup
- Available globally across all BMAD projects
- Updated installation documentation
Usage:
- Automatic: Skill is installed when running npx bmad-method install
- Manual access: /bmad-guide command in any project
- Optional: Add BMAD Method config to ~/.claude/CLAUDE.md for automatic invocation
Benefits:
- Prevents Claude from jumping straight to coding without workflows
- Ensures proper phase progression
- Guides workflow selection based on project level
- Self-corrects when going off track
- New /autonomous-epic command processes entire epic
- Just-in-time planning: creates each story before developing
- Auto-develops using super-dev-story or dev-story
- Progress tracking with resume capability
- Git commits after each story completion
- Error handling with retry logic and continue-on-failure
- Epic completion report with statistics
- Estimated: 100K-150K tokens per story
Use cases:
- Overnight epic completion
- CI/CD integration
- Batch sprint processing
Applies to both BMM and BMGD modules
- Complete gap analysis feature documentation
- Migration guide for existing users
- Usage examples for all planning styles
- Troubleshooting and FAQ sections
* 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
Major Changes:
- Add sample custom agents demonstrating installable agent system
- commit-poet: Generates semantic commit messages (BMAD Method repo sample)
- toolsmith: Development tooling expert with knowledge base covering bundlers, deployment, docs, installers, modules, and tests (BMAD Method repo sample)
- Both agents demonstrate custom agent architecture and are installable to projects via BMAD installer system
- Include comprehensive installation guides and sidecar knowledge bases
- Add bmad-quick-flow methodology for rapid development
- create-tech-spec: Direct technical specification workflow
- quick-dev: Flexible execution workflow supporting both tech-spec-driven and direct instruction development
- quick-flow-solo-dev (Barry): 1 man show agent specialized in bmad-quick-flow methodology
- Comprehensive documentation for quick-flow approach and solo development
- Remove deprecated tech-spec workflow track
- Delete entire tech-spec workflow directory and templates
- Remove quick-spec-flow.md documentation (replaced by quick-flow docs)
- Clean up unused epic and story templates
- Fix custom agent installation across IDE installers
- Repair antigravity and multiple IDE installers to properly support custom agents
- Enable custom agent installation via quick installer, agent installer, regular installer, and special agent installer
- All installation methods now accessible via npx with full documentation
Infrastructure:
- Update BMM module configurations and team setups
- Modify workflow status paths to support quick-flow integration
- Reorganize documentation with new agent and workflow guides
- Add custom/ directory for user customizations
- Update platform codes and installer configurations
- Change --path → --source (much clearer purpose)
- Change --target → --destination (more intuitive)
- Update all code references and documentation
- Add advanced parameter examples to installation guide
- Keep short aliases: -s for --source, -t for --destination
Parameters are now much more self-explanatory:
- --source: where to find the agent YAML
- --destination: where to install the compiled agent
- Fix npx bmad → npx bmad-method in documentation
- Only bmad-method is registered in npm registry, not bmad
- Clarify that bmad command works locally when BMAD is installed
- Update installation guides to use correct package name
Ensures users don't get 'package not found' errors when trying npx bmad
## The Tale of the Frame Expert
Once upon a time, BMad Method had a specialized agent called Frame Expert.
This agent was the master of all visual artifacts - flowcharts, diagrams,
wireframes, data flows. Whenever anyone needed a diagram, they called upon
Frame Expert. The agent lived in its own isolated domain with four dedicated
workflows and a library of shared templates.
## The Awakening
But something felt wrong. Teams using BMad Method were meant to mirror real
agile teams - Product Managers, Architects, UX Designers, Tech Writers,
Developers. Each agent represented an authentic role you'd find in any
software team.
Except Frame Expert.
No real agile team has a "Frame Expert" or "Diagram Specialist" who creates
all visual artifacts. In real teams, Architects diagram system architecture.
PMs flowchart processes. UX Designers wireframe interfaces. Tech Writers
create documentation diagrams. The visuals emerge from the domain experts
who need them, not from a centralized diagram factory.
Frame Expert was an abstraction that made technical sense but violated the
very soul of BMad Method - authentic agile role modeling.
## The Transformation
And so Frame Expert was dissolved, its knowledge distributed to those who
truly needed it:
**The Architect** inherited system architecture diagrams and data flows -
the blueprints of technical systems they design.
**The Product Manager** received process flowcharts - the visual maps of
features and workflows they orchestrate.
**The UX Designer** claimed wireframes - the interface sketches that bring
their vision to life.
**The Tech Writer** gained all diagram types - the visual aids that clarify
their documentation.
Each agent now creates diagrams in their domain, using their expertise,
serving their purpose.
## The Shared Knowledge
But the wisdom of diagram creation itself - the Excalidraw templates, the
component libraries, the validation patterns - this knowledge was too
valuable to scatter. It was elevated to core resources, where both BMM
agents AND the new CIS presentation-master agent could draw upon it.
Shared infrastructure for common needs. Distributed execution for domain
expertise.
## The Ripple Effects
With diagrams now properly distributed, other misalignments became visible:
Epic creation was happening in Phase 2 (Planning), before Architecture
existed. But epics need architectural context - API contracts, data models,
technical decisions. So epic creation migrated to Phase 3 (Solutioning),
after Architecture provides that foundation.
Workflow paths were updated. Documentation gained visual flowcharts showing
the complete journey. Agent naming standards were clarified - filenames are
stable roles, persona names are user dreams.
## What Changed
**Removed:**
- frame-expert.agent.yaml (the centralized specialist)
- All frame-expert workflows and shared resources
- Phase 2 epic creation workflow (wrong timing)
- game-design workflow path (consolidated to method track)
- v6-open-items.md (planning doc, now complete)
**Distributed Diagram Capabilities:**
- Architect: create-excalidraw-diagram, create-excalidraw-dataflow
- PM: create-excalidraw-flowchart
- Tech Writer: create-excalidraw-{diagram,dataflow,flowchart}, generate-mermaid
- UX Designer: create-excalidraw-wireframe
**Created:**
- src/core/resources/ (shared diagram context for all modules)
- src/modules/cis/agents/presentation-master.agent.yaml (visual comms specialist)
- src/modules/bmm/workflows/3-solutioning/create-epics-and-stories/ (epic creation's new home)
- src/modules/bmm/workflows/diagrams/ (distributed diagram implementations)
- src/modules/bmm/docs/images/ (workflow visualization assets)
**Enhanced:**
- All agent definitions with domain-appropriate diagram workflows
- Documentation with embedded workflow diagrams and visual guides
- Agent compilation docs with critical naming convention rules
- All 4 workflow paths (enterprise/method × brownfield/greenfield)
**Fixed:**
- Epic creation now in Phase 3 after Architecture
- Story context path variables in BMGD module
- PRD workflow descriptions (epics moved to Phase 3)
## For Users
The Frame Expert commands are gone. In their place:
- Need architecture diagrams? Ask `/architect`
- Need process flows? Ask `/pm`
- Need wireframes? Ask `/ux-designer`
- Need documentation visuals? Ask `/tech-writer`
Each expert creates diagrams in their domain, with their context, using
their judgment.
This is how real teams work.
Jonah Schulte
Alex Verkhovsky
Brian Madison
forcetrainer
Murat K Ozcan
Jonah Schulte
Wendy Smoak
mreis-atlassian