bmad-method 6.0.0-alpha.0 → 6.0.0-alpha.10

package/tools/cli/installers/lib/modules/manager.js

@@ -26,6 +26,70 @@ class ModuleManager {
     // Path to source modules directory
     this.modulesSourcePath = getSourcePath('modules');
     this.xmlHandler = new XmlHandler();
+    this.bmadFolderName = 'bmad'; // Default, can be overridden
+  }
+
+  /**
+   * Set the bmad folder name for placeholder replacement
+   * @param {string} bmadFolderName - The bmad folder name
+   */
+  setBmadFolderName(bmadFolderName) {
+    this.bmadFolderName = bmadFolderName;
+  }
+
+  /**
+   * Copy a file and replace {bmad_folder} placeholder with actual folder name
+   * @param {string} sourcePath - Source file path
+   * @param {string} targetPath - Target file path
+   */
+  async copyFileWithPlaceholderReplacement(sourcePath, targetPath) {
+    // List of text file extensions that should have placeholder replacement
+    const textExtensions = ['.md', '.yaml', '.yml', '.txt', '.json', '.js', '.ts', '.html', '.css', '.sh', '.bat', '.csv'];
+    const ext = path.extname(sourcePath).toLowerCase();
+
+    // Check if this is a text file that might contain placeholders
+    if (textExtensions.includes(ext)) {
+      try {
+        // Read the file content
+        let content = await fs.readFile(sourcePath, 'utf8');
+
+        // Replace {bmad_folder} placeholder with actual folder name
+        if (content.includes('{bmad_folder}')) {
+          content = content.replaceAll('{bmad_folder}', this.bmadFolderName);
+        }
+
+        // Write to target with replaced content
+        await fs.ensureDir(path.dirname(targetPath));
+        await fs.writeFile(targetPath, content, 'utf8');
+      } catch {
+        // If reading as text fails (might be binary despite extension), fall back to regular copy
+        await fs.copy(sourcePath, targetPath, { overwrite: true });
+      }
+    } else {
+      // Binary file or other file type - just copy directly
+      await fs.copy(sourcePath, targetPath, { overwrite: true });
+    }
+  }
+
+  /**
+   * Copy a directory recursively with placeholder replacement
+   * @param {string} sourceDir - Source directory path
+   * @param {string} targetDir - Target directory path
+   */
+  async copyDirectoryWithPlaceholderReplacement(sourceDir, targetDir) {
+    await fs.ensureDir(targetDir);
+    const entries = await fs.readdir(sourceDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const sourcePath = path.join(sourceDir, entry.name);
+      const targetPath = path.join(targetDir, entry.name);
+
+      if (entry.isDirectory()) {
+        await this.copyDirectoryWithPlaceholderReplacement(sourcePath, targetPath);
+      } else {
+        await this.copyFileWithPlaceholderReplacement(sourcePath, targetPath);
+      }
+    }
   }
 
   /**
@@ -46,7 +110,7 @@ class ModuleManager {
       if (entry.isDirectory()) {
         const modulePath = path.join(this.modulesSourcePath, entry.name);
         // Check for new structure first
-        const installerConfigPath = path.join(modulePath, '_module-installer', 'install-menu-config.yaml');
+        const installerConfigPath = path.join(modulePath, '_module-installer', 'install-config.yaml');
         // Fallback to old structure
         const configPath = path.join(modulePath, 'config.yaml');
 
@@ -112,8 +176,12 @@ class ModuleManager {
       await fs.remove(targetPath);
     }
 
+    // Vendor cross-module workflows BEFORE copying
+    // This reads source agent.yaml files and copies referenced workflows
+    await this.vendorCrossModuleWorkflows(sourcePath, targetPath, moduleName);
+
     // Copy module files with filtering
-    await this.copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback);
+    await this.copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback, options.moduleConfig);
 
     // Process agent files to inject activation block
     await this.processAgentFiles(targetPath, moduleName);
@@ -231,14 +299,26 @@ class ModuleManager {
   }
 
   /**
-   * Copy module with filtering for localskip agents
+   * Copy module with filtering for localskip agents and conditional content
    * @param {string} sourcePath - Source module path
    * @param {string} targetPath - Target module path
+   * @param {Function} fileTrackingCallback - Optional callback to track installed files
+   * @param {Object} moduleConfig - Module configuration with conditional flags
    */
-  async copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback = null) {
+  async copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback = null, moduleConfig = {}) {
     // Get all files in source
     const sourceFiles = await this.getFileList(sourcePath);
 
+    // Game development files to conditionally exclude
+    const gameDevFiles = [
+      'agents/game-architect.agent.yaml',
+      'agents/game-designer.agent.yaml',
+      'agents/game-dev.agent.yaml',
+      'workflows/1-analysis/brainstorm-game',
+      'workflows/1-analysis/game-brief',
+      'workflows/2-plan-workflows/gdd',
+    ];
+
     for (const file of sourceFiles) {
       // Skip sub-modules directory - these are IDE-specific and handled separately
       if (file.startsWith('sub-modules/')) {
@@ -255,6 +335,25 @@ class ModuleManager {
         continue;
       }
 
+      // Skip user documentation if install_user_docs is false
+      if (moduleConfig.install_user_docs === false && (file.startsWith('docs/') || file.startsWith('docs\\'))) {
+        console.log(chalk.dim(`  Skipping user documentation: ${file}`));
+        continue;
+      }
+
+      // Skip game development content if include_game_planning is false
+      if (moduleConfig.include_game_planning === false) {
+        const shouldSkipGameDev = gameDevFiles.some((gamePath) => {
+          // Check if file path starts with or is within any game dev directory
+          return file === gamePath || file.startsWith(gamePath + '/') || file.startsWith(gamePath + '\\');
+        });
+
+        if (shouldSkipGameDev) {
+          console.log(chalk.dim(`  Skipping game dev content: ${file}`));
+          continue;
+        }
+      }
+
       const sourceFile = path.join(sourcePath, file);
       const targetFile = path.join(targetPath, file);
 
@@ -271,9 +370,14 @@ class ModuleManager {
         }
       }
 
-      // Copy the file
-      await fs.ensureDir(path.dirname(targetFile));
-      await fs.copy(sourceFile, targetFile, { overwrite: true });
+      // Check if this is a workflow.yaml file
+      if (file.endsWith('workflow.yaml')) {
+        await fs.ensureDir(path.dirname(targetFile));
+        await this.copyWorkflowYamlStripped(sourceFile, targetFile);
+      } else {
+        // Copy the file with placeholder replacement
+        await this.copyFileWithPlaceholderReplacement(sourceFile, targetFile);
+      }
 
       // Track the file if callback provided
       if (fileTrackingCallback) {
@@ -282,6 +386,96 @@ class ModuleManager {
     }
   }
 
+  /**
+   * Copy workflow.yaml file with web_bundle section stripped
+   * Preserves comments, formatting, and line breaks
+   * @param {string} sourceFile - Source workflow.yaml file path
+   * @param {string} targetFile - Target workflow.yaml file path
+   */
+  async copyWorkflowYamlStripped(sourceFile, targetFile) {
+    // Read the source YAML file
+    let yamlContent = await fs.readFile(sourceFile, 'utf8');
+
+    // IMPORTANT: Replace {bmad_folder} BEFORE parsing YAML
+    // Otherwise parsing will fail on the placeholder
+    yamlContent = yamlContent.replaceAll('{bmad_folder}', this.bmadFolderName);
+
+    try {
+      // First check if web_bundle exists by parsing
+      const workflowConfig = yaml.load(yamlContent);
+
+      if (workflowConfig.web_bundle === undefined) {
+        // No web_bundle section, just write (placeholders already replaced above)
+        await fs.writeFile(targetFile, yamlContent, 'utf8');
+        return;
+      }
+
+      // Remove web_bundle section using regex to preserve formatting
+      // Match the web_bundle key and all its content (including nested items)
+      // This handles both web_bundle: false and web_bundle: {...}
+
+      // Find the line that starts web_bundle
+      const lines = yamlContent.split('\n');
+      let startIdx = -1;
+      let endIdx = -1;
+      let baseIndent = 0;
+
+      // Find the start of web_bundle section
+      for (const [i, line] of lines.entries()) {
+        const match = line.match(/^(\s*)web_bundle:/);
+        if (match) {
+          startIdx = i;
+          baseIndent = match[1].length;
+          break;
+        }
+      }
+
+      if (startIdx === -1) {
+        // web_bundle not found in text (shouldn't happen), copy as-is
+        await fs.writeFile(targetFile, yamlContent, 'utf8');
+        return;
+      }
+
+      // Find the end of web_bundle section
+      // It ends when we find a line with same or less indentation that's not empty/comment
+      endIdx = startIdx;
+      for (let i = startIdx + 1; i < lines.length; i++) {
+        const line = lines[i];
+
+        // Skip empty lines and comments
+        if (line.trim() === '' || line.trim().startsWith('#')) {
+          continue;
+        }
+
+        // Check indentation
+        const indent = line.match(/^(\s*)/)[1].length;
+        if (indent <= baseIndent) {
+          // Found next section at same or lower indentation
+          endIdx = i - 1;
+          break;
+        }
+      }
+
+      // If we didn't find an end, it goes to end of file
+      if (endIdx === startIdx) {
+        endIdx = lines.length - 1;
+      }
+
+      // Remove the web_bundle section (including the line before if it's just a blank line)
+      const newLines = [...lines.slice(0, startIdx), ...lines.slice(endIdx + 1)];
+
+      // Clean up any double blank lines that might result
+      const strippedYaml = newLines.join('\n').replaceAll(/\n\n\n+/g, '\n\n');
+
+      // Placeholders already replaced at the beginning of this function
+      await fs.writeFile(targetFile, strippedYaml, 'utf8');
+    } catch {
+      // If anything fails, just copy the file as-is
+      console.warn(chalk.yellow(`  Warning: Could not process ${path.basename(sourceFile)}, copying as-is`));
+      await fs.copy(sourceFile, targetFile, { overwrite: true });
+    }
+  }
+
   /**
    * Process agent files to inject activation block
    * @param {string} modulePath - Path to installed module
@@ -313,6 +507,135 @@ class ModuleManager {
     }
   }
 
+  /**
+   * Vendor cross-module workflows referenced in agent files
+   * Scans SOURCE agent.yaml files for workflow-install and copies workflows to destination
+   * @param {string} sourcePath - Source module path
+   * @param {string} targetPath - Target module path (destination)
+   * @param {string} moduleName - Module name being installed
+   */
+  async vendorCrossModuleWorkflows(sourcePath, targetPath, moduleName) {
+    const sourceAgentsPath = path.join(sourcePath, 'agents');
+
+    // Check if source agents directory exists
+    if (!(await fs.pathExists(sourceAgentsPath))) {
+      return; // No agents to process
+    }
+
+    // Get all agent YAML files from source
+    const agentFiles = await fs.readdir(sourceAgentsPath);
+    const yamlFiles = agentFiles.filter((f) => f.endsWith('.agent.yaml') || f.endsWith('.yaml'));
+
+    if (yamlFiles.length === 0) {
+      return; // No YAML agent files
+    }
+
+    let workflowsVendored = false;
+
+    for (const agentFile of yamlFiles) {
+      const agentPath = path.join(sourceAgentsPath, agentFile);
+      const agentYaml = yaml.load(await fs.readFile(agentPath, 'utf8'));
+
+      // Check if agent has menu items with workflow-install
+      const menuItems = agentYaml?.agent?.menu || [];
+      const workflowInstallItems = menuItems.filter((item) => item['workflow-install']);
+
+      if (workflowInstallItems.length === 0) {
+        continue; // No workflow-install in this agent
+      }
+
+      if (!workflowsVendored) {
+        console.log(chalk.cyan(`\n  Vendoring cross-module workflows for ${moduleName}...`));
+        workflowsVendored = true;
+      }
+
+      console.log(chalk.dim(`    Processing: ${agentFile}`));
+
+      for (const item of workflowInstallItems) {
+        const sourceWorkflowPath = item.workflow; // Where to copy FROM
+        const installWorkflowPath = item['workflow-install']; // Where to copy TO
+
+        // Parse SOURCE workflow path
+        // Handle both {bmad_folder} placeholder and hardcoded 'bmad'
+        // Example: {project-root}/{bmad_folder}/bmm/workflows/4-implementation/create-story/workflow.yaml
+        // Or: {project-root}/bmad/bmm/workflows/4-implementation/create-story/workflow.yaml
+        const sourceMatch = sourceWorkflowPath.match(/\{project-root\}\/(?:\{bmad_folder\}|bmad)\/([^/]+)\/workflows\/(.+)/);
+        if (!sourceMatch) {
+          console.warn(chalk.yellow(`      Could not parse workflow path: ${sourceWorkflowPath}`));
+          continue;
+        }
+
+        const [, sourceModule, sourceWorkflowSubPath] = sourceMatch;
+
+        // Parse INSTALL workflow path
+        // Handle both {bmad_folder} placeholder and hardcoded 'bmad'
+        // Example: {project-root}/{bmad_folder}/bmgd/workflows/4-production/create-story/workflow.yaml
+        const installMatch = installWorkflowPath.match(/\{project-root\}\/(?:\{bmad_folder\}|bmad)\/([^/]+)\/workflows\/(.+)/);
+        if (!installMatch) {
+          console.warn(chalk.yellow(`      Could not parse workflow-install path: ${installWorkflowPath}`));
+          continue;
+        }
+
+        const installWorkflowSubPath = installMatch[2];
+
+        // Determine actual filesystem paths
+        const sourceModulePath = path.join(this.modulesSourcePath, sourceModule);
+        const actualSourceWorkflowPath = path.join(sourceModulePath, 'workflows', sourceWorkflowSubPath.replace(/\/workflow\.yaml$/, ''));
+
+        const actualDestWorkflowPath = path.join(targetPath, 'workflows', installWorkflowSubPath.replace(/\/workflow\.yaml$/, ''));
+
+        // Check if source workflow exists
+        if (!(await fs.pathExists(actualSourceWorkflowPath))) {
+          console.warn(chalk.yellow(`      Source workflow not found: ${actualSourceWorkflowPath}`));
+          continue;
+        }
+
+        // Copy the entire workflow folder
+        console.log(
+          chalk.dim(
+            `      Vendoring: ${sourceModule}/workflows/${sourceWorkflowSubPath.replace(/\/workflow\.yaml$/, '')} → ${moduleName}/workflows/${installWorkflowSubPath.replace(/\/workflow\.yaml$/, '')}`,
+          ),
+        );
+
+        await fs.ensureDir(path.dirname(actualDestWorkflowPath));
+        // Copy the workflow directory recursively with placeholder replacement
+        await this.copyDirectoryWithPlaceholderReplacement(actualSourceWorkflowPath, actualDestWorkflowPath);
+
+        // Update the workflow.yaml config_source reference
+        const workflowYamlPath = path.join(actualDestWorkflowPath, 'workflow.yaml');
+        if (await fs.pathExists(workflowYamlPath)) {
+          await this.updateWorkflowConfigSource(workflowYamlPath, moduleName);
+        }
+      }
+    }
+
+    if (workflowsVendored) {
+      console.log(chalk.green(`  ✓ Workflow vendoring complete\n`));
+    }
+  }
+
+  /**
+   * Update workflow.yaml config_source to point to new module
+   * @param {string} workflowYamlPath - Path to workflow.yaml file
+   * @param {string} newModuleName - New module name to reference
+   */
+  async updateWorkflowConfigSource(workflowYamlPath, newModuleName) {
+    let yamlContent = await fs.readFile(workflowYamlPath, 'utf8');
+
+    // Replace config_source: "{project-root}/{bmad_folder}/OLD_MODULE/config.yaml"
+    // with config_source: "{project-root}/{bmad_folder}/NEW_MODULE/config.yaml"
+    // Note: At this point {bmad_folder} has already been replaced with actual folder name
+    const configSourcePattern = /config_source:\s*["']?\{project-root\}\/[^/]+\/[^/]+\/config\.yaml["']?/g;
+    const newConfigSource = `config_source: "{project-root}/${this.bmadFolderName}/${newModuleName}/config.yaml"`;
+
+    const updatedYaml = yamlContent.replaceAll(configSourcePattern, newConfigSource);
+
+    if (updatedYaml !== yamlContent) {
+      await fs.writeFile(workflowYamlPath, updatedYaml, 'utf8');
+      console.log(chalk.dim(`      Updated config_source to: ${this.bmadFolderName}/${newModuleName}/config.yaml`));
+    }
+  }
+
   /**
    * Run module-specific installer if it exists
    * @param {string} moduleName - Name of the module
@@ -414,9 +737,8 @@ class ModuleManager {
         }
       }
 
-      // Copy file
-      await fs.ensureDir(path.dirname(targetFile));
-      await fs.copy(sourceFile, targetFile, { overwrite: true });
+      // Copy file with placeholder replacement
+      await this.copyFileWithPlaceholderReplacement(sourceFile, targetFile);
     }
   }
 

package/tools/cli/lib/activation-builder.js

@@ -0,0 +1,168 @@
+const fs = require('fs-extra');
+const path = require('node:path');
+const { getSourcePath } = require('./project-root');
+
+/**
+ * Builds activation blocks from fragments based on agent profile
+ */
+class ActivationBuilder {
+  constructor() {
+    this.fragmentsDir = getSourcePath('utility', 'models', 'fragments');
+    this.fragmentCache = new Map();
+  }
+
+  /**
+   * Load a fragment file
+   * @param {string} fragmentName - Name of fragment file (e.g., 'activation-init.xml')
+   * @returns {string} Fragment content
+   */
+  async loadFragment(fragmentName) {
+    // Check cache first
+    if (this.fragmentCache.has(fragmentName)) {
+      return this.fragmentCache.get(fragmentName);
+    }
+
+    const fragmentPath = path.join(this.fragmentsDir, fragmentName);
+
+    if (!(await fs.pathExists(fragmentPath))) {
+      throw new Error(`Fragment not found: ${fragmentName}`);
+    }
+
+    const content = await fs.readFile(fragmentPath, 'utf8');
+    this.fragmentCache.set(fragmentName, content);
+    return content;
+  }
+
+  /**
+   * Build complete activation block based on agent profile
+   * @param {Object} profile - Agent profile from AgentAnalyzer
+   * @param {Object} metadata - Agent metadata (module, name, etc.)
+   * @param {Array} agentSpecificActions - Optional agent-specific critical actions
+   * @param {boolean} forWebBundle - Whether this is for a web bundle
+   * @returns {string} Complete activation block XML
+   */
+  async buildActivation(profile, metadata = {}, agentSpecificActions = [], forWebBundle = false) {
+    let activation = '<activation critical="MANDATORY">\n';
+
+    // 1. Build sequential steps (use web-specific steps for web bundles)
+    const steps = await this.buildSteps(metadata, agentSpecificActions, forWebBundle);
+    activation += this.indent(steps, 2) + '\n';
+
+    // 2. Build menu handlers section with dynamic handlers
+    const menuHandlers = await this.loadFragment('menu-handlers.xml');
+
+    // Build handlers (load only needed handlers)
+    const handlers = await this.buildHandlers(profile);
+
+    // Remove the extract line from the final output - it's just build metadata
+    // The extract list tells us which attributes to look for during processing
+    // but shouldn't appear in the final agent file
+    const processedHandlers = menuHandlers
+      .replace('<extract>{DYNAMIC_EXTRACT_LIST}</extract>\n', '') // Remove the entire extract line
+      .replace('{DYNAMIC_HANDLERS}', handlers);
+
+    activation += '\n' + this.indent(processedHandlers, 2) + '\n';
+
+    // 3. Include rules (skip for web bundles as they're in web-bundle-activation-steps.xml)
+    if (!forWebBundle) {
+      const rules = await this.loadFragment('activation-rules.xml');
+      activation += this.indent(rules, 2) + '\n';
+    }
+
+    activation += '</activation>';
+
+    return activation;
+  }
+
+  /**
+   * Build handlers section based on profile
+   * @param {Object} profile - Agent profile
+   * @returns {string} Handlers XML
+   */
+  async buildHandlers(profile) {
+    const handlerFragments = [];
+
+    for (const attrType of profile.usedAttributes) {
+      const fragmentName = `handler-${attrType}.xml`;
+      try {
+        const handler = await this.loadFragment(fragmentName);
+        handlerFragments.push(handler);
+      } catch {
+        console.warn(`Warning: Handler fragment not found: ${fragmentName}`);
+      }
+    }
+
+    return handlerFragments.join('\n');
+  }
+
+  /**
+   * Build sequential activation steps
+   * @param {Object} metadata - Agent metadata
+   * @param {Array} agentSpecificActions - Optional agent-specific actions
+   * @param {boolean} forWebBundle - Whether this is for a web bundle
+   * @returns {string} Steps XML
+   */
+  async buildSteps(metadata = {}, agentSpecificActions = [], forWebBundle = false) {
+    // Use web-specific fragment for web bundles, standard fragment otherwise
+    const fragmentName = forWebBundle ? 'web-bundle-activation-steps.xml' : 'activation-steps.xml';
+    const stepsTemplate = await this.loadFragment(fragmentName);
+
+    // Extract basename from agent ID (e.g., "bmad/bmm/agents/pm.md" → "pm")
+    const agentBasename = metadata.id ? metadata.id.split('/').pop().replace('.md', '') : metadata.name || 'agent';
+
+    // Build agent-specific steps
+    let agentStepsXml = '';
+    let currentStepNum = 4; // Steps 1-3 are standard
+
+    if (agentSpecificActions && agentSpecificActions.length > 0) {
+      agentStepsXml = agentSpecificActions
+        .map((action) => {
+          const step = `<step n="${currentStepNum}">${action}</step>`;
+          currentStepNum++;
+          return step;
+        })
+        .join('\n');
+    }
+
+    // Calculate final step numbers
+    const menuStep = currentStepNum;
+    const haltStep = currentStepNum + 1;
+    const inputStep = currentStepNum + 2;
+    const executeStep = currentStepNum + 3;
+
+    // Replace placeholders
+    const processed = stepsTemplate
+      .replace('{agent-file-basename}', agentBasename)
+      .replace('{{module}}', metadata.module || 'core') // Fixed to use {{module}}
+      .replace('{AGENT_SPECIFIC_STEPS}', agentStepsXml)
+      .replace('{MENU_STEP}', menuStep.toString())
+      .replace('{HALT_STEP}', haltStep.toString())
+      .replace('{INPUT_STEP}', inputStep.toString())
+      .replace('{EXECUTE_STEP}', executeStep.toString());
+
+    return processed;
+  }
+
+  /**
+   * Indent XML content
+   * @param {string} content - Content to indent
+   * @param {number} spaces - Number of spaces to indent
+   * @returns {string} Indented content
+   */
+  indent(content, spaces) {
+    const indentation = ' '.repeat(spaces);
+    return content
+      .split('\n')
+      .map((line) => (line ? indentation + line : line))
+      .join('\n');
+  }
+
+  /**
+   * Clear fragment cache (useful for testing or hot reload)
+   */
+  clearCache() {
+    this.fragmentCache.clear();
+  }
+}
+
+module.exports = { ActivationBuilder };

package/tools/cli/lib/agent-analyzer.js

@@ -0,0 +1,81 @@
+const yaml = require('js-yaml');
+const fs = require('fs-extra');
+
+/**
+ * Analyzes agent YAML files to detect which handlers are needed
+ */
+class AgentAnalyzer {
+  /**
+   * Analyze an agent YAML structure to determine which handlers it needs
+   * @param {Object} agentYaml - Parsed agent YAML object
+   * @returns {Object} Profile of needed handlers
+   */
+  analyzeAgentObject(agentYaml) {
+    const profile = {
+      usedAttributes: new Set(),
+      hasPrompts: false,
+      menuItems: [],
+    };
+
+    // Check if agent has prompts section
+    if (agentYaml.agent && agentYaml.agent.prompts) {
+      profile.hasPrompts = true;
+    }
+
+    // Analyze menu items (support both 'menu' and legacy 'commands')
+    const menuItems = agentYaml.agent?.menu || agentYaml.agent?.commands || [];
+
+    for (const item of menuItems) {
+      // Track the menu item
+      profile.menuItems.push(item);
+
+      // Check for each possible attribute
+      if (item.workflow) {
+        profile.usedAttributes.add('workflow');
+      }
+      if (item['validate-workflow']) {
+        profile.usedAttributes.add('validate-workflow');
+      }
+      if (item.exec) {
+        profile.usedAttributes.add('exec');
+      }
+      if (item.tmpl) {
+        profile.usedAttributes.add('tmpl');
+      }
+      if (item.data) {
+        profile.usedAttributes.add('data');
+      }
+      if (item.action) {
+        profile.usedAttributes.add('action');
+      }
+    }
+
+    // Convert Set to Array for easier use
+    profile.usedAttributes = [...profile.usedAttributes];
+
+    return profile;
+  }
+
+  /**
+   * Analyze an agent YAML file
+   * @param {string} filePath - Path to agent YAML file
+   * @returns {Object} Profile of needed handlers
+   */
+  async analyzeAgentFile(filePath) {
+    const content = await fs.readFile(filePath, 'utf8');
+    const agentYaml = yaml.load(content);
+    return this.analyzeAgentObject(agentYaml);
+  }
+
+  /**
+   * Check if an agent needs a specific handler
+   * @param {Object} profile - Agent profile from analyze
+   * @param {string} handlerType - Handler type to check
+   * @returns {boolean} True if handler is needed
+   */
+  needsHandler(profile, handlerType) {
+    return profile.usedAttributes.includes(handlerType);
+  }
+}
+
+module.exports = { AgentAnalyzer };

package/tools/cli/lib/agent-party-generator.js

@@ -3,7 +3,7 @@ const fs = require('fs-extra');
 
 const AgentPartyGenerator = {
   /**
-   * Generate agent-party.xml content
+   * Generate agent-manifest.csv content
    * @param {Array} agentDetails - Array of agent details
    * @param {Object} options - Generation options
    * @returns {string} XML content
@@ -28,7 +28,7 @@ const AgentPartyGenerator = {
     let xmlContent = `<!-- Powered by BMAD-CORE™ -->
 <!-- Agent Manifest - Generated during BMAD ${forWeb ? 'bundling' : 'installation'} -->
 <!-- This file contains a summary of all ${forWeb ? 'bundled' : 'installed'} agents for quick reference -->
-<manifest id="bmad/_cfg/agent-party.xml" version="1.0" generated="${new Date().toISOString()}">
+<manifest id="bmad/_cfg/agent-manifest.csv" version="1.0" generated="${new Date().toISOString()}">
   <description>
     Complete roster of ${forWeb ? 'bundled' : 'installed'} BMAD agents with summarized personas for efficient multi-agent orchestration.
     Used by party-mode and other multi-agent coordination features.
@@ -193,7 +193,7 @@ const AgentPartyGenerator = {
   },
 
   /**
-   * Write agent-party.xml to file
+   * Write agent-manifest.csv to file
    */
   async writeAgentParty(filePath, agentDetails, options = {}) {
     const content = this.generateAgentParty(agentDetails, options);