bmad-method 6.0.0-alpha.8 → 6.0.1

package/tools/cli/installers/lib/custom/handler.js

@@ -0,0 +1,358 @@
+const path = require('node:path');
+const fs = require('fs-extra');
+const yaml = require('yaml');
+const prompts = require('../../../lib/prompts');
+const { FileOps } = require('../../../lib/file-ops');
+const { XmlHandler } = require('../../../lib/xml-handler');
+
+/**
+ * Handler for custom content (custom.yaml)
+ * Installs custom agents and workflows without requiring a full module structure
+ */
+class CustomHandler {
+  constructor() {
+    this.fileOps = new FileOps();
+    this.xmlHandler = new XmlHandler();
+  }
+
+  /**
+   * Find all custom.yaml files in the project
+   * @param {string} projectRoot - Project root directory
+   * @returns {Array} List of custom content paths
+   */
+  async findCustomContent(projectRoot) {
+    const customPaths = [];
+
+    // Helper function to recursively scan directories
+    async function scanDirectory(dir, excludePaths = []) {
+      try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+
+        for (const entry of entries) {
+          const fullPath = path.join(dir, entry.name);
+
+          // Skip hidden directories and common exclusions
+          if (
+            entry.name.startsWith('.') ||
+            entry.name === 'node_modules' ||
+            entry.name === 'dist' ||
+            entry.name === 'build' ||
+            entry.name === '.git' ||
+            entry.name === 'bmad'
+          ) {
+            continue;
+          }
+
+          // Skip excluded paths
+          if (excludePaths.some((exclude) => fullPath.startsWith(exclude))) {
+            continue;
+          }
+
+          if (entry.isDirectory()) {
+            // Recursively scan subdirectories
+            await scanDirectory(fullPath, excludePaths);
+          } else if (entry.name === 'custom.yaml') {
+            // Found a custom.yaml file
+            customPaths.push(fullPath);
+          } else if (
+            entry.name === 'module.yaml' && // Check if this is a custom module (in root directory)
+            // Skip if it's in src/modules (those are standard modules)
+            !fullPath.includes(path.join('src', 'modules'))
+          ) {
+            customPaths.push(fullPath);
+          }
+        }
+      } catch {
+        // Ignore errors (e.g., permission denied)
+      }
+    }
+
+    // Scan the entire project, but exclude source directories
+    await scanDirectory(projectRoot, [path.join(projectRoot, 'src'), path.join(projectRoot, 'tools'), path.join(projectRoot, 'test')]);
+
+    return customPaths;
+  }
+
+  /**
+   * Get custom content info from a custom.yaml or module.yaml file
+   * @param {string} configPath - Path to config file
+   * @param {string} projectRoot - Project root directory for calculating relative paths
+   * @returns {Object|null} Custom content info
+   */
+  async getCustomInfo(configPath, projectRoot = null) {
+    try {
+      const configContent = await fs.readFile(configPath, 'utf8');
+
+      // Try to parse YAML with error handling
+      let config;
+      try {
+        config = yaml.parse(configContent);
+      } catch (parseError) {
+        await prompts.log.warn('YAML parse error in ' + configPath + ': ' + parseError.message);
+        return null;
+      }
+
+      // Check if this is an module.yaml (module) or custom.yaml (custom content)
+      const isInstallConfig = configPath.endsWith('module.yaml');
+      const configDir = path.dirname(configPath);
+
+      // Use provided projectRoot or fall back to process.cwd()
+      const basePath = projectRoot || process.cwd();
+      const relativePath = path.relative(basePath, configDir);
+
+      return {
+        id: config.code || 'unknown-code',
+        name: config.name,
+        description: config.description || '',
+        path: configDir,
+        relativePath: relativePath,
+        defaultSelected: config.default_selected === true,
+        config: config,
+        isInstallConfig: isInstallConfig, // Track which type this is
+      };
+    } catch (error) {
+      await prompts.log.warn('Failed to read ' + configPath + ': ' + error.message);
+      return null;
+    }
+  }
+
+  /**
+   * Install custom content
+   * @param {string} customPath - Path to custom content directory
+   * @param {string} bmadDir - Target bmad directory
+   * @param {Object} config - Configuration from custom.yaml
+   * @param {Function} fileTrackingCallback - Optional callback to track installed files
+   * @returns {Object} Installation result
+   */
+  async install(customPath, bmadDir, config, fileTrackingCallback = null) {
+    const results = {
+      agentsInstalled: 0,
+      workflowsInstalled: 0,
+      filesCopied: 0,
+      preserved: 0,
+      errors: [],
+    };
+
+    try {
+      // Create custom directories in bmad
+      const bmadCustomDir = path.join(bmadDir, 'custom');
+      const bmadAgentsDir = path.join(bmadCustomDir, 'agents');
+      const bmadWorkflowsDir = path.join(bmadCustomDir, 'workflows');
+
+      await fs.ensureDir(bmadCustomDir);
+      await fs.ensureDir(bmadAgentsDir);
+      await fs.ensureDir(bmadWorkflowsDir);
+
+      // Process agents - compile and copy agents
+      const agentsDir = path.join(customPath, 'agents');
+      if (await fs.pathExists(agentsDir)) {
+        await this.compileAndCopyAgents(agentsDir, bmadAgentsDir, bmadDir, config, fileTrackingCallback, results);
+
+        // Count agent files
+        const agentFiles = await this.findFilesRecursively(agentsDir, ['.agent.yaml', '.md']);
+        results.agentsInstalled = agentFiles.length;
+      }
+
+      // Process workflows - copy entire workflows directory structure
+      const workflowsDir = path.join(customPath, 'workflows');
+      if (await fs.pathExists(workflowsDir)) {
+        await this.copyDirectory(workflowsDir, bmadWorkflowsDir, results, fileTrackingCallback, config);
+
+        // Count workflow files
+        const workflowFiles = await this.findFilesRecursively(workflowsDir, ['.md']);
+        results.workflowsInstalled = workflowFiles.length;
+      }
+
+      // Process any additional files at root
+      const entries = await fs.readdir(customPath, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isFile() && entry.name !== 'custom.yaml' && !entry.name.startsWith('.') && !entry.name.endsWith('.md')) {
+          // Skip .md files at root as they're likely docs
+          const sourcePath = path.join(customPath, entry.name);
+          const targetPath = path.join(bmadCustomDir, entry.name);
+
+          try {
+            // Check if file already exists
+            if (await fs.pathExists(targetPath)) {
+              // File already exists, preserve it
+              results.preserved = (results.preserved || 0) + 1;
+            } else {
+              await fs.copy(sourcePath, targetPath);
+              results.filesCopied++;
+
+              if (fileTrackingCallback) {
+                fileTrackingCallback(targetPath);
+              }
+            }
+          } catch (error) {
+            results.errors.push(`Failed to copy file ${entry.name}: ${error.message}`);
+          }
+        }
+      }
+    } catch (error) {
+      results.errors.push(`Installation failed: ${error.message}`);
+    }
+
+    return results;
+  }
+
+  /**
+   * Find all files with specific extensions recursively
+   * @param {string} dir - Directory to search
+   * @param {Array} extensions - File extensions to match
+   * @returns {Array} List of matching files
+   */
+  async findFilesRecursively(dir, extensions) {
+    const files = [];
+
+    async function search(currentDir) {
+      const entries = await fs.readdir(currentDir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const fullPath = path.join(currentDir, entry.name);
+
+        if (entry.isDirectory()) {
+          await search(fullPath);
+        } else if (extensions.some((ext) => entry.name.endsWith(ext))) {
+          files.push(fullPath);
+        }
+      }
+    }
+
+    await search(dir);
+    return files;
+  }
+
+  /**
+   * Recursively copy a directory
+   * @param {string} sourceDir - Source directory
+   * @param {string} targetDir - Target directory
+   * @param {Object} results - Results object to update
+   * @param {Function} fileTrackingCallback - Optional callback
+   * @param {Object} config - Configuration for placeholder replacement
+   */
+  async copyDirectory(sourceDir, targetDir, results, fileTrackingCallback, config) {
+    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.copyDirectory(sourcePath, targetPath, results, fileTrackingCallback, config);
+      } else {
+        try {
+          // Check if file already exists
+          if (await fs.pathExists(targetPath)) {
+            // File already exists, preserve it
+            results.preserved = (results.preserved || 0) + 1;
+          } else {
+            // Copy with placeholder replacement for text files
+            const textExtensions = ['.md', '.yaml', '.yml', '.txt', '.json'];
+            if (textExtensions.some((ext) => entry.name.endsWith(ext))) {
+              // Read source content
+              let content = await fs.readFile(sourcePath, 'utf8');
+
+              // Replace placeholders
+              content = content.replaceAll('{user_name}', config.user_name || 'User');
+              content = content.replaceAll('{communication_language}', config.communication_language || 'English');
+              content = content.replaceAll('{output_folder}', config.output_folder || 'docs');
+
+              // Write to target
+              await fs.ensureDir(path.dirname(targetPath));
+              await fs.writeFile(targetPath, content, 'utf8');
+            } else {
+              // Copy binary files as-is
+              await fs.copy(sourcePath, targetPath);
+            }
+
+            results.filesCopied++;
+            if (entry.name.endsWith('.md')) {
+              results.workflowsInstalled++;
+            }
+            if (fileTrackingCallback) {
+              fileTrackingCallback(targetPath);
+            }
+          }
+        } catch (error) {
+          results.errors.push(`Failed to copy ${entry.name}: ${error.message}`);
+        }
+      }
+    }
+  }
+
+  /**
+   * Compile .agent.yaml files to .md format and handle sidecars
+   * @param {string} sourceAgentsPath - Source agents directory
+   * @param {string} targetAgentsPath - Target agents directory
+   * @param {string} bmadDir - BMAD installation directory
+   * @param {Object} config - Configuration for placeholder replacement
+   * @param {Function} fileTrackingCallback - Optional callback to track installed files
+   * @param {Object} results - Results object to update
+   */
+  async compileAndCopyAgents(sourceAgentsPath, targetAgentsPath, bmadDir, config, fileTrackingCallback, results) {
+    // Get all .agent.yaml files recursively
+    const agentFiles = await this.findFilesRecursively(sourceAgentsPath, ['.agent.yaml']);
+
+    for (const agentFile of agentFiles) {
+      const relativePath = path.relative(sourceAgentsPath, agentFile).split(path.sep).join('/');
+      const targetDir = path.join(targetAgentsPath, path.dirname(relativePath));
+
+      await fs.ensureDir(targetDir);
+
+      const agentName = path.basename(agentFile, '.agent.yaml');
+      const targetMdPath = path.join(targetDir, `${agentName}.md`);
+      // Use the actual bmadDir if available (for when installing to temp dir)
+      const actualBmadDir = config._bmadDir || bmadDir;
+      const customizePath = path.join(actualBmadDir, '_config', 'agents', `custom-${agentName}.customize.yaml`);
+
+      // Read and compile the YAML
+      try {
+        const yamlContent = await fs.readFile(agentFile, 'utf8');
+        const { compileAgent } = require('../../../lib/agent/compiler');
+
+        // Create customize template if it doesn't exist
+        if (!(await fs.pathExists(customizePath))) {
+          const { getSourcePath } = require('../../../lib/project-root');
+          const genericTemplatePath = getSourcePath('utility', 'agent-components', 'agent.customize.template.yaml');
+          if (await fs.pathExists(genericTemplatePath)) {
+            let templateContent = await fs.readFile(genericTemplatePath, 'utf8');
+            await fs.writeFile(customizePath, templateContent, 'utf8');
+            // Only show customize creation in verbose mode
+            if (process.env.BMAD_VERBOSE_INSTALL === 'true') {
+              await prompts.log.message('  Created customize: custom-' + agentName + '.customize.yaml');
+            }
+          }
+        }
+
+        // Compile the agent
+        const { xml } = compileAgent(yamlContent, {}, agentName, relativePath, { config });
+
+        // Replace placeholders in the compiled content
+        let processedXml = xml;
+        processedXml = processedXml.replaceAll('{user_name}', config.user_name || 'User');
+        processedXml = processedXml.replaceAll('{communication_language}', config.communication_language || 'English');
+        processedXml = processedXml.replaceAll('{output_folder}', config.output_folder || 'docs');
+
+        // Write the compiled MD file
+        await fs.writeFile(targetMdPath, processedXml, 'utf8');
+
+        // Track the file
+        if (fileTrackingCallback) {
+          fileTrackingCallback(targetMdPath);
+        }
+
+        // Only show compilation details in verbose mode
+        if (process.env.BMAD_VERBOSE_INSTALL === 'true') {
+          await prompts.log.message('    Compiled agent: ' + agentName + ' -> ' + path.relative(targetAgentsPath, targetMdPath));
+        }
+      } catch (error) {
+        await prompts.log.warn('    Failed to compile agent ' + agentName + ': ' + error.message);
+        results.errors.push(`Failed to compile agent ${agentName}: ${error.message}`);
+      }
+    }
+  }
+}
+
+module.exports = { CustomHandler };

package/tools/cli/installers/lib/ide/_base-ide.js

@@ -1,8 +1,9 @@
 const path = require('node:path');
 const fs = require('fs-extra');
-const chalk = require('chalk');
 const { XmlHandler } = require('../../../lib/xml-handler');
+const prompts = require('../../../lib/prompts');
 const { getSourcePath } = require('../../../lib/project-root');
+const { BMAD_FOLDER_NAME } = require('./shared/path-utils');
 
 /**
  * Base class for IDE-specific setup
@@ -18,7 +19,7 @@ class BaseIdeSetup {
     this.configFile = null; // Override in subclasses when detection is file-based
     this.detectionPaths = []; // Additional paths that indicate the IDE is configured
     this.xmlHandler = new XmlHandler();
-    this.bmadFolderName = 'bmad'; // Default, can be overridden
+    this.bmadFolderName = BMAD_FOLDER_NAME; // Default, can be overridden
   }
 
   /**
@@ -31,18 +32,11 @@ class BaseIdeSetup {
 
   /**
    * Get the agent command activation header from the central template
-   * @returns {string} The activation header text (without XML tags)
+   * @returns {string} The activation header text
    */
   async getAgentCommandHeader() {
-    const headerPath = path.join(getSourcePath(), 'src', 'utility', 'models', 'agent-command-header.md');
-    try {
-      const content = await fs.readFile(headerPath, 'utf8');
-      // Strip the <critical> tags to get plain text
-      return content.replaceAll(/<critical>|<\/critical>/g, '').trim();
-    } catch {
-      // Fallback if file doesn't exist
-      return "You must fully embody this agent's persona and follow all activation instructions, steps and rules exactly as specified. NEVER break character until given an exit command.";
-    }
+    const headerPath = getSourcePath('utility', 'agent-components', 'agent-command-header.md');
+    return await fs.readFile(headerPath, 'utf8');
   }
 
   /**
@@ -59,20 +53,33 @@ class BaseIdeSetup {
    * Cleanup IDE configuration
    * @param {string} projectDir - Project directory
    */
-  async cleanup(projectDir) {
+  async cleanup(projectDir, options = {}) {
     // Default implementation - can be overridden
     if (this.configDir) {
       const configPath = path.join(projectDir, this.configDir);
       if (await fs.pathExists(configPath)) {
-        const bmadRulesPath = path.join(configPath, 'bmad');
+        const bmadRulesPath = path.join(configPath, BMAD_FOLDER_NAME);
         if (await fs.pathExists(bmadRulesPath)) {
           await fs.remove(bmadRulesPath);
-          console.log(chalk.dim(`Removed ${this.name} BMAD configuration`));
+          if (!options.silent) await prompts.log.message(`Removed ${this.name} BMAD configuration`);
         }
       }
     }
   }
 
+  /**
+   * Install a custom agent launcher - subclasses should override
+   * @param {string} projectDir - Project directory
+   * @param {string} agentName - Agent name (e.g., "fred-commit-poet")
+   * @param {string} agentPath - Path to compiled agent (relative to project root)
+   * @param {Object} metadata - Agent metadata
+   * @returns {Object|null} Info about created command, or null if not supported
+   */
+  async installCustomAgentLauncher(projectDir, agentName, agentPath, metadata) {
+    // Default implementation - subclasses can override
+    return null;
+  }
+
   /**
    * Detect whether this IDE already has configuration in the project
    * Subclasses can override for custom logic
@@ -130,7 +137,7 @@ class BaseIdeSetup {
     // Get module agents
     const entries = await fs.readdir(bmadDir, { withFileTypes: true });
     for (const entry of entries) {
-      if (entry.isDirectory() && entry.name !== 'core' && entry.name !== '_cfg' && entry.name !== 'agents') {
+      if (entry.isDirectory() && entry.name !== 'core' && entry.name !== '_config' && entry.name !== 'agents') {
         const moduleAgentsPath = path.join(bmadDir, entry.name, 'agents');
         if (await fs.pathExists(moduleAgentsPath)) {
           const moduleAgents = await this.scanDirectory(moduleAgentsPath, '.md');
@@ -202,7 +209,7 @@ class BaseIdeSetup {
     // Get module tasks
     const entries = await fs.readdir(bmadDir, { withFileTypes: true });
     for (const entry of entries) {
-      if (entry.isDirectory() && entry.name !== 'core' && entry.name !== '_cfg' && entry.name !== 'agents') {
+      if (entry.isDirectory() && entry.name !== 'core' && entry.name !== '_config' && entry.name !== 'agents') {
         const moduleTasksPath = path.join(bmadDir, entry.name, 'tasks');
         if (await fs.pathExists(moduleTasksPath)) {
           const moduleTasks = await this.scanDirectoryWithStandalone(moduleTasksPath, ['.md', '.xml']);
@@ -248,7 +255,7 @@ class BaseIdeSetup {
     // Get module tools
     const entries = await fs.readdir(bmadDir, { withFileTypes: true });
     for (const entry of entries) {
-      if (entry.isDirectory() && entry.name !== 'core' && entry.name !== '_cfg' && entry.name !== 'agents') {
+      if (entry.isDirectory() && entry.name !== 'core' && entry.name !== '_config' && entry.name !== 'agents') {
         const moduleToolsPath = path.join(bmadDir, entry.name, 'tools');
         if (await fs.pathExists(moduleToolsPath)) {
           const moduleTools = await this.scanDirectoryWithStandalone(moduleToolsPath, ['.md', '.xml']);
@@ -294,7 +301,7 @@ class BaseIdeSetup {
     // Get module workflows
     const entries = await fs.readdir(bmadDir, { withFileTypes: true });
     for (const entry of entries) {
-      if (entry.isDirectory() && entry.name !== 'core' && entry.name !== '_cfg' && entry.name !== 'agents') {
+      if (entry.isDirectory() && entry.name !== 'core' && entry.name !== '_config' && entry.name !== 'agents') {
         const moduleWorkflowsPath = path.join(bmadDir, entry.name, 'workflows');
         if (await fs.pathExists(moduleWorkflowsPath)) {
           const moduleWorkflows = await this.findWorkflowYamlFiles(moduleWorkflowsPath);
@@ -340,18 +347,20 @@ class BaseIdeSetup {
       } else if (entry.isFile() && entry.name === 'workflow.yaml') {
         // Read workflow.yaml to get name and standalone property
         try {
-          const yaml = require('js-yaml');
+          const yaml = require('yaml');
           const content = await fs.readFile(fullPath, 'utf8');
-          const workflowData = yaml.load(content);
+          const workflowData = yaml.parse(content);
 
           if (workflowData && workflowData.name) {
+            // Workflows are standalone by default unless explicitly false
+            const standalone = workflowData.standalone !== false && workflowData.standalone !== 'false';
             workflows.push({
               name: workflowData.name,
               path: fullPath,
               relativePath: path.relative(dir, fullPath),
               filename: entry.name,
               description: workflowData.description || '',
-              standalone: workflowData.standalone === true, // Check standalone property
+              standalone: standalone,
             });
           }
         } catch {
@@ -435,31 +444,38 @@ class BaseIdeSetup {
         const matchedExt = extensions.find((e) => entry.name.endsWith(e));
         if (matchedExt) {
           // Read file content to check for standalone attribute
-          let standalone = false;
+          // All non-internal files are considered standalone by default
+          let standalone = true;
           try {
             const content = await fs.readFile(fullPath, 'utf8');
 
-            // Check for standalone="true" in XML files
+            // Skip internal/engine files (not user-facing)
+            if (content.includes('internal="true"')) {
+              continue;
+            }
+
+            // Check for explicit standalone: false
             if (entry.name.endsWith('.xml')) {
-              // Look for standalone="true" in the opening tag (task or tool)
-              const standaloneMatch = content.match(/<(?:task|tool)[^>]+standalone="true"/);
-              standalone = !!standaloneMatch;
+              // For XML files, check for standalone="false" attribute
+              const tagMatch = content.match(/<(task|tool)[^>]*standalone="false"/);
+              standalone = !tagMatch;
             } else if (entry.name.endsWith('.md')) {
-              // Check for standalone: true in YAML frontmatter
-              const frontmatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+              // For MD files, parse YAML frontmatter
+              const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
               if (frontmatterMatch) {
-                const yaml = require('js-yaml');
                 try {
-                  const frontmatter = yaml.load(frontmatterMatch[1]);
-                  standalone = frontmatter.standalone === true;
+                  const yaml = require('yaml');
+                  const frontmatter = yaml.parse(frontmatterMatch[1]);
+                  standalone = frontmatter.standalone !== false && frontmatter.standalone !== 'false';
                 } catch {
-                  // Ignore YAML parse errors
+                  // If YAML parsing fails, default to standalone
                 }
               }
+              // No frontmatter means standalone (default)
             }
           } catch {
-            // If we can't read the file, assume not standalone
-            standalone = false;
+            // If we can't read the file, default to standalone
+            standalone = true;
           }
 
           files.push({
@@ -514,21 +530,26 @@ class BaseIdeSetup {
   }
 
   /**
-   * Write file with content (replaces {bmad_folder} placeholder)
+   * Write file with content (replaces _bmad placeholder)
    * @param {string} filePath - File path
    * @param {string} content - File content
    */
   async writeFile(filePath, content) {
-    // Replace {bmad_folder} placeholder if present
-    if (typeof content === 'string' && content.includes('{bmad_folder}')) {
-      content = content.replaceAll('{bmad_folder}', this.bmadFolderName);
+    // Replace _bmad placeholder if present
+    if (typeof content === 'string' && content.includes('_bmad')) {
+      content = content.replaceAll('_bmad', this.bmadFolderName);
+    }
+
+    // Replace escape sequence _bmad with literal _bmad
+    if (typeof content === 'string' && content.includes('_bmad')) {
+      content = content.replaceAll('_bmad', '_bmad');
     }
     await this.ensureDir(path.dirname(filePath));
     await fs.writeFile(filePath, content, 'utf8');
   }
 
   /**
-   * Copy file from source to destination (replaces {bmad_folder} placeholder in text files)
+   * Copy file from source to destination (replaces _bmad placeholder in text files)
    * @param {string} source - Source file path
    * @param {string} dest - Destination file path
    */
@@ -545,9 +566,14 @@ class BaseIdeSetup {
         // Read the file content
         let content = await fs.readFile(source, 'utf8');
 
-        // Replace {bmad_folder} placeholder with actual folder name
-        if (content.includes('{bmad_folder}')) {
-          content = content.replaceAll('{bmad_folder}', this.bmadFolderName);
+        // Replace _bmad placeholder with actual folder name
+        if (content.includes('_bmad')) {
+          content = content.replaceAll('_bmad', this.bmadFolderName);
+        }
+
+        // Replace escape sequence _bmad with literal _bmad
+        if (content.includes('_bmad')) {
+          content = content.replaceAll('_bmad', '_bmad');
         }
 
         // Write to dest with replaced content
@@ -601,13 +627,26 @@ class BaseIdeSetup {
       .join(' ');
   }
 
+  /**
+   * Flatten a relative path to a single filename for flat slash command naming
+   * @deprecated Use toColonPath() or toDashPath() from shared/path-utils.js instead
+   * Example: 'module/agents/name.md' -> 'bmad-module-agents-name.md'
+   * Used by IDEs that ignore directory structure for slash commands (e.g., Antigravity, Codex)
+   * @param {string} relativePath - Relative path to flatten
+   * @returns {string} Flattened filename with 'bmad-' prefix
+   */
+  flattenFilename(relativePath) {
+    const sanitized = relativePath.replaceAll(/[/\\]/g, '-');
+    return `bmad-${sanitized}`;
+  }
+
   /**
    * Create agent configuration file
    * @param {string} bmadDir - BMAD installation directory
    * @param {Object} agent - Agent information
    */
   async createAgentConfig(bmadDir, agent) {
-    const agentConfigDir = path.join(bmadDir, '_cfg', 'agents');
+    const agentConfigDir = path.join(bmadDir, '_config', 'agents');
     await this.ensureDir(agentConfigDir);
 
     // Load agent config template