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

IDE Installer Standardization Plan

Overview

Standardize IDE installers to use flat file naming and centralize duplicated code in shared utilities.

Key Rule: Only folder-based IDEs convert to colon format. IDEs already using dashes keep using dashes.

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 (dashes)	.agent/workflows/bmad-module-agents-name.md
codex	Flattened (dashes)	~/.codex/prompts/bmad-module-agents-name.md
cline	Flattened (dashes)	.clinerules/workflows/bmad-module-type-name.md
roo	Flattened (dashes)	.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 Folder-Based IDEs (convert to colon format)

IDEs affected: claude-code, cursor, crush

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:whats-after.md
- Tool:       bmad:core:tools:code-review.md
- Custom:     bmad:custom:agents:fred-commit-poet.md

For Already-Flat IDEs (keep using dashes)

IDEs affected: antigravity, codex, cline, roo

Format: bmad-{module}-{type}-{name}.md

Examples:
- Agent:      bmad-bmm-agents-pm.md
- Workflow:   bmad-bmm-workflows-correct-course.md
- Task:       bmad-bmm-tasks-whats-after.md
- Custom:     bmad-custom-agents-fred-commit-poet.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 colon-separated name (for folder-based IDEs)
 * @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', 'correct-course')
 * @returns {string} Flat filename like 'bmad:bmm:agents:pm.md'
 */
function toColonName(module, type, name) {
  return `bmad:${module}:${type}:${name}.md`;
}

/**
 * Convert relative path to flat colon-separated name (for folder-based IDEs)
 * @param {string} relativePath - Path like 'bmm/agents/pm.md'
 * @returns {string} Flat filename like 'bmad:bmm:agents:pm.md'
 */
function toColonPath(relativePath) {
  const withoutExt = relativePath.replace('.md', '');
  const parts = withoutExt.split(/[\/\\]/);
  return `bmad:${parts.join(':')}.md`;
}

/**
 * Convert hierarchical path to flat dash-separated name (for flat IDEs)
 * @param {string} relativePath - Path like 'bmm/agents/pm.md'
 * @returns {string} Flat filename like 'bmad-bmm-agents-pm.md'
 */
function toDashPath(relativePath) {
  const withoutExt = relativePath.replace('.md', '');
  const parts = withoutExt.split(/[\/\\]/);
  return `bmad-${parts.join('-')}.md`;
}

/**
 * Create custom agent colon name
 * @param {string} agentName - Custom agent name
 * @returns {string} Flat filename like 'bmad:custom:agents:fred-commit-poet.md'
 */
function customAgentColonName(agentName) {
  return `bmad:custom:agents:${agentName}.md`;
}

/**
 * Create custom agent dash name
 * @param {string} agentName - Custom agent name
 * @returns {string} Flat filename like 'bmad-custom-agents-fred-commit-poet.md'
 */
function customAgentDashName(agentName) {
  return `bmad-custom-agents-${agentName}.md`;
}

module.exports = {
  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
4. Add method writeDashArtifacts() for flat IDEs

Phase 3: Update Folder-Based IDEs

Files to modify:

• claude-code.js
• cursor.js
• crush.js

Changes:

1. Import toColonPath, customAgentColonName from path-utils
2. Change from hierarchical to flat colon naming
3. Update cleanup to handle flat structure

Phase 4: Update Flat IDEs

Files to modify:

• antigravity.js
• codex.js
• cline.js
• roo.js

Changes:

1. Import toDashPath, customAgentDashName from path-utils
2. Replace local flattenFilename() with shared toDashPath()

Phase 5: 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

Folder-Based IDEs (convert to colon format)

• Update shared/agent-command-generator.js - add writeColonArtifacts()
• Update shared/task-tool-command-generator.js - add writeColonArtifacts()
• Update shared/workflow-command-generator.js - add writeColonArtifacts()
• Update claude-code.js - convert to colon format
• Update cursor.js - convert to colon format
• Update crush.js - convert to colon format

Flat IDEs (standardize dash format)

• Update shared/agent-command-generator.js - add writeDashArtifacts()
• Update shared/task-tool-command-generator.js - add writeDashArtifacts()
• Update shared/workflow-command-generator.js - add writeDashArtifacts()
• Update antigravity.js - use shared toDashPath()
• Update codex.js - use shared toDashPath()
• Update cline.js - use shared toDashPath()
• Update roo.js - use shared toDashPath()

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. Keep segments: agents, workflows, tasks, tools all become part of the flat name
2. Colon vs Dash: Colons for folder-based IDEs converting to flat, dashes for already-flat IDEs
3. Custom agents: Follow the same pattern as regular agents
4. Backward compatibility: Cleanup will remove old folder structure