@cloudkinetix/bmad-enhanced/ck-layer/docs/MIGRATION-TO-SIMPLE.md

Cloud-Kinetix enhanced fork of BMAD-METHOD - Breakthrough Method of Agile AI-driven Development with robust versioning and unified validation.

# Migration Guide: Complex to Simplified CK Installer

## Overview

This guide helps you migrate from the complex CK installer to the new simplified thin-layer architecture.

## What's Changing?

### Removed Complexity

- ❌ Complex dependency resolution wrapper (678 lines)
- ❌ Duplicate command parsing and validation
- ❌ Temporary directory management for npm issues
- ❌ Interactive prompt handling workarounds

### Kept Features

- ✅ All CK expansion packs (JIRA, AI Dev, Parallel, GitLab)
- ✅ Professional backup system
- ✅ Enhanced IDE support (7 IDEs)
- ✅ Web bundle generation
- ✅ Configuration management

## Migration Steps

### 1. Update package.json

```json
{
  "bin": {
    "bmad-enhanced": "ck-layer/bin/bmad-enhanced-simple.js",
    "bmad-enhanced-legacy": "ck-layer/bin/bmad-enhanced.js"
  }
}
```

### 2. Test Installation

```bash
# Test new simplified installer
node ck-layer/bin/bmad-enhanced-simple.js install --full

# Compare with legacy
node ck-layer/bin/bmad-enhanced.js install --full
```

### 3. Update Scripts

If you have scripts using the CK installer, update them:

```bash
# Before
npx @cloudkinetix/bmad-enhanced install \
  --full \
  --directory /path/to/project \
  --ide cursor claude-code \
  --expansion-packs ck-jira-integration

# After (same command, simpler implementation)
npx @cloudkinetix/bmad-enhanced install \
  --full \
  --directory /path/to/project \
  --ide cursor claude-code \
  --expansion-packs ck-jira-integration
```

## Key Differences

### 1. Dependency Handling

**Before**: Complex wrapper to install missing dependencies

```javascript
// 400+ lines of dependency resolution code
const missingDeps = await this.detectMissingDependencies();
for (const dep of missingDeps) {
  execSync(`npm install ${dep.name}@${dep.version}`);
}
```

**After**: Direct upstream execution

```javascript
// Simple npx call
spawn("npx", ["--yes", "bmad-method@latest", ...args]);
```

### 2. Command Structure

**Before**: Every command wrapped with complex logic
**After**: Only enhanced commands have hooks; others pass through

### 3. Error Handling

**Before**: Complex error recovery and retries
**After**: Simple error propagation from upstream

## Compatibility

### Backward Compatible

- All command-line options remain the same
- Output format unchanged
- Installation results identical

### Breaking Changes

- None for end users
- Internal API changes for developers extending CK

## Benefits

1. **Faster Installation**: No temporary npm installations
2. **More Reliable**: Fewer moving parts
3. **Easier Debugging**: Clear separation of CK vs upstream
4. **Better Maintenance**: 80% less code
5. **Automatic Updates**: Inherits upstream improvements

## Troubleshooting

### Issue: Installation fails with dependency errors

**Solution**: Update to latest npm/node version. The simplified installer relies on upstream BMAD being properly packaged.

### Issue: CK features not installing

**Solution**: Check that you're not using `--no-ck-features` flag

### Issue: Backup not working

**Solution**: Ensure write permissions in project directory

## Rollback Plan

If you need to rollback to the complex installer:

```bash
# Use legacy command
npx @cloudkinetix/bmad-enhanced-legacy install

# Or directly
node ck-layer/bin/bmad-enhanced.js install
```

## Timeline

1. **v1.11.0**: Simplified installer available as beta
2. **v1.12.0**: Simplified installer becomes default
3. **v2.0.0**: Complex installer removed

## Support

For issues with migration:

1. Check this guide
2. Run with `--verbose` flag
3. Report issues to Cloud Kinetix support