bmad-method 1.1.0 → 4.4.0

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

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": "1.1.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/bin/bmad.js

@@ -1,24 +1,34 @@
 #!/usr/bin/env node
 
 const { program } = require('commander');
-const inquirer = require('inquirer');
-const chalk = require('chalk');
-const path = require('path');
+
+// Dynamic imports for ES modules
+let chalk, inquirer;
+
+// Initialize ES modules
+async function initializeModules() {
+  if (!chalk) {
+    chalk = (await import('chalk')).default;
+    inquirer = (await import('inquirer')).default;
+  }
+}
 
 // Handle both execution contexts (from root via npx or from installer directory)
-let version, installer;
+let version;
+let installer;
 try {
   // Try installer context first (when run from tools/installer/)
   version = require('../package.json').version;
   installer = require('../lib/installer');
 } catch (e) {
   // Fall back to root context (when run via npx from GitHub)
+  console.log(`Installer context not found (${e.message}), trying root context...`);
   try {
     version = require('../../../package.json').version;
     installer = require('../../../tools/installer/lib/installer');
   } catch (e2) {
-    console.error(chalk.red('Error: Could not load required modules. Please ensure you are running from the correct directory.'));
-    console.error(chalk.yellow('Debug info:'), {
+    console.error('Error: Could not load required modules. Please ensure you are running from the correct directory.');
+    console.error('Debug info:', {
       __dirname,
       cwd: process.cwd(),
       error: e2.message
@@ -36,25 +46,27 @@ program
   .description('Install BMAD Method agents and tools')
   .option('-f, --full', 'Install complete .bmad-core folder')
   .option('-a, --agent <agent>', 'Install specific agent with dependencies')
-  .option('-d, --directory <path>', 'Installation directory (default: ./bmad-core)')
-  .option('-i, --ide <ide>', 'Configure for specific IDE (cursor, claude-code, windsurf, roo)')
+  .option('-d, --directory <path>', 'Installation directory (default: .bmad-core)')
+  .option('-i, --ide <ide...>', 'Configure for specific IDE(s) - can specify multiple (cursor, claude-code, windsurf, roo)')
   .action(async (options) => {
     try {
+      await initializeModules();
       if (!options.full && !options.agent) {
         // Interactive mode
-        const answers = await promptInstallation(options);
+        const answers = await promptInstallation();
         await installer.install(answers);
       } else {
         // Direct mode
         const config = {
           installType: options.full ? 'full' : 'single-agent',
           agent: options.agent,
-          directory: options.directory || './.bmad-core',
-          ide: options.ide
+          directory: options.directory || '.bmad-core',
+          ides: options.ide || []
         };
         await installer.install(config);
       }
     } catch (error) {
+      if (!chalk) await initializeModules();
       console.error(chalk.red('Installation failed:'), error.message);
       process.exit(1);
     }
@@ -65,10 +77,11 @@ program
   .description('Update existing BMAD installation')
   .option('--force', 'Force update, overwriting modified files')
   .option('--dry-run', 'Show what would be updated without making changes')
-  .action(async (options) => {
+  .action(async () => {
     try {
-      await installer.update(options);
+      await installer.update();
     } catch (error) {
+      if (!chalk) await initializeModules();
       console.error(chalk.red('Update failed:'), error.message);
       process.exit(1);
     }
@@ -81,6 +94,7 @@ program
     try {
       await installer.listAgents();
     } catch (error) {
+      if (!chalk) await initializeModules();
       console.error(chalk.red('Error:'), error.message);
       process.exit(1);
     }
@@ -93,27 +107,29 @@ program
     try {
       await installer.showStatus();
     } catch (error) {
+      if (!chalk) await initializeModules();
       console.error(chalk.red('Error:'), error.message);
       process.exit(1);
     }
   });
 
-async function promptInstallation(options) {
+async function promptInstallation() {
+  await initializeModules();
   console.log(chalk.bold.blue(`\nWelcome to BMAD Method Installer v${version}\n`));
-  
+
   const answers = {};
-  
+
   // Ask for installation directory
   const { directory } = await inquirer.prompt([
     {
       type: 'input',
       name: 'directory',
       message: 'Where would you like to install BMAD?',
-      default: './.bmad-core'
+      default: '.bmad-core'
     }
   ]);
   answers.directory = directory;
-  
+
   // Ask for installation type
   const { installType } = await inquirer.prompt([
     {
@@ -133,7 +149,7 @@ async function promptInstallation(options) {
     }
   ]);
   answers.installType = installType;
-  
+
   // If single agent, ask which one
   if (installType === 'single-agent') {
     const agents = await installer.getAvailableAgents();
@@ -150,24 +166,29 @@ async function promptInstallation(options) {
     ]);
     answers.agent = agent;
   }
-  
+
   // Ask for IDE configuration
-  const { ide } = await inquirer.prompt([
+  const { ides } = await inquirer.prompt([
     {
-      type: 'list',
-      name: 'ide',
-      message: 'Which IDE are you using?',
+      type: 'checkbox',
+      name: 'ides',
+      message: 'Which IDE(s) are you using? (Select all that apply)',
       choices: [
         { name: 'Cursor', value: 'cursor' },
         { name: 'Claude Code', value: 'claude-code' },
         { name: 'Windsurf', value: 'windsurf' },
-        { name: 'Roo Code', value: 'roo' },
-        { name: 'Other/Manual setup', value: null }
-      ]
+        { name: 'Roo Code', value: 'roo' }
+      ],
+      validate: (answer) => {
+        if (answer.length < 1) {
+          return 'You must choose at least one IDE, or press Ctrl+C to skip IDE setup.';
+        }
+        return true;
+      }
     }
   ]);
-  answers.ide = ide;
-  
+  answers.ides = ides;
+
   return answers;
 }