@cloudkinetix/bmad-enhanced/ck-layer/docs/UPSTREAM_SYNC_IMPROVEMENT.md

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

# Upstream Sync Improvement Summary

## Problem Solved

The Cloud Kinetix fork was experiencing massive merge conflicts (272+ files) during upstream syncs because:

- CK deleted upstream files (causing modify/delete conflicts)
- Both versions modified the same core files
- No clear separation between upstream and CK territories

## Solution Implemented: True Layered Architecture

### Before (Mixed Architecture)

```
bmad-enhanced/
├── lib/         # CK files mixed with upstream
├── config/      # CK files mixed with upstream
├── docs-ck/     # CK docs separate (good)
├── bmad-core/   # Upstream content
└── [deleted upstream dist files] # Causes conflicts!
```

### After (Layered Architecture)

```
bmad-enhanced/
├── ck-layer/          # ALL CK additions here
│   ├── lib/           # CK enterprise features
│   ├── config/        # CK configurations
│   ├── scripts/       # CK scripts
│   ├── bin/           # CK CLI entry points
│   ├── docs/          # CK documentation
│   └── expansion-packs/ # CK expansion packs
├── bmad-core/         # Pure upstream (never modify)
├── expansion-packs/   # Upstream packs
├── dist/              # Upstream dist (restored)
└── tools/             # Upstream tools
```

## Results

### Conflict Reduction

- **Before**: 272+ file conflicts
- **After**: ~18 file conflicts (mostly expected: README.md, package.json)
- **Reduction**: 93%+ fewer conflicts

### Clean Separation

- Upstream owns: `bmad-core/`, `tools/`, `dist/`, base `expansion-packs/`
- CK owns: `ck-layer/` and everything in it
- No file deletion conflicts anymore

### Key Changes Made

1. **Moved all CK files to ck-layer/**
   - lib/ → ck-layer/lib/
   - config/ → ck-layer/config/
   - scripts/ → ck-layer/scripts/
   - bin/ → ck-layer/bin/
   - docs-ck/ → ck-layer/docs/

2. **Restored upstream files**
   - Brought back dist/agents/\*.txt
   - Restored .github/ and .vscode/
   - Added .gitignore rules instead of deleting

3. **Updated all path references**
   - package.json bin paths
   - require() statements in lib files
   - npm scripts

## Future Upstream Sync Process

```bash
# 1. Fetch upstream
git fetch upstream-main

# 2. Merge - minimal conflicts now!
git merge upstream-main/main

# 3. Resolve the few remaining conflicts:
#    - README.md: Keep CK section at bottom
#    - package.json: Use package-minimal.json approach
#    - Any legitimate CK changes to upstream files

# 4. Commit
git commit -m "chore: sync with upstream BMAD vX.X.X"
```

## Benefits

1. **Easier maintenance** - Clear ownership boundaries
2. **Faster syncs** - 93% fewer conflicts to resolve
3. **Cleaner git history** - No more massive conflict resolutions
4. **Better architecture** - True separation of concerns
5. **Future flexibility** - Could become true NPM dependency