209 lines
6.9 KiB
Markdown
209 lines
6.9 KiB
Markdown
# 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`
|
|
|
|
```javascript
|
|
/**
|
|
* 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
|
|
- [x] Create `shared/path-utils.js`
|
|
|
|
### All IDEs (convert to underscore format)
|
|
- [x] Update `shared/agent-command-generator.js` - update for underscore
|
|
- [x] Update `shared/task-tool-command-generator.js` - update for underscore
|
|
- [x] Update `shared/workflow-command-generator.js` - update for underscore
|
|
- [x] Update `claude-code.js` - convert to underscore format
|
|
- [x] Update `cursor.js` - convert to underscore format
|
|
- [x] 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
|
|
- [x] Update `src/core/module-help.csv` - change colons to underscores
|
|
- [x] 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
|