bmad-method 4.27.5 → 4.28.0

package/dist/teams/team-no-ui.txt

@@ -63,9 +63,6 @@ CRITICAL: Read the full YAML, start activation to alter your state of being, fol
 ```yaml
 activation-instructions:
   - Mention *help shows all available commands and options
-  - Check for active workflow plan using .bmad-core/utils/plan-management.md
-  - 'If plan exists: Show 📋 Active plan: {workflow} ({progress}% complete). Use *plan-status for details.'
-  - 'If plan exists: Suggest next action based on plan progress'
   - Assess user goal against available agents and workflows in this bundle
   - If clear match to an agent's expertise, suggest transformation with *agent command
   - If project-oriented, suggest *workflow-guidance to explore options
@@ -187,7 +184,6 @@ dependencies:
     - bmad-kb.md
     - elicitation-methods.md
   utils:
-    - plan-management.md
     - workflow-management.md
 ```
 ==================== END: .bmad-core/agents/bmad-orchestrator.md ====================
@@ -1988,7 +1984,7 @@ For full details, see `CONTRIBUTING.md`. Key points:
 - Atomic commits - one logical change per commit
 - Must align with guiding principles
 
-**Core Principles** (from GUIDING-PRINCIPLES.md):
+**Core Principles** (from docs/GUIDING-PRINCIPLES.md):
 
 - **Dev Agents Must Be Lean**: Minimize dependencies, save context for code
 - **Natural Language First**: Everything in markdown, no code in core
@@ -2058,8 +2054,8 @@ Use the **expansion-creator** pack to build your own:
 
 ## Getting Help
 
-- **Commands**: Use `/help` in any environment to see available commands
-- **Agent Switching**: Use `/switch agent-name` with orchestrator for role changes
+- **Commands**: Use `*/*help` in any environment to see available commands
+- **Agent Switching**: Use `*/*switch agent-name` with orchestrator for role changes
 - **Documentation**: Check `docs/` folder for project-specific context
 - **Community**: Discord and GitHub resources available for support
 - **Contributing**: See `CONTRIBUTING.md` for full guidelines
@@ -2202,228 +2198,6 @@ Use the **expansion-creator** pack to build your own:
 - Prepare to continue without additional elicitation
 ==================== END: .bmad-core/data/elicitation-methods.md ====================
 
-==================== START: .bmad-core/utils/plan-management.md ====================
-# 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
-==================== END: .bmad-core/utils/plan-management.md ====================
-
 ==================== START: .bmad-core/utils/workflow-management.md ====================
 # Workflow Management
 
@@ -8574,7 +8348,7 @@ To comprehensively validate a story draft before implementation begins, ensuring
 
 ### 0. Load Core Configuration and Inputs
 
-- Load `.bmad-core/core-config.yaml` from the project root
+- Load `.bmad-core/core-config.yaml`
 - If the file does not exist, HALT and inform the user: "core-config.yaml not found. This file is required for story validation."
 - Extract key configurations: `devStoryLocation`, `prd.*`, `architecture.*`
 - Identify and load the following inputs:
@@ -9624,7 +9398,7 @@ workflow:
         All stories implemented and reviewed!
         Project development phase complete.
         
-        Reference: data#bmad-kb:IDE Development Workflow
+        Reference: .bmad-core/data/bmad-kb.md#IDE Development Workflow
 
   flow_diagram: |
     ```mermaid

package/docs/agentic-tools/claude-code-guide.md

@@ -7,7 +7,7 @@ For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.
 When running `npx bmad-method install`, select **Claude Code** as your IDE. This creates:
 
 - `.bmad-core/` folder with all agents
-- `.claude/commands/` folder with agent command files (`.md`)
+- `.claude/commands/BMad` folder with agent command files (`.md`)
 
 ## Using BMad Agents in Claude Code
 

package/docs/agentic-tools/gemini-cli-guide.md

@@ -6,23 +6,22 @@ For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.
 
 When running `npx bmad-method install`, select **Gemini CLI** as your IDE. This creates:
 
-- `.gemini/agents/` directory with all agent context files
-- `.gemini/settings.json` configured to load all agents automatically
+- `.gemini/bmad-method/` directory with all agent context in GEMINI.md file
 
 ## Using BMad Agents with Gemini CLI
 
 Simply mention the agent in your prompt:
 
-- "As @dev, implement the login feature"
-- "Acting as @architect, review this system design"
-- "@sm, create the next story for our project"
+- "As \*dev, implement the login feature"
+- "Acting as \*architect, review this system design"
+- "\*sm, create the next story for our project"
 
 The Gemini CLI automatically loads the appropriate agent context.
 
 ## Gemini CLI-Specific Features
 
-- **Context files**: All agents loaded as context in `.gemini/agents/`
-- **Automatic loading**: Settings.json ensures agents are always available
+- **Context files**: All agents loaded as context in `.gemini/bmad-method/GEMINI.md`
+- **Automatic loading**: GEMINI.md ensures agents are always available
 - **Natural language**: No special syntax needed, just mention the agent
 
 ## Tips for Gemini CLI Users

package/docs/bmad-workflow-guide.md

@@ -111,6 +111,7 @@ Follow the SM → Dev cycle for systematic story development:
 
 - **Claude Code**: `/agent-name` (e.g., `/bmad-master`)
 - **Cursor**: `@agent-name` (e.g., `@bmad-master`)
+- **Gemini CLI**: `*agent-name` (e.g., `*bmad-master`)
 - **Windsurf**: `@agent-name` (e.g., `@bmad-master`)
 - **Trae**: `@agent-name` (e.g., `@bmad-master`)
 - **Roo Code**: Select mode from mode selector (e.g., `bmad-bmad-master`)

package/expansion-packs/bmad-2d-phaser-game-dev/agents/game-designer.md

@@ -3,9 +3,8 @@
 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:
 
 ```yaml
-root: .bmad-2d-phaser-game-dev
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

package/expansion-packs/bmad-2d-phaser-game-dev/agents/game-developer.md

@@ -3,9 +3,8 @@
 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:
 
 ```yaml
-root: .bmad-2d-phaser-game-dev
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

package/expansion-packs/bmad-2d-phaser-game-dev/agents/game-sm.md

@@ -3,9 +3,8 @@
 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:
 
 ```yaml
-root: .bmad-2d-phaser-game-dev
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

package/expansion-packs/bmad-creator-tools/agents/bmad-the-creator.md

@@ -3,9 +3,8 @@
 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:
 
 ```yaml
-root: .bmad-creator-tools
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

package/expansion-packs/bmad-infrastructure-devops/agents/infra-devops-platform.md

@@ -3,9 +3,8 @@
 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:
 
 ```yaml
-root: .bmad-infrastructure-devops
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmad-method",
-  "version": "4.27.5",
+  "version": "4.28.0",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "main": "tools/cli.js",
   "bin": {

package/tools/installer/config/install.config.yaml

@@ -21,7 +21,7 @@ ide-configurations:
       # 3. The agent will adopt that persona for the conversation
   claude-code:
     name: Claude Code
-    rule-dir: .claude/commands/
+    rule-dir: .claude/commands/BMad/
     format: multi-file
     command-suffix: .md
     instructions: |
@@ -68,13 +68,14 @@ ide-configurations:
       # 4. Rules are stored in .clinerules/ directory in your project
   gemini:
     name: Gemini CLI
-    rule-dir: .gemini/agents/
-    format: context-files
+    rule-dir: .gemini/bmad-method/
+    format: single-file
+    command-suffix: .md
     instructions: |
       # To use BMad agents with the Gemini CLI:
-      # 1. The installer creates a .gemini/ directory in your project.
-      # 2. It also configures .gemini/settings.json to load all agent files.
-      # 3. Simply mention the agent in your prompt (e.g., "As @dev, ...").
+      # 1. The installer creates a .gemini/bmad-method/ directory in your project.
+      # 2. It concatenates all agent files into a single GEMINI.md file.
+      # 3. Simply mention the agent in your prompt (e.g., "As *dev, ...").
       # 4. The Gemini CLI will automatically have the context for that agent.
   github-copilot:
     name: Github Copilot

package/tools/installer/lib/file-manager.js

@@ -47,7 +47,7 @@ class FileManager {
     }
   }
 
-  async copyGlobPattern(pattern, sourceDir, destDir) {
+  async copyGlobPattern(pattern, sourceDir, destDir, rootValue = null) {
     const files = glob.sync(pattern, { cwd: sourceDir });
     const copied = [];
 
@@ -55,7 +55,17 @@ class FileManager {
       const sourcePath = path.join(sourceDir, file);
       const destPath = path.join(destDir, file);
 
-      if (await this.copyFile(sourcePath, destPath)) {
+      // Use root replacement if rootValue is provided and file needs it
+      const needsRootReplacement = rootValue && (file.endsWith('.md') || file.endsWith('.yaml') || file.endsWith('.yml'));
+      
+      let success = false;
+      if (needsRootReplacement) {
+        success = await this.copyFileWithRootReplacement(sourcePath, destPath, rootValue);
+      } else {
+        success = await this.copyFile(sourcePath, destPath);
+      }
+
+      if (success) {
         copied.push(file);
       }
     }
@@ -299,6 +309,71 @@ class FileManager {
       return false;
     }
   }
+
+  async copyFileWithRootReplacement(source, destination, rootValue) {
+    try {
+      // Read the source file content
+      const fs = require('fs').promises;
+      const content = await fs.readFile(source, 'utf8');
+      
+      // Replace {root} with the specified root value
+      const updatedContent = content.replace(/\{root\}/g, rootValue);
+      
+      // Ensure directory exists
+      await this.ensureDirectory(path.dirname(destination));
+      
+      // Write the updated content
+      await fs.writeFile(destination, updatedContent, 'utf8');
+      
+      return true;
+    } catch (error) {
+      await initializeModules();
+      console.error(chalk.red(`Failed to copy ${source} with root replacement:`), error.message);
+      return false;
+    }
+  }
+
+  async copyDirectoryWithRootReplacement(source, destination, rootValue, fileExtensions = ['.md', '.yaml', '.yml']) {
+    try {
+      await initializeModules(); // Ensure chalk is initialized
+      await this.ensureDirectory(destination);
+      
+      // Get all files in source directory
+      const files = glob.sync('**/*', { 
+        cwd: source, 
+        nodir: true 
+      });
+      
+      let replacedCount = 0;
+      
+      for (const file of files) {
+        const sourcePath = path.join(source, file);
+        const destPath = path.join(destination, file);
+        
+        // Check if this file type should have {root} replacement
+        const shouldReplace = fileExtensions.some(ext => file.endsWith(ext));
+        
+        if (shouldReplace) {
+          if (await this.copyFileWithRootReplacement(sourcePath, destPath, rootValue)) {
+            replacedCount++;
+          }
+        } else {
+          // Regular copy for files that don't need replacement
+          await this.copyFile(sourcePath, destPath);
+        }
+      }
+      
+      if (replacedCount > 0) {
+        console.log(chalk.dim(`  Processed ${replacedCount} files with {root} replacement`));
+      }
+      
+      return true;
+    } catch (error) {
+      await initializeModules();
+      console.error(chalk.red(`Failed to copy directory ${source} with root replacement:`), error.message);
+      return false;
+    }
+  }
 }
 
 module.exports = new FileManager();