bmad-method 4.27.5 → 4.28.0

package/tools/installer/lib/ide-setup.js

@@ -131,7 +131,7 @@ class IdeSetup {
   }
 
   async setupClaudeCode(installDir, selectedAgent) {
-    const commandsDir = path.join(installDir, ".claude", "commands");
+    const commandsDir = path.join(installDir, ".claude", "commands", "BMad");
     const agents = selectedAgent ? [selectedAgent] : await this.getAllAgentIds(installDir);
 
     await fileManager.ensureDirectory(commandsDir);
@@ -512,12 +512,53 @@ class IdeSetup {
   async setupGeminiCli(installDir, selectedAgent) {
     await initializeModules();
     const geminiDir = path.join(installDir, ".gemini");
-    const agentsContextDir = path.join(geminiDir, "agents");
-    await fileManager.ensureDirectory(agentsContextDir);
+    const bmadMethodDir = path.join(geminiDir, "bmad-method");
+    await fileManager.ensureDirectory(bmadMethodDir);
+
+    // Update logic for existing settings.json
+    const settingsPath = path.join(geminiDir, "settings.json");
+    if (await fileManager.pathExists(settingsPath)) {
+      try {
+        const settingsContent = await fileManager.readFile(settingsPath);
+        const settings = JSON.parse(settingsContent);
+        let updated = false;
+        
+        // Handle contextFileName property
+        if (settings.contextFileName && Array.isArray(settings.contextFileName)) {
+          const originalLength = settings.contextFileName.length;
+          settings.contextFileName = settings.contextFileName.filter(
+            (fileName) => !fileName.startsWith("agents/")
+          );
+          if (settings.contextFileName.length !== originalLength) {
+            updated = true;
+          }
+        }
+        
+        if (updated) {
+          await fileManager.writeFile(
+            settingsPath,
+            JSON.stringify(settings, null, 2)
+          );
+          console.log(chalk.green("✓ Updated .gemini/settings.json - removed agent file references"));
+        }
+      } catch (error) {
+        console.warn(
+          chalk.yellow("Could not update .gemini/settings.json"),
+          error
+        );
+      }
+    }
+
+    // Remove old agents directory
+    const agentsDir = path.join(geminiDir, "agents");
+    if (await fileManager.pathExists(agentsDir)) {
+      await fileManager.removeDirectory(agentsDir);
+      console.log(chalk.green("✓ Removed old .gemini/agents directory"));
+    }
 
     // Get all available agents
     const agents = await this.getAllAgentIds(installDir);
-    const agentContextFiles = [];
+    let concatenatedContent = "";
 
     for (const agentId of agents) {
       // Find the source agent file
@@ -525,43 +566,46 @@ class IdeSetup {
 
       if (agentPath) {
         const agentContent = await fileManager.readFile(agentPath);
-        const contextFilePath = path.join(agentsContextDir, `${agentId}.md`);
-
-        // Copy the agent content directly into its own context file
-        await fileManager.writeFile(contextFilePath, agentContent);
-
-        // Store the relative path for settings.json
-        const relativePath = path.relative(geminiDir, contextFilePath);
-        agentContextFiles.push(relativePath.replace(/\\/g, '/')); // Ensure forward slashes for consistency
-        console.log(chalk.green(`✓ Created context file for @${agentId}`));
-      }
-    }
-
-    console.log(chalk.green(`\n✓ Created individual agent context files in ${agentsContextDir}`));
-
-    // Add GEMINI.md to the context files array
-    agentContextFiles.push("GEMINI.md");
-
-    // Create or update settings.json
-    const settingsPath = path.join(geminiDir, "settings.json");
-    let settings = {};
-
-    if (await fileManager.pathExists(settingsPath)) {
-      try {
-        const existingSettings = await fileManager.readFile(settingsPath);
-        settings = JSON.parse(existingSettings);
-        console.log(chalk.yellow("Found existing .gemini/settings.json. Merging settings..."));
-      } catch (e) {
-        console.error(chalk.red("Error parsing existing settings.json. It will be overwritten."), e);
-        settings = {};
+        
+        // Create properly formatted agent rule content (similar to trae)
+        let agentRuleContent = `# ${agentId.toUpperCase()} Agent Rule\n\n`;
+        agentRuleContent += `This rule is triggered when the user types \`*${agentId}\` and activates the ${await this.getAgentTitle(
+          agentId,
+          installDir
+        )} agent persona.\n\n`;
+        agentRuleContent += "## Agent Activation\n\n";
+        agentRuleContent +=
+          "CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:\n\n";
+        agentRuleContent += "```yaml\n";
+        // Extract just the YAML content from the agent file
+        const yamlContent = extractYamlFromAgent(agentContent);
+        if (yamlContent) {
+          agentRuleContent += yamlContent;
+        }
+        else {
+          // If no YAML found, include the whole content minus the header
+          agentRuleContent += agentContent.replace(/^#.*$/m, "").trim();
+        }
+        agentRuleContent += "\n```\n\n";
+        agentRuleContent += "## File Reference\n\n";
+        const relativePath = path.relative(installDir, agentPath).replace(/\\/g, '/');
+        agentRuleContent += `The complete agent definition is available in [${relativePath}](${relativePath}).\n\n`;
+        agentRuleContent += "## Usage\n\n";
+        agentRuleContent += `When the user types \`*${agentId}\`, activate this ${await this.getAgentTitle(
+          agentId,
+          installDir
+        )} persona and follow all instructions defined in the YAML configuration above.\n`;
+        
+        // Add to concatenated content with separator
+        concatenatedContent += agentRuleContent + "\n\n---\n\n";
+        console.log(chalk.green(`✓ Added context for @${agentId}`));
       }
     }
 
-    // Set contextFileName to our new array of files
-    settings.contextFileName = agentContextFiles;
-
-    await fileManager.writeFile(settingsPath, JSON.stringify(settings, null, 2));
-    console.log(chalk.green(`✓ Configured .gemini/settings.json to load all agent context files.`));
+    // Write the concatenated content to GEMINI.md
+    const geminiMdPath = path.join(bmadMethodDir, "GEMINI.md");
+    await fileManager.writeFile(geminiMdPath, concatenatedContent);
+    console.log(chalk.green(`\n✓ Created GEMINI.md in ${bmadMethodDir}`));
 
     return true;
   }

package/tools/installer/lib/installer.js

@@ -244,7 +244,7 @@ class Installer {
       spinner.text = "Copying complete .bmad-core folder...";
       const sourceDir = configLoader.getBmadCorePath();
       const bmadCoreDestDir = path.join(installDir, ".bmad-core");
-      await fileManager.copyDirectory(sourceDir, bmadCoreDestDir);
+      await fileManager.copyDirectoryWithRootReplacement(sourceDir, bmadCoreDestDir, ".bmad-core");
       
       // Copy common/ items to .bmad-core
       spinner.text = "Copying common utilities...";
@@ -263,7 +263,7 @@ class Installer {
       // Single agent installation
       spinner.text = `Installing ${config.agent} agent...`;
 
-      // Copy agent file
+      // Copy agent file with {root} replacement
       const agentPath = configLoader.getAgentPath(config.agent);
       const destAgentPath = path.join(
         installDir,
@@ -271,7 +271,7 @@ class Installer {
         "agents",
         `${config.agent}.md`
       );
-      await fileManager.copyFile(agentPath, destAgentPath);
+      await fileManager.copyFileWithRootReplacement(agentPath, destAgentPath, ".bmad-core");
       files.push(`.bmad-core/agents/${config.agent}.md`);
 
       // Copy dependencies
@@ -284,15 +284,16 @@ class Installer {
         spinner.text = `Copying dependency: ${dep}`;
 
         if (dep.includes("*")) {
-          // Handle glob patterns
+          // Handle glob patterns with {root} replacement
           const copiedFiles = await fileManager.copyGlobPattern(
             dep.replace(".bmad-core/", ""),
             sourceBase,
-            path.join(installDir, ".bmad-core")
+            path.join(installDir, ".bmad-core"),
+            ".bmad-core"
           );
           files.push(...copiedFiles.map(f => `.bmad-core/${f}`));
         } else {
-          // Handle single files
+          // Handle single files with {root} replacement if needed
           const sourcePath = path.join(
             sourceBase,
             dep.replace(".bmad-core/", "")
@@ -302,7 +303,16 @@ class Installer {
             dep
           );
 
-          if (await fileManager.copyFile(sourcePath, destPath)) {
+          const needsRootReplacement = dep.endsWith('.md') || dep.endsWith('.yaml') || dep.endsWith('.yml');
+          let success = false;
+          
+          if (needsRootReplacement) {
+            success = await fileManager.copyFileWithRootReplacement(sourcePath, destPath, ".bmad-core");
+          } else {
+            success = await fileManager.copyFile(sourcePath, destPath);
+          }
+
+          if (success) {
             files.push(dep);
           }
         }
@@ -325,19 +335,29 @@ class Installer {
         spinner.text = `Copying team dependency: ${dep}`;
         
         if (dep.includes("*")) {
-          // Handle glob patterns
+          // Handle glob patterns with {root} replacement
           const copiedFiles = await fileManager.copyGlobPattern(
             dep.replace(".bmad-core/", ""),
             sourceBase,
-            path.join(installDir, ".bmad-core")
+            path.join(installDir, ".bmad-core"),
+            ".bmad-core"
           );
           files.push(...copiedFiles.map(f => `.bmad-core/${f}`));
         } else {
-          // Handle single files
+          // Handle single files with {root} replacement if needed
           const sourcePath = path.join(sourceBase, dep.replace(".bmad-core/", ""));
           const destPath = path.join(installDir, dep);
           
-          if (await fileManager.copyFile(sourcePath, destPath)) {
+          const needsRootReplacement = dep.endsWith('.md') || dep.endsWith('.yaml') || dep.endsWith('.yml');
+          let success = false;
+          
+          if (needsRootReplacement) {
+            success = await fileManager.copyFileWithRootReplacement(sourcePath, destPath, ".bmad-core");
+          } else {
+            success = await fileManager.copyFile(sourcePath, destPath);
+          }
+
+          if (success) {
             files.push(dep);
           }
         }
@@ -1172,32 +1192,41 @@ class Installer {
               nodir: true
             });
 
-            // Copy each file to the expansion pack's dot folder
+            // Copy each file to the expansion pack's dot folder with {root} replacement
             for (const file of files) {
               const sourcePath = path.join(sourceFolder, file);
               const destPath = path.join(expansionDotFolder, folder, file);
               
-              if (await fileManager.copyFile(sourcePath, destPath)) {
+              const needsRootReplacement = file.endsWith('.md') || file.endsWith('.yaml') || file.endsWith('.yml');
+              let success = false;
+              
+              if (needsRootReplacement) {
+                success = await fileManager.copyFileWithRootReplacement(sourcePath, destPath, `.${packId}`);
+              } else {
+                success = await fileManager.copyFile(sourcePath, destPath);
+              }
+              
+              if (success) {
                 installedFiles.push(path.join(`.${packId}`, folder, file));
               }
             }
           }
         }
 
-        // Copy config.yaml
+        // Copy config.yaml with {root} replacement
         const configPath = path.join(expansionPackDir, 'config.yaml');
         if (await fileManager.pathExists(configPath)) {
           const configDestPath = path.join(expansionDotFolder, 'config.yaml');
-          if (await fileManager.copyFile(configPath, configDestPath)) {
+          if (await fileManager.copyFileWithRootReplacement(configPath, configDestPath, `.${packId}`)) {
             installedFiles.push(path.join(`.${packId}`, 'config.yaml'));
           }
         }
         
-        // Copy README if it exists
+        // Copy README if it exists with {root} replacement
         const readmePath = path.join(expansionPackDir, 'README.md');
         if (await fileManager.pathExists(readmePath)) {
           const readmeDestPath = path.join(expansionDotFolder, 'README.md');
-          if (await fileManager.copyFile(readmePath, readmeDestPath)) {
+          if (await fileManager.copyFileWithRootReplacement(readmePath, readmeDestPath, `.${packId}`)) {
             installedFiles.push(path.join(`.${packId}`, 'README.md'));
           }
         }
@@ -1258,7 +1287,7 @@ class Installer {
       const yamlContent = extractYamlFromAgent(agentContent);
       if (yamlContent) {
         try {
-          const agentConfig = yaml.parse(yamlContent);
+          const agentConfig = yaml.load(yamlContent);
           const dependencies = agentConfig.dependencies || {};
           
           // Check for core dependencies (those that don't exist in the expansion pack)
@@ -1277,9 +1306,9 @@ class Installer {
                 if (await fileManager.pathExists(coreDepPath)) {
                   spinner.text = `Copying core dependency ${dep} for ${packId}...`;
                   
-                  // Copy from core to expansion pack dot folder
+                  // Copy from core to expansion pack dot folder with {root} replacement
                   const destPath = path.join(expansionDotFolder, depType, depFileName);
-                  await fileManager.copyFile(coreDepPath, destPath);
+                  await fileManager.copyFileWithRootReplacement(coreDepPath, destPath, `.${packId}`);
                   
                   console.log(chalk.dim(`  Added core dependency: ${depType}/${depFileName}`));
                 } else {
@@ -1321,7 +1350,7 @@ class Installer {
       const teamContent = await fs.readFile(teamPath, 'utf8');
       
       try {
-        const teamConfig = yaml.parse(teamContent);
+        const teamConfig = yaml.load(teamContent);
         const agents = teamConfig.agents || [];
         
         // Add bmad-orchestrator if not present (required for all teams)
@@ -1338,9 +1367,9 @@ class Installer {
             if (await fileManager.pathExists(coreAgentPath)) {
               spinner.text = `Copying core agent ${agentId} for ${packId}...`;
               
-              // Copy agent file
+              // Copy agent file with {root} replacement
               const destPath = path.join(expansionDotFolder, 'agents', `${agentId}.md`);
-              await fileManager.copyFile(coreAgentPath, destPath);
+              await fileManager.copyFileWithRootReplacement(coreAgentPath, destPath, `.${packId}`);
               existingAgents.add(agentId);
               
               console.log(chalk.dim(`  Added core agent: ${agentId}`));
@@ -1352,7 +1381,7 @@ class Installer {
               if (yamlContent) {
                 try {
                   
-                  const agentConfig = yaml.parse(yamlContent);
+                  const agentConfig = yaml.load(yamlContent);
                   const dependencies = agentConfig.dependencies || {};
                   
                   // Copy all dependencies for this agent
@@ -1370,7 +1399,7 @@ class Installer {
                         
                         if (await fileManager.pathExists(coreDepPath)) {
                           const destDepPath = path.join(expansionDotFolder, depType, depFileName);
-                          await fileManager.copyFile(coreDepPath, destDepPath);
+                          await fileManager.copyFileWithRootReplacement(coreDepPath, destDepPath, `.${packId}`);
                           console.log(chalk.dim(`    Added agent dependency: ${depType}/${depFileName}`));
                         } else {
                           // Try common folder

package/tools/installer/package.json

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

package/tools/upgraders/v3-to-v4-upgrader.js

@@ -558,7 +558,7 @@ class V3ToV4Upgrader {
     try {
       const ideMessages = {
         cursor: "Rules created in .cursor/rules/",
-        "claude-code": "Commands created in .claude/commands/",
+        "claude-code": "Commands created in .claude/commands/BMad/",
         windsurf: "Rules created in .windsurf/rules/",
         trae: "Rules created in.trae/rules/",
         roo: "Custom modes created in .roomodes",

package/bmad-core/utils/plan-management.md

@@ -1,219 +0,0 @@
-# Plan Management Utility
-
-## Purpose
-
-Provides utilities for agents and tasks to interact with workflow plans, check progress, update status, and ensure workflow steps are executed in the appropriate sequence.
-
-## Core Functions
-
-### 1. Check Plan Existence
-
-Check for workflow plan:
-
-1. Look for docs/workflow-plan.md (default location)
-2. Return plan status to user (exists/not exists) - if not exists then HALT.
-
-### 2. Parse Plan Status
-
-[[LLM: Extract current progress from the plan document]]
-
-**Plan Parsing Logic:**
-
-1. **Identify Step Structure**:
-   - Look for checkbox lines: `- [ ]` or `- [x]`
-   - Extract step IDs from comments: `<!-- step-id: X.Y -->`
-   - Identify agent assignments: `<!-- agent: pm -->`
-
-2. **Determine Current State**:
-   - Last completed step (highest numbered `[x]`)
-   - Next expected step (first `[ ]` after completed steps)
-   - Overall progress percentage
-
-3. **Extract Metadata**:
-   - Workflow type from plan header
-   - Decision points and their status
-   - Any deviation notes
-
-### 3. Sequence Validation
-
-[[LLM: Check if requested action aligns with plan sequence]]
-
-**Validation Rules:**
-
-1. **Strict Mode** (enforceSequence: true):
-   - Must complete steps in exact order
-   - Warn and block if out of sequence
-   - Require explicit override justification
-
-2. **Flexible Mode** (enforceSequence: false):
-   - Warn about sequence deviation
-   - Allow with confirmation
-   - Log deviation reason
-
-**Warning Templates:**
-
-```text
-SEQUENCE WARNING: 
-The workflow plan shows you should complete "{expected_step}" next.
-You're attempting to: "{requested_action}"
-
-In strict mode: Block and require plan update
-In flexible mode: Allow with confirmation
-```
-
-### 4. Plan Update Operations
-
-[[LLM: Provide consistent way to update plan progress]]
-
-**Update Actions:**
-
-1. **Mark Step Complete**:
-   - Change `- [ ]` to `- [x]`
-   - Add completion timestamp comment
-   - Update any status metadata
-
-2. **Add Deviation Note**:
-   - Insert note explaining why sequence changed
-   - Reference the deviation in plan
-
-3. **Update Current Step Pointer**:
-   - Add/move `<!-- current-step -->` marker
-   - Update last-modified timestamp
-
-### 5. Integration Instructions
-
-[[LLM: How agents and tasks should use this utility]]
-
-**For Agents (startup sequence)**:
-
-```text
-1. Check if plan exists using this utility
-2. If exists:
-   - Parse current status
-   - Show user: "Active workflow plan detected. Current step: {X}"
-   - Suggest: "Next recommended action: {next_step}"
-3. Continue with normal startup
-```
-
-**For Tasks (pre-execution)**:
-
-```text
-1. Check if plan exists
-2. If exists:
-   - Verify this task aligns with plan
-   - If not aligned:
-     - In strict mode: Show warning and stop
-     - In flexible mode: Show warning and ask for confirmation
-3. After task completion:
-   - Update plan if task was a planned step
-   - Add note if task was unplanned
-```
-
-### 6. Plan Status Report Format
-
-[[LLM: Standard format for showing plan status]]
-
-```text
-📋 Workflow Plan Status
-━━━━━━━━━━━━━━━━━━━━
-Workflow: {workflow_name}
-Progress: {X}% complete ({completed}/{total} steps)
-
-✅ Completed:
-- {completed_step_1}
-- {completed_step_2}
-
-🔄 Current Step:
-- {current_step_description}
-
-📌 Upcoming:
-- {next_step_1}
-- {next_step_2}
-
-⚠️ Notes:
-- {any_deviations_or_notes}
-```
-
-### 7. Decision Point Handling
-
-[[LLM: Special handling for workflow decision points]]
-
-When encountering a decision point in the plan:
-
-1. **Identify Decision Marker**: `<!-- decision: {decision_id} -->`
-2. **Check Decision Status**: Made/Pending
-3. **If Pending**: 
-   - Block progress until decision made
-   - Show options to user
-   - Record decision when made
-4. **If Made**: 
-   - Verify current path aligns with decision
-   - Warn if attempting alternate path
-
-### 8. Plan Abandonment
-
-[[LLM: Graceful handling when user wants to stop following plan]]
-
-If user wants to abandon plan:
-
-1. Confirm abandonment intent
-2. Add abandonment note to plan
-3. Mark plan as "Abandoned" in header
-4. Stop plan checking for remainder of session
-5. Suggest creating new plan if needed
-
-## Usage Examples
-
-### Example 1: Agent Startup Check
-
-```text
-BMad Master starting...
-
-[Check for plan]
-Found active workflow plan: brownfield-fullstack
-Progress: 40% complete (4/10 steps)
-Current step: Create PRD (pm agent)
-
-Suggestion: Based on your plan, you should work with the PM agent next.
-Use *agent pm to switch, or *plan-status to see full progress.
-```
-
-### Example 2: Task Sequence Warning
-
-```text
-User: *task create-next-story
-
-[Plan check triggered]
-⚠️ SEQUENCE WARNING: 
-Your workflow plan indicates the PRD hasn't been created yet.
-Creating stories before the PRD may lead to incomplete requirements.
-
-Would you like to:
-1. Continue anyway (will note deviation in plan)
-2. Switch to creating PRD first (*agent pm)
-3. View plan status (*plan-status)
-```
-
-### Example 3: Automatic Plan Update
-
-```text
-[After completing create-doc task for PRD]
-
-✅ Plan Updated: Marked "Create PRD" as complete
-📍 Next step: Create Architecture Document (architect agent)
-```
-
-## Implementation Notes
-
-- This utility should be lightweight and fast
-- Plan parsing should be resilient to format variations
-- Always preserve user agency - warnings not blocks (unless strict mode)
-- Plan updates should be atomic to prevent corruption
-- Consider plan versioning for rollback capability
-
-## Error Handling
-
-- Missing plan: Return null, don't error
-- Malformed plan: Warn but continue, treat as no plan
-- Update failures: Log but don't block task completion
-- Parse errors: Fallback to basic text search