# Cloud Kinetix Layered Architecture

## Overview

The Cloud Kinetix Enhanced fork now uses a **true layered architecture** that cleanly separates CK enhancements from upstream BMAD content. This enables conflict-free upstream syncing while maintaining all enterprise features.

## Directory Structure

```
bmad-enhanced/
├── bmad-core/          # Pure upstream BMAD (never modify)
├── ck-layer/           # Cloud Kinetix code additions
│   ├── lib/            # Enterprise features
│   ├── config/         # CK configuration
│   ├── scripts/        # Build and release scripts
│   ├── bin/            # CLI entry points
│   └── docs/           # CK technical documentation
├── docs-ck/            # CK user documentation (exception #1)
├── expansion-packs/    # All expansion packs (exception #2)
│   ├── bmad-*          # Upstream expansion packs
│   └── ck-*            # Cloud Kinetix expansion packs
├── tools/              # Upstream build tools
├── dist/               # Build outputs (both layers)
└── package.json        # Minimal, delegates to both
```

**Exceptions to the layered architecture:**

1. **`docs-ck/`** - User documentation at root for better discoverability
2. **`expansion-packs/ck-*`** - CK expansion packs alongside upstream packs for consistency

## Key Benefits

1. **Clean Upstream Syncs**
   - No more modify/delete conflicts
   - Upstream changes flow through automatically
   - CK changes isolated in ck-layer/

2. **Clear Ownership**
   - Upstream owns: bmad-core/, tools/, expansion-packs/bmad-\*
   - CK owns: ck-layer/, expansion-packs/ck-\*, docs-ck/
   - No file conflicts between layers

3. **Build-Time Integration**
   - Installer reads from both layers
   - Merges content during installation
   - Git repository stays clean

## Migration Steps

### For Development

1. Pull the restructured branch
2. Update any scripts that reference old paths:
   - `lib/` → `ck-layer/lib/`
   - `config/` → `ck-layer/config/`
   - `scripts/` → `ck-layer/scripts/`
   - `bin/` → `ck-layer/bin/`

3. Test the installer:
   ```bash
   node ck-layer/bin/bmad-enhanced.js install --default
   ```

### For CI/CD

Update any CI scripts that reference:

- `bin/bmad-enhanced.js` → `ck-layer/bin/bmad-enhanced.js`
- Direct lib imports → Use ck-layer paths

## Upstream Sync Process

With the new structure, upstream syncs are simple:

```bash
# Fetch upstream changes
git fetch upstream-main

# Merge - should have minimal conflicts
git merge upstream-main/main

# Conflicts should only be in:
# - README.md (keep CK section at bottom)
# - package.json (if needed, use package-minimal.json)
```

## Important Rules

1. **Never modify files in bmad-core/** - These come from upstream
2. **Most CK changes go in ck-layer/** - This is our territory
3. **Use .gitignore for upstream dist/** - Prevents modify/delete conflicts
4. **Build process handles integration** - Don't merge in git
5. **Two exceptions for user-facing content:**
   - **docs-ck/** - User documentation at root for accessibility
   - **expansion-packs/ck-\*/** - CK packs alongside upstream for consistency

## Future Improvements

1. Consider making CK a true NPM dependency of upstream
2. Contribute generic improvements back to upstream
3. Further minimize overlap between layers