bmad-method 4.30.4 → 4.32.0

package/{docs → bmad-core}/working-in-the-brownfield.md

@@ -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
-
-Follow the enhanced IDE Development Workflow:
-
-1. **Ensure documents are in project**:
+### Phase 4: Save and Shard Documents
 
-   - Copy `docs/prd.md` (or brownfield-prd.md)
-   - Copy `docs/architecture.md` (or brownfield-architecture.md)
+1. Save your PRD and Architecture as:
+   docs/brownfield-prd.md
+   docs/brownfield-architecture.md
+2. Shard your docs:
+   In your IDE
 
-2. **Shard documents**:
+   ```bash
+   @po
+   shard docs/brownfield-prd.md
+   ```
 
    ```bash
    @po
-   # Ask to shard docs/prd.md
+   shard docs/brownfield-architecture.md
    ```
 
-3. **Development cycle**:
-   - **SM** creates stories with integration awareness
-   - **Dev** implements with existing code respect
-   - **QA** reviews for compatibility and improvements
+### 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

package/dist/agents/analyst.txt

@@ -76,14 +76,14 @@ persona:
     - Numbered Options Protocol - Always use numbered lists for selections
 commands:
   - help: Show numbered list of the following commands to allow selection
-  - create-doc {template}: execute task create-doc (no template = ONLY show available templates listed under dependencies/templates below)
+  - create-project-brief: use task create-doc with project-brief-tmpl.yaml
+  - perform-market-research: use task create-doc with market-research-tmpl.yaml
+  - create-competitor-analysis: use task create-doc with competitor-analysis-tmpl.yaml
   - yolo: Toggle Yolo Mode
-  - doc-out: Output full document to current destination file
-  - execute-checklist {checklist}: Run task execute-checklist (default->architect-checklist)
-  - research-prompt {topic}: execute task create-deep-research-prompt for architectural decisions
-  - brainstorm {topic}: Facilitate structured brainstorming session
+  - doc-out: Output full document in progress to current destination file
+  - research-prompt {topic}: execute task create-deep-research-prompt.md
+  - brainstorm {topic}: Facilitate structured brainstorming session (run task facilitate-brainstorming-session.md with template brainstorming-output-tmpl.yaml)
   - elicit: run the task advanced-elicitation
-  - document-project: Analyze and document existing project structure comprehensively
   - exit: Say goodbye as the Business Analyst, and then abandon inhabiting this persona
 dependencies:
   tasks:

package/dist/agents/architect.txt

@@ -76,11 +76,16 @@ persona:
     - Living Architecture - Design for change and adaptation
 commands:
   - help: Show numbered list of the following commands to allow selection
-  - create-doc {template}: execute task create-doc (no template = ONLY show available templates listed under dependencies/templates below)
-  - yolo: Toggle Yolo Mode
+  - create-full-stack-architecture: use create-doc with fullstack-architecture-tmpl.yaml
+  - create-backend-architecture: use create-doc with architecture-tmpl.yaml
+  - create-front-end-architecture: use create-doc with front-end-architecture-tmpl.yaml
+  - create-brownfield-architecture: use create-doc with brownfield-architecture-tmpl.yaml
   - doc-out: Output full document to current destination file
+  - document-project: execute the task document-project.md
   - execute-checklist {checklist}: Run task execute-checklist (default->architect-checklist)
-  - research {topic}: execute task create-deep-research-prompt for architectural decisions
+  - research {topic}: execute task create-deep-research-prompt
+  - shard-prd: run the task shard-doc.md for the provided architecture.md (ask if not found)
+  - yolo: Toggle Yolo Mode
   - exit: Say goodbye as the Architect, and then abandon inhabiting this persona
 dependencies:
   tasks:

package/dist/agents/bmad-master.txt

@@ -70,10 +70,11 @@ commands:
   - kb: Toggle KB mode off (default) or on, when on will load and reference the .bmad-core/data/bmad-kb.md and converse with the user answering his questions with this informational resource
   - task {task}: Execute task, if not found or none specified, ONLY list available dependencies/tasks listed below
   - create-doc {template}: execute task create-doc (no template = ONLY show available templates listed under dependencies/templates below)
+  - doc-out: Output full document to current destination file
+  - document-project: execute the task document-project.md
   - execute-checklist {checklist}: Run task execute-checklist (no checklist = ONLY show available checklists listed under dependencies/checklist below)
   - shard-doc {document} {destination}: run the task shard-doc against the optionally provided document to the specified destination
   - yolo: Toggle Yolo Mode
-  - doc-out: Output full document to current destination file
   - exit: Exit (confirm)
 dependencies:
   tasks:

package/dist/agents/pm.txt

@@ -72,9 +72,16 @@ persona:
     - Strategic thinking & outcome-oriented
 commands:
   - help: Show numbered list of the following commands to allow selection
-  - create-doc {template}: execute task create-doc for template provided, if no template then ONLY list dependencies.templates
-  - yolo: Toggle Yolo Mode
+  - 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
+  - shard-prd: run the task shard-doc.md for the provided prd.md (ask if not found)
+  - correct-course: execute the correct-course task
+  - yolo: Toggle Yolo Mode
   - exit: Exit (confirm)
 dependencies:
   tasks:

package/dist/agents/po.txt

@@ -75,23 +75,20 @@ persona:
     - Documentation Ecosystem Integrity - Maintain consistency across all documents
 commands:
   - help: Show numbered list of the following commands to allow selection
-  - create-doc {template}: execute task create-doc (no template = ONLY show available templates listed under dependencies/templates below)
-  - execute-checklist {checklist}: Run task execute-checklist (default->po-master-checklist)
+  - execute-checklist-po: Run task execute-checklist (checklist po-master-checklist)
   - shard-doc {document} {destination}: run the task shard-doc against the optionally provided document to the specified destination
   - correct-course: execute the correct-course task
   - create-epic: Create epic for brownfield projects (task brownfield-create-epic)
   - create-story: Create user story from requirements (task brownfield-create-story)
-  - yolo: Toggle Yolo Mode off on - on will skip doc section confirmations
   - doc-out: Output full document to current destination file
   - validate-story-draft {story}: run the task validate-next-story against the provided story file
+  - yolo: Toggle Yolo Mode off on - on will skip doc section confirmations
   - exit: Exit (confirm)
 dependencies:
   tasks:
     - execute-checklist.md
     - shard-doc.md
     - correct-course.md
-    - brownfield-create-epic.md
-    - brownfield-create-story.md
     - validate-next-story.md
   templates:
     - story-tmpl.yaml
@@ -460,319 +457,6 @@ Document sharded successfully:
 - **Implicit:** An annotated change-checklist (or the record of its completion) reflecting the discussions, findings, and decisions made during the process.
 ==================== END: .bmad-core/tasks/correct-course.md ====================
 
-==================== START: .bmad-core/tasks/brownfield-create-epic.md ====================
-# Create Brownfield Epic Task
-
-## Purpose
-
-Create a single epic for smaller brownfield enhancements that don't require the full PRD and Architecture documentation process. This task is for isolated features or modifications that can be completed within a focused scope.
-
-## When to Use This Task
-
-**Use this task when:**
-
-- The enhancement can be completed in 1-3 stories
-- No significant architectural changes are required
-- The enhancement follows existing project patterns
-- Integration complexity is minimal
-- Risk to existing system is low
-
-**Use the full brownfield PRD/Architecture process when:**
-
-- The enhancement requires multiple coordinated stories
-- Architectural planning is needed
-- Significant integration work is required
-- Risk assessment and mitigation planning is necessary
-
-## Instructions
-
-### 1. Project Analysis (Required)
-
-Before creating the epic, gather essential information about the existing project:
-
-**Existing Project Context:**
-
-- [ ] Project purpose and current functionality understood
-- [ ] Existing technology stack identified
-- [ ] Current architecture patterns noted
-- [ ] Integration points with existing system identified
-
-**Enhancement Scope:**
-
-- [ ] Enhancement clearly defined and scoped
-- [ ] Impact on existing functionality assessed
-- [ ] Required integration points identified
-- [ ] Success criteria established
-
-### 2. Epic Creation
-
-Create a focused epic following this structure:
-
-#### Epic Title
-
-{{Enhancement Name}} - Brownfield Enhancement
-
-#### Epic Goal
-
-{{1-2 sentences describing what the epic will accomplish and why it adds value}}
-
-#### Epic Description
-
-**Existing System Context:**
-
-- Current relevant functionality: {{brief description}}
-- Technology stack: {{relevant existing technologies}}
-- Integration points: {{where new work connects to existing system}}
-
-**Enhancement Details:**
-
-- What's being added/changed: {{clear description}}
-- How it integrates: {{integration approach}}
-- Success criteria: {{measurable outcomes}}
-
-#### Stories
-
-List 1-3 focused stories that complete the epic:
-
-1. **Story 1:** {{Story title and brief description}}
-2. **Story 2:** {{Story title and brief description}}
-3. **Story 3:** {{Story title and brief description}}
-
-#### Compatibility Requirements
-
-- [ ] Existing APIs remain unchanged
-- [ ] Database schema changes are backward compatible
-- [ ] UI changes follow existing patterns
-- [ ] Performance impact is minimal
-
-#### Risk Mitigation
-
-- **Primary Risk:** {{main risk to existing system}}
-- **Mitigation:** {{how risk will be addressed}}
-- **Rollback Plan:** {{how to undo changes if needed}}
-
-#### Definition of Done
-
-- [ ] All stories completed with acceptance criteria met
-- [ ] Existing functionality verified through testing
-- [ ] Integration points working correctly
-- [ ] Documentation updated appropriately
-- [ ] No regression in existing features
-
-### 3. Validation Checklist
-
-Before finalizing the epic, ensure:
-
-**Scope Validation:**
-
-- [ ] Epic can be completed in 1-3 stories maximum
-- [ ] No architectural documentation is required
-- [ ] Enhancement follows existing patterns
-- [ ] Integration complexity is manageable
-
-**Risk Assessment:**
-
-- [ ] Risk to existing system is low
-- [ ] Rollback plan is feasible
-- [ ] Testing approach covers existing functionality
-- [ ] Team has sufficient knowledge of integration points
-
-**Completeness Check:**
-
-- [ ] Epic goal is clear and achievable
-- [ ] Stories are properly scoped
-- [ ] Success criteria are measurable
-- [ ] Dependencies are identified
-
-### 4. Handoff to Story Manager
-
-Once the epic is validated, provide this handoff to the Story Manager:
-
----
-
-**Story Manager Handoff:**
-
-"Please develop detailed user stories for this brownfield epic. Key considerations:
-
-- This is an enhancement to an existing system running {{technology stack}}
-- Integration points: {{list key integration points}}
-- Existing patterns to follow: {{relevant existing patterns}}
-- Critical compatibility requirements: {{key requirements}}
-- Each story must include verification that existing functionality remains intact
-
-The epic should maintain system integrity while delivering {{epic goal}}."
-
----
-
-## Success Criteria
-
-The epic creation is successful when:
-
-1. Enhancement scope is clearly defined and appropriately sized
-2. Integration approach respects existing system architecture
-3. Risk to existing functionality is minimized
-4. Stories are logically sequenced for safe implementation
-5. Compatibility requirements are clearly specified
-6. Rollback plan is feasible and documented
-
-## Important Notes
-
-- This task is specifically for SMALL brownfield enhancements
-- If the scope grows beyond 3 stories, consider the full brownfield PRD process
-- Always prioritize existing system integrity over new functionality
-- When in doubt about scope or complexity, escalate to full brownfield planning
-==================== END: .bmad-core/tasks/brownfield-create-epic.md ====================
-
-==================== START: .bmad-core/tasks/brownfield-create-story.md ====================
-# Create Brownfield Story Task
-
-## Purpose
-
-Create a single user story for very small brownfield enhancements that can be completed in one focused development session. This task is for minimal additions or bug fixes that require existing system integration awareness.
-
-## When to Use This Task
-
-**Use this task when:**
-
-- The enhancement can be completed in a single story
-- No new architecture or significant design is required
-- The change follows existing patterns exactly
-- Integration is straightforward with minimal risk
-- Change is isolated with clear boundaries
-
-**Use brownfield-create-epic when:**
-
-- The enhancement requires 2-3 coordinated stories
-- Some design work is needed
-- Multiple integration points are involved
-
-**Use the full brownfield PRD/Architecture process when:**
-
-- The enhancement requires multiple coordinated stories
-- Architectural planning is needed
-- Significant integration work is required
-
-## Instructions
-
-### 1. Quick Project Assessment
-
-Gather minimal but essential context about the existing project:
-
-**Current System Context:**
-
-- [ ] Relevant existing functionality identified
-- [ ] Technology stack for this area noted
-- [ ] Integration point(s) clearly understood
-- [ ] Existing patterns for similar work identified
-
-**Change Scope:**
-
-- [ ] Specific change clearly defined
-- [ ] Impact boundaries identified
-- [ ] Success criteria established
-
-### 2. Story Creation
-
-Create a single focused story following this structure:
-
-#### Story Title
-
-{{Specific Enhancement}} - Brownfield Addition
-
-#### User Story
-
-As a {{user type}},
-I want {{specific action/capability}},
-So that {{clear benefit/value}}.
-
-#### Story Context
-
-**Existing System Integration:**
-
-- Integrates with: {{existing component/system}}
-- Technology: {{relevant tech stack}}
-- Follows pattern: {{existing pattern to follow}}
-- Touch points: {{specific integration points}}
-
-#### Acceptance Criteria
-
-**Functional Requirements:**
-
-1. {{Primary functional requirement}}
-2. {{Secondary functional requirement (if any)}}
-3. {{Integration requirement}}
-
-**Integration Requirements:** 4. Existing {{relevant functionality}} continues to work unchanged 5. New functionality follows existing {{pattern}} pattern 6. Integration with {{system/component}} maintains current behavior
-
-**Quality Requirements:** 7. Change is covered by appropriate tests 8. Documentation is updated if needed 9. No regression in existing functionality verified
-
-#### Technical Notes
-
-- **Integration Approach:** {{how it connects to existing system}}
-- **Existing Pattern Reference:** {{link or description of pattern to follow}}
-- **Key Constraints:** {{any important limitations or requirements}}
-
-#### Definition of Done
-
-- [ ] Functional requirements met
-- [ ] Integration requirements verified
-- [ ] Existing functionality regression tested
-- [ ] Code follows existing patterns and standards
-- [ ] Tests pass (existing and new)
-- [ ] Documentation updated if applicable
-
-### 3. Risk and Compatibility Check
-
-**Minimal Risk Assessment:**
-
-- **Primary Risk:** {{main risk to existing system}}
-- **Mitigation:** {{simple mitigation approach}}
-- **Rollback:** {{how to undo if needed}}
-
-**Compatibility Verification:**
-
-- [ ] No breaking changes to existing APIs
-- [ ] Database changes (if any) are additive only
-- [ ] UI changes follow existing design patterns
-- [ ] Performance impact is negligible
-
-### 4. Validation Checklist
-
-Before finalizing the story, confirm:
-
-**Scope Validation:**
-
-- [ ] Story can be completed in one development session
-- [ ] Integration approach is straightforward
-- [ ] Follows existing patterns exactly
-- [ ] No design or architecture work required
-
-**Clarity Check:**
-
-- [ ] Story requirements are unambiguous
-- [ ] Integration points are clearly specified
-- [ ] Success criteria are testable
-- [ ] Rollback approach is simple
-
-## Success Criteria
-
-The story creation is successful when:
-
-1. Enhancement is clearly defined and appropriately scoped for single session
-2. Integration approach is straightforward and low-risk
-3. Existing system patterns are identified and will be followed
-4. Rollback plan is simple and feasible
-5. Acceptance criteria include existing functionality verification
-
-## Important Notes
-
-- This task is for VERY SMALL brownfield changes only
-- If complexity grows during analysis, escalate to brownfield-create-epic
-- Always prioritize existing system integrity
-- When in doubt about integration complexity, use brownfield-create-epic instead
-- Stories should take no more than 4 hours of focused development work
-==================== END: .bmad-core/tasks/brownfield-create-story.md ====================
-
 ==================== START: .bmad-core/tasks/validate-next-story.md ====================
 # Validate Next Story Task
 

package/dist/agents/qa.txt

@@ -80,7 +80,6 @@ story-file-permissions:
 commands:
   - help: Show numbered list of the following commands to allow selection
   - review {story}: execute the task review-story for the highest sequence story in docs/stories unless another is specified - keep any specified technical-preferences in mind as needed
-  - create-doc {template}: execute task create-doc (no template = ONLY show available templates listed under dependencies/templates below)
   - exit: Say goodbye as the QA Engineer, and then abandon inhabiting this persona
 dependencies:
   tasks:

package/dist/agents/sm.txt

@@ -68,9 +68,9 @@ persona:
     - You are NOT allowed to implement stories or modify code EVER!
 commands:
   - help: Show numbered list of the following commands to allow selection
-  - draft: Execute task create-next-story
-  - correct-course: Execute task correct-course
-  - checklist {checklist}: Show numbered list of checklists if not provided, execute task execute-checklist
+  - draft: Execute task create-next-story.md
+  - correct-course: Execute task correct-course.md
+  - story-checklist: Execute task execute-checklist.md with checklist story-draft-checklist.md
   - exit: Say goodbye as the Scrum Master, and then abandon inhabiting this persona
 dependencies:
   tasks: