BMAD-METHOD/tools/cli/installers/lib/ide/STANDARDIZATION_PLAN.md

IDE Installer Standardization Plan

Overview

Standardize IDE installers to use flat file naming with underscores (Windows-compatible) and centralize duplicated code in shared utilities.

Key Rule: All IDEs use underscore format for Windows compatibility (colons don't work on Windows).

Current State Analysis

File Structure Patterns

IDE	Current Pattern	Path Format
claude-code	Hierarchical	.claude/commands/bmad/{module}/agents/{name}.md
cursor	Hierarchical	.cursor/commands/bmad/{module}/agents/{name}.md
crush	Hierarchical	.crush/commands/bmad/{module}/agents/{name}.md
antigravity	Flattened (underscores)	.agent/workflows/bmad_module_agents_name.md
codex	Flattened (underscores)	~/.codex/prompts/bmad_module_agents_name.md
cline	Flattened (underscores)	.clinerules/workflows/bmad_module_type_name.md
roo	Flattened (underscores)	.roo/commands/bmad_module_agent_name.md
auggie	Hybrid	.augment/commands/bmad/agents/{module}-{name}.md
iflow	Hybrid	.iflow/commands/bmad/agents/{module}-{name}.md
trae	Different (rules)	.trae/rules/bmad-agent-{module}-{name}.md
github-copilot	Different (agents)	.github/agents/bmd-custom-{module}-{name}.agent.md

Shared Generators (in /shared)

1. agent-command-generator.js - generates agent launchers
2. task-tool-command-generator.js - generates task/tool commands
3. workflow-command-generator.js - generates workflow commands

All currently create artifacts with nested relative paths like {module}/agents/{name}.md

Code Duplication Issues

1. Flattening logic duplicated in multiple IDEs
2. Agent launcher content creation duplicated
3. Path transformation duplicated

Target Standardization

For All IDEs (underscore format - Windows-compatible)

IDEs affected: claude-code, cursor, crush, antigravity, codex, cline, roo

Format: bmad_{module}_{type}_{name}.md

Examples:
- Agent:      bmad_bmm_agents_pm.md
- Agent:      bmad_core_agents_dev.md
- Workflow:   bmad_bmm_workflows_correct-course.md
- Task:       bmad_bmm_tasks_bmad-help.md
- Tool:       bmad_core_tools_code-review.md
- Custom:     bmad_custom_agents_fred-commit-poet.md

Note: Type segments (agents, workflows, tasks, tools) are filtered out from names:

• bmm/agents/pm.md → bmad_bmm_pm.md (not bmad_bmm_agents_pm.md)

For Hybrid IDEs (keep as-is)

IDEs affected: auggie, iflow

These use {module}-{name}.md format within subdirectories - keep as-is.

Skip (drastically different)

IDEs affected: trae, github-copilot

Implementation Plan

Phase 1: Create Shared Utility

File: shared/path-utils.js

/**
 * Convert hierarchical path to flat underscore-separated name (Windows-compatible)
 * @param {string} module - Module name (e.g., 'bmm', 'core')
 * @param {string} type - Artifact type ('agents', 'workflows', 'tasks', 'tools') - filtered out
 * @param {string} name - Artifact name (e.g., 'pm', 'correct-course')
 * @returns {string} Flat filename like 'bmad_bmm_pm.md'
 */
function toUnderscoreName(module, type, name) {
  return `bmad_${module}_${name}.md`;
}

/**
 * Convert relative path to flat underscore-separated name (Windows-compatible)
 * @param {string} relativePath - Path like 'bmm/agents/pm.md'
 * @returns {string} Flat filename like 'bmad_bmm_pm.md'
 */
function toUnderscorePath(relativePath) {
  const withoutExt = relativePath.replace('.md', '');
  const parts = withoutExt.split(/[\/\\]/);
  // Filter out type segments (agents, workflows, tasks, tools)
  const filtered = parts.filter((p) => !TYPE_SEGMENTS.includes(p));
  return `bmad_${filtered.join('_')}.md`;
}

/**
 * Create custom agent underscore name
 * @param {string} agentName - Custom agent name
 * @returns {string} Flat filename like 'bmad_custom_fred-commit-poet.md'
 */
function customAgentUnderscoreName(agentName) {
  return `bmad_custom_${agentName}.md`;
}

// Backward compatibility aliases
const toColonName = toUnderscoreName;
const toColonPath = toUnderscorePath;
const toDashPath = toUnderscorePath;
const customAgentColonName = customAgentUnderscoreName;
const customAgentDashName = customAgentUnderscoreName;

module.exports = {
  toUnderscoreName,
  toUnderscorePath,
  customAgentUnderscoreName,
  // Backward compatibility
  toColonName,
  toColonPath,
  toDashPath,
  customAgentColonName,
  customAgentDashName,
};

Phase 2: Update Shared Generators

Files to modify:

• shared/agent-command-generator.js
• shared/task-tool-command-generator.js
• shared/workflow-command-generator.js

Changes:

1. Import path utilities
2. Change relativePath to use flat format
3. Add method writeColonArtifacts() for folder-based IDEs (uses underscore)
4. Add method writeDashArtifacts() for flat IDEs (uses underscore)

Phase 3: Update All IDEs

Files to modify:

• claude-code.js
• cursor.js
• crush.js
• antigravity.js
• codex.js
• cline.js
• roo.js

Changes:

1. Import utilities from path-utils
2. Change from hierarchical to flat underscore naming
3. Update cleanup to handle flat structure (startsWith('bmad'))

Phase 4: Update Base Class

File: _base-ide.js

Changes:

1. Mark flattenFilename() as @deprecated
2. Add comment pointing to new path-utils

Migration Checklist

New Files

• Create shared/path-utils.js

All IDEs (convert to underscore format)

• Update shared/agent-command-generator.js - update for underscore
• Update shared/task-tool-command-generator.js - update for underscore
• Update shared/workflow-command-generator.js - update for underscore
• Update claude-code.js - convert to underscore format
• Update cursor.js - convert to underscore format
• Update crush.js - convert to underscore format
• Update antigravity.js - use underscore format
• Update codex.js - use underscore format
• Update cline.js - use underscore format
• Update roo.js - use underscore format

CSV Command Files

• Update src/core/module-help.csv - change colons to underscores
• Update src/bmm/module-help.csv - change colons to underscores

Base Class

• Update _base-ide.js - add deprecation notice

Testing

• Test claude-code installation
• Test cursor installation
• Test crush installation
• Test antigravity installation
• Test codex installation
• Test cline installation
• Test roo installation

Notes

1. Filter type segments: agents, workflows, tasks, tools are filtered out from flat names
2. Underscore format: Universal underscore format for Windows compatibility
3. Custom agents: Follow the same pattern as regular agents
4. Backward compatibility: Old function names kept as aliases
5. Cleanup: Will remove old bmad: format files on next install