/upgrade-framework

Framework Upgrade Protocol

**Purpose:** Migrate project from old Framework version (v1.x or v2.0) to current version (v2.2).

**When to use:** Project already has `.claude/` directory with older Framework structure.

---

Step 0: Initialize Migration Log

Before starting, create migration log for crash recovery:

# Get old version from migration context
OLD_VERSION=$(cat .claude/migration-context.json 2>/dev/null | grep -o '"old_version"[^,]*' | cut -d'"' -f4)

echo '{
  "status": "in_progress",
  "mode": "upgrade",
  "old_version": "'$OLD_VERSION'",
  "started": "'$(date -Iseconds)'",
  "updated": "'$(date -Iseconds)'",
  "current_step": 1,
  "current_step_name": "detect",
  "steps_completed": [],
  "last_error": null
}' > .claude/migration-log.json

**Update log after each step** (same as migrate-legacy).

---

Core Principles

1. 💾 **Preserve ALL existing data** - never lose user's work 2. 🔄 **Incremental migration** - step by step with verification 3. 📋 **Show migration plan** before executing 4. 🎓 **Explain changes** in simple terms 5. ✅ **Backup first** - create safety backup before changes

---

Step 1: Detect Old Framework Version

1.1 Check Framework Markers

# Check for v2.x markers
if [ -f ".claude/SNAPSHOT.md" ]; then
  grep "Framework:" .claude/SNAPSHOT.md | awk '{print $2}'
fi

# Check for v1.x markers (old structure)
if [ -f "Init/PROJECT_SNAPSHOT.md" ]; then
  echo "v1.x (legacy structure)"
fi

# Check BACKLOG structure
if [ -f ".claude/BACKLOG.md" ]; then
  # v2.0 if no ROADMAP.md
  if [ ! -f ".claude/ROADMAP.md" ]; then
    echo "v2.0 (missing ROADMAP/IDEAS)"
  fi
fi

1.2 Report Detected Version

Show user what was detected:

🔍 Framework Version Detection

Found: Framework v[VERSION]

Structure detected:
[v1.x]
  ✅ Init/PROJECT_SNAPSHOT.md
  ✅ Init/BACKLOG.md
  ✅ Init/ARCHITECTURE.md
  ❌ .claude/ (missing)

[v2.0]
  ✅ .claude/SNAPSHOT.md
  ✅ .claude/BACKLOG.md
  ✅ .claude/ARCHITECTURE.md
  ❌ ROADMAP.md (missing)
  ❌ IDEAS.md (missing)

[v2.1+] TARGET
  ✅ .claude/SNAPSHOT.md
  ✅ .claude/BACKLOG.md
  ✅ .claude/ROADMAP.md (new)
  ✅ .claude/IDEAS.md (new)
  ✅ .claude/ARCHITECTURE.md

Migration required: [VERSION] → v2.1
````

---

## Step 2: Read Existing Files

Read all existing Framework files to preserve data.

### 2.1 For v1.x Projects

```bash
# Old structure
cat Init/PROJECT_SNAPSHOT.md
cat Init/BACKLOG.md
cat Init/ARCHITECTURE.md
cat Init/CHANGELOG.md 2>/dev/null
cat Init/docs/MIGRATION_GUIDE.md 2>/dev/null

# Check for migration/ folder
ls -la migration/ 2>/dev/null

2.2 For v2.0 Projects

# Current structure
cat .claude/SNAPSHOT.md
cat .claude/BACKLOG.md
cat .claude/ARCHITECTURE.md

# Check what's missing
[ -f ".claude/ROADMAP.md" ] || echo "ROADMAP.md missing"
[ -f ".claude/IDEAS.md" ] || echo "IDEAS.md missing"

2.3 Extract Key Information

From read files, extract:

• **Current version** (from SNAPSHOT)
• **Active tasks** (from BACKLOG)
• **Project structure** (from ARCHITECTURE)
• **Development phase** (from SNAPSHOT)
• **Recent achievements** (from SNAPSHOT)

---

Step 3: Create Migration Plan

Based on detected version, create detailed migration plan.

Migration: v1.x → v2.1

# 📋 Migration Plan: v1.x → v2.1

## Overview
Upgrade from legacy Init/ structure to modern .claude/ structure.

## Changes Required:

### 1. File Relocations

Init/PROJECT_SNAPSHOT.md → .claude/SNAPSHOT.md Init/BACKLOG.md → .claude/BACKLOG.md Init/ARCHITECTURE.md → .claude/ARCHITECTURE.md Init/ → [archived]

### 2. New Files to Create

.claude/ROADMAP.md (NEW) - Strategic planning .claude/IDEAS.md (NEW) - Spontaneous ideas

### 3. BACKLOG.md Restructure
**Current format:**
```markdown
## Tasks
- [ ] Task 1
- [ ] Task 2

**New format (3-level):**

## Phase X: [Current Sprint]
- [ ] Task 1
  - [ ] Subtask

Priority 1 moved to → ROADMAP.md
Ideas moved to → IDEAS.md

4. SNAPSHOT.md Updates

**Add new sections:**

• Link to ROADMAP.md
• Link to IDEAS.md
• Framework version marker

5. migration/ Folder

Keep migration/ folder (contains templates)
Add init-project.sh if missing

What Will NOT Change:

✅ All your task data preserved ✅ All your architecture notes preserved ✅ All your project information preserved ✅ Git history untouched ✅ Code untouched

Backup Strategy:

Before making changes:

cp -r Init/ Init-backup-$(date +%Y%m%d)
cp -r .claude/ .claude-backup-$(date +%Y%m%d) 2>/dev/null

Estimated Time: 2-3 minutes

Estimated Tokens: ~5k tokens

### Migration: v2.0 → v2.1

````markdown
# 📋 Migration Plan: v2.0 → v2.1

## Overview
Add new 3-level planning structure (IDEAS → ROADMAP → BACKLOG).

## Changes Required:

### 1. Extract from Current BACKLOG

Analyze current `.claude/BACKLOG.md`:
- **Concrete tasks** → stay in BACKLOG.md
- **Priority 1 ideas** → move to ROADMAP.md
- **Unstructured ideas** → move to IDEAS.md

### 2. Create New Files

.claude/ROADMAP.md (NEW)

• Extract from BACKLOG Priority 1
• Extract from README roadmap section if exists
• Organize by versions (v2.2, v2.3, v3.0)

.claude/IDEAS.md (NEW)

• Create empty template
• Optionally extract "good to have" from BACKLOG

### 3. Restructure BACKLOG.md

**Current:**
```markdown
## Phase X
- tasks

## Priority 1
- ideas

**New:**

## Phase X
- only concrete tasks

[Priority 1 moved to ROADMAP.md]

4. Update SNAPSHOT.md

Add references:

> **Planning:**
> - Current tasks: [BACKLOG.md](./BACKLOG.md)
> - Strategic plan: [ROADMAP.md](./ROADMAP.md)
> - Ideas: [IDEAS.md](./IDEAS.md)

5. Update README.md

Replace full roadmap with link:

## Roadmap
See [.claude/ROADMAP.md](.claude/ROADMAP.md)

What Will NOT Change:

✅ All your tasks preserved ✅ All your ideas preserved (just reorganized) ✅ SNAPSHOT content intact ✅ ARCHITECTURE content intact

Backu