bmad-method 6.0.0-alpha.14 → 6.0.0-alpha.15

package/src/modules/bmb/docs/agents/index.md

@@ -37,7 +37,7 @@ Production-ready examples in `/src/modules/bmb/reference/agents/`:
 
 For installing standalone simple and expert agents, see:
 
-- [Custom Agent Installation](/docs/custom-agent-installation.md)
+- [Custom Agent Installation](/docs/custom-content-installation.md)
 
 ## Key Concepts
 

package/src/modules/bmb/workflows/create-module/steps/step-04-structure.md

@@ -113,10 +113,10 @@ For a [module type] module, we'll create this structure:"
 │   └── [template-files]
 ├── data/                      # Module data files
 │   └── [data-files]
+├── module.yaml                # Required
 ├── _module-installer/         # Installation configuration
-│   ├── install-config.yaml   # Required
-│   ├── installer.js          # Optional
-│   └── assets/               # Optional install assets
+│   ├── installer.js           # Optional
+│   └── assets/                # Optional install assets
 └── README.md                  # Module documentation
 ```
 

package/src/modules/bmb/workflows/create-module/steps/step-05-config.md

@@ -184,7 +184,7 @@ Update module-plan.md with configuration section:
 
 ### Result Configuration Structure
 
-The install-config.yaml will generate:
+The module.yaml will generate:
 - Module configuration at: {bmad_folder}/{module_code}/config.yaml
 - User settings stored as: [describe structure]
 ````

package/src/modules/bmb/workflows/create-module/steps/step-08-installer.md

@@ -37,7 +37,7 @@ partyModeWorkflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workf
 ## EXECUTION PROTOCOLS:
 
 - 🎯 Use configuration plan from step 5
-- 💾 Create install-config.yaml with all fields
+- 💾 Create module.yaml with all fields
 - 📖 Add "step-08-installer" to stepsCompleted array` before loading next step
 - 🚫 FORBIDDEN to load next step until user selects 'C'
 
@@ -50,7 +50,7 @@ partyModeWorkflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workf
 
 ## STEP GOAL:
 
-To create the module installer configuration (install-config.yaml) that defines how users will install and configure the module.
+To create the module installer configuration (module.yaml) that defines how users will install and configure the module.
 
 ## INSTALLER SETUP PROCESS:
 
@@ -74,11 +74,11 @@ From step 5, we planned these configuration fields:
 Ensure \_module-installer directory exists
 Directory: {custom_module_location}/{module_name}/\_module-installer/
 
-### 3. Create install-config.yaml
+### 3. Create module.yaml
 
-"I'll create the install-config.yaml file based on your configuration plan. This is the core installer configuration file."
+"I'll create the module.yaml file based on your configuration plan. This is the core installer configuration file."
 
-Create file: {custom_module_location}/{module_name}/\_module-installer/install-config.yaml from template {installConfigTemplate}
+Create file: {custom_module_location}/{module_name}/module.yaml from template {installConfigTemplate}
 
 ### 4. Handle Custom Installation Logic
 
@@ -117,7 +117,7 @@ Update module-plan.md with installer section:
 
 ### Install Configuration
 
-- File: \_module-installer/install-config.yaml
+- File: module.yaml
 - Module code: {module_name}
 - Default selected: false
 - Configuration fields: [count]
@@ -166,7 +166,7 @@ Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Conti
 
 ### ✅ SUCCESS:
 
-- install-config.yaml created with all planned fields
+- module.yaml created with all planned fields
 - YAML syntax valid
 - Custom installation logic prepared (if needed)
 - Installer follows BMAD standards
@@ -174,7 +174,7 @@ Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Conti
 
 ### ❌ SYSTEM FAILURE:
 
-- Not creating install-config.yaml
+- Not creating module.yaml
 - Invalid YAML syntax
 - Missing required fields
 - Not using proper path templates

package/src/modules/bmb/workflows/create-module/steps/step-09-documentation.md

@@ -133,7 +133,8 @@ bmad install {module_name}
 ├── tasks/                     # Task files
 ├── templates/                 # Shared templates
 ├── data/                      # Module data
-├── _module-installer/         # Installation config
+├── _module-installer/         # Installation optional js file with custom install routine
+├── module.yaml                # yaml config and install questions
 └── README.md                  # This file
 ```
 

package/src/modules/bmb/workflows/create-module/steps/step-10-roadmap.md

@@ -207,9 +207,10 @@ workflow {workflow_name}
 ├── workflows/       # ✅ Structure created, plans written
 ├── tasks/           # ✅ Created
 ├── templates/       # ✅ Created
-├── data/           # ✅ Created
+├── data/            # ✅ Created
 ├── _module-installer/  # ✅ Configured
-└── README.md       # ✅ Complete
+└── README.md        # ✅ Complete
+└── module.yaml      # ✅ Complete
 ```
 
 ## Completion Criteria

package/src/modules/bmb/workflows/create-module/steps/step-11-validate.md

@@ -73,8 +73,8 @@ Expected Structure:
 ├── templates/                 [✅/❌]
 ├── data/                      [✅/❌]
 ├── _module-installer/         [✅/❌]
-│   ├── install-config.yaml   [✅/❌]
-│   └── installer.js          [✅/N/A]
+│   └── installer.js           [✅/N/A]
+├── module.yaml                [✅/❌]
 └── README.md                  [✅/❌]
 ```
 
@@ -87,7 +87,7 @@ Expected Structure:
 "**2. Configuration Files Check**"
 
 **Install Configuration:**
-Validate install-config.yaml
+Validate module.yaml
 
 - [ ] YAML syntax valid
 - [ ] Module code matches folder name

package/src/modules/bmb/workflows/create-module/templates/installer.template.js

@@ -6,7 +6,7 @@
 /**
  * @param {Object} options - Installation options
  * @param {string} options.projectRoot - Project root directory
- * @param {Object} options.config - Module configuration from install-config.yaml
+ * @param {Object} options.config - Module configuration from module.yaml
  * @param {Array} options.installedIDEs - List of IDE codes being configured
  * @param {Object} options.logger - Logger instance (log, warn, error methods)
  * @returns {boolean} - true if successful, false to abort installation

package/src/modules/bmb/workflows/create-module/validation.md

@@ -13,15 +13,15 @@ This document provides the validation criteria used in step-11-validate.md to en
 - [ ] data/ - Module data
 - [ ] \_module-installer/ - Installation config
 - [ ] README.md - Module documentation
+- [ ] module.yaml - module config file
 
-### Required Files in \_module-installer/
+### Optional File in \_module-installer/
 
-- [ ] install-config.yaml - Installation configuration
 - [ ] installer.js - Custom logic (if needed)
 
 ## Configuration Validation
 
-### install-config.yaml
+### module.yaml
 
 - [ ] Valid YAML syntax
 - [ ] Module code matches folder name

package/src/modules/bmb/workflows/create-workflow/steps/step-01-init.md

@@ -98,7 +98,7 @@ After getting the workflow name:
 Based on the module selection, confirm the target location:
 
 - For bmb module: `{custom_workflow_location}` (defaults to `{bmad_folder}/custom/src/workflows`)
-- For other modules: Check their install-config.yaml for custom workflow locations
+- For other modules: Check their module.yaml for custom workflow locations
 - Confirm the exact folder path where the workflow will be created
 - Store the confirmed path as `{targetWorkflowPath}`
 

package/src/modules/bmb/workflows/create-workflow/steps/step-07-build.md

@@ -109,7 +109,7 @@ Create the workflow folder structure in the target location:
 ```
 
 For bmb module, this will be: `{bmad_folder}/custom/src/workflows/{workflow_name}/`
-For other modules, check their install-config.yaml for custom_workflow_location
+For other modules, check their module.yaml for custom_workflow_location
 
 ### 3. Generate workflow.md
 

package/src/modules/bmgd/README.md

@@ -129,8 +129,9 @@ bmgd/
 │       (Uses BMM workflows via cross-module references)
 ├── templates/
 ├── data/
+├── module.yaml
 └── _module-installer/
-    └── install-config.yaml
+    └── installer.js (optional)
 ```
 
 ## Configuration

package/src/modules/bmm/_module-installer/installer.js

@@ -9,7 +9,7 @@ const platformCodes = require(path.join(__dirname, '../../../../tools/cli/lib/pl
  *
  * @param {Object} options - Installation options
  * @param {string} options.projectRoot - The root directory of the target project
- * @param {Object} options.config - Module configuration from install-config.yaml
+ * @param {Object} options.config - Module configuration from module.yaml
  * @param {Array<string>} options.installedIDEs - Array of IDE codes that were installed
  * @param {Object} options.logger - Logger instance for output
  * @returns {Promise<boolean>} - Success status

package/src/modules/bmm/_module-installer/platform-specifics/claude-code.js

@@ -5,7 +5,7 @@ const chalk = require('chalk');
  *
  * @param {Object} options - Installation options
  * @param {string} options.projectRoot - The root directory of the target project
- * @param {Object} options.config - Module configuration from install-config.yaml
+ * @param {Object} options.config - Module configuration from module.yaml
  * @param {Object} options.logger - Logger instance for output
  * @param {Object} options.platformInfo - Platform metadata from global config
  * @returns {Promise<boolean>} - Success status

package/src/modules/bmm/_module-installer/platform-specifics/windsurf.js

@@ -5,7 +5,7 @@ const chalk = require('chalk');
  *
  * @param {Object} options - Installation options
  * @param {string} options.projectRoot - The root directory of the target project
- * @param {Object} options.config - Module configuration from install-config.yaml
+ * @param {Object} options.config - Module configuration from module.yaml
  * @param {Object} options.logger - Logger instance for output
  * @returns {Promise<boolean>} - Success status
  */

package/src/modules/cis/_module-installer/installer.js

@@ -8,7 +8,7 @@ const chalk = require('chalk');
  *
  * @param {Object} options - Installation options
  * @param {string} options.projectRoot - The root directory of the target project
- * @param {Object} options.config - Module configuration from install-config.yaml
+ * @param {Object} options.config - Module configuration from module.yaml
  * @param {Array<string>} options.installedIDEs - Array of IDE codes that were installed
  * @param {Object} options.logger - Logger instance for output
  * @returns {Promise<boolean>} - Success status

package/tools/cli/README.md

@@ -98,7 +98,7 @@ The installer is a multi-stage system that handles agent compilation, IDE integr
 ```
 1. Collect User Input
    - Target directory, modules, IDEs
-   - Custom module configuration (via install-config.yaml)
+   - Custom module configuration (via module.yaml)
 
 2. Pre-Installation
    - Validate target, check conflicts, backup existing installations
@@ -183,12 +183,12 @@ The installer supports **15 IDE environments** through a base-derived architectu
 
 ### Custom Module Configuration
 
-Modules define interactive configuration menus via `install-config.yaml` files in their `_module-installer/` directories.
+Modules define interactive configuration menus via `module.yaml` files in their `_module-installer/` directories.
 
 **Config File Location**:
 
-- Core: `src/core/_module-installer/install-config.yaml`
-- Modules: `src/modules/{module}/_module-installer/install-config.yaml`
+- Core: `src/core/module.yaml`
+- Modules: `src/modules/{module}/module.yaml`
 
 **Configuration Types**:
 

package/tools/cli/installers/lib/core/config-collector.js

@@ -183,24 +183,28 @@ class ConfigCollector {
 
     // Load module's install config schema
     // First, try the standard src/modules location
-    let installerConfigPath = path.join(getModulePath(moduleName), '_module-installer', 'install-config.yaml');
+    let installerConfigPath = path.join(getModulePath(moduleName), '_module-installer', 'module.yaml');
+    let moduleConfigPath = path.join(getModulePath(moduleName), 'module.yaml');
 
     // If not found in src/modules, we need to find it by searching the project
-    if (!(await fs.pathExists(installerConfigPath))) {
+    if (!(await fs.pathExists(installerConfigPath)) && !(await fs.pathExists(moduleConfigPath))) {
       // Use the module manager to find the module source
       const { ModuleManager } = require('../modules/manager');
       const moduleManager = new ModuleManager();
       const moduleSourcePath = await moduleManager.findModuleSource(moduleName);
 
       if (moduleSourcePath) {
-        installerConfigPath = path.join(moduleSourcePath, '_module-installer', 'install-config.yaml');
+        installerConfigPath = path.join(moduleSourcePath, '_module-installer', 'module.yaml');
+        moduleConfigPath = path.join(moduleSourcePath, 'module.yaml');
       }
     }
 
     let configPath = null;
     let isCustomModule = false;
 
-    if (await fs.pathExists(installerConfigPath)) {
+    if (await fs.pathExists(moduleConfigPath)) {
+      configPath = moduleConfigPath;
+    } else if (await fs.pathExists(installerConfigPath)) {
       configPath = installerConfigPath;
     } else {
       // Check if this is a custom module with custom.yaml
@@ -448,22 +452,26 @@ class ConfigCollector {
     }
     // Load module's config
     // First, try the standard src/modules location
-    let installerConfigPath = path.join(getModulePath(moduleName), '_module-installer', 'install-config.yaml');
+    let installerConfigPath = path.join(getModulePath(moduleName), '_module-installer', 'module.yaml');
+    let moduleConfigPath = path.join(getModulePath(moduleName), 'module.yaml');
 
     // If not found in src/modules, we need to find it by searching the project
-    if (!(await fs.pathExists(installerConfigPath))) {
+    if (!(await fs.pathExists(installerConfigPath)) && !(await fs.pathExists(moduleConfigPath))) {
       // Use the module manager to find the module source
       const { ModuleManager } = require('../modules/manager');
       const moduleManager = new ModuleManager();
       const moduleSourcePath = await moduleManager.findModuleSource(moduleName);
 
       if (moduleSourcePath) {
-        installerConfigPath = path.join(moduleSourcePath, '_module-installer', 'install-config.yaml');
+        installerConfigPath = path.join(moduleSourcePath, '_module-installer', 'module.yaml');
+        moduleConfigPath = path.join(moduleSourcePath, 'module.yaml');
       }
     }
 
     let configPath = null;
-    if (await fs.pathExists(installerConfigPath)) {
+    if (await fs.pathExists(moduleConfigPath)) {
+      configPath = moduleConfigPath;
+    } else if (await fs.pathExists(installerConfigPath)) {
       configPath = installerConfigPath;
     } else {
       // No config for this module

package/tools/cli/installers/lib/core/custom-module-cache.js

@@ -0,0 +1,239 @@
+/**
+ * Custom Module Source Cache
+ * Caches custom module sources under _cfg/custom/ to ensure they're never lost
+ * and can be checked into source control
+ */
+
+const fs = require('fs-extra');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+class CustomModuleCache {
+  constructor(bmadDir) {
+    this.bmadDir = bmadDir;
+    this.customCacheDir = path.join(bmadDir, '_cfg', 'custom');
+    this.manifestPath = path.join(this.customCacheDir, 'cache-manifest.yaml');
+  }
+
+  /**
+   * Ensure the custom cache directory exists
+   */
+  async ensureCacheDir() {
+    await fs.ensureDir(this.customCacheDir);
+  }
+
+  /**
+   * Get cache manifest
+   */
+  async getCacheManifest() {
+    if (!(await fs.pathExists(this.manifestPath))) {
+      return {};
+    }
+
+    const content = await fs.readFile(this.manifestPath, 'utf8');
+    const yaml = require('js-yaml');
+    return yaml.load(content) || {};
+  }
+
+  /**
+   * Update cache manifest
+   */
+  async updateCacheManifest(manifest) {
+    const yaml = require('js-yaml');
+    const content = yaml.dump(manifest, {
+      indent: 2,
+      lineWidth: -1,
+      noRefs: true,
+      sortKeys: false,
+    });
+
+    await fs.writeFile(this.manifestPath, content);
+  }
+
+  /**
+   * Calculate hash of a file or directory
+   */
+  async calculateHash(sourcePath) {
+    const hash = crypto.createHash('sha256');
+
+    const isDir = (await fs.stat(sourcePath)).isDirectory();
+
+    if (isDir) {
+      // For directories, hash all files
+      const files = [];
+      async function collectFiles(dir) {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.isFile()) {
+            files.push(path.join(dir, entry.name));
+          } else if (entry.isDirectory() && !entry.name.startsWith('.')) {
+            await collectFiles(path.join(dir, entry.name));
+          }
+        }
+      }
+
+      await collectFiles(sourcePath);
+      files.sort(); // Ensure consistent order
+
+      for (const file of files) {
+        const content = await fs.readFile(file);
+        const relativePath = path.relative(sourcePath, file);
+        hash.update(relativePath + '|' + content.toString('base64'));
+      }
+    } else {
+      // For single files
+      const content = await fs.readFile(sourcePath);
+      hash.update(content);
+    }
+
+    return hash.digest('hex');
+  }
+
+  /**
+   * Cache a custom module source
+   * @param {string} moduleId - Module ID
+   * @param {string} sourcePath - Original source path
+   * @param {Object} metadata - Additional metadata to store
+   * @returns {Object} Cached module info
+   */
+  async cacheModule(moduleId, sourcePath, metadata = {}) {
+    await this.ensureCacheDir();
+
+    const cacheDir = path.join(this.customCacheDir, moduleId);
+    const cacheManifest = await this.getCacheManifest();
+
+    // Check if already cached and unchanged
+    if (cacheManifest[moduleId]) {
+      const cached = cacheManifest[moduleId];
+      if (cached.originalHash && cached.originalHash === (await this.calculateHash(sourcePath))) {
+        // Source unchanged, return existing cache info
+        return {
+          moduleId,
+          cachePath: cacheDir,
+          ...cached,
+        };
+      }
+    }
+
+    // Remove existing cache if it exists
+    if (await fs.pathExists(cacheDir)) {
+      await fs.remove(cacheDir);
+    }
+
+    // Copy module to cache
+    await fs.copy(sourcePath, cacheDir, {
+      filter: (src) => {
+        const relative = path.relative(sourcePath, src);
+        // Skip node_modules, .git, and other common ignore patterns
+        return !relative.includes('node_modules') && !relative.startsWith('.git') && !relative.startsWith('.DS_Store');
+      },
+    });
+
+    // Calculate hash of the source
+    const sourceHash = await this.calculateHash(sourcePath);
+    const cacheHash = await this.calculateHash(cacheDir);
+
+    // Update manifest - don't store originalPath for source control friendliness
+    cacheManifest[moduleId] = {
+      originalHash: sourceHash,
+      cacheHash: cacheHash,
+      cachedAt: new Date().toISOString(),
+      ...metadata,
+    };
+
+    await this.updateCacheManifest(cacheManifest);
+
+    return {
+      moduleId,
+      cachePath: cacheDir,
+      ...cacheManifest[moduleId],
+    };
+  }
+
+  /**
+   * Get cached module info
+   * @param {string} moduleId - Module ID
+   * @returns {Object|null} Cached module info or null
+   */
+  async getCachedModule(moduleId) {
+    const cacheManifest = await this.getCacheManifest();
+    const cached = cacheManifest[moduleId];
+
+    if (!cached) {
+      return null;
+    }
+
+    const cacheDir = path.join(this.customCacheDir, moduleId);
+
+    if (!(await fs.pathExists(cacheDir))) {
+      // Cache dir missing, remove from manifest
+      delete cacheManifest[moduleId];
+      await this.updateCacheManifest(cacheManifest);
+      return null;
+    }
+
+    // Verify cache integrity
+    const currentCacheHash = await this.calculateHash(cacheDir);
+    if (currentCacheHash !== cached.cacheHash) {
+      console.warn(`Warning: Cache integrity check failed for ${moduleId}`);
+    }
+
+    return {
+      moduleId,
+      cachePath: cacheDir,
+      ...cached,
+    };
+  }
+
+  /**
+   * Get all cached modules
+   * @returns {Array} Array of cached module info
+   */
+  async getAllCachedModules() {
+    const cacheManifest = await this.getCacheManifest();
+    const cached = [];
+
+    for (const [moduleId, info] of Object.entries(cacheManifest)) {
+      const cachedModule = await this.getCachedModule(moduleId);
+      if (cachedModule) {
+        cached.push(cachedModule);
+      }
+    }
+
+    return cached;
+  }
+
+  /**
+   * Remove a cached module
+   * @param {string} moduleId - Module ID to remove
+   */
+  async removeCachedModule(moduleId) {
+    const cacheManifest = await this.getCacheManifest();
+    const cacheDir = path.join(this.customCacheDir, moduleId);
+
+    // Remove cache directory
+    if (await fs.pathExists(cacheDir)) {
+      await fs.remove(cacheDir);
+    }
+
+    // Remove from manifest
+    delete cacheManifest[moduleId];
+    await this.updateCacheManifest(cacheManifest);
+  }
+
+  /**
+   * Sync cached modules with a list of module IDs
+   * @param {Array<string>} moduleIds - Module IDs to keep
+   */
+  async syncCache(moduleIds) {
+    const cached = await this.getAllCachedModules();
+
+    for (const cachedModule of cached) {
+      if (!moduleIds.includes(cachedModule.moduleId)) {
+        await this.removeCachedModule(cachedModule.moduleId);
+      }
+    }
+  }
+}
+
+module.exports = { CustomModuleCache };

package/tools/cli/installers/lib/core/detector.js

@@ -17,6 +17,7 @@ class Detector {
       hasCore: false,
       modules: [],
       ides: [],
+      customModules: [],
       manifest: null,
     };
 
@@ -32,6 +33,10 @@ class Detector {
       result.manifest = manifestData;
       result.version = manifestData.version;
       result.installed = true;
+      // Copy custom modules if they exist
+      if (manifestData.customModules) {
+        result.customModules = manifestData.customModules;
+      }
     }
 
     // Check for core
@@ -275,10 +280,9 @@ class Detector {
             hasV6Installation = true;
             // Don't break - continue scanning to be thorough
           } else {
-            // Not V6+, check if folder name contains "bmad" (case insensitive)
-            const nameLower = name.toLowerCase();
-            if (nameLower.includes('bmad')) {
-              // Potential V4 legacy folder
+            // Not V6+, check if this is the exact V4 folder name "bmad-method"
+            if (name === 'bmad-method') {
+              // This is the V4 default folder - flag it as legacy
               potentialV4Folders.push(fullPath);
             }
           }