ros/BMAD-METHOD
1
0
Fork 0
Code Issues Pull Requests Actions 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

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