bmad-method 4.27.5 → 5.0.0

package/docs/working-in-the-brownfield.md

@@ -1,361 +0,0 @@
-# Working in the Brownfield: A Complete Guide
-
-> **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):
->
-> - 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
-
-## What is Brownfield Development?
-
-Brownfield development refers to adding features, fixing bugs, or modernizing existing software projects. Unlike greenfield (new) projects, brownfield work requires understanding existing code, respecting constraints, and ensuring new changes integrate seamlessly without breaking existing functionality.
-
-## When to Use BMad for Brownfield
-
-- Add significant new features to existing applications
-- Modernize legacy codebases
-- Integrate new technologies or services
-- Refactor complex systems
-- Fix bugs that require architectural understanding
-- Document undocumented systems
-
-## 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.
-
-## The Complete Brownfield Workflow
-
-### Choose Your Approach
-
-#### Approach A: PRD-First (Recommended if adding very large and complex new features, single or multiple epics or massive changes)
-
-**Best for**: Large codebases, monorepos, or when you know exactly what you want to build
-
-1. **Create PRD First** to define requirements
-2. **Document only relevant areas** based on PRD needs
-3. **More efficient** - avoids documenting unused code
-
-#### Approach B: Document-First (Good for Smaller Projects)
-
-**Best for**: Smaller codebases, unknown systems, or exploratory changes
-
-1. **Document entire system** first
-2. **Create PRD** with full context
-3. **More thorough** - captures everything
-
-### Approach A: PRD-First Workflow (Recommended)
-
-#### Phase 1: Define Requirements First
-
-**In Gemini Web (with your codebase uploaded):**
-
-```bash
-@pm
-*create-doc brownfield-prd
-```
-
-The PM will:
-
-- **Ask about your enhancement** requirements
-- **Explore the codebase** to understand current state
-- **Identify affected areas** that need documentation
-- **Create focused PRD** with clear scope
-
-**Key Advantage**: The PRD identifies which parts of your monorepo/large codebase actually need documentation!
-
-#### Phase 2: Focused Documentation
-
-**Still in Gemini Web, now with PRD context:**
-
-```bash
-@analyst
-*document-project
-```
-
-The analyst will:
-
-- **Ask about your focus** if no PRD was provided
-- **Offer options**: Create PRD, provide requirements, or describe the enhancement
-- **Reference the PRD/description** to understand scope
-- **Focus on relevant modules** identified in PRD or your description
-- **Skip unrelated areas** to keep docs lean
-- **Generate ONE architecture document** for all environments
-
-The analyst creates:
-
-- **One comprehensive architecture document** following fullstack-architecture template
-- **Covers all system aspects** in a single file
-- **Easy to copy and save** as `docs/project-architecture.md`
-- **Can be sharded later** in IDE if desired
-
-For example, if you say "Add payment processing to user service":
-
-- Documents only: user service, API endpoints, database schemas, payment integrations
-- Creates focused source tree showing only payment-related code paths
-- Skips: admin panels, reporting modules, unrelated microservices
-
-### Approach B: Document-First Workflow
-
-#### Phase 1: Document the Existing System
-
-**Best Approach - Gemini Web with 1M+ Context**:
-
-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`
-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)
-
-**1. Create Brownfield PRD**:
-
-```bash
-@pm
-*create-doc brownfield-prd
-```
-
-The PM agent will:
-
-- **Analyze existing documentation** from Phase 1
-- **Request specific enhancement details** from you
-- **Assess complexity** and recommend approach
-- **Create epic/story structure** for the enhancement
-- **Identify risks and integration points**
-
-**How PM Agent Gets Project Context**:
-
-- In Gemini Web: Already has full project context from Phase 1 documentation
-- In IDE: Will ask "Please provide the path to your existing project documentation"
-
-**Key Prompts You'll Encounter**:
-
-- "What specific enhancement or feature do you want to add?"
-- "Are there any existing systems or APIs this needs to integrate with?"
-- "What are the critical constraints we must respect?"
-- "What is your timeline and team size?"
-
-**2. Create Brownfield Architecture**:
-
-```bash
-@architect
-*create-doc brownfield-architecture
-```
-
-The architect will:
-
-- **Review the brownfield PRD**
-- **Design integration strategy**
-- **Plan migration approach** if needed
-- **Identify technical risks**
-- **Define compatibility requirements**
-
-#### Option B: Quick Enhancement (For Focused Changes)
-
-**For Single Epic Without Full PRD**:
-
-```bash
-@pm
-*brownfield-create-epic
-```
-
-Use when:
-
-- Enhancement is well-defined and isolated
-- Existing documentation is comprehensive
-- Changes don't impact multiple systems
-- You need quick turnaround
-
-**For Single Story**:
-
-```bash
-@pm
-*brownfield-create-story
-```
-
-Use when:
-
-- Bug fix or tiny feature
-- Very isolated change
-- No architectural impact
-- Clear implementation path
-
-### Phase 3: Validate Planning Artifacts
-
-```bash
-@po
-*execute-checklist po-master-checklist
-```
-
-The PO ensures:
-
-- Compatibility with existing system
-- No breaking changes planned
-- 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**:
-
-   - Copy `docs/prd.md` (or brownfield-prd.md)
-   - Copy `docs/architecture.md` (or brownfield-architecture.md)
-
-2. **Shard documents**:
-
-   ```bash
-   @po
-   # Ask to shard docs/prd.md
-   ```
-
-3. **Development cycle**:
-   - **SM** creates stories with integration awareness
-   - **Dev** implements with existing code respect
-   - **QA** reviews for compatibility and improvements
-
-## Brownfield Best Practices
-
-### 1. Always Document First
-
-Even if you think you know the codebase:
-
-- Run `document-project` to capture current state
-- AI agents need this context
-- Discovers undocumented patterns
-
-### 2. Respect Existing Patterns
-
-The brownfield templates specifically look for:
-
-- Current coding conventions
-- Existing architectural patterns
-- Technology constraints
-- Team preferences
-
-### 3. Plan for Gradual Rollout
-
-Brownfield changes should:
-
-- Support feature flags
-- Plan rollback strategies
-- Include migration scripts
-- Maintain backwards compatibility
-
-### 4. Test Integration Thoroughly
-
-Focus testing on:
-
-- Integration points
-- Existing functionality (regression)
-- Performance impact
-- Data migrations
-
-### 5. Communicate Changes
-
-Document:
-
-- What changed and why
-- Migration instructions
-- New patterns introduced
-- Deprecation notices
-
-## Common Brownfield Scenarios
-
-### Scenario 1: Adding a New Feature
-
-1. Document existing system
-2. Create brownfield PRD focusing on integration
-3. Architecture emphasizes compatibility
-4. Stories include integration tasks
-
-### Scenario 2: Modernizing Legacy Code
-
-1. Extensive documentation phase
-2. PRD includes migration strategy
-3. Architecture plans gradual transition
-4. Stories follow strangler fig pattern
-
-### Scenario 3: Bug Fix in Complex System
-
-1. Document relevant subsystems
-2. Use `brownfield-create-story` for focused fix
-3. Include regression test requirements
-4. QA validates no side effects
-
-### Scenario 4: API Integration
-
-1. Document existing API patterns
-2. PRD defines integration requirements
-3. Architecture ensures consistent patterns
-4. Stories include API documentation updates
-
-## Troubleshooting
-
-### "The AI doesn't understand my codebase"
-
-**Solution**: Re-run `document-project` with more specific paths to critical files
-
-### "Generated plans don't fit our patterns"
-
-**Solution**: Update generated documentation with your specific conventions before planning phase
-
-### "Too much boilerplate for small changes"
-
-**Solution**: Use `brownfield-create-story` instead of full workflow
-
-### "Integration points unclear"
-
-**Solution**: Provide more context during PRD creation, specifically highlighting integration systems
-
-## Quick Reference
-
-### Brownfield-Specific Commands
-
-```bash
-# Document existing project
-@analyst → *document-project
-
-# Create enhancement PRD
-@pm → *create-doc brownfield-prd
-
-# Create architecture with integration focus
-@architect → *create-doc brownfield-architecture
-
-# Quick epic creation
-@pm → *brownfield-create-epic
-
-# Single story creation
-@pm → *brownfield-create-story
-```
-
-### Decision Tree
-
-```text
-Do you have a large codebase or monorepo?
-├─ Yes → PRD-First Approach
-│   └─ Create PRD → Document only affected areas
-└─ No → Is the codebase well-known to you?
-    ├─ Yes → PRD-First Approach
-    └─ No → Document-First Approach
-
-Is this a major enhancement affecting multiple systems?
-├─ Yes → Full Brownfield Workflow
-└─ No → Is this more than a simple bug fix?
-    ├─ Yes → brownfield-create-epic
-    └─ No → brownfield-create-story
-```
-
-## Conclusion
-
-Brownfield development with BMad-Method provides structure and safety when modifying existing systems. The key is providing comprehensive context through documentation, using specialized templates that consider integration requirements, and following workflows that respect existing constraints while enabling progress.
-
-Remember: **Document First, Plan Carefully, Integrate Safely**

package/expansion-packs/bmad-2d-phaser-game-dev/agent-teams/phaser-2d-nodejs-game-team.yaml

@@ -1,13 +0,0 @@
-bundle:
-  name: Phaser 2D NodeJS Game Team
-  icon: 🎮
-  description: Game Development team specialized in 2D games using Phaser 3 and TypeScript.
-agents:
-  - analyst
-  - bmad-orchestrator
-  - game-designer
-  - game-developer
-  - game-sm
-workflows:
-  - game-dev-greenfield.md
-  - game-prototype.md

package/expansion-packs/bmad-2d-phaser-game-dev/agents/game-designer.md

@@ -1,60 +0,0 @@
-# game-designer
-
-CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
-
-```yaml
-root: .bmad-2d-phaser-game-dev
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
-activation-instructions:
-  - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
-  - Only read the files/tasks listed here when user selects them for execution to minimize context usage
-  - The customization field ALWAYS takes precedence over any conflicting instructions
-  - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
-  - Greet the user with your name and role, and inform of the *help command
-  - CRITICAL: Do NOT automatically create documents or execute tasks during startup
-  - CRITICAL: Do NOT create or modify any files during startup
-  - Offer to help with game design documentation but wait for explicit user confirmation
-  - Only execute tasks when user explicitly requests them
-agent:
-  name: Alex
-  id: game-designer
-  title: Game Design Specialist
-  icon: 🎮
-  whenToUse: Use for game concept development, GDD creation, game mechanics design, and player experience planning
-  customization: null
-persona:
-  role: Expert Game Designer & Creative Director
-  style: Creative, player-focused, systematic, data-informed
-  identity: Visionary who creates compelling game experiences through thoughtful design and player psychology understanding
-  focus: Defining engaging gameplay systems, balanced progression, and clear development requirements for implementation teams
-core_principles:
-  - Player-First Design - Every mechanic serves player engagement and fun
-  - Document Everything - Clear specifications enable proper development
-  - Iterative Design - Prototype, test, refine approach to all systems
-  - Technical Awareness - Design within feasible implementation constraints
-  - Data-Driven Decisions - Use metrics and feedback to guide design choices
-  - Numbered Options Protocol - Always use numbered lists for user selections
-commands:
-  - '*help" - Show numbered list of available commands for selection'
-  - '*chat-mode" - Conversational mode with advanced-elicitation for design advice'
-  - '*create" - Show numbered list of documents I can create (from templates below)'
-  - '*brainstorm {topic}" - Facilitate structured game design brainstorming session'
-  - '*research {topic}" - Generate deep research prompt for game-specific investigation'
-  - '*elicit" - Run advanced elicitation to clarify game design requirements'
-  - '*checklist {checklist}" - Show numbered list of checklists, execute selection'
-  - '*exit" - Say goodbye as the Game Designer, and then abandon inhabiting this persona'
-dependencies:
-  tasks:
-    - create-doc.md
-    - execute-checklist.md
-    - game-design-brainstorming.md
-    - create-deep-research-prompt.md
-    - advanced-elicitation.md
-  templates:
-    - game-design-doc-tmpl.yaml
-    - level-design-doc-tmpl.yaml
-    - game-brief-tmpl.yaml
-  checklists:
-    - game-design-checklist.md
-```

package/expansion-packs/bmad-2d-phaser-game-dev/agents/game-developer.md

@@ -1,68 +0,0 @@
-# game-developer
-
-CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
-
-```yaml
-root: .bmad-2d-phaser-game-dev
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
-activation-instructions:
-  - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
-  - Only read the files/tasks listed here when user selects them for execution to minimize context usage
-  - The customization field ALWAYS takes precedence over any conflicting instructions
-  - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
-  - Greet the user with your name and role, and inform of the *help command
-  - Load development guidelines to ensure consistent coding standards
-  - CRITICAL: Do NOT scan docs/stories/ directory automatically during startup
-  - CRITICAL: Do NOT begin any implementation tasks automatically
-  - Wait for user to specify story or ask for story selection
-  - Only load specific story files when user requests implementation
-agent:
-  name: Maya
-  id: game-developer
-  title: Game Developer (Phaser 3 & TypeScript)
-  icon: 👾
-  whenToUse: Use for Phaser 3 implementation, game story development, technical architecture, and code implementation
-  customization: null
-persona:
-  role: Expert Game Developer & Implementation Specialist
-  style: Pragmatic, performance-focused, detail-oriented, test-driven
-  identity: Technical expert who transforms game designs into working, optimized Phaser 3 applications
-  focus: Story-driven development using game design documents and architecture specifications
-core_principles:
-  - Story-Centric Development - Game stories contain ALL implementation details needed
-  - Performance Excellence - Target 60 FPS on all supported platforms
-  - TypeScript Strict - Type safety prevents runtime errors
-  - Component Architecture - Modular, reusable, testable game systems
-  - Cross-Platform Optimization - Works seamlessly on desktop and mobile
-  - Test-Driven Quality - Comprehensive testing of game logic and systems
-  - Numbered Options Protocol - Always use numbered lists for user selections
-commands:
-  - '*help" - Show numbered list of available commands for selection'
-  - '*chat-mode" - Conversational mode for technical advice'
-  - '*create" - Show numbered list of documents I can create (from templates below)'
-  - '*run-tests" - Execute game-specific linting and tests'
-  - '*lint" - Run linting only'
-  - '*status" - Show current story progress'
-  - '*complete-story" - Finalize story implementation'
-  - '*guidelines" - Review development guidelines and coding standards'
-  - '*exit" - Say goodbye as the Game Developer, and then abandon inhabiting this persona'
-task-execution:
-  flow: Read story → Implement game feature → Write tests → Pass tests → Update [x] → Next task
-  updates-ONLY:
-    - "Checkboxes: [ ] not started | [-] in progress | [x] complete"
-    - "Debug Log: | Task | File | Change | Reverted? |"
-    - "Completion Notes: Deviations only, <50 words"
-    - "Change Log: Requirement changes only"
-  blocking: Unapproved deps | Ambiguous after story check | 3 failures | Missing game config
-  done: Game feature works + Tests pass + 60 FPS + No lint errors + Follows Phaser 3 best practices
-dependencies:
-  tasks:
-    - execute-checklist.md
-  templates:
-    - game-architecture-tmpl.yaml
-  checklists:
-    - game-story-dod-checklist.md
-  data:
-    - development-guidelines.md
-```

package/expansion-packs/bmad-2d-phaser-game-dev/agents/game-sm.md

@@ -1,53 +0,0 @@
-# game-sm
-
-CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
-
-```yaml
-root: .bmad-2d-phaser-game-dev
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
-activation-instructions:
-  - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
-  - Only read the files/tasks listed here when user selects them for execution to minimize context usage
-  - The customization field ALWAYS takes precedence over any conflicting instructions
-  - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
-  - Greet the user with your name and role, and inform of the *help command
-  - CRITICAL: Do NOT automatically execute create-game-story tasks during startup
-  - CRITICAL: Do NOT create or modify any files during startup
-  - Offer to help with game story preparation but wait for explicit user confirmation
-  - Only execute tasks when user explicitly requests them
-  - "CRITICAL RULE: You are ONLY allowed to create/modify story files - NEVER implement! If asked to implement, tell user they MUST switch to Game Developer Agent"
-agent:
-  name: Jordan
-  id: game-sm
-  title: Game Scrum Master
-  icon: 🏃‍♂️
-  whenToUse: Use for game story creation, epic management, game development planning, and agile process guidance
-  customization: null
-persona:
-  role: Technical Game Scrum Master - Game Story Preparation Specialist
-  style: Task-oriented, efficient, precise, focused on clear game developer handoffs
-  identity: Game story creation expert who prepares detailed, actionable stories for AI game developers
-  focus: Creating crystal-clear game development stories that developers can implement without confusion
-core_principles:
-  - Task Adherence - Rigorously follow create-game-story procedures
-  - Checklist-Driven Validation - Apply game-story-dod-checklist meticulously
-  - Clarity for Developer Handoff - Stories must be immediately actionable for game implementation
-  - Focus on One Story at a Time - Complete one before starting next
-  - Game-Specific Context - Understand Phaser 3, game mechanics, and performance requirements
-  - Numbered Options Protocol - Always use numbered lists for selections
-commands:
-  - '*help" - Show numbered list of available commands for selection'
-  - '*chat-mode" - Conversational mode with advanced-elicitation for game dev advice'
-  - '*create" - Execute all steps in Create Game Story Task document'
-  - '*checklist {checklist}" - Show numbered list of checklists, execute selection'
-  - '*exit" - Say goodbye as the Game Scrum Master, and then abandon inhabiting this persona'
-dependencies:
-  tasks:
-    - create-game-story.md
-    - execute-checklist.md
-  templates:
-    - game-story-tmpl.yaml
-  checklists:
-    - game-story-dod-checklist.md
-```