Remove hardcoded .bmad folder references throughout documentation and source files, replacing them with the configurable {bmad_folder} placeholder. This change enables users to customize the BMAD installation folder name via configuration, improving flexibility and reducing coupling to a specific directory structure.
Changes include:
- Update all documentation to reference {bmad_folder} instead of .bmad
- Remove legacy configuration files from .bmad and .claude directories
- Update workflow.xml and CLI documentation with new placeholder syntax
## 📚 Complete Documentation Restructure
**BMM Documentation Hub Created:**
- New centralized documentation system at `src/modules/bmm/docs/`
- 18 comprehensive guides organized by topic (7000+ lines total)
- Clear learning paths for greenfield, brownfield, and quick spec flows
- Professional technical writing standards throughout
**New Documentation:**
- `README.md` - Complete documentation hub with navigation
- `quick-start.md` - 15-minute getting started guide
- `agents-guide.md` - Comprehensive 12-agent reference (45 min read)
- `party-mode.md` - Multi-agent collaboration guide (20 min read)
- `scale-adaptive-system.md` - Deep dive on Levels 0-4 (42 min read)
- `brownfield-guide.md` - Existing codebase development (53 min read)
- `quick-spec-flow.md` - Rapid Level 0-1 development (26 min read)
- `workflows-analysis.md` - Phase 1 workflows (12 min read)
- `workflows-planning.md` - Phase 2 workflows (19 min read)
- `workflows-solutioning.md` - Phase 3 workflows (13 min read)
- `workflows-implementation.md` - Phase 4 workflows (33 min read)
- `workflows-testing.md` - Testing & QA workflows (29 min read)
- `workflow-architecture-reference.md` - Architecture workflow deep-dive
- `workflow-document-project-reference.md` - Document-project workflow reference
- `enterprise-agentic-development.md` - Team collaboration patterns
- `faq.md` - Comprehensive Q&A covering all topics
- `glossary.md` - Complete terminology reference
- `troubleshooting.md` - Common issues and solutions
**Documentation Improvements:**
- Removed all version/date footers (git handles versioning)
- Agent customization docs now include full rebuild process
- Cross-referenced links between all guides
- Reading time estimates for all major docs
- Consistent professional formatting and structure
**Consolidated & Streamlined:**
- Module README (`src/modules/bmm/README.md`) streamlined to lean signpost
- Root README polished with better hierarchy and clear CTAs
- Moved docs from root `docs/` to module-specific locations
- Better separation of user docs vs. developer reference
## 🤖 New Agent: Paige (Documentation Guide)
**Role:** Technical documentation specialist and information architect
**Expertise:**
- Professional technical writing standards
- Documentation structure and organization
- Information architecture and navigation
- User-focused content design
- Style guide enforcement
**Status:** Work in progress - Paige will evolve as documentation needs grow
**Integration:**
- Listed in agents-guide.md, glossary.md, FAQ
- Available for all phases (documentation is continuous)
- Can be customized like all BMM agents
## 🔧 Additional Changes
- Updated agent manifest with Paige
- Updated workflow manifest with new documentation workflows
- Fixed workflow-to-agent mappings across all guides
- Improved root README with clearer Quick Start section
- Better module structure explanations
- Enhanced community links with Discord channel names
**Total Impact:**
- 18 new/restructured documentation files
- 7000+ lines of professional technical documentation
- Complete navigation system with cross-references
- Clear learning paths for all user types
- Foundation for knowledge base (coming in beta)
Co-Authored-By: Claude <noreply@anthropic.com>
This major enhancement revolutionizes the tech-spec workflow from a basic template-filling exercise into a context-aware, intelligent planning system for rapid development of bug fixes and small features.
## Tech-Spec Workflow Transformation (11 files)
### Core Workflow Intelligence (instructions.md)
- Add standalone mode with interactive level/field-type detection
- Implement brownfield convention detection and user confirmation
- Integrate WebSearch for current framework versions and starter templates
- Add comprehensive context discovery (stack, patterns, dependencies)
- Implement auto-validation with quality scoring (always runs)
- Add UX/UI considerations capture for user-facing changes
- Add test framework detection and pattern analysis
- Transform from batch generation to living document approach
### Comprehensive Tech-Spec Template (tech-spec-template.md)
- Expand from 8 to 23 sections for complete context
- Add Context section (available docs, project stack, existing structure)
- Add Development Context (conventions, test framework, existing code)
- Add UX/UI Considerations section
- Add Developer Resources (file paths, key locations, testing)
- Add Integration Points and Configuration Changes
- All sections populated via template-output tags during workflow
### Enhanced Story Generation
- Level 0 (instructions-level0-story.md): Extract from comprehensive tech-spec
- Level 1 (instructions-level1-stories.md): Add story sequence validation, AC quality checks
- User Story Template: Add Dev Agent Record sections for implementation tracking
- Epic Template: Complete rewrite with proper structure and variables
### Validation & Quality (checklist.md)
- Add context gathering completeness checks
- Add definitiveness validation (no "use X or Y" statements)
- Add brownfield integration quality scoring
- Add stack alignment verification
- Add implementation readiness assessment
- Auto-generates validation report with scores
### Configuration (workflow.yaml)
- Add runtime variables: project_level, project_type, development_context, change_type, field_type
- Enable standalone operation without workflow-status.yaml
- Support both workflow-init integration and quick-start mode
## Phase 4 Integration (3 files)
### Story Context Workflow
- Add tech_spec to input_file_patterns (recognizes as authoritative source)
- Update instructions to prioritize tech-spec for Level 0-1 projects
- Tech-spec provides brownfield analysis, framework details, existing patterns
### Create Story Workflow
- Add tech_spec to input_file_patterns
- Enable story generation from tech-spec (alternative to PRD)
- Supports both Quick Spec Flow and traditional BMM flow
## Documentation (2 new files)
### Quick Spec Flow Guide (docs/quick-spec-flow.md)
- Comprehensive 595-line guide for Level 0-1 rapid development
- Complete user journey examples (bug fix, small feature)
- Context discovery explanation (stack, brownfield, conventions)
- Auto-validation details and benefits
- Integration with Phase 4 workflows
- Comparison: Quick Spec vs Full BMM
- Real-world examples and best practices
### Scale Adaptive System (docs/scale-adaptive-system.md)
- Complete 950-line technical guide to BMad Method's 5-level system
- Key terminology: Analysis, Tech-Spec, Epic-Tech-Spec, Architecture
- Level 0-4 workflows, planning docs, and progression
- Brownfield emphasis: document-project required first
- Tech-spec (upfront, Level 0-1) vs epic-tech-spec (during implementation, Level 2-4)
- Architecture document replaces tech-spec at Level 2+ (scales with complexity)
- Retrospectives after each epic in multi-epic projects
- Workflow path configuration reference
### README Updates
- Add Quick Spec Flow announcement with benefits
- Link to Scale Adaptive System documentation
- Clarify when to use Quick Spec Flow vs Full BMM
## Key Features
### Context-Aware Intelligence
- Auto-detects project stack from package.json, requirements.txt, etc.
- Analyzes brownfield codebases using document-project output
- Detects code conventions and confirms with user before proceeding
- Uses WebSearch for up-to-date framework info and starter templates
### Brownfield Respect
- Detects existing patterns (code style, test framework, naming conventions)
- Asks user for confirmation before applying conventions
- Adapts to existing code vs forcing changes
- References document-project analysis for comprehensive context
### Auto-Validation
- Always runs (not optional)
- Validates context gathering, definitiveness, brownfield integration
- Scores tech-spec quality and implementation readiness
- Validates story sequence for Level 1 (no forward dependencies)
### Living Document Approach
- Write to tech-spec continuously during discovery
- Progressive refinement vs batch generation
- Template variables populated via template-output tags in real-time
## Breaking Changes
None - all changes are additive and backward compatible.
## Impact
This transformation enables:
- Bug fixes and small features implemented in minutes vs hours
- Automatic stack detection and brownfield analysis
- Respect for existing conventions and patterns
- Current best practices via WebSearch integration
- Comprehensive context that can replace story-context for simple efforts
- Seamless integration with Phase 4 implementation workflows
Quick Spec Flow now provides a **true fast path from idea to implementation** for Level 0-1 projects while maintaining quality through auto-validation and comprehensive context gathering.
- Added support for a new optional `.bmad-flattenignore` file to allow users to specify additional files to exclude from the flattened XML output.
- Updated README and documentation to reflect the new feature and provide examples for usage.
- Modified ignore rules to incorporate patterns from the `.bmad-flattenignore` file after applying `.gitignore` rules.
Benefits:
- Greater flexibility in managing file exclusions for AI model consumption.
- Remove IDE-specific Codex documentation from end of README
- This content was oddly placed after the footer
- IDE-specific docs should be in separate documentation
- CI/CD disabled by default in forks to conserve resources
- Users can enable via ENABLE_CI_IN_FORK repository variable
- Added comprehensive Fork Guide documentation
- Updated README with Contributing section
- Created automation script for future implementations
Benefits:
- Saves GitHub Actions minutes across 1,600+ forks
- Cleaner fork experience for contributors
- Full control for fork owners
- PR validation still runs automatically
BREAKING CHANGE: CI/CD no longer runs automatically in forks.
Fork owners must set ENABLE_CI_IN_FORK=true to enable workflows.
Co-authored-by: Brian <bmadcode@gmail.com>
Co-authored-by: PinkyD <paulbeanjr@gmail.com>
- Remove automatic versioning and dual publishing strategy
- Delete release.yaml and promote-to-stable.yaml workflows
- Add manual-release.yaml for controlled releases
- Remove semantic-release dependencies and config
- Update all documentation to use npx bmad-method install
- Configure NPM to publish to @stable tag by default
- Users can now use simple npx bmad-method install command
* feat(cli): move flatten command to installer and update docs
Refactor the flatten command from tools/cli.js to tools/installer/bin/bmad.js for better integration. Add support for custom input directory and improve error handling. Update documentation in README.md and working-in-the-brownfield.md to reflect new command usage. Also clean up package-lock.json and add it to .gitignore.
* chore: update gitignore and add package-lock.json for installer tool
Remove package-lock.json from root gitignore since it's now needed for the installer tool
Add package-lock.json with dependencies for the bmad-method installer
---------
Co-authored-by: Devin Stagner <devin@blackstag.family>
* This PR introduces a powerful new Codebase Flattener Tool that aggregates entire codebases into AI-optimized XML format, making it easy to share project context with AI assistants for analysis, debugging, and development assistance.
- AI-Optimized XML Output : Generates clean, structured XML specifically designed for AI model consumption
- Smart File Discovery : Recursive file scanning with intelligent filtering using glob patterns
- Binary File Detection : Automatically identifies and excludes binary files, focusing on source code
- Progress Tracking : Real-time progress indicators with comprehensive completion statistics
- Flexible Output : Customizable output file location and naming via CLI arguments
- Gitignore Integration : Automatically respects .gitignore patterns to exclude unnecessary files
- CDATA Handling : Proper XML CDATA sections with escape sequence handling for ]]> patterns
- Content Indentation : Beautiful XML formatting with properly indented file content (4-space indentation)
- Error Handling : Robust error handling with detailed logging for problematic files
- Hierarchical Formatting : Clean XML structure with proper indentation and formatting
- File Content Preservation : Maintains original file formatting within indented CDATA sections
- Exclusion Logic : Prevents self-inclusion of output files ( flattened-codebase.xml , repomix-output.xml )
- tools/flattener/main.js - Complete flattener implementation with CLI interface
- package.json - Added new dependencies (glob, minimatch, fs-extra, commander, ora, chalk)
- package-lock.json - Updated dependency tree
- .gitignore - Added exclusions for flattener outputs
- README.md - Comprehensive documentation with usage examples
- docs/bmad-workflow-guide.md - Integration guidance
- tools/cli.js - CLI integration
- .vscode/settings.json - SonarLint configuration
```
current directory
npm run flatten
npm run flatten -- --output my-project.xml
npm run flatten -- -o /path/to/output/codebase.xml
```
The tool provides comprehensive completion summaries including:
- File count and breakdown (text/binary/errors)
- Source code size and generated XML size
- Total lines of code and estimated token count
- Processing progress and performance metrics
- Bug Fix : Corrected typo in exclusion patterns ( repromix-output.xml → repomix-output.xml )
- Performance : Efficient file processing with streaming and progress indicators
- Reliability : Comprehensive error handling and validation
- Maintainability : Clean, well-documented code with modular functions
- AI Integration : Perfect for sharing codebase context with AI assistants
- Code Reviews : Streamlined code review process with complete project context
- Documentation : Enhanced project documentation and analysis capabilities
- Development Workflow : Improved development assistance and debugging support
This tool significantly enhances the BMad-Method framework's AI integration capabilities, providing developers with a seamless way to share complete project context for enhanced AI-assisted development workflows.
* docs(bmad-core): update documentation for enhanced workflow and user guide
- Fix typos and improve clarity in user guide
- Add new enhanced development workflow documentation
- Update brownfield workflow with flattened codebase instructions
- Improve consistency in documentation formatting
* chore: remove unused files and configurations
- Delete deprecated bmad workflow guide and roomodes file
- Remove sonarlint project configuration
- Downgrade ora dependency version
- Remove jest test script
* Update package.json
Removed jest as it is not needed.
* Update working-in-the-brownfield.md
added documentation for sharding docs
* perf(flattener): improve memory efficiency by streaming xml output
- Replace in-memory XML generation with streaming approach
- Add comprehensive common ignore patterns list
- Update statistics calculation to use file size instead of content length
* fix/chore: Update console.log for user-guide.md install path. Cleaned up config files/folders and updated .gitignore (#347)
* fix: Update console.log for user-guide.md install path
Changed
IMPORTANT: Please read the user guide installed at docs/user-guilde.md
to
IMPORTANT: Please read the user guide installed at .bmad-core/user-guide.md
WHY: the actual install location of the user-guide.md is in the .bmad-core directory.
* chore: remove formatting configs and clean up gitignore
- Delete husky pre-commit hook and prettier config files
- Remove VS Code chat/copilot settings
- Reorganize and clean up gitignore entries
* feat: Overhaul and Enhance 2D Unity Game Dev Expansion Pack (#350)
* Updated game-sm agent to match the new core framework patterns
* feat:Created more comprehensive game story matching new format system as well
* feat:Added Game specific course correct task
* feat:Updated dod-checklist to match new DoD format
* feat:Added new Architect agent for appropriate architecture doc creation and design
* feat:Overhaul of game-architecture-tmpl template
* feat:Updated rest of templates besides level which doesnt really need it
* feat: Finished extended architecture documentation needed for new game story tasks
* feat: Updated game Developer to new format
* feat: Updated last agent to new format and updated bmad-kb. bmad-kb I did my best with but im not sure of it's valid usage in the expansion pack, the AI generated more of the file then myself. I made sure to include it due to the new core-config file
* feat: Finished updating designer agent to new format and cleaned up template linting errors
* Built dist for web bundle
* Increased expansion pack minor verison number
* Updated architecht and design for sharding built-in
* chore: bump bmad-2d-unity-game-dev version (minor)
* updated config.yaml for game-specific pieces to supplement core-config.yaml
* Updated game-core-config and epic processing for game story and game design. Initial implementation was far too generic
* chore: bump bmad-2d-unity-game-dev version (patch)
* feat: Fixed issue with multi-configs being needed. chore: bump bmad-2d-unity-game-dev version (patch)
* Chore: Built web-bundle
* feat: Added the ability to specify the unity editor install location.\nchore: bump bmad-2d-unity-game-dev version (patch)
* feat: core-config must be in two places to support inherited tasks at this time so added instructions to copy and create one in expansion pack folder as well. chore: bump bmad-2d-unity-game-dev version (patch)
* This PR introduces a powerful new Codebase Flattener Tool that aggregates entire codebases into AI-optimized XML format, making it easy to share project context with AI assistants for analysis, debugging, and development assistance.
- AI-Optimized XML Output : Generates clean, structured XML specifically designed for AI model consumption
- Smart File Discovery : Recursive file scanning with intelligent filtering using glob patterns
- Binary File Detection : Automatically identifies and excludes binary files, focusing on source code
- Progress Tracking : Real-time progress indicators with comprehensive completion statistics
- Flexible Output : Customizable output file location and naming via CLI arguments
- Gitignore Integration : Automatically respects .gitignore patterns to exclude unnecessary files
- CDATA Handling : Proper XML CDATA sections with escape sequence handling for ]]> patterns
- Content Indentation : Beautiful XML formatting with properly indented file content (4-space indentation)
- Error Handling : Robust error handling with detailed logging for problematic files
- Hierarchical Formatting : Clean XML structure with proper indentation and formatting
- File Content Preservation : Maintains original file formatting within indented CDATA sections
- Exclusion Logic : Prevents self-inclusion of output files ( flattened-codebase.xml , repomix-output.xml )
- tools/flattener/main.js - Complete flattener implementation with CLI interface
- package.json - Added new dependencies (glob, minimatch, fs-extra, commander, ora, chalk)
- package-lock.json - Updated dependency tree
- .gitignore - Added exclusions for flattener outputs
- README.md - Comprehensive documentation with usage examples
- docs/bmad-workflow-guide.md - Integration guidance
- tools/cli.js - CLI integration
- .vscode/settings.json - SonarLint configuration
```
current directory
npm run flatten
npm run flatten -- --output my-project.xml
npm run flatten -- -o /path/to/output/codebase.xml
```
The tool provides comprehensive completion summaries including:
- File count and breakdown (text/binary/errors)
- Source code size and generated XML size
- Total lines of code and estimated token count
- Processing progress and performance metrics
- Bug Fix : Corrected typo in exclusion patterns ( repromix-output.xml → repomix-output.xml )
- Performance : Efficient file processing with streaming and progress indicators
- Reliability : Comprehensive error handling and validation
- Maintainability : Clean, well-documented code with modular functions
- AI Integration : Perfect for sharing codebase context with AI assistants
- Code Reviews : Streamlined code review process with complete project context
- Documentation : Enhanced project documentation and analysis capabilities
- Development Workflow : Improved development assistance and debugging support
This tool significantly enhances the BMad-Method framework's AI integration capabilities, providing developers with a seamless way to share complete project context for enhanced AI-assisted development workflows.
* chore: remove unused files and configurations
- Delete deprecated bmad workflow guide and roomodes file
- Remove sonarlint project configuration
- Downgrade ora dependency version
- Remove jest test script
* docs: update command names and agent references in documentation
- Change `*create` to `*draft` in workflow guide
- Update PM agent commands to use consistent naming
- Replace `analyst` references with `architect`
- Fix command examples to match new naming conventions
---------
Co-authored-by: PinkyD <paulbeanjr@gmail.com>
* refactor: Standardize on 'GitHub Copilot' branding
- Update all references from 'Github Copilot' to 'GitHub Copilot' (official branding)
- Simplify GitHub Copilot guide reference in README
- Rebuild distribution files to reflect changes
- Ensure consistent branding across documentation and configuration
* fix: add Trae IDE support while maintaining GitHub Copilot branding
* fix: correct typos in documentation and agent files
Fix multiple instances of "assest" typo to "assets" in documentation
Correct "quetsions" typo to "questions" in repository structure sections
Add new words to cSpell dictionary in VS Code settings
* feat(trae): add support for trae ide integration
- Add trae guide documentation
- Update installer to support trae configuration
- Include trae in ide options and documentation references
- Fix typo in architect agent documentation
* chore: ignore windsurf and trae directories in git
* docs: add npm install step to README
The npm install step was missing from the setup instructions, which is required before running build commands.
---------
Co-authored-by: Devin Stagner <devin@blackstag.family>
* fix: correct typos in documentation and agent files
Fix multiple instances of "assest" typo to "assets" in documentation
Correct "quetsions" typo to "questions" in repository structure sections
Add new words to cSpell dictionary in VS Code settings
* feat(trae): add support for trae ide integration
- Add trae guide documentation
- Update installer to support trae configuration
- Include trae in ide options and documentation references
- Fix typo in architect agent documentation
---------
Co-authored-by: Devin Stagner <devin@blackstag.family>
Brian Madison
Murat K Ozcan
Carson
Daniel Dabrowski
Jonathan Borgwing
Bragatte
Chris Calo
manjaroblack
Yanqing Wang
yaksh gandhi
A. R.
David Elisma