bmad-method 6.0.0-Beta.1 → 6.0.0-Beta.2

package/tools/cli/installers/lib/ide/shared/path-utils.js

@@ -2,7 +2,16 @@
  * Path transformation utilities for IDE installer standardization
  *
  * Provides utilities to convert hierarchical paths to flat naming conventions.
- * - Underscore format (bmad_module_name.md) - Windows-compatible universal format
+ *
+ * DASH-BASED NAMING (new standard):
+ * - Agents: bmad-module-name.agent.md (with .agent.md suffix)
+ * - Workflows/Tasks/Tools: bmad-module-name.md
+ *
+ * Example outputs:
+ * - cis/agents/storymaster.md → bmad-cis-storymaster.agent.md
+ * - bmm/workflows/plan-project.md → bmad-bmm-plan-project.md
+ * - bmm/tasks/create-story.md → bmad-bmm-create-story.md
+ * - core/agents/brainstorming.md → bmad-brainstorming.agent.md
  */
 
 // Type segments - agents are included in naming, others are filtered out
@@ -10,19 +19,148 @@ const TYPE_SEGMENTS = ['workflows', 'tasks', 'tools'];
 const AGENT_SEGMENT = 'agents';
 
 /**
- * Convert hierarchical path to flat underscore-separated name
- * Converts: 'bmm', 'agents', 'pm' → 'bmad_bmm_agent_pm.md'
- * Converts: 'bmm', 'workflows', 'correct-course' → 'bmad_bmm_correct-course.md'
- * Converts: 'core', 'agents', 'brainstorming' → 'bmad_agent_brainstorming.md' (core items skip module prefix)
+ * Convert hierarchical path to flat dash-separated name (NEW STANDARD)
+ * Converts: 'bmm', 'agents', 'pm' → 'bmad-bmm-pm.agent.md'
+ * Converts: 'bmm', 'workflows', 'correct-course' → 'bmad-bmm-correct-course.md'
+ * Converts: 'core', 'agents', 'brainstorming' → 'bmad-brainstorming.agent.md' (core items skip module prefix)
  *
  * @param {string} module - Module name (e.g., 'bmm', 'core')
  * @param {string} type - Artifact type ('agents', 'workflows', 'tasks', 'tools')
  * @param {string} name - Artifact name (e.g., 'pm', 'brainstorming')
- * @returns {string} Flat filename like 'bmad_bmm_agent_pm.md' or 'bmad_bmm_correct-course.md'
+ * @returns {string} Flat filename like 'bmad-bmm-pm.agent.md' or 'bmad-bmm-correct-course.md'
+ */
+function toDashName(module, type, name) {
+  const isAgent = type === AGENT_SEGMENT;
+
+  // For core module, skip the module prefix: use 'bmad-name.md' instead of 'bmad-core-name.md'
+  if (module === 'core') {
+    return isAgent ? `bmad-${name}.agent.md` : `bmad-${name}.md`;
+  }
+
+  // Module artifacts: bmad-module-name.md or bmad-module-name.agent.md
+  // eslint-disable-next-line unicorn/prefer-string-replace-all -- regex replace is intentional here
+  const dashName = name.replace(/\//g, '-'); // Flatten nested paths
+  return isAgent ? `bmad-${module}-${dashName}.agent.md` : `bmad-${module}-${dashName}.md`;
+}
+
+/**
+ * Convert relative path to flat dash-separated name
+ * Converts: 'bmm/agents/pm.md' → 'bmad-bmm-pm.agent.md'
+ * Converts: 'bmm/workflows/correct-course.md' → 'bmad-bmm-correct-course.md'
+ * Converts: 'core/agents/brainstorming.md' → 'bmad-brainstorming.agent.md' (core items skip module prefix)
+ *
+ * @param {string} relativePath - Path like 'bmm/agents/pm.md'
+ * @returns {string} Flat filename like 'bmad-bmm-pm.agent.md' or 'bmad-brainstorming.md'
+ */
+function toDashPath(relativePath) {
+  if (!relativePath || typeof relativePath !== 'string') {
+    // Return a safe default for invalid input
+    return 'bmad-unknown.md';
+  }
+
+  const withoutExt = relativePath.replace('.md', '');
+  const parts = withoutExt.split(/[/\\]/);
+
+  const module = parts[0];
+  const type = parts[1];
+  const name = parts.slice(2).join('-');
+
+  return toDashName(module, type, name);
+}
+
+/**
+ * Create custom agent dash name
+ * Creates: 'bmad-custom-fred-commit-poet.agent.md'
+ *
+ * @param {string} agentName - Custom agent name
+ * @returns {string} Flat filename like 'bmad-custom-fred-commit-poet.agent.md'
+ */
+function customAgentDashName(agentName) {
+  return `bmad-custom-${agentName}.agent.md`;
+}
+
+/**
+ * Check if a filename uses dash format
+ * @param {string} filename - Filename to check
+ * @returns {boolean} True if filename uses dash format
+ */
+function isDashFormat(filename) {
+  return filename.startsWith('bmad-') && filename.includes('-');
+}
+
+/**
+ * Extract parts from a dash-formatted filename
+ * Parses: 'bmad-bmm-pm.agent.md' → { prefix: 'bmad', module: 'bmm', type: 'agents', name: 'pm' }
+ * Parses: 'bmad-bmm-correct-course.md' → { prefix: 'bmad', module: 'bmm', type: 'workflows', name: 'correct-course' }
+ * Parses: 'bmad-brainstorming.agent.md' → { prefix: 'bmad', module: 'core', type: 'agents', name: 'brainstorming' } (core agents)
+ * Parses: 'bmad-brainstorming.md' → { prefix: 'bmad', module: 'core', type: 'workflows', name: 'brainstorming' } (core workflows)
+ *
+ * @param {string} filename - Dash-formatted filename
+ * @returns {Object|null} Parsed parts or null if invalid format
+ */
+function parseDashName(filename) {
+  const withoutExt = filename.replace('.md', '');
+  const parts = withoutExt.split('-');
+
+  if (parts.length < 2 || parts[0] !== 'bmad') {
+    return null;
+  }
+
+  // Check if this is an agent file (has .agent suffix)
+  const isAgent = withoutExt.endsWith('.agent');
+
+  if (isAgent) {
+    // This is an agent file
+    // Format: bmad-name.agent (core) or bmad-module-name.agent
+    if (parts.length === 3) {
+      // Core agent: bmad-name.agent
+      return {
+        prefix: parts[0],
+        module: 'core',
+        type: 'agents',
+        name: parts[1],
+      };
+    } else {
+      // Module agent: bmad-module-name.agent
+      return {
+        prefix: parts[0],
+        module: parts[1],
+        type: 'agents',
+        name: parts.slice(2).join('-'),
+      };
+    }
+  }
+
+  // Not an agent file - must be a workflow/tool/task
+  // If only 2 parts (bmad-name), it's a core workflow/tool/task
+  if (parts.length === 2) {
+    return {
+      prefix: parts[0],
+      module: 'core',
+      type: 'workflows', // Default to workflows for non-agent core items
+      name: parts[1],
+    };
+  }
+
+  // Otherwise, it's a module workflow/tool/task (bmad-module-name)
+  return {
+    prefix: parts[0],
+    module: parts[1],
+    type: 'workflows', // Default to workflows for non-agent module items
+    name: parts.slice(2).join('-'),
+  };
+}
+
+// ============================================================================
+// LEGACY FUNCTIONS (underscore format) - kept for backward compatibility
+// ============================================================================
+
+/**
+ * Convert hierarchical path to flat underscore-separated name (LEGACY)
+ * @deprecated Use toDashName instead
  */
 function toUnderscoreName(module, type, name) {
   const isAgent = type === AGENT_SEGMENT;
-  // For core module, skip the module prefix: use 'bmad_name.md' instead of 'bmad_core_name.md'
   if (module === 'core') {
     return isAgent ? `bmad_agent_${name}.md` : `bmad_${name}.md`;
   }
@@ -30,13 +168,8 @@ function toUnderscoreName(module, type, name) {
 }
 
 /**
- * Convert relative path to flat underscore-separated name
- * Converts: 'bmm/agents/pm.md' → 'bmad_bmm_agent_pm.md'
- * Converts: 'bmm/workflows/correct-course.md' → 'bmad_bmm_correct-course.md'
- * Converts: 'core/agents/brainstorming.md' → 'bmad_agent_brainstorming.md' (core items skip module prefix)
- *
- * @param {string} relativePath - Path like 'bmm/agents/pm.md'
- * @returns {string} Flat filename like 'bmad_bmm_agent_pm.md' or 'bmad_brainstorming.md'
+ * Convert relative path to flat underscore-separated name (LEGACY)
+ * @deprecated Use toDashPath instead
  */
 function toUnderscorePath(relativePath) {
   const withoutExt = relativePath.replace('.md', '');
@@ -46,39 +179,28 @@ function toUnderscorePath(relativePath) {
   const type = parts[1];
   const name = parts.slice(2).join('_');
 
-  // Use toUnderscoreName for consistency
   return toUnderscoreName(module, type, name);
 }
 
 /**
- * Create custom agent underscore name
- * Creates: 'bmad_custom_fred-commit-poet.md'
- *
- * @param {string} agentName - Custom agent name
- * @returns {string} Flat filename like 'bmad_custom_fred-commit-poet.md'
+ * Create custom agent underscore name (LEGACY)
+ * @deprecated Use customAgentDashName instead
  */
 function customAgentUnderscoreName(agentName) {
   return `bmad_custom_${agentName}.md`;
 }
 
 /**
- * Check if a filename uses underscore format
- * @param {string} filename - Filename to check
- * @returns {boolean} True if filename uses underscore format
+ * Check if a filename uses underscore format (LEGACY)
+ * @deprecated Use isDashFormat instead
  */
 function isUnderscoreFormat(filename) {
   return filename.startsWith('bmad_') && filename.includes('_');
 }
 
 /**
- * Extract parts from an underscore-formatted filename
- * Parses: 'bmad_bmm_agent_pm.md' → { prefix: 'bmad', module: 'bmm', type: 'agents', name: 'pm' }
- * Parses: 'bmad_bmm_correct-course.md' → { prefix: 'bmad', module: 'bmm', type: 'workflows', name: 'correct-course' }
- * Parses: 'bmad_agent_brainstorming.md' → { prefix: 'bmad', module: 'core', type: 'agents', name: 'brainstorming' } (core agents)
- * Parses: 'bmad_brainstorming.md' → { prefix: 'bmad', module: 'core', type: 'workflows', name: 'brainstorming' } (core workflows)
- *
- * @param {string} filename - Underscore-formatted filename
- * @returns {Object|null} Parsed parts or null if invalid format
+ * Extract parts from an underscore-formatted filename (LEGACY)
+ * @deprecated Use parseDashName instead
  */
 function parseUnderscoreName(filename) {
   const withoutExt = filename.replace('.md', '');
@@ -88,14 +210,10 @@ function parseUnderscoreName(filename) {
     return null;
   }
 
-  // Check if this is an agent file (has 'agent' as one of the parts)
   const agentIndex = parts.indexOf('agent');
 
   if (agentIndex !== -1) {
-    // This is an agent file
-    // Format: bmad_agent_name (core) or bmad_module_agent_name
     if (agentIndex === 1) {
-      // Core agent: bmad_agent_name
       return {
         prefix: parts[0],
         module: 'core',
@@ -103,7 +221,6 @@ function parseUnderscoreName(filename) {
         name: parts.slice(agentIndex + 1).join('_'),
       };
     } else {
-      // Module agent: bmad_module_agent_name
       return {
         prefix: parts[0],
         module: parts[1],
@@ -113,53 +230,52 @@ function parseUnderscoreName(filename) {
     }
   }
 
-  // Not an agent file - must be a workflow/tool/task
-  // If only 2 parts (bmad_name), it's a core workflow/tool/task
   if (parts.length === 2) {
     return {
       prefix: parts[0],
       module: 'core',
-      type: 'workflows', // Default to workflows for non-agent core items
+      type: 'workflows',
       name: parts[1],
     };
   }
 
-  // Otherwise, it's a module workflow/tool/task (bmad_module_name)
   return {
     prefix: parts[0],
     module: parts[1],
-    type: 'workflows', // Default to workflows for non-agent module items
+    type: 'workflows',
     name: parts.slice(2).join('_'),
   };
 }
 
-// Backward compatibility aliases (deprecated)
+// Backward compatibility aliases (colon format was same as underscore)
 const toColonName = toUnderscoreName;
 const toColonPath = toUnderscorePath;
-const toDashPath = toUnderscorePath;
 const customAgentColonName = customAgentUnderscoreName;
-const customAgentDashName = customAgentUnderscoreName;
 const isColonFormat = isUnderscoreFormat;
-const isDashFormat = isUnderscoreFormat;
 const parseColonName = parseUnderscoreName;
-const parseDashName = parseUnderscoreName;
 
 module.exports = {
+  // New standard (dash-based)
+  toDashName,
+  toDashPath,
+  customAgentDashName,
+  isDashFormat,
+  parseDashName,
+
+  // Legacy (underscore-based) - kept for backward compatibility
   toUnderscoreName,
   toUnderscorePath,
   customAgentUnderscoreName,
   isUnderscoreFormat,
   parseUnderscoreName,
+
   // Backward compatibility aliases
   toColonName,
   toColonPath,
-  toDashPath,
   customAgentColonName,
-  customAgentDashName,
   isColonFormat,
-  isDashFormat,
   parseColonName,
-  parseDashName,
+
   TYPE_SEGMENTS,
   AGENT_SEGMENT,
 };

package/tools/cli/installers/lib/ide/shared/task-tool-command-generator.js

@@ -66,7 +66,7 @@ class TaskToolCommandGenerator {
 
     // Convert path to use {project-root} placeholder
     let itemPath = item.path;
-    if (itemPath.startsWith('bmad/')) {
+    if (itemPath && typeof itemPath === 'string' && itemPath.startsWith('bmad/')) {
       itemPath = `{project-root}/${itemPath}`;
     }
 
@@ -76,7 +76,7 @@ description: '${description.replaceAll("'", "''")}'
 
 # ${item.displayName || item.name}
 
-LOAD and execute the ${type} at: ${itemPath}
+Read the entire ${type} file at: ${itemPath}
 
 Follow all instructions in the ${type} file exactly as written.
 `;
@@ -239,8 +239,10 @@ Follow all instructions in the ${type} file exactly as written.
   }
 
   /**
-   * Write task/tool artifacts using underscore format (Windows-compatible)
-   * Creates flat files like: bmad_bmm_bmad-help.md
+   * Write task/tool artifacts using dash format (NEW STANDARD)
+   * Creates flat files like: bmad-bmm-bmad-help.md
+   *
+   * Note: Tasks/tools do NOT have .agent.md suffix - only agents do.
    *
    * @param {string} baseCommandsDir - Base commands directory for the IDE
    * @param {Array} artifacts - Task/tool artifacts with relativePath
@@ -252,7 +254,7 @@ Follow all instructions in the ${type} file exactly as written.
     for (const artifact of artifacts) {
       if (artifact.type === 'task' || artifact.type === 'tool') {
         const commandContent = this.generateCommandContent(artifact, artifact.type);
-        // Use underscore format: bmad_module_name.md
+        // Use dash format: bmad-module-name.md
         const flatName = toDashPath(artifact.relativePath);
         const commandPath = path.join(baseCommandsDir, flatName);
         await fs.ensureDir(path.dirname(commandPath));

package/tools/cli/installers/lib/ide/shared/workflow-command-generator.js

@@ -67,10 +67,26 @@ class WorkflowCommandGenerator {
 
     for (const workflow of allWorkflows) {
       const commandContent = await this.generateCommandContent(workflow, bmadDir);
+      // Calculate the relative workflow path (e.g., bmm/workflows/4-implementation/sprint-planning/workflow.yaml)
+      let workflowRelPath = workflow.path;
+      // Remove _bmad/ prefix if present to get relative path from project root
+      // Handle both absolute paths (/path/to/_bmad/...) and relative paths (_bmad/...)
+      if (workflowRelPath.includes('_bmad/')) {
+        const parts = workflowRelPath.split(/_bmad\//);
+        if (parts.length > 1) {
+          workflowRelPath = parts.slice(1).join('/');
+        }
+      }
+      // Determine if this is a YAML workflow
+      const isYamlWorkflow = workflow.path.endsWith('.yaml') || workflow.path.endsWith('.yml');
       artifacts.push({
         type: 'workflow-command',
+        isYamlWorkflow: isYamlWorkflow, // For template selection
+        name: workflow.name,
+        description: workflow.description || `${workflow.name} workflow`,
         module: workflow.module,
         relativePath: path.join(workflow.module, 'workflows', `${workflow.name}.md`),
+        workflowPath: workflowRelPath, // Relative path to actual workflow file
         content: commandContent,
         sourcePath: workflow.path,
       });
@@ -265,8 +281,10 @@ When running any workflow:
   }
 
   /**
-   * Write workflow command artifacts using underscore format (Windows-compatible)
-   * Creates flat files like: bmad_bmm_correct-course.md
+   * Write workflow command artifacts using dash format (NEW STANDARD)
+   * Creates flat files like: bmad-bmm-correct-course.md
+   *
+   * Note: Workflows do NOT have .agent.md suffix - only agents do.
    *
    * @param {string} baseCommandsDir - Base commands directory for the IDE
    * @param {Array} artifacts - Workflow artifacts
@@ -277,7 +295,7 @@ When running any workflow:
 
     for (const artifact of artifacts) {
       if (artifact.type === 'workflow-command') {
-        // Convert relativePath to underscore format: bmm/workflows/correct-course.md → bmad_bmm_correct-course.md
+        // Convert relativePath to dash format: bmm/workflows/correct-course.md → bmad-bmm-correct-course.md
         const flatName = toDashPath(artifact.relativePath);
         const commandPath = path.join(baseCommandsDir, flatName);
         await fs.ensureDir(path.dirname(commandPath));

package/tools/cli/installers/lib/ide/templates/combined/antigravity.md

@@ -0,0 +1,8 @@
+---
+name: '{{name}}'
+description: '{{description}}'
+---
+
+Read the entire workflow file at: {project-root}/_bmad/{{workflow_path}}
+
+Follow all instructions in the workflow file exactly as written.

package/tools/cli/installers/lib/ide/templates/combined/default-agent.md

@@ -0,0 +1,15 @@
+---
+name: '{{name}}'
+description: '{{description}}'
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from {project-root}/_bmad/{{path}}
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. FOLLOW every step in the <activation> section precisely
+4. DISPLAY the welcome/greeting as instructed
+5. PRESENT the numbered menu
+6. WAIT for user input before proceeding
+</agent-activation>

package/tools/cli/installers/lib/ide/templates/combined/default-workflow-yaml.md

@@ -0,0 +1,14 @@
+---
+name: '{{name}}'
+description: '{{description}}'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @{project-root}/{{bmadFolderName}}/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @{project-root}/{{bmadFolderName}}/{{path}}
+3. Pass the yaml path @{project-root}/{{bmadFolderName}}/{{path}} as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

package/tools/cli/installers/lib/ide/templates/combined/default-workflow.md

@@ -0,0 +1,6 @@
+---
+name: '{{name}}'
+description: '{{description}}'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @{project-root}/{{bmadFolderName}}/{{path}}, READ its entire contents and follow its directions exactly!

package/tools/cli/installers/lib/ide/templates/combined/rovodev.md

@@ -0,0 +1,9 @@
+# {{name}}
+
+{{description}}
+
+---
+
+Read the entire workflow file at: {project-root}/_bmad/{{workflow_path}}
+
+Follow all instructions in the workflow file exactly as written.

package/tools/cli/installers/lib/ide/templates/combined/trae.md

@@ -0,0 +1,9 @@
+# {{name}}
+
+{{description}}
+
+## Instructions
+
+Read the entire workflow file at: {project-root}/_bmad/{{workflow_path}}
+
+Follow all instructions in the workflow file exactly as written.

package/tools/cli/installers/lib/ide/templates/combined/windsurf-workflow.md

@@ -0,0 +1,10 @@
+---
+description: '{{description}}'
+auto_execution_mode: "iterate"
+---
+
+# {{name}}
+
+Read the entire workflow file at {project-root}/_bmad/{{workflow_path}}
+
+Follow all instructions in the workflow file exactly as written.

package/tools/cli/installers/lib/ide/templates/split/gemini/body.md

@@ -0,0 +1,10 @@
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from {project-root}/_bmad/{{path}}
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. FOLLOW every step in the <activation> section precisely
+4. DISPLAY the welcome/greeting as instructed
+5. PRESENT the numbered menu
+6. WAIT for user input before proceeding
+</agent-activation>

package/tools/cli/installers/lib/ide/templates/split/gemini/header.toml

@@ -0,0 +1,2 @@
+name = "{{name}}"
+description = "{{description}}"

package/tools/cli/installers/lib/ide/templates/split/opencode/body.md

@@ -0,0 +1,10 @@
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from {project-root}/_bmad/{{path}}
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. FOLLOW every step in the <activation> section precisely
+4. DISPLAY the welcome/greeting as instructed
+5. PRESENT the numbered menu
+6. WAIT for user input before proceeding
+</agent-activation>

package/tools/cli/installers/lib/ide/templates/split/opencode/header.md

@@ -0,0 +1,4 @@
+---
+name: '{{name}}'
+description: '{{description}}'
+---