bmad-method 4.17.0 → 4.19.0

package/tools/installer/lib/installer.js

@@ -225,6 +225,10 @@ class Installer {
       const sourceDir = configLoader.getBmadCorePath();
       const bmadCoreDestDir = path.join(installDir, ".bmad-core");
       await fileManager.copyDirectory(sourceDir, bmadCoreDestDir);
+      
+      // Copy common/ items to .bmad-core
+      spinner.text = "Copying common utilities...";
+      await this.copyCommonItems(installDir, ".bmad-core", spinner);
 
       // Get list of all files for manifest
       const glob = require("glob");
@@ -283,6 +287,11 @@ class Installer {
           }
         }
       }
+      
+      // Copy common/ items to .bmad-core
+      spinner.text = "Copying common utilities...";
+      const commonFiles = await this.copyCommonItems(installDir, ".bmad-core", spinner);
+      files.push(...commonFiles);
     } else if (config.installType === "team") {
       // Team installation
       spinner.text = `Installing ${config.team} team...`;
@@ -313,6 +322,11 @@ class Installer {
           }
         }
       }
+      
+      // Copy common/ items to .bmad-core
+      spinner.text = "Copying common utilities...";
+      const commonFiles = await this.copyCommonItems(installDir, ".bmad-core", spinner);
+      files.push(...commonFiles);
     } else if (config.installType === "expansion-only") {
       // Expansion-only installation - create minimal .bmad-core structure
       spinner.text = "Creating minimal .bmad-core structure for expansion packs...";
@@ -341,6 +355,10 @@ class Installer {
         );
         files.push(...copiedFiles.map(f => `.bmad-core/${f}`));
       }
+      
+      // Copy common/ items to .bmad-core
+      spinner.text = "Copying common utilities...";
+      await this.copyCommonItems(installDir, ".bmad-core", spinner);
     }
 
     // Install expansion packs if requested
@@ -607,8 +625,10 @@ class Installer {
     console.log(chalk.green("✓ .bmad-core framework installed with all agents and workflows"));
     
     if (config.expansionPacks && config.expansionPacks.length > 0) {
-      const packNames = config.expansionPacks.join(", ");
-      console.log(chalk.green(`✓ Expansion packs installed: ${packNames}`));
+      console.log(chalk.green(`✓ Expansion packs installed:`));
+      for (const packId of config.expansionPacks) {
+        console.log(chalk.green(`  - ${packId} → .${packId}/`));
+      }
     }
     
     if (config.includeWebBundles && config.webBundlesDirectory) {
@@ -797,9 +817,13 @@ class Installer {
           continue;
         }
 
-        const expansionPackDir = path.dirname(pack.manifestPath);
+        const expansionPackDir = pack.packPath;
         
-        // Define the folders to copy from expansion packs to .bmad-core
+        // Create dedicated dot folder for this expansion pack
+        const expansionDotFolder = path.join(installDir, `.${packId}`);
+        await fileManager.ensureDirectory(expansionDotFolder);
+        
+        // Define the folders to copy from expansion packs
         const foldersToSync = [
           'agents',
           'agent-teams',
@@ -824,21 +848,47 @@ class Installer {
               nodir: true
             });
 
-            // Copy each file to the destination
+            // Copy each file to the expansion pack's dot folder
             for (const file of files) {
               const sourcePath = path.join(sourceFolder, file);
-              const destPath = path.join(installDir, '.bmad-core', folder, file);
+              const destPath = path.join(expansionDotFolder, folder, file);
               
               if (await fileManager.copyFile(sourcePath, destPath)) {
-                installedFiles.push(path.join('.bmad-core', folder, file));
+                installedFiles.push(path.join(`.${packId}`, folder, file));
               }
             }
           }
         }
 
-        // Web bundles are now available in the dist/ directory and don't need to be copied
+        // Copy config.yml
+        const configPath = path.join(expansionPackDir, 'config.yml');
+        if (await fileManager.pathExists(configPath)) {
+          const configDestPath = path.join(expansionDotFolder, 'config.yml');
+          if (await fileManager.copyFile(configPath, configDestPath)) {
+            installedFiles.push(path.join(`.${packId}`, 'config.yml'));
+          }
+        }
+        
+        // Copy README if it exists
+        const readmePath = path.join(expansionPackDir, 'README.md');
+        if (await fileManager.pathExists(readmePath)) {
+          const readmeDestPath = path.join(expansionDotFolder, 'README.md');
+          if (await fileManager.copyFile(readmePath, readmeDestPath)) {
+            installedFiles.push(path.join(`.${packId}`, 'README.md'));
+          }
+        }
+
+        // Copy common/ items to expansion pack folder
+        spinner.text = `Copying common utilities to ${packId}...`;
+        await this.copyCommonItems(installDir, `.${packId}`, spinner);
+        
+        // Check and resolve core dependencies
+        await this.resolveExpansionPackCoreDependencies(installDir, expansionDotFolder, packId, spinner);
+        
+        // Check and resolve core agents referenced by teams
+        await this.resolveExpansionPackCoreAgents(installDir, expansionDotFolder, packId, spinner);
 
-        console.log(chalk.green(`✓ Installed expansion pack: ${pack.name}`));
+        console.log(chalk.green(`✓ Installed expansion pack: ${pack.name} to ${`.${packId}`}`));
       } catch (error) {
         console.error(chalk.red(`Failed to install expansion pack ${packId}: ${error.message}`));
       }
@@ -847,6 +897,168 @@ class Installer {
     return installedFiles;
   }
 
+  async resolveExpansionPackCoreDependencies(installDir, expansionDotFolder, packId, spinner) {
+    const glob = require('glob');
+    const yaml = require('yaml');
+    const fs = require('fs').promises;
+    
+    // Find all agent files in the expansion pack
+    const agentFiles = glob.sync('agents/*.md', {
+      cwd: expansionDotFolder
+    });
+
+    for (const agentFile of agentFiles) {
+      const agentPath = path.join(expansionDotFolder, agentFile);
+      const agentContent = await fs.readFile(agentPath, 'utf8');
+      
+      // Extract YAML frontmatter to check dependencies
+      const yamlMatch = agentContent.match(/```yaml\n([\s\S]*?)```/);
+      if (yamlMatch) {
+        try {
+          const agentConfig = yaml.parse(yamlMatch[1]);
+          const dependencies = agentConfig.dependencies || {};
+          
+          // Check for core dependencies (those that don't exist in the expansion pack)
+          for (const depType of ['tasks', 'templates', 'checklists', 'workflows', 'utils', 'data']) {
+            const deps = dependencies[depType] || [];
+            
+            for (const dep of deps) {
+              const depFileName = dep.endsWith('.md') ? dep : `${dep}.md`;
+              const expansionDepPath = path.join(expansionDotFolder, depType, depFileName);
+              
+              // Check if dependency exists in expansion pack
+              if (!(await fileManager.pathExists(expansionDepPath))) {
+                // Try to find it in core
+                const coreDepPath = path.join(configLoader.getBmadCorePath(), depType, depFileName);
+                
+                if (await fileManager.pathExists(coreDepPath)) {
+                  spinner.text = `Copying core dependency ${dep} for ${packId}...`;
+                  
+                  // Copy from core to expansion pack dot folder
+                  const destPath = path.join(expansionDotFolder, depType, depFileName);
+                  await fileManager.copyFile(coreDepPath, destPath);
+                  
+                  console.log(chalk.dim(`  Added core dependency: ${depType}/${depFileName}`));
+                } else {
+                  console.warn(chalk.yellow(`  Warning: Dependency ${depType}/${dep} not found in core or expansion pack`));
+                }
+              }
+            }
+          }
+        } catch (error) {
+          console.warn(chalk.yellow(`  Warning: Could not parse agent dependencies: ${error.message}`));
+        }
+      }
+    }
+  }
+
+  async resolveExpansionPackCoreAgents(installDir, expansionDotFolder, packId, spinner) {
+    const glob = require('glob');
+    const yaml = require('yaml');
+    const fs = require('fs').promises;
+    
+    // Find all team files in the expansion pack
+    const teamFiles = glob.sync('agent-teams/*.yml', {
+      cwd: expansionDotFolder
+    });
+
+    // Also get existing agents in the expansion pack
+    const existingAgents = new Set();
+    const agentFiles = glob.sync('agents/*.md', {
+      cwd: expansionDotFolder
+    });
+    for (const agentFile of agentFiles) {
+      const agentName = path.basename(agentFile, '.md');
+      existingAgents.add(agentName);
+    }
+
+    // Process each team file
+    for (const teamFile of teamFiles) {
+      const teamPath = path.join(expansionDotFolder, teamFile);
+      const teamContent = await fs.readFile(teamPath, 'utf8');
+      
+      try {
+        const teamConfig = yaml.parse(teamContent);
+        const agents = teamConfig.agents || [];
+        
+        // Add bmad-orchestrator if not present (required for all teams)
+        if (!agents.includes('bmad-orchestrator')) {
+          agents.unshift('bmad-orchestrator');
+        }
+        
+        // Check each agent in the team
+        for (const agentId of agents) {
+          if (!existingAgents.has(agentId)) {
+            // Agent not in expansion pack, try to get from core
+            const coreAgentPath = path.join(configLoader.getBmadCorePath(), 'agents', `${agentId}.md`);
+            
+            if (await fileManager.pathExists(coreAgentPath)) {
+              spinner.text = `Copying core agent ${agentId} for ${packId}...`;
+              
+              // Copy agent file
+              const destPath = path.join(expansionDotFolder, 'agents', `${agentId}.md`);
+              await fileManager.copyFile(coreAgentPath, destPath);
+              existingAgents.add(agentId);
+              
+              console.log(chalk.dim(`  Added core agent: ${agentId}`));
+              
+              // Now resolve this agent's dependencies too
+              const agentContent = await fs.readFile(coreAgentPath, 'utf8');
+              const yamlMatch = agentContent.match(/```ya?ml\n([\s\S]*?)```/);
+              
+              if (yamlMatch) {
+                try {
+                  // Clean up the YAML to handle command descriptions
+                  let yamlContent = yamlMatch[1];
+                  yamlContent = yamlContent.replace(/^(\s*-)(\s*"[^"]+")(\s*-\s*.*)$/gm, '$1$2');
+                  
+                  const agentConfig = yaml.parse(yamlContent);
+                  const dependencies = agentConfig.dependencies || {};
+                  
+                  // Copy all dependencies for this agent
+                  for (const depType of ['tasks', 'templates', 'checklists', 'workflows', 'utils', 'data']) {
+                    const deps = dependencies[depType] || [];
+                    
+                    for (const dep of deps) {
+                      const depFileName = dep.endsWith('.md') || dep.endsWith('.yml') ? dep : `${dep}.md`;
+                      const expansionDepPath = path.join(expansionDotFolder, depType, depFileName);
+                      
+                      // Check if dependency exists in expansion pack
+                      if (!(await fileManager.pathExists(expansionDepPath))) {
+                        // Try to find it in core
+                        const coreDepPath = path.join(configLoader.getBmadCorePath(), depType, depFileName);
+                        
+                        if (await fileManager.pathExists(coreDepPath)) {
+                          const destDepPath = path.join(expansionDotFolder, depType, depFileName);
+                          await fileManager.copyFile(coreDepPath, destDepPath);
+                          console.log(chalk.dim(`    Added agent dependency: ${depType}/${depFileName}`));
+                        } else {
+                          // Try common folder
+                          const commonDepPath = path.join(this.rootDir, 'common', depType, depFileName);
+                          if (await fileManager.pathExists(commonDepPath)) {
+                            const destDepPath = path.join(expansionDotFolder, depType, depFileName);
+                            await fileManager.copyFile(commonDepPath, destDepPath);
+                            console.log(chalk.dim(`    Added agent dependency from common: ${depType}/${depFileName}`));
+                          }
+                        }
+                      }
+                    }
+                  }
+                } catch (error) {
+                  console.warn(chalk.yellow(`  Warning: Could not parse agent ${agentId} dependencies: ${error.message}`));
+                }
+              }
+            } else {
+              console.warn(chalk.yellow(`  Warning: Core agent ${agentId} not found for team ${path.basename(teamFile, '.yml')}`));
+            }
+          }
+        }
+      } catch (error) {
+        console.warn(chalk.yellow(`  Warning: Could not parse team file ${teamFile}: ${error.message}`));
+      }
+    }
+  }
+
   getWebBundleInfo(config) {
     const webBundleType = config.webBundleType || 'all';
     
@@ -944,6 +1156,48 @@ class Installer {
     }
   }
 
+  async copyCommonItems(installDir, targetSubdir, spinner) {
+    const glob = require('glob');
+    const fs = require('fs').promises;
+    const sourceBase = path.dirname(path.dirname(path.dirname(path.dirname(__filename)))); // Go up to project root
+    const commonPath = path.join(sourceBase, 'common');
+    const targetPath = path.join(installDir, targetSubdir);
+    const copiedFiles = [];
+    
+    // Check if common/ exists
+    if (!(await fileManager.pathExists(commonPath))) {
+      console.warn(chalk.yellow('Warning: common/ folder not found'));
+      return copiedFiles;
+    }
+    
+    // Copy all items from common/ to target
+    const commonItems = glob.sync('**/*', {
+      cwd: commonPath,
+      nodir: true
+    });
+    
+    for (const item of commonItems) {
+      const sourcePath = path.join(commonPath, item);
+      const destPath = path.join(targetPath, item);
+      
+      // Read the file content
+      const content = await fs.readFile(sourcePath, 'utf8');
+      
+      // Replace {root} with the target subdirectory
+      const updatedContent = content.replace(/\{root\}/g, targetSubdir);
+      
+      // Ensure directory exists
+      await fileManager.ensureDirectory(path.dirname(destPath));
+      
+      // Write the updated content
+      await fs.writeFile(destPath, updatedContent, 'utf8');
+      copiedFiles.push(path.join(targetSubdir, item));
+    }
+    
+    console.log(chalk.dim(`  Added ${commonItems.length} common utilities`));
+    return copiedFiles;
+  }
+
   async findInstallation() {
     // Look for .bmad-core in current directory or parent directories
     let currentDir = process.cwd();

package/tools/installer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmad-method",
-  "version": "4.17.0",
+  "version": "4.19.0",
   "description": "BMAD Method installer - AI-powered Agile development framework",
   "main": "lib/installer.js",
   "bin": {

package/tools/lib/dependency-resolver.js

@@ -6,6 +6,7 @@ class DependencyResolver {
   constructor(rootDir) {
     this.rootDir = rootDir;
     this.bmadCore = path.join(rootDir, 'bmad-core');
+    this.common = path.join(rootDir, 'common');
     this.cache = new Map();
   }
 
@@ -123,6 +124,7 @@ class DependencyResolver {
       let content = null;
       let filePath = null;
 
+      // First try bmad-core
       for (const ext of extensions) {
         try {
           filePath = path.join(this.bmadCore, type, `${id}${ext}`);
@@ -132,6 +134,19 @@ class DependencyResolver {
           // Try next extension
         }
       }
+      
+      // If not found in bmad-core, try common folder
+      if (!content) {
+        for (const ext of extensions) {
+          try {
+            filePath = path.join(this.common, type, `${id}${ext}`);
+            content = await fs.readFile(filePath, 'utf8');
+            break;
+          } catch (e) {
+            // Try next extension
+          }
+        }
+      }
 
       if (!content) {
         console.warn(`Resource not found: ${type}/${id}`);

package/bmad-core/tasks/core-dump.md

@@ -1,74 +0,0 @@
-# Core Dump Task
-
-## Purpose
-
-To create a concise memory recording file (`.ai/core-dump-n.md`) that captures the essential context of the current agent session, enabling seamless continuation of work in future agent sessions. This task ensures persistent context across agent conversations while maintaining minimal token usage for efficient context loading.
-
-## Inputs for this Task
-
-- Current session conversation history and accomplishments
-- Files created, modified, or deleted during the session
-- Key decisions made and procedures followed
-- Current project state and next logical steps
-- User requests and agent responses that shaped the session
-
-## Task Execution Instructions
-
-### 0. Check Existing Core Dump
-
-Before proceeding, check if `.ai/core-dump.md` already exists:
-
-- If file exists, ask user: "Core dump file exists. Should I: 1. Overwrite, 2. Update, 3. Append or 4. Create new?"
-- **Overwrite**: Replace entire file with new content
-- **Update**: Merge new session info with existing content, updating relevant sections
-- **Append**: Add new session as a separate entry while preserving existing content
-- **Create New**: Create a new file, appending the next possible -# to the file, such as core-dump-3.md if 1 and 2 already exist.
-- If file doesn't exist, proceed with creation of `core-dump-1.md`
-
-### 1. Analyze Session Context
-
-- Review the entire conversation to identify key accomplishments
-- Note any specific tasks, procedures, or workflows that were executed
-- Identify important decisions made or problems solved
-- Capture the user's working style and preferences observed during the session
-
-### 2. Document What Was Accomplished
-
-- **Primary Actions**: List the main tasks completed concisely
-- **Story Progress**: For story work, use format "Tasks Complete: 1-6, 8. Next Task Pending: 7, 9"
-- **Problem Solving**: Document any challenges encountered and how they were resolved
-- **User Communications**: Summarize key user requests, preferences, and discussion points
-
-### 3. Record File System Changes (Concise Format)
-
-- **Files Created**: `filename.ext` (brief purpose/size)
-- **Files Modified**: `filename.ext` (what changed)
-- **Files Deleted**: `filename.ext` (why removed)
-- Focus on essential details, avoid verbose descriptions
-
-### 4. Capture Current Project State
-
-- **Project Progress**: Where the project stands after this session
-- **Current Issues**: Any blockers or problems that need resolution
-- **Next Logical Steps**: What would be the natural next actions to take
-
-### 5. Create/Update Core Dump File
-
-Based on user's choice from step 0, handle the file accordingly:
-
-### 6. Optimize for Minimal Context
-
-- Keep descriptions concise but informative
-- Use abbreviated formats where possible (file sizes, task numbers)
-- Focus on actionable information rather than detailed explanations
-- Avoid redundant information that can be found in project documentation
-- Prioritize information that would be lost without this recording
-- Ensure the file can be quickly scanned and understood
-
-### 7. Validate Completeness
-
-- Verify all significant session activities are captured
-- Ensure a future agent could understand the current state
-- Check that file changes are accurately recorded
-- Confirm next steps are clear and actionable
-- Verify user communication style and preferences are noted

package/bmad-core/tasks/execute-checklist.md

@@ -1,97 +0,0 @@
-# Checklist Validation Task
-
-This task provides instructions for validating documentation against checklists. The agent MUST follow these instructions to ensure thorough and systematic validation of documents.
-
-## Context
-
-The BMAD Method uses various checklists to ensure quality and completeness of different artifacts. Each checklist contains embedded prompts and instructions to guide the LLM through thorough validation and advanced elicitation. The checklists automatically identify their required artifacts and guide the validation process.
-
-## Available Checklists
-
-If the user asks or does not specify a specific checklist, list the checklists available to the agent persona. If the task is being run not with a specific agent, tell the user to check the bmad-core/checklists folder to select the appropriate one to run.
-
-## Instructions
-
-1. **Initial Assessment**
-
-   - If user or the task being run provides a checklist name:
-     - Try fuzzy matching (e.g. "architecture checklist" -> "architect-checklist")
-     - If multiple matches found, ask user to clarify
-     - Load the appropriate checklist from bmad-core/checklists/
-   - If no checklist specified:
-     - Ask the user which checklist they want to use
-     - Present the available options from the files in the checklists folder
-   - Confirm if they want to work through the checklist:
-     - Section by section (interactive mode - very time consuming)
-     - All at once (YOLO mode - recommended for checklists, there will be a summary of sections at the end to discuss)
-
-2. **Document and Artifact Gathering**
-
-   - Each checklist will specify its required documents/artifacts at the beginning
-   - Follow the checklist's specific instructions for what to gather, generally a file can be resolved in the docs folder, if not or unsure, halt and ask or confirm with the user.
-
-3. **Checklist Processing**
-
-   If in interactive mode:
-
-   - Work through each section of the checklist one at a time
-   - For each section:
-     - Review all items in the section following instructions for that section embedded in the checklist
-     - Check each item against the relevant documentation or artifacts as appropriate
-     - Present summary of findings for that section, highlighting warnings, errors and non applicable items (rationale for non-applicability).
-     - Get user confirmation before proceeding to next section or if any thing major do we need to halt and take corrective action
-
-   If in YOLO mode:
-
-   - Process all sections at once
-   - Create a comprehensive report of all findings
-   - Present the complete analysis to the user
-
-4. **Validation Approach**
-
-   For each checklist item:
-
-   - Read and understand the requirement
-   - Look for evidence in the documentation that satisfies the requirement
-   - Consider both explicit mentions and implicit coverage
-   - Aside from this, follow all checklist llm instructions
-   - Mark items as:
-     - ✅ PASS: Requirement clearly met
-     - ❌ FAIL: Requirement not met or insufficient coverage
-     - ⚠️ PARTIAL: Some aspects covered but needs improvement
-     - N/A: Not applicable to this case
-
-5. **Section Analysis**
-
-   For each section:
-
-   - think step by step to calculate pass rate
-   - Identify common themes in failed items
-   - Provide specific recommendations for improvement
-   - In interactive mode, discuss findings with user
-   - Document any user decisions or explanations
-
-6. **Final Report**
-
-   Prepare a summary that includes:
-
-   - Overall checklist completion status
-   - Pass rates by section
-   - List of failed items with context
-   - Specific recommendations for improvement
-   - Any sections or items marked as N/A with justification
-
-## Checklist Execution Methodology
-
-Each checklist now contains embedded LLM prompts and instructions that will:
-
-1. **Guide thorough thinking** - Prompts ensure deep analysis of each section
-2. **Request specific artifacts** - Clear instructions on what documents/access is needed
-3. **Provide contextual guidance** - Section-specific prompts for better validation
-4. **Generate comprehensive reports** - Final summary with detailed findings
-
-The LLM will:
-
-- Execute the complete checklist validation
-- Present a final report with pass/fail rates and key findings
-- Offer to provide detailed analysis of any section, especially those with warnings or failures

package/bmad-core/utils/file-resolution-context.md

@@ -1,10 +0,0 @@
-# File Resolution Context
-
-Update the installer/upgrader so that when agents are added to a project (under Add these two lines to any agent's `activation-instructions` for ide installation:
-
-```yaml
-- IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}.md 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.
-```
-
-and add `root: .bmad-core` as the first root yml property.