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

package/tools/cli/lib/ui.js

@@ -59,6 +59,17 @@ class UI {
     const bmadDir = await installer.findBmadDir(confirmedDirectory);
     const hasExistingInstall = await fs.pathExists(bmadDir);
 
+    // Always ask for custom content, but we'll handle it differently for new installs
+    let customContentConfig = { hasCustomContent: false };
+    if (hasExistingInstall) {
+      // Existing installation - prompt to add/update custom content
+      customContentConfig = await this.promptCustomContentForExisting();
+    } else {
+      // New installation - we'll prompt after creating the directory structure
+      // For now, set a flag to indicate we should ask later
+      customContentConfig._shouldAsk = true;
+    }
+
     // Track action type (only set if there's an existing installation)
     let actionType;
 
@@ -85,9 +96,11 @@ class UI {
 
       // Handle quick update separately
       if (actionType === 'quick-update') {
+        // Quick update doesn't install custom content - just updates existing modules
         return {
           actionType: 'quick-update',
           directory: confirmedDirectory,
+          customContent: { hasCustomContent: false },
         };
       }
 
@@ -117,6 +130,64 @@ class UI {
     const { installedModuleIds } = await this.getExistingInstallation(confirmedDirectory);
     const coreConfig = await this.collectCoreConfig(confirmedDirectory);
 
+    // For new installations, create the directory structure first so we can cache custom content
+    if (!hasExistingInstall && customContentConfig._shouldAsk) {
+      // Create the bmad directory based on core config
+      const path = require('node:path');
+      const fs = require('fs-extra');
+      const bmadFolderName = coreConfig.bmad_folder || 'bmad';
+      const bmadDir = path.join(confirmedDirectory, bmadFolderName);
+
+      await fs.ensureDir(bmadDir);
+      await fs.ensureDir(path.join(bmadDir, '_cfg'));
+      await fs.ensureDir(path.join(bmadDir, '_cfg', 'custom'));
+
+      // Now prompt for custom content
+      customContentConfig = await this.promptCustomContentLocation();
+
+      // If custom content found, cache it
+      if (customContentConfig.hasCustomContent) {
+        const { CustomModuleCache } = require('../installers/lib/core/custom-module-cache');
+        const cache = new CustomModuleCache(bmadDir);
+
+        const { CustomHandler } = require('../installers/lib/custom/handler');
+        const customHandler = new CustomHandler();
+        const customFiles = await customHandler.findCustomContent(customContentConfig.customPath);
+
+        for (const customFile of customFiles) {
+          const customInfo = await customHandler.getCustomInfo(customFile);
+          if (customInfo && customInfo.id) {
+            // Cache the module source
+            await cache.cacheModule(customInfo.id, customInfo.path, {
+              name: customInfo.name,
+              type: 'custom',
+            });
+
+            console.log(chalk.dim(`  Cached ${customInfo.name} to _cfg/custom/${customInfo.id}`));
+          }
+        }
+
+        // Update config to use cached modules
+        customContentConfig.cachedModules = [];
+        for (const customFile of customFiles) {
+          const customInfo = await customHandler.getCustomInfo(customFile);
+          if (customInfo && customInfo.id) {
+            customContentConfig.cachedModules.push({
+              id: customInfo.id,
+              cachePath: path.join(bmadDir, '_cfg', 'custom', customInfo.id),
+              // Store relative path from cache for the manifest
+              relativePath: path.join('_cfg', 'custom', customInfo.id),
+            });
+          }
+        }
+
+        console.log(chalk.green(`✓ Cached ${customFiles.length} custom module(s)`));
+      }
+
+      // Clear the flag
+      delete customContentConfig._shouldAsk;
+    }
+
     // Skip module selection during update/reinstall - keep existing modules
     let selectedModules;
     if (actionType === 'update' || actionType === 'reinstall') {
@@ -125,8 +196,52 @@ class UI {
       console.log(chalk.cyan('\n📦 Keeping existing modules: ') + selectedModules.join(', '));
     } else {
       // Only show module selection for new installs
-      const moduleChoices = await this.getModuleChoices(installedModuleIds);
+      const moduleChoices = await this.getModuleChoices(installedModuleIds, customContentConfig);
       selectedModules = await this.selectModules(moduleChoices);
+
+      // Check which custom content items were selected
+      const selectedCustomContent = selectedModules.filter((mod) => mod.startsWith('__CUSTOM_CONTENT__'));
+
+      // For cached modules (new installs), check if any cached modules were selected
+      let selectedCachedModules = [];
+      if (customContentConfig.cachedModules) {
+        selectedCachedModules = selectedModules.filter(
+          (mod) => !mod.startsWith('__CUSTOM_CONTENT__') && customContentConfig.cachedModules.some((cm) => cm.id === mod),
+        );
+      }
+
+      if (selectedCustomContent.length > 0 || selectedCachedModules.length > 0) {
+        customContentConfig.selected = true;
+
+        // Handle directory-based custom content (existing installs)
+        if (selectedCustomContent.length > 0) {
+          customContentConfig.selectedFiles = selectedCustomContent.map((mod) => mod.replace('__CUSTOM_CONTENT__', ''));
+          // Convert custom content to module IDs for installation
+          const customContentModuleIds = [];
+          const { CustomHandler } = require('../installers/lib/custom/handler');
+          const customHandler = new CustomHandler();
+          for (const customFile of customContentConfig.selectedFiles) {
+            // Get the module info to extract the ID
+            const customInfo = await customHandler.getCustomInfo(customFile);
+            if (customInfo) {
+              customContentModuleIds.push(customInfo.id);
+            }
+          }
+          // Filter out custom content markers and add module IDs
+          selectedModules = [...selectedModules.filter((mod) => !mod.startsWith('__CUSTOM_CONTENT__')), ...customContentModuleIds];
+        }
+
+        // For cached modules, they're already module IDs, just mark as selected
+        if (selectedCachedModules.length > 0) {
+          customContentConfig.selectedCachedModules = selectedCachedModules;
+          // No need to filter since they're already proper module IDs
+        }
+      } else if (customContentConfig.hasCustomContent) {
+        // User provided custom content but didn't select any
+        customContentConfig.selected = false;
+        customContentConfig.selectedFiles = [];
+        customContentConfig.selectedCachedModules = [];
+      }
     }
 
     // Prompt for AgentVibes TTS integration
@@ -147,7 +262,9 @@ class UI {
       ides: toolSelection.ides,
       skipIde: toolSelection.skipIde,
       coreConfig: coreConfig, // Pass collected core config to installer
-      enableAgentVibes: agentVibesConfig.enabled, // AgentVibes TTS integration
+      // Custom content configuration
+      customContent: customContentConfig,
+      enableAgentVibes: agentVibesConfig.enabled,
       agentVibesInstalled: agentVibesConfig.alreadyInstalled,
     };
   }
@@ -483,19 +600,142 @@ class UI {
   /**
    * Get module choices for selection
    * @param {Set} installedModuleIds - Currently installed module IDs
+   * @param {Object} customContentConfig - Custom content configuration
    * @returns {Array} Module choices for inquirer
    */
-  async getModuleChoices(installedModuleIds) {
+  async getModuleChoices(installedModuleIds, customContentConfig = null) {
+    const moduleChoices = [];
+    const isNewInstallation = installedModuleIds.size === 0;
+
+    const customContentItems = [];
+    const hasCustomContentItems = false;
+
+    // Add custom content items
+    if (customContentConfig && customContentConfig.hasCustomContent) {
+      if (customContentConfig.cachedModules) {
+        // New installation - show cached modules
+        for (const cachedModule of customContentConfig.cachedModules) {
+          // Get the module info from cache
+          const yaml = require('js-yaml');
+          const fs = require('fs-extra');
+
+          // Try multiple possible config file locations
+          const possibleConfigPaths = [
+            path.join(cachedModule.cachePath, 'module.yaml'),
+            path.join(cachedModule.cachePath, 'custom.yaml'),
+            path.join(cachedModule.cachePath, '_module-installer', 'module.yaml'),
+            path.join(cachedModule.cachePath, '_module-installer', 'custom.yaml'),
+          ];
+
+          let moduleData = null;
+          let foundPath = null;
+
+          for (const configPath of possibleConfigPaths) {
+            if (await fs.pathExists(configPath)) {
+              try {
+                const yamlContent = await fs.readFile(configPath, 'utf8');
+                moduleData = yaml.load(yamlContent);
+                foundPath = configPath;
+                break;
+              } catch {
+                // Continue to next path
+              }
+            }
+          }
+
+          if (moduleData) {
+            // Use the name from the custom info if we have it
+            const moduleName = cachedModule.name || moduleData.name || cachedModule.id;
+
+            customContentItems.push({
+              name: `${chalk.cyan('✓')} ${moduleName} ${chalk.gray('(cached)')}`,
+              value: cachedModule.id, // Use module ID directly
+              checked: true, // Default to selected
+              cached: true,
+            });
+          } else {
+            // Debug: show what paths we tried to check
+            console.log(chalk.dim(`DEBUG: No module config found for ${cachedModule.id}`));
+            console.log(
+              chalk.dim(
+                `DEBUG: Tried paths:`,
+                possibleConfigPaths.map((p) => p.replace(cachedModule.cachePath, '.')),
+              ),
+            );
+            console.log(chalk.dim(`DEBUG: cachedModule:`, JSON.stringify(cachedModule, null, 2)));
+          }
+        }
+      } else if (customContentConfig.customPath) {
+        // Existing installation - show from directory
+        const { CustomHandler } = require('../installers/lib/custom/handler');
+        const customHandler = new CustomHandler();
+        const customFiles = await customHandler.findCustomContent(customContentConfig.customPath);
+
+        for (const customFile of customFiles) {
+          const customInfo = await customHandler.getCustomInfo(customFile);
+          if (customInfo) {
+            customContentItems.push({
+              name: `${chalk.cyan('✓')} ${customInfo.name} ${chalk.gray(`(${customInfo.relativePath})`)}`,
+              value: `__CUSTOM_CONTENT__${customFile}`, // Unique value for each custom content
+              checked: true, // Default to selected since user chose to provide custom content
+              path: customInfo.path, // Track path to avoid duplicates
+            });
+          }
+        }
+      }
+    }
+
+    // Add official modules
     const { ModuleManager } = require('../installers/lib/modules/manager');
-    const moduleManager = new ModuleManager();
-    const availableModules = await moduleManager.listAvailable();
+    // For new installations, don't scan project yet (will do after custom content is discovered)
+    // For existing installations, scan if user selected custom content
+    const shouldScanProject =
+      !isNewInstallation && customContentConfig && customContentConfig.hasCustomContent && customContentConfig.selected;
+    const moduleManager = new ModuleManager({
+      scanProjectForModules: shouldScanProject,
+    });
+    const { modules: availableModules, customModules: customModulesFromProject } = await moduleManager.listAvailable();
 
-    const isNewInstallation = installedModuleIds.size === 0;
-    const moduleChoices = availableModules.map((mod) => ({
-      name: mod.isCustom ? `${mod.name} ${chalk.red('(Custom)')}` : mod.name,
-      value: mod.id,
-      checked: isNewInstallation ? mod.defaultSelected || false : installedModuleIds.has(mod.id),
-    }));
+    // First, add all items to appropriate sections
+    const allCustomModules = [];
+
+    // Add custom content items from directory
+    allCustomModules.push(...customContentItems);
+
+    // Add custom modules from project scan (if scanning is enabled)
+    for (const mod of customModulesFromProject) {
+      // Skip if this module is already in customContentItems (by path)
+      const isDuplicate = allCustomModules.some((item) => item.path && mod.path && path.resolve(item.path) === path.resolve(mod.path));
+
+      if (!isDuplicate) {
+        allCustomModules.push({
+          name: `${chalk.cyan('✓')} ${mod.name} ${chalk.gray(`(${mod.source})`)}`,
+          value: mod.id,
+          checked: isNewInstallation ? mod.defaultSelected || false : installedModuleIds.has(mod.id),
+        });
+      }
+    }
+
+    // Add separators and modules in correct order
+    if (allCustomModules.length > 0) {
+      // Add separator for custom content, all custom modules, and official content separator
+      moduleChoices.push(
+        new inquirer.Separator('── Custom Content ──'),
+        ...allCustomModules,
+        new inquirer.Separator('── Official Content ──'),
+      );
+    }
+
+    // Add official modules (only non-custom ones)
+    for (const mod of availableModules) {
+      if (!mod.isCustom) {
+        moduleChoices.push({
+          name: mod.name,
+          value: mod.id,
+          checked: isNewInstallation ? mod.defaultSelected || false : installedModuleIds.has(mod.id),
+        });
+      }
+    }
 
     return moduleChoices;
   }
@@ -574,6 +814,116 @@ class UI {
     }
   }
 
+  /**
+   * Prompt for custom content location
+   * @returns {Object} Custom content configuration
+   */
+  async promptCustomContentLocation() {
+    try {
+      CLIUtils.displaySection('Custom Content', 'Optional: Add custom agents, workflows, and modules');
+
+      const { hasCustomContent } = await inquirer.prompt([
+        {
+          type: 'list',
+          name: 'hasCustomContent',
+          message: 'Do you have custom content to install?',
+          choices: [
+            { name: 'No (skip custom content)', value: 'none' },
+            { name: 'Enter a directory path', value: 'directory' },
+            { name: 'Enter a URL', value: 'url' },
+          ],
+          default: 'none',
+        },
+      ]);
+
+      if (hasCustomContent === 'none') {
+        return { hasCustomContent: false };
+      }
+
+      if (hasCustomContent === 'url') {
+        console.log(chalk.yellow('\nURL-based custom content installation is coming soon!'));
+        console.log(chalk.cyan('For now, please download your custom content and choose "Enter a directory path".\n'));
+        return { hasCustomContent: false };
+      }
+
+      if (hasCustomContent === 'directory') {
+        let customPath;
+        while (!customPath) {
+          let expandedPath;
+          const { directory } = await inquirer.prompt([
+            {
+              type: 'input',
+              name: 'directory',
+              message: 'Enter directory to search for custom content (will scan subfolders):',
+              default: process.cwd(), // Use actual current working directory
+              validate: async (input) => {
+                if (!input || input.trim() === '') {
+                  return 'Please enter a directory path';
+                }
+
+                try {
+                  expandedPath = this.expandUserPath(input.trim());
+                } catch (error) {
+                  return error.message;
+                }
+
+                // Check if the path exists
+                const pathExists = await fs.pathExists(expandedPath);
+                if (!pathExists) {
+                  return 'Directory does not exist';
+                }
+
+                return true;
+              },
+            },
+          ]);
+
+          // Now expand the path for use after the prompt
+          expandedPath = this.expandUserPath(directory.trim());
+
+          // Check if directory has custom content
+          const { CustomHandler } = require('../installers/lib/custom/handler');
+          const customHandler = new CustomHandler();
+          const customFiles = await customHandler.findCustomContent(expandedPath);
+
+          if (customFiles.length === 0) {
+            console.log(chalk.yellow(`\nNo custom content found in ${expandedPath}`));
+
+            const { tryAgain } = await inquirer.prompt([
+              {
+                type: 'confirm',
+                name: 'tryAgain',
+                message: 'Try a different directory?',
+                default: true,
+              },
+            ]);
+
+            if (tryAgain) {
+              continue;
+            } else {
+              return { hasCustomContent: false };
+            }
+          }
+
+          customPath = expandedPath;
+          console.log(chalk.green(`\n✓ Found ${customFiles.length} custom content item(s):`));
+          for (const file of customFiles) {
+            const relativePath = path.relative(expandedPath, path.dirname(file));
+            const folderName = path.dirname(file).split(path.sep).pop();
+            console.log(chalk.dim(`  • ${folderName} ${chalk.gray(`(${relativePath})`)}`));
+          }
+        }
+
+        return { hasCustomContent: true, customPath };
+      }
+
+      return { hasCustomContent: false };
+    } catch (error) {
+      console.error(chalk.red('Error in custom content prompt:'), error);
+      return { hasCustomContent: false };
+    }
+  }
+
   /**
    * Confirm directory selection
    * @param {string} directory - The directory path
@@ -859,6 +1209,144 @@ class UI {
 
     return (await fs.pathExists(hookPath)) && (await fs.pathExists(playTtsPath));
   }
+
+  /**
+   * Prompt for custom content for existing installations
+   * @returns {Object} Custom content configuration
+   */
+  async promptCustomContentForExisting() {
+    try {
+      CLIUtils.displaySection('Custom Content', 'Add new custom agents, workflows, or modules to your installation');
+
+      const { hasCustomContent } = await inquirer.prompt([
+        {
+          type: 'list',
+          name: 'hasCustomContent',
+          message: 'Do you want to add or update custom content?',
+          choices: [
+            {
+              name: 'No, continue with current installation only',
+              value: false,
+            },
+            {
+              name: 'Yes, I have custom content to add or update',
+              value: true,
+            },
+          ],
+          default: false,
+        },
+      ]);
+
+      if (!hasCustomContent) {
+        return { hasCustomContent: false };
+      }
+
+      // Get directory path
+      const { customPath } = await inquirer.prompt([
+        {
+          type: 'input',
+          name: 'customPath',
+          message: 'Enter directory to search for custom content (will scan subfolders):',
+          default: process.cwd(),
+          validate: async (input) => {
+            if (!input || input.trim() === '') {
+              return 'Please enter a directory path';
+            }
+
+            // Normalize and check if path exists
+            const expandedPath = CLIUtils.expandPath(input.trim());
+            const pathExists = await fs.pathExists(expandedPath);
+            if (!pathExists) {
+              return 'Directory does not exist';
+            }
+
+            // Check if it's actually a directory
+            const stats = await fs.stat(expandedPath);
+            if (!stats.isDirectory()) {
+              return 'Path must be a directory';
+            }
+
+            return true;
+          },
+          transformer: (input) => {
+            return CLIUtils.expandPath(input);
+          },
+        },
+      ]);
+
+      const resolvedPath = CLIUtils.expandPath(customPath);
+
+      // Find custom content
+      const { CustomHandler } = require('../installers/lib/custom/handler');
+      const customHandler = new CustomHandler();
+      const customFiles = await customHandler.findCustomContent(resolvedPath);
+
+      if (customFiles.length === 0) {
+        console.log(chalk.yellow(`\nNo custom content found in ${resolvedPath}`));
+
+        const { tryDifferent } = await inquirer.prompt([
+          {
+            type: 'confirm',
+            name: 'tryDifferent',
+            message: 'Try a different directory?',
+            default: true,
+          },
+        ]);
+
+        if (tryDifferent) {
+          return await this.promptCustomContentForExisting();
+        }
+
+        return { hasCustomContent: false };
+      }
+
+      // Display found items
+      console.log(chalk.cyan(`\nFound ${customFiles.length} custom content file(s):`));
+      const { CustomHandler: CustomHandler2 } = require('../installers/lib/custom/handler');
+      const customHandler2 = new CustomHandler2();
+      const customContentItems = [];
+
+      for (const customFile of customFiles) {
+        const customInfo = await customHandler2.getCustomInfo(customFile);
+        if (customInfo) {
+          customContentItems.push({
+            name: `${chalk.cyan('✓')} ${customInfo.name} ${chalk.gray(`(${customInfo.relativePath})`)}`,
+            value: `__CUSTOM_CONTENT__${customFile}`,
+            checked: true,
+          });
+        }
+      }
+
+      // Add option to keep existing custom content
+      console.log(chalk.yellow('\nExisting custom modules will be preserved unless you remove them'));
+
+      const { selectedFiles } = await inquirer.prompt([
+        {
+          type: 'checkbox',
+          name: 'selectedFiles',
+          message: 'Select custom content to add:',
+          choices: customContentItems,
+          pageSize: 15,
+          validate: (answer) => {
+            if (answer.length === 0) {
+              return 'You must select at least one item';
+            }
+            return true;
+          },
+        },
+      ]);
+
+      return {
+        hasCustomContent: true,
+        customPath: resolvedPath,
+        selected: true,
+        selectedFiles: selectedFiles,
+      };
+    } catch (error) {
+      console.error(chalk.red('Error configuring custom content:'), error);
+      return { hasCustomContent: false };
+    }
+  }
 }
 
 module.exports = { UI };

package/tools/maintainer/review-pr-README.md

@@ -0,0 +1,55 @@
+# Raven's Verdict - Deep PR Review Tool
+
+Adversarial code review for GitHub PRs. Works with any LLM agent.
+
+> **Status: Experimental.** We're still figuring out how to use this effectively. Expect the workflow to evolve.
+
+## How It Works
+
+Point your agent at `review-pr.md` and ask it to review a specific PR:
+
+> "Read tools/maintainer/review-pr.md and apply it to PR #123"
+
+The tool will:
+
+1. Check out the PR branch locally
+2. Run an adversarial review (find at least 5 issues)
+3. Transform findings into professional tone
+4. Preview the review and ask before posting
+
+See `review-pr.md` for full prompt structure, severity ratings, and sandboxing rules.
+
+## When to Use
+
+**Good candidates:**
+
+- PRs with meaningful logic changes
+- Refactors touching multiple files
+- New features or architectural changes
+
+**Skip it for:**
+
+- Trivial PRs (typo fixes, version bumps, single-line changes)
+- PRs you've already reviewed manually
+- PRs where you haven't agreed on the approach yet — fix the direction before the implementation
+
+## Workflow Tips
+
+**Always review before posting.** The preview step exists for a reason:
+
+- **[y] Yes** — Post as-is (only if you're confident)
+- **[e] Edit** — Modify findings before posting
+- **[s] Save only** — Write to file, don't post
+
+The save option is useful when you want to:
+
+- Hand-edit the review before posting
+- Use the findings as input for a second opinion ("Hey Claude, here's what Raven found — what do you think?")
+- Cherry-pick specific findings
+
+**Trust but verify.** LLM reviews can miss context or flag non-issues. Skim the findings before they hit the PR.
+
+## Prerequisites
+
+- `gh` CLI installed and authenticated (`gh auth status`)
+- Any LLM agent capable of running bash commands