bmad-method 4.2.0 → 4.4.0

package/docs/versioning-and-releases.md

@@ -8,7 +8,7 @@ The easiest way to release new versions is through **automatic semantic releases
 
 Use these prefixes to control what type of release happens:
 
-```bash
+````bash
 fix: resolve CLI argument parsing bug      # → patch release (4.1.0 → 4.1.1)
 feat: add new agent orchestration mode     # → minor release (4.1.0 → 4.2.0)
 feat!: redesign CLI interface              # → major release (4.1.0 → 5.0.0)
@@ -35,13 +35,13 @@ git push
 
 # That's it! Release happens automatically 🎉
 # Users can now run: npx bmad-method (and get the new version)
-```
+````
 
 ### Commits That DON'T Trigger Releases
 
 These commit types won't create releases (use them for maintenance):
 
-```bash
+````bash
 chore: update dependencies     # No release
 docs: fix typo in readme      # No release
 style: format code            # No release
@@ -52,7 +52,7 @@ test: add unit tests          # No release
 
 ```bash
 npm run release:test    # Safe to run locally - tests the config
-```
+````
 
 ---
 

package/docs/windsurf-guide.md

@@ -0,0 +1,127 @@
+# BMAD Method Guide for Windsurf
+
+This guide walks you through the complete BMAD workflow using Windsurf as your AI-powered IDE.
+
+## Step 1: Install BMAD in Your Project
+
+1. Navigate to your project directory
+2. Run the BMAD installer:
+   ```bash
+   npx bmad-method install
+   ```
+3. When prompted:
+   - **Installation Type**: Choose "Complete installation (recommended)"
+   - **IDE**: Select "Windsurf"
+
+This creates a `.bmad-core` folder with all agents and a `.windsurf/rules` folder with agent rules.
+
+## Step 2: Set Up Team Fullstack in Gemini
+
+For ideation and planning, use Google's Gemini with the team-fullstack configuration:
+
+1. Open [Google AI Studio (Gemini)](https://aistudio.google.com/)
+2. Create a new chat
+3. Copy the contents of `/Users/brianmadison/dev/BMAD-METHOD/.bmad-core/web-bundles/teams/team-fullstack.txt`
+4. Paste this content into Gemini to set up the team
+
+### Gemini Planning Phase
+
+In Gemini, ask the BMAD team to help you:
+
+- **Ideate** your project concept
+- **Brainstorm** features and requirements
+- **Create a PRD** (Product Requirements Document)
+- **Design the architecture**
+
+Ask questions like:
+
+- "Help me brainstorm a [type of application] that does [core functionality]"
+- "Create a comprehensive PRD for this concept"
+- "Design the technical architecture for this system"
+
+Copy the PRD and architecture documents that Gemini creates into your project's `docs/` folder:
+
+- `docs/prd.md`
+- `docs/architecture.md`
+
+## Step 3: Back to Windsurf - Document Sharding
+
+Once you have your PRD and architecture documents in the `docs/` folder:
+
+1. **Start a new chat in Windsurf**
+2. **Load the bmad-master agent**: Type `@bmad-master`
+3. **Shard the PRD**: Type `*shard-doc docs/prd.md prd`
+4. **Shard the architecture**: Type `*shard-doc docs/architecture.md architecture`
+
+This creates organized folders:
+
+- `docs/prd/` - Contains broken down PRD sections
+- `docs/architecture/` - Contains broken down architecture sections
+
+## Step 4: Story Development Cycle
+
+Now begin the iterative development cycle:
+
+### Create Stories (Scrum Master)
+
+1. **Start a new chat**
+2. **Load SM agent**: Type `@sm`
+3. **Create story**: Type `*create` (this runs the create-next-story task)
+4. **Review the generated story**
+5. **If approved**: Set story status to "Approved" in the story file
+
+### Implement Stories (Developer)
+
+1. **Start a new chat**
+2. **Load Dev agent**: Type `@dev`
+3. **The agent will ask which story to implement**
+4. **Follow the development tasks** the agent provides
+5. **When story is complete**: Mark status as "Done"
+
+### Repeat the Cycle
+
+1. **Start a new chat with SM agent** (`@sm`)
+2. **Create next story**: Type `*create`
+3. **Review and approve**
+4. **Start new chat with Dev agent** (`@dev`)
+5. **Implement the story**
+6. **Repeat until project complete**
+
+## Available Agent Rules in Windsurf
+
+All BMAD agents are available as Windsurf rules (use `@` prefix):
+
+- `@bmad-master` - Universal task executor
+- `@sm` - Scrum Master for story creation
+- `@dev` - Full-stack developer for implementation
+- `@architect` - Solution architect for design
+- `@pm` - Product manager for planning
+- `@analyst` - Business analyst for requirements
+- `@qa` - QA specialist for testing
+- `@po` - Product owner for prioritization
+- `@ux-expert` - UX specialist for design
+
+## Windsurf-Specific Features
+
+- **Agent rules are stored in**: `.windsurf/rules/` as `.md` files
+- **Rule activation**: Rules activate when you mention `@agent-name` in chat
+- **Collaborative workflow**: Windsurf's collaborative features work well with BMAD's agent-switching pattern
+- **Context awareness**: Agents have access to your project context
+
+## Key Workflow Principles
+
+1. **Always start new chats** when switching agents to avoid context confusion
+2. **Use Gemini for initial planning** and ideation with the team-fullstack bundle
+3. **Use bmad-master for document management** (sharding, templates, etc.)
+4. **Follow the SM → Dev cycle** for consistent story development
+5. **Review and approve stories** before implementation begins
+
+## Tips for Success
+
+- **Keep chats focused**: Each chat should have one agent and one primary task
+- **Use \*help command**: Every agent supports `*help` to see available commands
+- **Review generated content**: Always review and approve stories before marking them ready
+- **Maintain status updates**: Keep story statuses current (Draft → Approved → InProgress → Done)
+- **Leverage Windsurf's collaboration**: Use the collaborative features for team reviews
+
+This workflow ensures systematic, AI-assisted development following agile principles with clear handoffs between planning, story creation, and implementation phases.

package/expansion-packs/README.md

@@ -1,113 +1,3 @@
 # BMAD Method Expansion Packs
 
-## Overview
-
-Expansion packs extend BMAD Method with specialized capabilities for specific use cases. They allow teams to add functionality without cluttering the core workflow.
-
-## Core BMAD Flow
-
-The original BMAD Method follows a simple, proven flow:
-
-````text
-Analyst → PM → Architect → SM → Dev
-(Brief) → (PRD) → (Architecture) → (Stories) → (Implementation)
-```text
-
-This core flow remains clean and focused on getting from business requirements to working software.
-
-## Why Expansion Packs?
-
-As BMAD has evolved, we've identified specialized needs that don't fit every project:
-
-- Infrastructure and DevOps workflows
-- UX/UI design processes
-- Data engineering pipelines
-- Security and compliance workflows
-- Mobile development patterns
-- Real World assistance and workflows without AI Agents development in mind
-
-Rather than complicate the core method, expansion packs let you "opt-in" to additional capabilities.
-
-## Available Expansion Packs
-
-### 1. Infrastructure & DevOps
-
-- **Purpose**: Cloud infrastructure design and platform engineering
-- **Adds**: DevOps agent, infrastructure templates, validation checklists
-- **Use When**: You need to design and implement cloud infrastructure
-
-### 2. UX/Design (Coming Soon)
-
-- **Purpose**: User experience and interface design workflows
-- **Adds**: Design Architect agent, UI component templates
-- **Use When**: You need detailed UI/UX design processes
-
-### 3. Data Engineering (Planned)
-
-- **Purpose**: Data pipeline and analytics infrastructure
-- **Adds**: Data Engineer agent, ETL templates, data architecture patterns
-- **Use When**: You're building data-intensive applications
-
-## Structure of an Expansion Pack
-
-Each expansion pack contains:
-
-```text
-expansion-pack-name/
-├── README.md           # Overview and usage instructions
-├── manifest.yml        # Installation configuration
-├── agents/            # Agent configurations (.yml)
-├── personas/          # Persona definitions (.md)
-├── ide-agents/        # IDE-specific agents (.ide.md)
-├── templates/         # Document templates (.md)
-├── tasks/            # Specialized tasks (.md)
-└── checklists/       # Validation checklists (.md)
-````
-
-## Installing an Expansion Pack
-
-### Method 1: NPM Script
-
-````bash
-npm run install:expansion <pack-name>
-```text
-
-### Method 2: Direct Script
-
-```bash
-node tools/install-expansion-pack.js <pack-name>
-````
-
-### Method 3: Manual
-
-1. Copy files according to manifest.yml
-2. Update team configurations as needed
-3. Rebuild bundles with `npm run build`
-
-## Creating Your Own Expansion Pack
-
-1. Create a new folder under `expansion-packs/`
-2. Add your specialized agents, templates, and tasks
-3. Create a manifest.yml defining installation mappings
-4. Write a README explaining purpose and usage
-5. Test installation process
-
-## Best Practices
-
-1. **Keep Core Simple**: Don't add to core what could be an expansion
-2. **Clear Purpose**: Each pack should solve a specific need
-3. **Self-Contained**: Packs should work independently when possible
-4. **Document Well**: Clear README and usage examples
-5. **Version Compatibility**: Note which BMAD version the pack requires
-
-## Future Vision
-
-We envision a library of expansion packs for various industries and use cases:
-
-- Healthcare compliance workflows
-- Financial services security patterns
-- E-commerce optimization flows
-- Gaming development pipelines
-- IoT device management
-
-The goal is to keep BMAD's core simple while allowing infinite extensibility through modular expansion packs.
+Expansion packs extend BMAD-METHOD beyond traditional software development, providing specialized agent teams, templates, and workflows for specific domains and industries. Each pack is a self-contained ecosystem designed to bring the power of AI-assisted workflows to any field. Coming soon.

package/expansion-packs/infrastructure-devops/agents/infra-devops-platform.md

@@ -2,7 +2,7 @@
 
 CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
-```yml
+```yaml
 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
@@ -31,8 +31,8 @@ persona:
     - Collaborative Operations - Work closely with development teams fostering shared responsibility for system reliability
 startup:
   - Announce: Hey! I'm Alex, your DevOps Infrastructure Specialist. I love when things run secure, stable, reliable and performant. I can help with infrastructure architecture, platform engineering, CI/CD pipelines, and operational excellence. What infrastructure challenge can I help you with today?
-  - 'List available tasks: review-infrastructure, validate-infrastructure, create infrastructure documentation'
-  - 'List available templates: infrastructure-architecture, infrastructure-platform-from-arch'
+  - "List available tasks: review-infrastructure, validate-infrastructure, create infrastructure documentation"
+  - "List available templates: infrastructure-architecture, infrastructure-platform-from-arch"
   - Execute selected task or stay in persona to help guided by Core DevOps Principles
 commands:
   - '*help" - Show: numbered list of the following commands to allow selection'

package/expansion-packs/infrastructure-devops/tasks/create-doc.md

@@ -0,0 +1,74 @@
+# Create Document from Template Task
+
+## Purpose
+
+- Generate documents from any specified template following embedded instructions from the perspective of the selected agent persona
+
+## Instructions
+
+### 1. Identify Template and Context
+
+- Determine which template to use (user-provided or list available for selection to user)
+
+  - Agent-specific templates are listed in the agent's dependencies under `templates`. For each template listed, consider it a document the agent can create. So if an agent has:
+
+    @{example}
+    dependencies:
+    templates: - prd-tmpl - architecture-tmpl
+    @{/example}
+
+    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+
+- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
+- Understand the document purpose and target audience
+
+### 2. Determine Interaction Mode
+
+Confirm with the user their preferred interaction style:
+
+- **Incremental:** Work through chunks of the document.
+- **YOLO Mode:** Draft complete document making reasonable assumptions in one shot. (Can be entered also after starting incremental by just typing /yolo)
+
+### 3. Execute Template
+
+- Load specified template from `templates#*` or the /templates directory
+- Follow ALL embedded LLM instructions within the template
+- Process template markup according to `utils#template-format` conventions
+
+### 4. Template Processing Rules
+
+#### CRITICAL: Never display template markup, LLM instructions, or examples to users
+
+- Replace all {{placeholders}} with actual content
+- Execute all [[LLM: instructions]] internally
+- Process `<<REPEAT>>` sections as needed
+- Evaluate ^^CONDITION^^ blocks and include only if applicable
+- Use @{examples} for guidance but never output them
+
+### 5. Content Generation
+
+- **Incremental Mode**: Present each major section for review before proceeding
+- **YOLO Mode**: Generate all sections, then review complete document with user
+- Apply any elicitation protocols specified in template
+- Incorporate user feedback and iterate as needed
+
+### 6. Validation
+
+If template specifies a checklist:
+
+- Run the appropriate checklist against completed document
+- Document completion status for each item
+- Address any deficiencies found
+- Present validation summary to user
+
+### 7. Final Presentation
+
+- Present clean, formatted content only
+- Ensure all sections are complete
+- DO NOT truncate or summarize content
+- Begin directly with document content (no preamble)
+- Include any handoff prompts specified in template
+
+## Important Notes
+
+- Template markup is for AI processing only - never expose to users

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "bmad-method",
-  "version": "4.2.0",
+  "version": "4.4.0",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "main": "tools/cli.js",
   "bin": {
-    "bmad": "./tools/bmad-npx-wrapper.js",
-    "bmad-method": "./tools/bmad-npx-wrapper.js"
+    "bmad": "tools/bmad-npx-wrapper.js",
+    "bmad-method": "tools/bmad-npx-wrapper.js"
   },
   "scripts": {
     "build": "node tools/cli.js build",
@@ -23,14 +23,14 @@
     "prepare": "husky"
   },
   "dependencies": {
-    "@kayvan/markdown-tree-parser": "^1.4.2",
-    "chalk": "^4.1.2",
-    "commander": "^9.4.1",
-    "fs-extra": "^11.1.0",
-    "glob": "^8.0.3",
-    "inquirer": "^8.2.5",
+    "@kayvan/markdown-tree-parser": "^1.5.0",
+    "chalk": "^5.4.1",
+    "commander": "^14.0.0",
+    "fs-extra": "^11.3.0",
+    "glob": "^11.0.3",
+    "inquirer": "^12.6.3",
     "js-yaml": "^4.1.0",
-    "ora": "^5.4.1"
+    "ora": "^8.2.0"
   },
   "keywords": [
     "agile",
@@ -45,7 +45,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/bmadcode/BMAD-METHOD.git"
+    "url": "git+https://github.com/bmadcode/BMAD-METHOD.git"
   },
   "engines": {
     "node": ">=14.0.0"
@@ -60,14 +60,20 @@
     "yaml-lint": "^1.7.0"
   },
   "lint-staged": {
-    "*.{yml,yaml}": [
+    "**/*.{yml,yaml}": [
       "node tools/yaml-format.js"
     ],
-    "*.md": [
+    "**/*.md": [
       "node tools/yaml-format.js"
     ],
     ".roomodes": [
       "node tools/yaml-format.js"
+    ],
+    ".bmad-core/**/*.yml": [
+      "node tools/yaml-format.js"
+    ],
+    ".github/**/*.yml": [
+      "node tools/yaml-format.js"
     ]
   }
 }

package/tools/builders/web-builder.js

@@ -1,5 +1,5 @@
-const fs = require('fs').promises;
-const path = require('path');
+const fs = require('node:fs').promises;
+const path = require('node:path');
 const DependencyResolver = require('../lib/dependency-resolver');
 
 class WebBuilder {
@@ -19,6 +19,7 @@ class WebBuilder {
         await fs.rm(dir, { recursive: true, force: true });
         console.log(`Cleaned: ${path.relative(this.rootDir, dir)}`);
       } catch (error) {
+        console.debug(`Failed to clean directory ${dir}:`, error.message);
         // Directory might not exist, that's fine
       }
     }
@@ -26,11 +27,11 @@ class WebBuilder {
 
   async buildAgents() {
     const agents = await this.resolver.listAgents();
-    
+
     for (const agentId of agents) {
       console.log(`  Building agent: ${agentId}`);
       const bundle = await this.buildAgentBundle(agentId);
-      
+
       // Write to all output directories
       for (const outputDir of this.outputDirs) {
         const outputPath = path.join(outputDir, 'agents');
@@ -45,11 +46,11 @@ class WebBuilder {
 
   async buildTeams() {
     const teams = await this.resolver.listTeams();
-    
+
     for (const teamId of teams) {
       console.log(`  Building team: ${teamId}`);
       const bundle = await this.buildTeamBundle(teamId);
-      
+
       // Write to all output directories
       for (const outputDir of this.outputDirs) {
         const outputPath = path.join(outputDir, 'teams');
@@ -65,39 +66,39 @@ class WebBuilder {
   async buildAgentBundle(agentId) {
     const dependencies = await this.resolver.resolveAgentDependencies(agentId);
     const template = await fs.readFile(this.templatePath, 'utf8');
-    
+
     const sections = [template];
-    
+
     // Add agent configuration
     sections.push(this.formatSection(dependencies.agent.path, dependencies.agent.content));
-    
+
     // Add all dependencies
     for (const resource of dependencies.resources) {
       sections.push(this.formatSection(resource.path, resource.content));
     }
-    
+
     return sections.join('\n');
   }
 
   async buildTeamBundle(teamId) {
     const dependencies = await this.resolver.resolveTeamDependencies(teamId);
     const template = await fs.readFile(this.templatePath, 'utf8');
-    
+
     const sections = [template];
-    
+
     // Add team configuration
     sections.push(this.formatSection(dependencies.team.path, dependencies.team.content));
-    
+
     // Add all agents
     for (const agent of dependencies.agents) {
       sections.push(this.formatSection(agent.path, agent.content));
     }
-    
+
     // Add all deduplicated resources
     for (const resource of dependencies.resources) {
       sections.push(this.formatSection(resource.path, resource.content));
     }
-    
+
     return sections.join('\n');
   }
 

package/tools/installer/README.md

@@ -33,7 +33,7 @@ installer/
 
 ## Usage
 
-```bash
+````bash
 # Interactive installation
 npx bmad-method install
 
@@ -55,4 +55,4 @@ npm test
 
 # Lint code
 npm run lint
-```
+````