External/BMAD-METHOD
1
0
Fork 0
mirror of https://github.com/bmadcode/BMAD-METHOD.git synced 2025-12-29 16:14:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

Feat/flattener-tool (#337)

Browse Source 
* 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>
This commit is contained in:
manjaroblack
2025-07-26 14:56:00 -05:00
committed by GitHub
parent a7038d43d1
commit 5efbff3227
9 changed files with 780 additions and 120 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
bmad-core/agents/pm.md
View File

@@ -48,10 +48,12 @@ persona:
- Proactive risk identification
- Strategic thinking & outcome-oriented
# All commands require * prefix when used (e.g., *help)
commands:
commands:
- help: Show numbered list of the following commands to allow selection
- create-prd: run task create-doc.md with template prd-tmpl.yaml
- create-brownfield-prd: run task create-doc.md with template brownfield-prd-tmpl.yaml
- create-brownfield-epic: run task brownfield-create-epic.md
- create-brownfield-story: run task brownfield-create-story.md
- create-epic: Create epic for brownfield projects (task brownfield-create-epic)
- create-story: Create user story from requirements (task brownfield-create-story)
- doc-out: Output full document to current destination file

0
bmad-core/bmad-core/user-guide.md Normal file
View File

43
bmad-core/enhanced-ide-development-workflow.md Normal file
View File

@@ -0,0 +1,43 @@
# Enhanced Development Workflow
This is a simple step-by-step guide to help you efficiently manage your development workflow using the BMad Method. Refer to the **[<ins>User Guide</ins>](user-guide.md)** for any scenario that is not covered here.
## Create new Branch
1. **Start new branch**
## Story Creation (Scrum Master)
1. **Start new chat/conversation**
2. **Load SM agent**
3. **Execute**: `*draft` (runs create-next-story task)
4. **Review generated story** in `docs/stories/`
5. **Update status**: Change from "Draft" to "Approved"
## Story Implementation (Developer)
1. **Start new chat/conversation**
2. **Load Dev agent**
3. **Execute**: `*develop-story {selected-story}` (runs execute-checklist task)
4. **Review generated report** in `{selected-story}`
## Story Review (Quality Assurance)
1. **Start new chat/conversation**
2. **Load QA agent**
3. **Execute**: `*review {selected-story}` (runs review-story task)
4. **Review generated report** in `{selected-story}`
## Commit Changes and Push
1. **Commit changes**
2. **Push to remote**
## Repeat Until Complete
- **SM**: Create next story → Review → Approve
- **Dev**: Implement story → Complete → Mark Ready for Review
- **QA**: Review story → Mark done
- **Commit**: All changes
- **Push**: To remote
- **Continue**: Until all features implemented

13
bmad-core/user-guide.md
View File

@@ -1,12 +1,12 @@
# BMad-Method BMAd Code User Guide
This guide will help you understand and effectively use the BMad Method for agile ai driven planning and development.
This guide will help you understand and effectively use the BMad Method for agile AI driven planning and development.
## The BMad Plan and Execute Workflow
First, here is the full standard Greenfield Planning + Execution Workflow. Brownfield is very similar, but its suggested to understand this greenfield first, even if on a simple project before tackling a brownfield project. The BMad Method needs to be installed to the root of your new project folder. For the planning phase, you can optionally perform it with powerful web agents, potentially resulting in higher quality results at a fraction of the cost it would take to complete if providing your own API key or credits in some Agentic tools. For planning, powerful thinking models and larger context - along with working as a partner with the agents will net the best results.
First, here is the full standard Greenfield Planning + Execution Workflow. Brownfield is very similar, but it's suggested to understand this greenfield first, even if on a simple project before tackling a brownfield project. The BMad Method needs to be installed to the root of your new project folder. For the planning phase, you can optionally perform it with powerful web agents, potentially resulting in higher quality results at a fraction of the cost it would take to complete if providing your own API key or credits in some Agentic tools. For planning, powerful thinking models and larger context - along with working as a partner with the agents will net the best results.
If you are going to use the BMad Method with a Brownfield project (an existing project), review [Working in the Brownfield](./working-in-the-brownfield.md)
If you are going to use the BMad Method with a Brownfield project (an existing project), review **[Working in the Brownfield](./working-in-the-brownfield.md)**.
If you do not see the diagrams that following rendering, you can install Markdown All in One along with the Markdown Preview Mermaid Support plugins to VSCode (or one of the forked clones). With these plugin's, if you right click on the tab when open, there should be a Open Preview option, or check the IDE documentation.
@@ -132,7 +132,7 @@ graph TD
If you want to do the planning in the Web with Claude (Sonnet 4 or Opus), Gemini Gem (2.5 Pro), or Custom GPT's:
1. Navigate to `dist/teams/`
2. Copy `team-fullstack.txt` content
2. Copy `team-fullstack.txt`
3. Create new Gemini Gem or CustomGPT
4. Upload file with instructions: "Your critical operating instructions are attached, do not break character as directed"
5. Type `/help` to see available commands
@@ -152,7 +152,7 @@ There are two bmad agents - in the future they will be consolidated into the sin
This agent can do any task or command that all other agents can do, aside from actual story implementation. Additionally, this agent can help explain the BMad Method when in the web by accessing the knowledge base and explaining anything to you about the process.
If you dont want to bother switching between different agents aside from the dev, this is the agent for you.
If you don't want to bother switching between different agents aside from the dev, this is the agent for you. Just remember that as the context grows, the performance of the agent degrades, therefore it is important to instruct the agent to compact the conversation and start a new conversation with the compacted conversation as the initial message. Do this often, preferably after each story is implemented.
### BMad-Orchestrator
@@ -210,6 +210,7 @@ dependencies:
- **Agent Selection**: Use appropriate agent for task
- **Iterative Development**: Work in small, focused tasks
- **File Organization**: Maintain clean project structure
- **Commit Regularly**: Save your work frequently
## Technical Preferences System
@@ -236,7 +237,7 @@ devLoadAlwaysFiles:
You will want to verify from sharding your architecture that these documents exist, that they are as lean as possible, and contain exactly the information you want your dev agent to ALWAYS load into it's context. These are the rules the agent will follow.
As your project grows and the code starts to build consistent patterns, coding standards should be reduced to just the items that the agent makes mistakes at still - must with the better models, they will look at surrounding code in files and not need a rule from that file to guide them.
As your project grows and the code starts to build consistent patterns, coding standards should be reduced to include only the standards that the agent still makes with. The agent will look at surrounding code in files to infer the coding standards that are relevant to the current task.
## Getting Help

77
bmad-core/working-in-the-brownfield.md
View File

@@ -2,10 +2,10 @@
> **HIGHLY RECOMMENDED: Use Gemini Web or Gemini CLI for Brownfield Documentation Generation!**
>
> Gemini Web's 1M+ token context window or Gemini CLI (when its working) can analyze your ENTIRE codebase or critical sections of it all at once (obviously within reason):
> Gemini Web's 1M+ token context window or Gemini CLI (when it's working) can analyze your ENTIRE codebase, or critical sections of it, all at once (obviously within reason):
>
> - Upload via GitHub URL or use gemini cli in the project folder
> - If in the web: Upload up to 1000 files or the zipped project or just give it the github url
> - If working in the web: use the flattener-tool to flatten your project into a single file, then upload that file to your web agent.
## What is Brownfield Development?
@@ -22,10 +22,13 @@ Brownfield development refers to adding features, fixing bugs, or modernizing ex
## When NOT to use a Brownfield Flow
If you have just completed an MVP with BMad, and you want to continue with post-MVP, its easier to just talk to the PM and ask him to work with you to create a new epic to add into the PRD, shard out the epic, update any architecture documents with the architect, and just go from there.
If you have just completed an MVP with BMad, and you want to continue with post-MVP, its easier to just talk to the PM and ask it to work with you to create a new epic to add into the PRD, shard out the epic, update any architecture documents with the architect, and just go from there.
## The Complete Brownfield Workflow
1. **Follow the [<ins>User Guide - Installation</ins>](user-guide.md#installation) steps to setup your agent in the web.**
2. **Generate a 'flattened' single file of your entire codebase** run: ```npm run flatten```
### Choose Your Approach
#### Approach A: PRD-First (Recommended if adding very large and complex new features, single or multiple epics or massive changes)
@@ -48,11 +51,11 @@ If you have just completed an MVP with BMad, and you want to continue with post-
#### Phase 1: Define Requirements First
**In Gemini Web (with your codebase uploaded):**
**In Gemini Web (with your flattened-codebase.xml uploaded):**
```bash
@pm
*create-doc brownfield-prd
*create-brownfield-prd
```
The PM will:
@@ -69,7 +72,7 @@ The PM will:
**Still in Gemini Web, now with PRD context:**
```bash
@analyst
@architect
*document-project
```
@@ -104,22 +107,21 @@ For example, if you say "Add payment processing to user service":
1. **Go to Gemini Web** (gemini.google.com)
2. **Upload your project**:
- **Option A**: Paste your GitHub repository URL directly
- **Option B**: Upload up to 1000 files from your src/project folder
- **Option C**: Zip your project and upload the archive
3. **Load the analyst agent**: Upload `dist/agents/analyst.txt`
- **Option B**: Upload your flattened-codebase.xml file
3. **Load the analyst agent**: Upload `dist/agents/architect.txt`
4. **Run documentation**: Type `*document-project`
The analyst will generate comprehensive documentation of everything.
#### Phase 2: Plan Your Enhancement
#### Option A: Full Brownfield Workflow (Recommended for Major Changes)
##### Option A: Full Brownfield Workflow (Recommended for Major Changes)
**1. Create Brownfield PRD**:
```bash
@pm
*create-doc brownfield-prd
*create-brownfield-prd
```
The PM agent will:
@@ -146,7 +148,7 @@ The PM agent will:
```bash
@architect
*create-doc brownfield-architecture
*create-brownfield-architecture
```
The architect will:
@@ -157,13 +159,13 @@ The architect will:
- **Identify technical risks**
- **Define compatibility requirements**
#### Option B: Quick Enhancement (For Focused Changes)
##### Option B: Quick Enhancement (For Focused Changes)
**For Single Epic Without Full PRD**:
```bash
@pm
*brownfield-create-epic
*create-brownfield-epic
```
Use when:
@@ -177,7 +179,7 @@ Use when:
```bash
@pm
*brownfield-create-story
*create-brownfield-story
```
Use when:
@@ -191,7 +193,7 @@ Use when:
```bash
@po
*execute-checklist po-master-checklist
*execute-checklist-po
```
The PO ensures:
@@ -201,26 +203,27 @@ The PO ensures:
- Risk mitigation strategies in place
- Clear integration approach
### Phase 4: Transition to Development
### Phase 4: Save and Shard Documents
Follow the enhanced IDE Development Workflow:
1. **Ensure documents are in project**:
- Copy `docs/prd.md` (or brownfield-prd.md)
- Copy `docs/architecture.md` (or brownfield-architecture.md)
2. **Shard documents**:
1. Save your PRD and Architecture as:
docs/brownfield-prd.md
docs/brownfield-architecture.md
2. Shard your docs:
In your IDE
```bash
@po
# Ask to shard docs/prd.md
shard docs/brownfield-prd.md
```
3. **Development cycle**:
- **SM** creates stories with integration awareness
- **Dev** implements with existing code respect
- **QA** reviews for compatibility and improvements
```bash
@po
shard docs/brownfield-architecture.md
```
### Phase 5: Transition to Development
**Follow the [<ins>Enhanced IDE Development Workflow</ins>](enhanced-ide-development-workflow.md)**
## Brownfield Best Practices
@@ -287,7 +290,7 @@ Document:
### Scenario 3: Bug Fix in Complex System
1. Document relevant subsystems
2. Use `brownfield-create-story` for focused fix
2. Use `create-brownfield-story` for focused fix
3. Include regression test requirements
4. QA validates no side effects
@@ -310,7 +313,7 @@ Document:
### "Too much boilerplate for small changes"
**Solution**: Use `brownfield-create-story` instead of full workflow
**Solution**: Use `create-brownfield-story` instead of full workflow
### "Integration points unclear"
@@ -322,19 +325,19 @@ Document:
```bash
# Document existing project
@analyst → *document-project
@architect → *document-project
# Create enhancement PRD
@pm → *create-doc brownfield-prd
@pm → *create-brownfield-prd
# Create architecture with integration focus
@architect → *create-doc brownfield-architecture
@architect → *create-brownfield-architecture
# Quick epic creation
@pm → *brownfield-create-epic
@pm → *create-brownfield-epic
# Single story creation
@pm → *brownfield-create-story
@pm → *create-brownfield-story
```
### Decision Tree