bmad-method 6.0.3 → 6.0.5-next.0

package/tools/cli/installers/lib/ide/manager.js

@@ -1,5 +1,3 @@
-const fs = require('fs-extra');
-const path = require('node:path');
 const { BMAD_FOLDER_NAME } = require('./shared/path-utils');
 const prompts = require('../../../lib/prompts');
 
@@ -8,8 +6,7 @@ const prompts = require('../../../lib/prompts');
  * Dynamically discovers and loads IDE handlers
  *
  * Loading strategy:
- * 1. Custom installer files (codex.js, github-copilot.js, kilo.js, rovodev.js) - for platforms with unique installation logic
- * 2. Config-driven handlers (from platform-codes.yaml) - for standard IDE installation patterns
+ * All platforms are config-driven from platform-codes.yaml.
  */
 class IdeManager {
   constructor() {
@@ -43,49 +40,12 @@ class IdeManager {
   }
 
   /**
-   * Dynamically load all IDE handlers
-   * 1. Load custom installer files first (codex.js, github-copilot.js, kilo.js, rovodev.js)
-   * 2. Load config-driven handlers from platform-codes.yaml
+   * Dynamically load all IDE handlers from platform-codes.yaml
    */
   async loadHandlers() {
-    // Load custom installer files
-    await this.loadCustomInstallerFiles();
-
-    // Load config-driven handlers from platform-codes.yaml
     await this.loadConfigDrivenHandlers();
   }
 
-  /**
-   * Load custom installer files (unique installation logic)
-   * These files have special installation patterns that don't fit the config-driven model
-   */
-  async loadCustomInstallerFiles() {
-    const ideDir = __dirname;
-    const customFiles = ['codex.js', 'github-copilot.js', 'kilo.js', 'rovodev.js'];
-
-    for (const file of customFiles) {
-      const filePath = path.join(ideDir, file);
-      if (!fs.existsSync(filePath)) continue;
-
-      try {
-        const HandlerModule = require(filePath);
-        const HandlerClass = HandlerModule.default || Object.values(HandlerModule)[0];
-
-        if (HandlerClass) {
-          const instance = new HandlerClass();
-          if (instance.name && typeof instance.name === 'string') {
-            if (typeof instance.setBmadFolderName === 'function') {
-              instance.setBmadFolderName(this.bmadFolderName);
-            }
-            this.handlers.set(instance.name, instance);
-          }
-        }
-      } catch (error) {
-        await prompts.log.warn(`Warning: Could not load ${file}: ${error.message}`);
-      }
-    }
-  }
-
   /**
    * Load config-driven handlers from platform-codes.yaml
    * This creates ConfigDrivenIdeSetup instances for platforms with installer config
@@ -97,9 +57,6 @@ class IdeManager {
     const { ConfigDrivenIdeSetup } = require('./_config-driven');
 
     for (const [platformCode, platformInfo] of Object.entries(platformConfig.platforms)) {
-      // Skip if already loaded by custom installer
-      if (this.handlers.has(platformCode)) continue;
-
       // Skip if no installer config (platform may not need installation)
       if (!platformInfo.installer) continue;
 
@@ -127,6 +84,11 @@ class IdeManager {
         continue;
       }
 
+      // Skip suspended platforms (e.g., IDE doesn't support skills yet)
+      if (handler.platformConfig?.suspended) {
+        continue;
+      }
+
       ides.push({
         value: key,
         name: name,
@@ -176,6 +138,22 @@ class IdeManager {
       return { success: false, ide: ideName, error: 'unsupported IDE' };
     }
 
+    // Block suspended platforms — clean up legacy files but don't install
+    if (handler.platformConfig?.suspended) {
+      if (!options.silent) {
+        await prompts.log.warn(`${handler.displayName || ideName}: ${handler.platformConfig.suspended}`);
+      }
+      // Still clean up legacy artifacts so old broken configs don't linger
+      if (typeof handler.cleanup === 'function') {
+        try {
+          await handler.cleanup(projectDir, { silent: true });
+        } catch {
+          // Best-effort cleanup — don't let stale files block the suspended result
+        }
+      }
+      return { success: false, ide: ideName, error: 'suspended' };
+    }
+
     try {
       const handlerResult = await handler.setup(projectDir, bmadDir, options);
       // Build detail string from handler-returned data
@@ -189,24 +167,10 @@ class IdeManager {
         if (r.tasks > 0) parts.push(`${r.tasks} tasks`);
         if (r.tools > 0) parts.push(`${r.tools} tools`);
         detail = parts.join(', ');
-      } else if (handlerResult && handlerResult.counts) {
-        // Codex handler returns { success, counts: { agents, workflows, tasks }, written }
-        const c = handlerResult.counts;
-        const parts = [];
-        if (c.agents > 0) parts.push(`${c.agents} agents`);
-        if (c.workflows > 0) parts.push(`${c.workflows} workflows`);
-        if (c.tasks > 0) parts.push(`${c.tasks} tasks`);
-        detail = parts.join(', ');
-      } else if (handlerResult && handlerResult.modes !== undefined) {
-        // Kilo handler returns { success, modes, workflows, tasks, tools }
-        const parts = [];
-        if (handlerResult.modes > 0) parts.push(`${handlerResult.modes} modes`);
-        if (handlerResult.workflows > 0) parts.push(`${handlerResult.workflows} workflows`);
-        if (handlerResult.tasks > 0) parts.push(`${handlerResult.tasks} tasks`);
-        if (handlerResult.tools > 0) parts.push(`${handlerResult.tools} tools`);
-        detail = parts.join(', ');
       }
-      return { success: true, ide: ideName, detail, handlerResult };
+      // Propagate handler's success status (default true for backward compat)
+      const success = handlerResult?.success !== false;
+      return { success, ide: ideName, detail, error: handlerResult?.error, handlerResult };
     } catch (error) {
       await prompts.log.error(`Failed to setup ${ideName}: ${error.message}`);
       return { success: false, ide: ideName, error: error.message };

package/tools/cli/installers/lib/ide/platform-codes.yaml

@@ -20,8 +20,11 @@ platforms:
     category: ide
     description: "Google's AI development environment"
     installer:
-      target_dir: .agent/workflows
+      legacy_targets:
+        - .agent/workflows
+      target_dir: .agent/skills
       template_type: antigravity
+      skill_format: true
 
   auggie:
     name: "Auggie"
@@ -29,8 +32,11 @@ platforms:
     category: cli
     description: "AI development tool"
     installer:
-      target_dir: .augment/commands
+      legacy_targets:
+        - .augment/commands
+      target_dir: .augment/skills
       template_type: default
+      skill_format: true
 
   claude-code:
     name: "Claude Code"
@@ -38,8 +44,12 @@ platforms:
     category: cli
     description: "Anthropic's official CLI for Claude"
     installer:
-      target_dir: .claude/commands
+      legacy_targets:
+        - .claude/commands
+      target_dir: .claude/skills
       template_type: default
+      skill_format: true
+      ancestor_conflict_check: true
 
   cline:
     name: "Cline"
@@ -47,15 +57,26 @@ platforms:
     category: ide
     description: "AI coding assistant"
     installer:
-      target_dir: .clinerules/workflows
-      template_type: windsurf
+      legacy_targets:
+        - .clinerules/workflows
+      target_dir: .cline/skills
+      template_type: default
+      skill_format: true
 
   codex:
     name: "Codex"
     preferred: false
     category: cli
     description: "OpenAI Codex integration"
-    # No installer config - uses custom codex.js
+    installer:
+      legacy_targets:
+        - .codex/prompts
+        - ~/.codex/prompts
+      target_dir: .agents/skills
+      template_type: default
+      skill_format: true
+      ancestor_conflict_check: true
+      artifact_types: [agents, workflows, tasks]
 
   codebuddy:
     name: "CodeBuddy"
@@ -63,8 +84,11 @@ platforms:
     category: ide
     description: "Tencent Cloud Code Assistant - AI-powered coding companion"
     installer:
-      target_dir: .codebuddy/commands
+      legacy_targets:
+        - .codebuddy/commands
+      target_dir: .codebuddy/skills
       template_type: default
+      skill_format: true
 
   crush:
     name: "Crush"
@@ -72,8 +96,11 @@ platforms:
     category: ide
     description: "AI development assistant"
     installer:
-      target_dir: .crush/commands
+      legacy_targets:
+        - .crush/commands
+      target_dir: .crush/skills
       template_type: default
+      skill_format: true
 
   cursor:
     name: "Cursor"
@@ -81,8 +108,11 @@ platforms:
     category: ide
     description: "AI-first code editor"
     installer:
-      target_dir: .cursor/commands
+      legacy_targets:
+        - .cursor/commands
+      target_dir: .cursor/skills
       template_type: default
+      skill_format: true
 
   gemini:
     name: "Gemini CLI"
@@ -90,15 +120,24 @@ platforms:
     category: cli
     description: "Google's CLI for Gemini"
     installer:
-      target_dir: .gemini/commands
-      template_type: gemini
+      legacy_targets:
+        - .gemini/commands
+      target_dir: .gemini/skills
+      template_type: default
+      skill_format: true
 
   github-copilot:
     name: "GitHub Copilot"
     preferred: false
     category: ide
     description: "GitHub's AI pair programmer"
-    # No installer config - uses custom github-copilot.js
+    installer:
+      legacy_targets:
+        - .github/agents
+        - .github/prompts
+      target_dir: .github/skills
+      template_type: default
+      skill_format: true
 
   iflow:
     name: "iFlow"
@@ -106,15 +145,24 @@ platforms:
     category: ide
     description: "AI workflow automation"
     installer:
-      target_dir: .iflow/commands
+      legacy_targets:
+        - .iflow/commands
+      target_dir: .iflow/skills
       template_type: default
+      skill_format: true
 
   kilo:
     name: "KiloCoder"
     preferred: false
     category: ide
     description: "AI coding platform"
-    # No installer config - uses custom kilo.js (creates .kilocodemodes file)
+    suspended: "Kilo Code does not yet support the Agent Skills standard. Support is paused until they implement it. See https://github.com/kilocode/kilo-code/issues for updates."
+    installer:
+      legacy_targets:
+        - .kilocode/workflows
+      target_dir: .kilocode/skills
+      template_type: default
+      skill_format: true
 
   kiro:
     name: "Kiro"
@@ -122,8 +170,11 @@ platforms:
     category: ide
     description: "Amazon's AI-powered IDE"
     installer:
-      target_dir: .kiro/steering
+      legacy_targets:
+        - .kiro/steering
+      target_dir: .kiro/skills
       template_type: kiro
+      skill_format: true
 
   opencode:
     name: "OpenCode"
@@ -131,13 +182,25 @@ platforms:
     category: ide
     description: "OpenCode terminal coding assistant"
     installer:
-      targets:
-        - target_dir: .opencode/agent
-          template_type: opencode
-          artifact_types: [agents]
-        - target_dir: .opencode/command
-          template_type: opencode
-          artifact_types: [workflows, tasks, tools]
+      legacy_targets:
+        - .opencode/agents
+        - .opencode/commands
+        - .opencode/agent
+        - .opencode/command
+      target_dir: .opencode/skills
+      template_type: opencode
+      skill_format: true
+      ancestor_conflict_check: true
+
+  pi:
+    name: "Pi"
+    preferred: false
+    category: cli
+    description: "Provider-agnostic terminal-native AI coding agent"
+    installer:
+      target_dir: .pi/skills
+      template_type: default
+      skill_format: true
 
   qwen:
     name: "QwenCoder"
@@ -145,24 +208,35 @@ platforms:
     category: ide
     description: "Qwen AI coding assistant"
     installer:
-      target_dir: .qwen/commands
+      legacy_targets:
+        - .qwen/commands
+      target_dir: .qwen/skills
       template_type: default
+      skill_format: true
 
   roo:
-    name: "Roo Cline"
+    name: "Roo Code"
     preferred: false
     category: ide
     description: "Enhanced Cline fork"
     installer:
-      target_dir: .roo/commands
+      legacy_targets:
+        - .roo/commands
+      target_dir: .roo/skills
       template_type: default
+      skill_format: true
 
   rovo-dev:
     name: "Rovo Dev"
     preferred: false
     category: ide
     description: "Atlassian's Rovo development environment"
-    # No installer config - uses custom rovodev.js (generates prompts.yml manifest)
+    installer:
+      legacy_targets:
+        - .rovodev/workflows
+      target_dir: .rovodev/skills
+      template_type: default
+      skill_format: true
 
   trae:
     name: "Trae"
@@ -170,8 +244,11 @@ platforms:
     category: ide
     description: "AI coding tool"
     installer:
-      target_dir: .trae/rules
-      template_type: trae
+      legacy_targets:
+        - .trae/rules
+      target_dir: .trae/skills
+      template_type: default
+      skill_format: true
 
   windsurf:
     name: "Windsurf"
@@ -179,8 +256,11 @@ platforms:
     category: ide
     description: "AI-powered IDE with cascade flows"
     installer:
-      target_dir: .windsurf/workflows
+      legacy_targets:
+        - .windsurf/workflows
+      target_dir: .windsurf/skills
       template_type: windsurf
+      skill_format: true
 
 # ============================================================================
 # Installer Config Schema
@@ -191,12 +271,19 @@ platforms:
 #   template_type: string                 # Default template type to use
 #   header_template: string (optional)    # Override for header/frontmatter template
 #   body_template: string (optional)      # Override for body/content template
+#   legacy_targets: array (optional)      # Old target dirs to clean up on reinstall (migration)
+#     - string                            # Relative path, e.g. .opencode/agent
 #   targets: array (optional)             # For multi-target installations
 #     - target_dir: string
 #       template_type: string
 #       artifact_types: [agents, workflows, tasks, tools]
 #   artifact_types: array (optional)      # Filter which artifacts to install (default: all)
 #   skip_existing: boolean (optional)     # Skip files that already exist (default: false)
+#   skill_format: boolean (optional)   # Use directory-per-skill output: <name>/SKILL.md
+#                                     # with clean frontmatter (name + description, unquoted)
+#   ancestor_conflict_check: boolean (optional) # Refuse install when ancestor dir has BMAD files
+#                                                # in the same target_dir (for IDEs that inherit
+#                                                # skills from parent directories)
 
 # ============================================================================
 # Platform Categories

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

@@ -47,6 +47,7 @@ class AgentCommandGenerator {
         name: agent.name,
         description: agent.description || `${agent.name} agent`,
         module: agent.module,
+        canonicalId: agent.canonicalId || '',
         relativePath: path.join(agent.module, 'agents', agentPathInModule), // For command filename
         agentPath: agentRelPath, // Relative path to actual agent file
         content: launcherContent,

package/tools/cli/installers/lib/ide/shared/bmad-artifacts.js

@@ -1,5 +1,6 @@
 const path = require('node:path');
 const fs = require('fs-extra');
+const { loadSkillManifest, getCanonicalId } = require('./skill-manifest');
 
 /**
  * Helpers for gathering BMAD agents/tasks from the installed tree.
@@ -34,6 +35,7 @@ async function getAgentsFromBmad(bmadDir, selectedModules = []) {
 
       const agentDirPath = path.join(standaloneAgentsDir, agentDir.name);
       const agentFiles = await fs.readdir(agentDirPath);
+      const skillManifest = await loadSkillManifest(agentDirPath);
 
       for (const file of agentFiles) {
         if (!file.endsWith('.md')) continue;
@@ -48,6 +50,7 @@ async function getAgentsFromBmad(bmadDir, selectedModules = []) {
           path: filePath,
           name: file.replace('.md', ''),
           module: 'standalone', // Mark as standalone agent
+          canonicalId: getCanonicalId(skillManifest, file),
         });
       }
     }
@@ -84,6 +87,7 @@ async function getAgentsFromDir(dirPath, moduleName, relativePath = '') {
   }
 
   const entries = await fs.readdir(dirPath, { withFileTypes: true });
+  const skillManifest = await loadSkillManifest(dirPath);
 
   for (const entry of entries) {
     // Skip if entry.name is undefined or not a string
@@ -124,6 +128,7 @@ async function getAgentsFromDir(dirPath, moduleName, relativePath = '') {
         name: entry.name.replace('.md', ''),
         module: moduleName,
         relativePath: newRelativePath, // Keep the .md extension for the full path
+        canonicalId: getCanonicalId(skillManifest, entry.name),
       });
     }
   }
@@ -139,6 +144,7 @@ async function getTasksFromDir(dirPath, moduleName) {
   }
 
   const files = await fs.readdir(dirPath);
+  const skillManifest = await loadSkillManifest(dirPath);
 
   for (const file of files) {
     // Include both .md and .xml task files
@@ -160,6 +166,7 @@ async function getTasksFromDir(dirPath, moduleName) {
       path: filePath,
       name: file.replace(ext, ''),
       module: moduleName,
+      canonicalId: getCanonicalId(skillManifest, file),
     });
   }
 

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

@@ -12,6 +12,7 @@
  * - 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-agent-brainstorming.md (core agents skip module name)
+ * - standalone/agents/fred.md → bmad-agent-standalone-fred.md
  */
 
 // Type segments - agents are included in naming, others are filtered out
@@ -26,8 +27,9 @@ const BMAD_FOLDER_NAME = '_bmad';
  * Converts: 'bmm', 'agents', 'pm' → 'bmad-agent-bmm-pm.md'
  * Converts: 'bmm', 'workflows', 'correct-course' → 'bmad-bmm-correct-course.md'
  * Converts: 'core', 'agents', 'brainstorming' → 'bmad-agent-brainstorming.md' (core agents skip module name)
+ * Converts: 'standalone', 'agents', 'fred' → 'bmad-agent-standalone-fred.md'
  *
- * @param {string} module - Module name (e.g., 'bmm', 'core')
+ * @param {string} module - Module name (e.g., 'bmm', 'core', 'standalone')
  * @param {string} type - Artifact type ('agents', 'workflows', 'tasks', 'tools')
  * @param {string} name - Artifact name (e.g., 'pm', 'brainstorming')
  * @returns {string} Flat filename like 'bmad-agent-bmm-pm.md' or 'bmad-bmm-correct-course.md'
@@ -39,6 +41,10 @@ function toDashName(module, type, name) {
   if (module === 'core') {
     return isAgent ? `bmad-agent-${name}.md` : `bmad-${name}.md`;
   }
+  // For standalone module, include 'standalone' in the name
+  if (module === 'standalone') {
+    return isAgent ? `bmad-agent-standalone-${name}.md` : `bmad-standalone-${name}.md`;
+  }
 
   // Module artifacts: bmad-module-name.md or bmad-agent-module-name.md
   // eslint-disable-next-line unicorn/prefer-string-replace-all -- regex replace is intentional here
@@ -63,7 +69,7 @@ function toDashPath(relativePath) {
   }
 
   // Strip common file extensions to avoid double extensions in generated filenames
-  // e.g., 'create-story.xml' → 'create-story', 'workflow.yaml' → 'workflow'
+  // e.g., 'create-story.xml' → 'create-story', 'workflow.md' → 'workflow'
   const withoutExt = relativePath.replace(/\.(md|yaml|yml|json|xml|toml)$/i, '');
   const parts = withoutExt.split(/[/\\]/);
 
@@ -110,6 +116,8 @@ function isDashFormat(filename) {
  * 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)
+ * Parses: 'bmad-agent-standalone-fred.md' → { prefix: 'bmad', module: 'standalone', type: 'agents', name: 'fred' }
+ * Parses: 'bmad-standalone-foo.md' → { prefix: 'bmad', module: 'standalone', type: 'workflows', name: 'foo' }
  *
  * @param {string} filename - Dash-formatted filename
  * @returns {Object|null} Parsed parts or null if invalid format
@@ -127,7 +135,16 @@ function parseDashName(filename) {
 
   if (isAgent) {
     // This is an agent file
-    // Format: bmad-agent-name (core) or bmad-agent-module-name
+    // Format: bmad-agent-name (core) or bmad-agent-standalone-name or bmad-agent-module-name
+    if (parts.length >= 4 && parts[2] === 'standalone') {
+      // Standalone agent: bmad-agent-standalone-name
+      return {
+        prefix: parts[0],
+        module: 'standalone',
+        type: 'agents',
+        name: parts.slice(3).join('-'),
+      };
+    }
     if (parts.length === 3) {
       // Core agent: bmad-agent-name
       return {
@@ -158,6 +175,16 @@ function parseDashName(filename) {
     };
   }
 
+  // Check for standalone non-agent: bmad-standalone-name
+  if (parts[1] === 'standalone') {
+    return {
+      prefix: parts[0],
+      module: 'standalone',
+      type: 'workflows', // Default to workflows for non-agent standalone items
+      name: parts.slice(2).join('-'),
+    };
+  }
+
   // Otherwise, it's a module workflow/tool/task (bmad-module-name)
   return {
     prefix: parts[0],
@@ -180,6 +207,9 @@ function toUnderscoreName(module, type, name) {
   if (module === 'core') {
     return isAgent ? `bmad_agent_${name}.md` : `bmad_${name}.md`;
   }
+  if (module === 'standalone') {
+    return isAgent ? `bmad_agent_standalone_${name}.md` : `bmad_standalone_${name}.md`;
+  }
   return isAgent ? `bmad_${module}_agent_${name}.md` : `bmad_${module}_${name}.md`;
 }
 
@@ -231,6 +261,15 @@ function parseUnderscoreName(filename) {
 
   if (agentIndex !== -1) {
     if (agentIndex === 1) {
+      // bmad_agent_... - check for standalone
+      if (parts.length >= 4 && parts[2] === 'standalone') {
+        return {
+          prefix: parts[0],
+          module: 'standalone',
+          type: 'agents',
+          name: parts.slice(3).join('_'),
+        };
+      }
       return {
         prefix: parts[0],
         module: 'core',
@@ -256,6 +295,16 @@ function parseUnderscoreName(filename) {
     };
   }
 
+  // Check for standalone non-agent: bmad_standalone_name
+  if (parts[1] === 'standalone') {
+    return {
+      prefix: parts[0],
+      module: 'standalone',
+      type: 'workflows',
+      name: parts.slice(2).join('_'),
+    };
+  }
+
   return {
     prefix: parts[0],
     module: parts[1],
@@ -264,6 +313,21 @@ function parseUnderscoreName(filename) {
   };
 }
 
+/**
+ * Resolve the skill name for an artifact.
+ * Prefers canonicalId from a bmad-skill-manifest.yaml sidecar when available,
+ * falling back to the path-derived name from toDashPath().
+ *
+ * @param {Object} artifact - Artifact object (must have relativePath; may have canonicalId)
+ * @returns {string} Filename like 'bmad-create-prd.md' or 'bmad-agent-bmm-pm.md'
+ */
+function resolveSkillName(artifact) {
+  if (artifact.canonicalId) {
+    return `${artifact.canonicalId}.md`;
+  }
+  return toDashPath(artifact.relativePath);
+}
+
 // Backward compatibility aliases (colon format was same as underscore)
 const toColonName = toUnderscoreName;
 const toColonPath = toUnderscorePath;
@@ -275,6 +339,7 @@ module.exports = {
   // New standard (dash-based)
   toDashName,
   toDashPath,
+  resolveSkillName,
   customAgentDashName,
   isDashFormat,
   parseDashName,