/migrate-legacy

Legacy Project Migration Protocol

**Purpose:** Analyze existing project without Framework and generate Framework files based on deep analysis.

**When to use:** Legacy project with code but no `.claude/` directory.

---

Step 0: Initialize Migration Log

Before starting, create migration log for crash recovery:

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

**Update log after each step:**

# Template for updating log (replace STEP_NUM and STEP_NAME)
echo '{
  "status": "in_progress",
  "mode": "legacy",
  "started": "[keep original]",
  "updated": "'$(date -Iseconds)'",
  "current_step": STEP_NUM,
  "current_step_name": "STEP_NAME",
  "steps_completed": ["discovery", "analysis", ...],
  "last_error": null
}' > .claude/migration-log.json

---

Core Principles

1. ❌ **NEVER modify existing project files** - only create `.claude/` files 2. 🎓 **User is not technical** - explain everything in simple terms 3. 🤝 **Qualifying questions** - always provide options with clear recommendations 4. 📊 **Detailed report first** - show analysis before generating files 5. 💰 **Token transparency** - track and report token usage

---

Step 1: Initial Context

Check if migration context exists:

cat .claude/migration-context.json 2>/dev/null

If exists, you're in legacy migration mode. If not, ask user to run `./init-project.sh` first.

---

Step 2: Discovery Phase

Search for potential analog files and project info.

2.1 Find Documentation Files

**IMPORTANT:** Scan both root AND subdirectories (docs/, documentation/, notes/, wiki/, .github/)

# Step 2.1.1: Search root directory for common meta-documentation files
echo "🔍 Scanning root directory..."
ROOT_DOCS=$(find . -maxdepth 1 -type f \( \
  -name "README*" -o \
  -name "TODO*" -o \
  -name "TASKS*" -o \
  -name "BACKLOG*" -o \
  -name "ROADMAP*" -o \
  -name "ARCHITECTURE*" -o \
  -name "DESIGN*" -o \
  -name "STATUS*" -o \
  -name "CHANGELOG*" \
\) 2>/dev/null)

# Step 2.1.2: Search subdirectories for meta-documentation
echo "🔍 Scanning subdirectories (docs/, documentation/, notes/, wiki/, .github/)..."

SUBDIRS_DOCS=""

# Scan each subdirectory if it exists
for DIR in docs documentation notes wiki .github; do
  if [ -d "$DIR" ]; then
    # Find ALL .md files in subdirectory
    SUBDIR_MD=$(find "$DIR" -type f -name "*.md" 2>/dev/null | grep -v node_modules | grep -v .git)

    if [ -n "$SUBDIR_MD" ]; then
      SUBDIRS_DOCS="$SUBDIRS_DOCS
$SUBDIR_MD"
    fi
  fi
done

# Combine results
ALL_DOCS="$ROOT_DOCS
$SUBDIRS_DOCS"

**Step 2.1.3: Classify by Content (Meta-documentation vs Code docs)**

For each found .md file, read first 50 lines and classify:

# Function to classify file by content
classify_doc() {
  FILE=$1
  CONTENT=$(head -50 "$FILE" 2>/dev/null)

  # Meta-documentation indicators
  META_SCORE=0
  echo "$CONTENT" | grep -qi "roadmap\|backlog\|todo\|status\|project intake\|requirements\|we decided\|our project\|architecture decision\|design decision\|security policy\|workflow\|meeting notes" && META_SCORE=$((META_SCORE + 1))

  # Code documentation indicators
  CODE_SCORE=0
  echo "$CONTENT" | grep -qi "api reference\|api documentation\|function reference\|class documentation\|how to use\|tutorial\|example:\|usage:" && CODE_SCORE=$((CODE_SCORE + 1))

  # Classify
  if [ $META_SCORE -gt $CODE_SCORE ]; then
    echo "meta"
  elif [ $CODE_SCORE -gt $META_SCORE ]; then
    echo "code"
  else
    # Ambiguous - default to meta if contains certain keywords in filename
    if echo "$FILE" | grep -qi "backlog\|roadmap\|status\|architecture\|design\|requirements"; then
      echo "meta"
    else
      echo "ambiguous"
    fi
  fi
}

# Classify all found docs
META_DOCS=""
CODE_DOCS=""
AMBIGUOUS_DOCS=""

while IFS= read -r FILE; do
  [ -z "$FILE" ] && continue

  CLASSIFICATION=$(classify_doc "$FILE")

  case $CLASSIFICATION in
    meta)
      META_DOCS="$META_DOCS
$FILE"
      ;;
    code)
      CODE_DOCS="$CODE_DOCS
$FILE"
      ;;
    ambiguous)
      AMBIGUOUS_DOCS="$AMBIGUOUS_DOCS
$FILE"
      ;;
  esac
done <<< "$ALL_DOCS"

2.2 Check Project Metadata

# Package info
cat package.json 2>/dev/null | head -20

# Git history
git log --oneline --all -50 2>/dev/null

# GitHub Issues (if available)
gh issue list --limit 50 --state all 2>/dev/null

2.3 Report Discovery Results

Show user what you found with classification:

🔍 Discovery Results:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 META-DOCUMENTATION (will be migrated)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Root directory:
  ✅ README.md (145 lines, has roadmap section)
  ✅ TODO.md (23 tasks)

docs/ subdirectory:
  ✅ docs/BACKLOG.md (491 lines, roadmap v0.2-v1.3) ← CRITICAL!
  ✅ docs/STATUS.md (273 lines, project status v0.3.3)
  ✅ docs/ARCHITECTURE.md (89 lines)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📖 CODE DOCUMENTATION (will be skipped)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

docs/ subdirectory:
  🟡 docs/api-reference.md (API documentation)
  🟡 docs/installation.md (user guide)
  🟡 docs/tutorial.md (how-to guide)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❓ AMBIGUOUS (need your input)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

docs/ subdirectory:
  ⚪ docs/project-notes.md (87 lines)
     Reason: Contains both project decisions and usage examples

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📦 Project Info:
  • Name: [from package.json]
  • Version: [version]
  • Type: [React/Node.js/etc]

📊 History:
  • Total commits: 237
  • Recent activity: 15 commits last week
  • Contributors: 3

🐛 Issues:
  • Open: 8
  • Closed: 45

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
````

**If ambiguous files found, ask user:**

````
❓ Question: How to handle ambiguous files?

I found docs/p