bmad-method 4.12.0 → 4.14.0

package/docs/expansion-packs.md

@@ -0,0 +1,265 @@
+# The Power of BMAD Expansion Packs
+
+## Overview
+
+BMAD Method's expansion packs unlock the framework's true potential by extending its natural language AI orchestration to ANY domain. While the core framework focuses on software development, expansion packs transform BMAD into a universal AI agent system.
+
+## Why Expansion Packs?
+
+### Keep Core Lean
+
+The core BMAD framework maintains its focus on software development, ensuring dev agents have maximum context for coding. Expansion packs handle everything else.
+
+### Domain Expertise
+
+Each expansion pack provides deep, specialized knowledge without bloating the core system. Install only what you need.
+
+### Community Innovation
+
+Anyone can create and share expansion packs, fostering a ecosystem of AI-powered solutions across all industries and interests.
+
+## Technical Expansion Packs
+
+### Game Development Pack
+
+Transform your AI into a complete game development studio:
+
+- **Game Designer**: Mechanics, balance, progression systems
+- **Level Designer**: Map layouts, puzzle design, difficulty curves
+- **Narrative Designer**: Story arcs, dialog trees, lore creation
+- **Art Director**: Visual style guides, asset specifications
+- **Sound Designer**: Audio direction, music themes, SFX planning
+
+### Mobile Development Pack
+
+Specialized agents for mobile app creation:
+
+- **iOS Specialist**: Swift/SwiftUI patterns, Apple guidelines
+- **Android Expert**: Kotlin best practices, Material Design
+- **Mobile UX Designer**: Touch interfaces, gesture patterns
+- **App Store Optimizer**: ASO strategies, listing optimization
+- **Performance Tuner**: Battery optimization, network efficiency
+
+### DevOps/Infrastructure Pack
+
+Complete infrastructure automation team:
+
+- **Cloud Architect**: AWS/Azure/GCP design patterns
+- **Security Specialist**: Zero-trust implementation, compliance
+- **SRE Expert**: Monitoring, alerting, incident response
+- **Container Orchestrator**: Kubernetes, Docker optimization
+- **Cost Optimizer**: Cloud spend analysis, resource right-sizing
+
+### Data Science Pack
+
+AI-powered data analysis team:
+
+- **Data Scientist**: Statistical analysis, ML model selection
+- **Data Engineer**: Pipeline design, ETL processes
+- **ML Engineer**: Model deployment, A/B testing
+- **Visualization Expert**: Dashboard design, insight communication
+- **Ethics Advisor**: Bias detection, fairness assessment
+
+## Non-Technical Expansion Packs
+
+### Business Strategy Pack
+
+Complete business advisory team:
+
+- **Strategy Consultant**: Market positioning, competitive analysis
+- **Financial Analyst**: Projections, unit economics, funding strategies
+- **Operations Manager**: Process optimization, efficiency improvements
+- **Marketing Strategist**: Go-to-market plans, growth hacking
+- **HR Advisor**: Talent strategies, culture building
+
+### Creative Writing Pack
+
+Your personal writing team:
+
+- **Plot Architect**: Three-act structure, story beats, pacing
+- **Character Psychologist**: Deep motivations, authentic dialog
+- **World Builder**: Consistent universes, cultural systems
+- **Editor**: Style consistency, grammar, flow
+- **Beta Reader**: Feedback simulation, plot hole detection
+
+### Health & Wellness Pack
+
+Personal wellness coaching system:
+
+- **Fitness Trainer**: Progressive overload, form correction
+- **Nutritionist**: Macro planning, supplement guidance
+- **Sleep Coach**: Circadian optimization, sleep hygiene
+- **Stress Manager**: Coping strategies, work-life balance
+- **Habit Engineer**: Behavior change, accountability systems
+
+### Education Pack
+
+Complete learning design system:
+
+- **Curriculum Architect**: Learning objectives, scope & sequence
+- **Instructional Designer**: Engagement strategies, multimedia learning
+- **Assessment Specialist**: Rubrics, formative/summative evaluation
+- **Differentiation Expert**: Adaptive learning, special needs
+- **EdTech Integrator**: Tool selection, digital pedagogy
+
+### Mental Health Support Pack
+
+Therapeutic support system:
+
+- **CBT Guide**: Cognitive restructuring, thought challenging
+- **Mindfulness Teacher**: Meditation scripts, awareness exercises
+- **Journal Therapist**: Reflective prompts, emotional processing
+- **Crisis Support**: Coping strategies, safety planning
+- **Habit Tracker**: Mood monitoring, trigger identification
+
+### Legal Assistant Pack
+
+Legal document and research support:
+
+- **Contract Analyst**: Term review, risk assessment
+- **Legal Researcher**: Case law, precedent analysis
+- **Document Drafter**: Template customization, clause libraries
+- **Compliance Checker**: Regulatory alignment, audit prep
+- **IP Advisor**: Patent strategies, trademark guidance
+
+### Real Estate Pack
+
+Property investment and management:
+
+- **Market Analyst**: Comparable analysis, trend prediction
+- **Investment Calculator**: ROI modeling, cash flow analysis
+- **Property Manager**: Tenant screening, maintenance scheduling
+- **Flip Strategist**: Renovation ROI, project planning
+- **Agent Assistant**: Listing optimization, showing prep
+
+## Unique & Innovative Packs
+
+### Role-Playing Game Master Pack
+
+AI-powered tabletop RPG assistance:
+
+- **World Master**: Dynamic world generation, NPC creation
+- **Combat Referee**: Initiative tracking, rule clarification
+- **Story Weaver**: Plot hooks, side quests, consequences
+- **Character Builder**: Backstory generation, stat optimization
+- **Loot Master**: Treasure generation, magic item creation
+
+### Life Event Planning Pack
+
+Major life event coordination:
+
+- **Wedding Planner**: Vendor coordination, timeline creation
+- **Event Designer**: Theme development, decoration plans
+- **Budget Manager**: Cost tracking, vendor negotiation
+- **Guest Coordinator**: RSVP tracking, seating arrangements
+- **Timeline Keeper**: Day-of scheduling, contingency planning
+
+### Hobby Mastery Pack
+
+Deep dive into specific hobbies:
+
+- **Garden Designer**: Plant selection, seasonal planning
+- **Brew Master**: Recipe formulation, process optimization
+- **Maker Assistant**: 3D printing, woodworking, crafts
+- **Collection Curator**: Organization, valuation, trading
+- **Photography Coach**: Composition, lighting, post-processing
+
+### Scientific Research Pack
+
+Research acceleration tools:
+
+- **Literature Reviewer**: Paper summarization, gap analysis
+- **Hypothesis Generator**: Research question formulation
+- **Methodology Designer**: Experiment planning, control design
+- **Statistical Advisor**: Test selection, power analysis
+- **Grant Writer**: Proposal structure, impact statements
+
+## Creating Your Own Expansion Pack
+
+### Step 1: Define Your Domain
+
+What expertise are you capturing? What problems will it solve?
+
+### Step 2: Design Your Agents
+
+Each agent should have:
+
+- Clear expertise area
+- Specific personality traits
+- Defined capabilities
+- Knowledge boundaries
+
+### Step 3: Create Tasks
+
+Tasks should be:
+
+- Step-by-step procedures
+- Reusable across scenarios
+- Clear and actionable
+- Domain-specific
+
+### Step 4: Build Templates
+
+Templates need:
+
+- Structured output format
+- Embedded LLM instructions
+- Placeholders for customization
+- Professional formatting
+
+### Step 5: Test & Iterate
+
+- Use with real scenarios
+- Gather user feedback
+- Refine agent responses
+- Improve task clarity
+
+### Step 6: Package & Share
+
+- Create clear documentation
+- Include usage examples
+- Add to expansion-packs directory
+- Share with community
+
+## The Future of Expansion Packs
+
+### Marketplace Potential
+
+Imagine a future where:
+
+- Professional expansion packs are sold
+- Certified packs for regulated industries
+- Community ratings and reviews
+- Automatic updates and improvements
+
+### AI Agent Ecosystems
+
+Expansion packs could enable:
+
+- Cross-pack agent collaboration
+- Industry-standard agent protocols
+- Interoperable AI workflows
+- Universal agent languages
+
+### Democratizing Expertise
+
+Every expansion pack:
+
+- Makes expert knowledge accessible
+- Reduces barriers to entry
+- Enables solo entrepreneurs
+- Empowers small teams
+
+## Getting Started
+
+1. **Browse existing packs**: Check `expansion-packs/` directory
+2. **Install what you need**: Use the installer's expansion pack option
+3. **Create your own**: Use the expansion-creator pack
+4. **Share with others**: Submit PRs with new packs
+5. **Build the future**: Help shape AI-assisted work
+
+## Remember
+
+The BMAD Method is more than a development framework - it's a platform for structuring human expertise into AI-accessible formats. Every expansion pack you create makes specialized knowledge more accessible to everyone.
+
+**What expertise will you share with the world?**

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

@@ -0,0 +1,362 @@
+# Working in the Brownfield: A Complete Guide
+
+> 🚀 **HIGHLY RECOMMENDED: Use Gemini Web for Brownfield Documentation!**
+>
+> Gemini Web's 1M+ token context window can analyze your ENTIRE codebase at once:
+>
+> - Upload via GitHub URL
+> - Upload up to 1000 files
+> - Upload zipped project
+>
+> This is MUCH more cost-effective than IDE analysis which reads files one by one!
+
+## 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
+
+BMAD-METHOD excels at brownfield development when you need to:
+
+- 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
+
+## The Complete Brownfield Workflow
+
+### Choose Your Approach
+
+#### Approach A: PRD-First (Recommended for Large Codebases/Monorepos)
+
+**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/expansion-creator/tasks/create-agent.md

@@ -4,7 +4,7 @@ This task guides you through creating a new BMAD agent following the standard te
 
 ## Prerequisites
 
-- Agent template: `.bmad-core/templates/agent-tmpl.md`
+- Agent template: `../templates/agent-tmpl.md`
 - Target directory: `.bmad-core/agents/`
 
 ## Steps

package/expansion-packs/expansion-creator/tasks/generate-expansion-pack.md

@@ -18,7 +18,7 @@ Every expansion pack MUST include a custom BMAD orchestrator agent with sophisti
 
 1. **Create Planning Document First**: Before any implementation, create a comprehensive plan for user approval
 2. **Agent Architecture Standards**: Use YAML-in-Markdown structure with activation instructions, personas, and command systems
-3. **Character Consistency**: Every agent must have a persistent persona with name, communication style, and numbered options protocol
+3. **Character Consistency**: Every agent must have a persistent persona with name, communication style, and numbered options protocol similar to `expansion-packs/bmad-2d-phaser-game-dev/agents/game-designer.md`
 4. **Custom Themed Orchestrator**: The orchestrator should embody the domain theme (e.g., Office Manager for medical, Project Lead for tech) for better user experience
 5. **Core Utilities Required**: ALWAYS include these core files in every expansion pack:
    - `tasks/create-doc.md` - Document creation from templates
@@ -26,8 +26,8 @@ Every expansion pack MUST include a custom BMAD orchestrator agent with sophisti
    - `utils/template-format.md` - Template markup conventions
    - `utils/workflow-management.md` - Workflow orchestration
 6. **Team and Workflow Requirements**: If pack has >1 agent, MUST include:
-   - At least one team configuration in `agent-teams/`
-   - At least one workflow in `workflows/`
+   - At least one team configuration in `expansion-packs/{new-expansion}/agent-teams/`
+   - At least one workflow in `expansion-packs/{new-expansion}workflows/`
 7. **Template Sophistication**: Implement LLM instruction embedding with `[[LLM: guidance]]`, conditional content, and variable systems
 8. **Workflow Orchestration**: Include decision trees, handoff protocols, and validation loops
 9. **Quality Assurance Integration**: Multi-level checklists with star ratings and ready/not-ready frameworks
@@ -1018,11 +1018,3 @@ Embedded knowledge (automatic):
 - [ ] Template conditional content tested with different scenarios
 - [ ] Workflow decision trees validated with sample use cases
 - [ ] Character interactions tested for consistency and professional authenticity
-
-```
-
-```
-
-```
-
-```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmad-method",
-  "version": "4.12.0",
+  "version": "4.14.0",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "main": "tools/cli.js",
   "bin": {