2998 Task 09 Migration System 9773f398

TASK-09: Plugin Update Migration System

Created: 2025-10-18 Status: Planning Priority: Critical Complexity: High

Context

Need robust migration system for updating Navigator plugin across versions (v1.6 → v2.0 → v3.0) without breaking existing user projects.

Current Reality

User projects found with old config:

/Users/aleks.petrov/Projects/startups/linearinvoices/.agent/.jitd-config.json
/Users/aleks.petrov/Projects/startups/quant-flow-landing/.agent/.jitd-config.json
/Users/aleks.petrov/Projects/tmp/jitd-test/.agent/.jitd-config.json

Migration challenges:

1. Plugin name change: jitd → navigator
2. Config file rename: .jitd-config.json → .nav-config.json
3. Command changes: /jitd:* → /nav:*
4. Skills added (v2.0+)
5. Commands deprecated (v2.5+)
6. Commands removed (v3.0+)
7. User projects reference old names in documentation
8. CLAUDE.md in user projects has old /jitd:* commands

Problem Statement

When user updates plugin from v1.6 to v3.0:

• ❌ Old config .jitd-config.json not recognized
• ❌ Old commands /jitd:* don't exist
• ❌ Documentation references broken links
• ❌ No automatic migration
• ❌ User doesn't know what to fix
• ❌ Breaking changes without warning

What we need:

• ✅ Automatic detection of old config
• ✅ Automatic migration of config file
• ✅ Backward compatibility layer
• ✅ Clear upgrade path with warnings
• ✅ Migration script for documentation
• ✅ Zero breaking changes for users
• ✅ Smooth transition across versions

Migration System Architecture

1. Semantic Versioning Strategy

v1.x → v2.x: Minor breaking (deprecation warnings)
v2.x → v3.x: Major breaking (full migration required)

v1.6 (JITD)
  ├─ Config: .jitd-config.json
  ├─ Commands: /jitd:*
  └─ No skills

v2.0 (Navigator - Hybrid)
  ├─ Config: .nav-config.json (auto-migrate from .jitd-config.json)
  ├─ Commands: /nav:* (backward compat: /jitd:* → /nav:* redirect)
  ├─ Skills: 5 core skills
  └─ Deprecation warnings for /jitd:*

v2.1 (Enhanced)
  ├─ Config: .nav-config.json
  ├─ Commands: /nav:* (still supports /jitd:* with warnings)
  ├─ Skills: 6 skills + predefined functions
  └─ Migration helper: /nav:migrate command

v2.5 (Pre-v3)
  ├─ Config: .nav-config.json
  ├─ Commands: /nav:* (loud warnings for /jitd:*, suggest migration)
  ├─ Skills: 11+ skills (core + project-specific)
  └─ Migration required warning

v3.0 (Skills-Only)
  ├─ Config: .nav-config.json (auto-migrate, remove old)
  ├─ Commands: REMOVED (error with migration instructions)
  ├─ Skills: All automation via skills
  └─ Breaking: Old commands fail with helpful error

2. Config Migration System

Location: scripts/migrate-config.sh

#!/bin/bash
# Config migration script
# Called automatically on plugin update

PROJECT_ROOT="$1"
AGENT_DIR="$PROJECT_ROOT/.agent"

# Detect old config
if [ -f "$AGENT_DIR/.jitd-config.json" ] && [ ! -f "$AGENT_DIR/.nav-config.json" ]; then
    echo "🔄 Migrating Navigator config: .jitd-config.json → .nav-config.json"

    # Rename config
    mv "$AGENT_DIR/.jitd-config.json" "$AGENT_DIR/.nav-config.json"

    # Update version in config
    sed -i '' 's/"version": "1\.0\.0"/"version": "2.0.0"/' "$AGENT_DIR/.nav-config.json"

    echo "✅ Config migrated successfully"
    echo "📝 Old commands (/jitd:*) will work but are deprecated"
    echo "💡 Update to new commands: /jitd:start → /nav:start"
fi

# Detect both configs (user needs to clean up)
if [ -f "$AGENT_DIR/.jitd-config.json" ] && [ -f "$AGENT_DIR/.nav-config.json" ]; then
    echo "⚠️  Both .jitd-config.json and .nav-config.json found"
    echo "📝 Please remove .jitd-config.json (already migrated)"
fi

3. Backward Compatibility Layer

Location: commands/_backward_compat.md (hidden command)

---
description: "[INTERNAL] Backward compatibility redirects for deprecated commands"
---

# Backward Compatibility Layer

This file provides redirects from old `/jitd:*` commands to new `/nav:*` commands.

## Redirect Map

When user types:          Execute:           Show warning:
/jitd:init         →      /nav:init          ⚠️ Deprecated, use /nav:init
/jitd:start        →      /nav:start         ⚠️ Deprecated, use /nav:start
/jitd:update-doc   →      /nav:doc           ⚠️ Deprecated, use /nav:doc
/jitd:marker       →      /nav:marker        ⚠️ Deprecated, use /nav:marker
/jitd:markers      →      /nav:markers       ⚠️ Deprecated, use /nav:markers
/jitd:compact      →      /nav:compact       ⚠️ Deprecated, use /nav:compact

## Implementation

Slash commands registered in plugin.json:
```json
{
  "commands": [
    "./commands/init.md",
    "./commands/start.md",
    "./commands/doc.md",
    "./commands/marker.md",
    "./commands/markers.md",
    "./commands/compact.md",
    "./commands/_jitd_init.md",        // Redirect with warning
    "./commands/_jitd_start.md",       // Redirect with warning
    "./commands/_jitd_update_doc.md",  // Redirect with warning
    "./commands/_jitd_marker.md",      // Redirect with warning
    "./commands/_jitd_markers.md",     // Redirect with warning
    "./commands/_jitd_compact.md"      // Redirect with warning
  ]
}

Each _jitd_*.md file shows warning and calls new command.

**Example**: `commands/_jitd_start.md`

```markdown
---
description: "[DEPRECATED] Use /nav:start instead"
---

⚠️ **DEPRECATION WARNING**

The `/jitd:start` command is deprecated. Please use `/nav:start` instead.

**Navigator plugin was renamed from JITD to Navigator in v2.0**

Update your workflow:
- ~~`/jitd:start`~~ → `/nav:start`
- ~~`/jitd:marker`~~ → `/nav:marker`
- ~~`/jitd:compact`~~ → `/nav:compact`

This backward compatibility will be removed in v3.0.

---

**Executing /nav:start for you...**

<!-- Include actual /nav:start content here -->
{{INCLUDE:commands/start.md}}

4. Migration Command

Location: commands/migrate.md

---
description: Migrate Navigator plugin from v1.x to v2.x+
---

# Navigator Migration Tool

Migrate your project from JITD (v1.x) to Navigator (v2.x+).

## What This Does

1. ✅ Renames `.jitd-config.json` → `.nav-config.json`
2. ✅ Updates config version to 2.0.0
3. ✅ Scans CLAUDE.md for `/jitd:*` references
4. ✅ Scans `.agent/` docs for `/jitd:*` references
5. ✅ Generates migration report
6. ✅ Optionally auto-fixes documentation

## Usage

```bash
/nav:migrate

Migration Steps

Step 1: Detect Old Config

Checking for .agent/.jitd-config.json...

Found: .agent/.jitd-config.json Action: Rename to .nav-config.json

Step 2: Scan Documentation

Scanning for /jitd:* references...

Files with old references:

• CLAUDE.md (5 references)
• .agent/DEVELOPMENT-README.md (12 references)
• .agent/tasks/TASK-01.md (3 references)

Step 3: Show Changes

Config Migration:

- .agent/.jitd-config.json
+ .agent/.nav-config.json

Config Updates:

{
-  "version": "1.0.0"
+  "version": "2.0.0"
}

Documentation Updates:

CLAUDE.md:
-  /jitd:start
+  /nav:start

.agent/DEVELOPMENT-README.md:
-  Use `/jitd:marker` to save progress
+  Use `/nav:marker` to save progress

Step 4: Confirm Migration

Proceed with migration? [y/N]

Step 5: Execute Migration

✅ Renamed .jitd-config.json → .nav-config.json ✅ Updated config version to 2.0.0 ✅ Updated CLAUDE.md (5 references) ✅ Updated .agent/DEVELOPMENT-README.md (12 references) ✅ Updated .agent/tasks/TASK-01.md (3 references)

Migration complete!

Next steps:

1. Review changes with git diff
2. Test new commands: /nav:start, /nav:marker, etc.
3. Commit migration: git add . && git commit -m "chore: migrate to Navigator v2.0"

Rollback

If migration fails, restore from git:

git checkout .agent/.jitd-config.json
git checkout CLAUDE.md .agent/

### 5. Auto-Migration on Plugin Update

**Location**: `scripts/post-install.sh`

```bash
#!/bin/bash
# Post-install hook for Navigator plugin
# Called automatically by Claude Code after plugin install/update

PLUGIN_DIR="$(cd "$(dirname "$0")/.." && pwd)"
PLUGIN_VERSION="$(jq -r '.version' "$PLUGIN_DIR/.claude-plugin/plugin.json")"

echo "🔧 Navigator Plugin Post-Install (v$PLUGIN_VERSION)"

# Function to migrate a single project
migrate_project() {
    local project_dir="$1"
    local agent_dir="$project_dir/.agent"

    # Skip if no .agent directory
    [ ! -d "$agent_dir" ] && return

    # Check for old config
    if [ -f "$agent_dir/.jitd-config.json" ]; then
        echo ""
        echo "📦 Found Navigator project: $project_dir"
        echo "🔄 Migration needed: .jitd-config.json detected"

        # Ask user for migration (or auto-migrate based on config)
        echo ""
        echo "Migrate automatically? [Y/n]"
        read -r response

        if [[ "$response" =~ ^([yY][eE][sS]|[yY]|)$ ]]; then
            # Run migration
            bash "$PLUGIN_DIR/scripts/migrate-config.sh" "$project_dir"

            echo ""
            echo "💡 Tip: Run '/nav:migrate' in Claude Code to update documentation"
        else
            echo "⏭️  Skipped migration for $project_dir"
            echo "💡 Run '/nav:migrate' when ready"
        fi
    fi
}

# Find all Navigator projects in common locations
echo ""
echo "🔍 Scanning for Navigator projects..."

# Scan ~/Projects (customize based on user's workspace)
if [ -d "$HOME/Projects" ]; then
    while IFS= read -r -d '' project; do
        migrate_project "$(dirname "$(dirname "$project")")"
    done < <(find "$HOME/Projects" -name ".jitd-config.json" -print0 2>/dev/null)
fi

echo ""
echo "✅ Post-install complete"
echo ""
echo "📚 Documentation: https://github.com/alekspetrov/navigator-plugin"
echo "💬 Issues: https://github.com/alekspetrov/navigator-plugin/issues"

6. Version Detection in Commands

All commands should detect config version and adapt:

Example: commands/start.md

---
description: Start Navigator session - load navigator, set context, check tasks
---

# Start Navigator Session

<!-- Version detection -->
{{#if config.version < 2.0.0}}
⚠️ **Old config detected**: You're using Navigator v1.x config format.

**Recommended**: Migrate to v2.0 for new features (Skills, improved token efficiency)

Run: `/nav:migrate`

---
{{/if}}

<!-- Rest of command -->
Initialize your development session with Navigator workflow...

7. Breaking Changes in v3.0

v3.0 removes all commands - only Skills remain

Strategy: Hard fail with migration instructions

Location: commands/_deprecated_all.md (registered for all old commands in v3.0)

---
description: "[REMOVED IN v3.0] Commands have been replaced by Skills"
---

# ❌ Command Removed in Navigator v3.0

Commands have been replaced by **Skills** for better auto-invocation and token efficiency.

## What Happened?

Navigator v3.0 is **Skills-only**. Manual `/nav:*` commands have been removed.

## How to Migrate

### Before (v2.x - Commands):

User types: /nav:start → Manual command execution

### After (v3.0 - Skills):

User types: "Start my work session" → nav-start skill auto-invokes automatically → No manual command needed

## Migration Steps

1. **Remove command usage from your workflow**
   - ~~`/nav:start`~~ → Just say "start session" or "begin work"
   - ~~`/nav:marker`~~ → Just say "save my progress"
   - ~~`/nav:compact`~~ → Just say "clear context"

2. **Update CLAUDE.md** (if you customized it)
   ```bash
   # Run migration tool
   /nav:migrate  # (this still works as transition helper)

3. Learn Skills
   • Skills auto-invoke based on natural language
   • No need to remember command syntax
   • More intuitive workflow

Available Skills (v3.0)

Core Skills:

• nav-start - Triggers on: "start session", "begin work", "load navigator"
• nav-marker - Triggers on: "save progress", "create checkpoint"
• nav-compact - Triggers on: "clear context", "start fresh"
• nav-task - Triggers on: "document feature", "create task"
• nav-sop - Triggers on: "save this solution", "create SOP"
• nav-skill-creator - Triggers on: "create a skill for...", "automate this"

Project Skills (generated by nav-skill-creator):

• frontend-component - Triggers on: "create component"
• backend-endpoint - Triggers on: "add endpoint"
• database-migration - Triggers on: "create migration"
• And more...

Need Help?

• Documentation: https://github.com/alekspetrov/navigator-plugin
• Migration Guide: https://github.com/alekspetrov/navigator-plugin/blob/main/MIGRATION.md
• Issues: https://github.com/alekspetrov/navigator-plugin/issues

Rollback to v2.x

If you need commands back temporarily:

claude plugins install alekspetrov/navigator-plugin@2.5.0

Note: v2.x will receive security updates only (no new features)

---

## Migration Paths

### Path 1: v1.6 → v2.0 (Smooth)

**User experience**:
1. User updates plugin: `claude plugins update jitd-marketplace`
2. Post-install script runs, detects old config
3. Asks: "Migrate automatically? [Y/n]"
4. User presses Enter (yes)
5. Config renamed automatically
6. Message: "💡 Run '/nav:migrate' to update documentation"
7. User continues working with `/jitd:*` commands (they still work with warnings)
8. User runs `/nav:migrate` when ready
9. Documentation updated automatically
10. User commits migration

**No breaking changes** - everything still works

### Path 2: v1.6 → v2.5 (Warning Phase)

**User experience**:
1. Same as Path 1 (config auto-migrates)
2. Old commands work but show LOUD warnings:

⚠️ ⚠️ ⚠️ DEPRECATION WARNING ⚠️ ⚠️ ⚠️

/jitd:start will be REMOVED in v3.0

Please migrate: Run /nav:migrate

This is your last warning before breaking changes

Continuing with /nav:start...

3. User motivated to migrate

**Still no breaking changes** - just warnings

### Path 3: v1.6 → v3.0 (Hard Break with Guidance)

**User experience**:
1. User updates plugin: `claude plugins update navigator-marketplace`
2. Post-install detects v1.6, shows migration guide
3. User types `/jitd:start` (old habit)
4. **FAILS** with helpful error:

❌ Command removed in Navigator v3.0

Commands replaced by Skills (auto-invocation)

Instead of: /nav:start Just say: "start session" or "begin work"

Migration guide: /nav:migrate (transition helper)

5. User learns about Skills
6. User says "start my session"
7. nav-start skill auto-invokes
8. User realizes this is better (no command syntax to remember)

**Breaking change** - but clear path forward

### Path 4: v2.0 → v2.5 → v3.0 (Recommended)

**Best user experience** (gradual adoption):

**v2.0** (user learns Skills exist):
- Commands work fine
- Skills auto-invoke alongside commands
- User discovers: "Oh, I can just say 'start session' instead of /nav:start"

**v2.5** (user motivated to switch):
- Commands show warnings
- Skills work great
- User switches naturally

**v3.0** (user already using Skills):
- Commands removed
- User doesn't notice (already using Skills)
- Smooth transition

---

## Implementation Checklist

### v2.0 (Immediate)

- [ ] Create `scripts/migrate-config.sh`
- [ ] Create `scripts/post-install.sh`
- [ ] Create `commands/migrate.md`
- [ ] Add backward compat commands (`commands/_jitd_*.md`)
- [ ] Update plugin.json with both command sets
- [ ] Test migration v1.6 → v2.0
- [ ] Document migration in README.md
- [ ] Create MIGRATION.md guide

### v2.1 (Enhanced Migration)

- [ ] Add version detection to all commands
- [ ] Add auto-fix for common migration issues
- [ ] Create migration report generator
- [ ] Add rollback capability
- [ ] Test migration with real user projects

### v2.5 (Warning Phase)

- [ ] Add loud warnings to deprecated commands
- [ ] Create v3.0 migration preview
- [ ] Add Skills tutorial in deprecation warnings
- [ ] Send email to users about upcoming v3.0
- [ ] Create migration timeline

### v3.0 (Skills-Only)

- [ ] Remove all command files (except migrate helper)
- [ ] Replace with `commands/_deprecated_all.md`
- [ ] Update plugin.json (remove command references)
- [ ] Test that Skills auto-invoke correctly
- [ ] Create v3.0 migration completion report
- [ ] Update marketplace listing

---

## File Structure Evolution

### v1.6 (JITD)

.claude/plugins/marketplaces/jitd-marketplace/ ├── .claude-plugin/ │ └── plugin.json ├── commands/ │ ├── init.md │ ├── start.md │ ├── update-doc.md │ ├── marker.md │ ├── markers.md │ └── compact.md └── scripts/ └── session-stats.sh

### v2.0 (Navigator - Hybrid)

.claude/plugins/marketplaces/navigator-marketplace/ ├── .claude-plugin/ │ ├── plugin.json (both /nav:* and /jitd:*) │ └── marketplace.json ├── commands/ │ ├── init.md │ ├── start.md │ ├── doc.md (renamed from update-doc.md) │ ├── marker.md │ ├── markers.md │ ├── compact.md │ ├── migrate.md (NEW) │ ├── _jitd_init.md (backward compat) │ ├── _jitd_start.md │ ├── _jitd_update_doc.md │ ├── _jitd_marker.md │ ├── _jitd_markers.md │ └── _jitd_compact.md ├── skills/ (NEW) │ ├── nav-start/ │ ├── nav-marker/ │ ├── nav-compact/ │ ├── nav-task/ │ └── nav-sop/ └── scripts/ ├── migrate-config.sh (NEW) ├── post-install.sh (NEW) └── session_stats.py

### v2.5 (Warning Phase)

Same as v2.0, but:

• jitd*.md files show LOUD warnings
• migrate.md enhanced with v3.0 preview

### v3.0 (Skills-Only)

.claude/plugins/marketplaces/navigator-marketplace/ ├── .claude-plugin/ │ ├── plugin.json (skills only) │ └── marketplace.json ├── commands/ │ └── _deprecated_all.md (shows helpful error) ├── skills/ │ ├── nav-start/ │ ├── nav-marker/ │ ├── nav-compact/ │ ├── nav-task/ │ ├── nav-sop/ │ ├── nav-skill-creator/ │ ├── frontend-component/ (project-specific) │ ├── backend-endpoint/ │ ├── database-migration/ │ ├── backend-test/ │ └── frontend-test/ └── scripts/ ├── migrate-config.sh (still works for stragglers) ├── post-install.sh (updated for v3.0) └── session_stats.py

---

## Testing Strategy

### Test Scenario 1: Fresh Install v2.0

**Steps**:
1. User installs Navigator v2.0 (never had JITD)
2. Runs `/nav:init`
3. Creates `.nav-config.json`
4. No migration needed

**Expected**: Clean install, no warnings

### Test Scenario 2: Update v1.6 → v2.0

**Steps**:
1. User has JITD v1.6 with `.jitd-config.json`
2. User runs `claude plugins update`
3. Post-install detects old config
4. Prompts for migration
5. User accepts
6. Config renamed
7. User runs `/nav:migrate` for docs
8. Documentation updated

**Expected**: Smooth migration, old commands still work

### Test Scenario 3: Update v1.6 → v2.0 (Decline Migration)

**Steps**:
1. User has JITD v1.6
2. Update to v2.0
3. Decline auto-migration
4. User types `/jitd:start`
5. Gets warning but command works
6. User later runs `/nav:migrate` manually

**Expected**: Backward compat works, user migrates when ready

### Test Scenario 4: Update v1.6 → v3.0 (Direct Jump)

**Steps**:
1. User has JITD v1.6
2. Update directly to v3.0
3. Post-install shows migration guide
4. User types `/jitd:start`
5. Command fails with helpful error
6. User says "start my session"
7. Skill auto-invokes

**Expected**: Breaking change with clear guidance

### Test Scenario 5: Multiple Projects

**Steps**:
1. User has 3 projects with `.jitd-config.json`
2. Update to v2.0
3. Post-install finds all 3
4. Migrates each one
5. All projects updated

**Expected**: Batch migration works

---

## Success Metrics

**v2.0 Migration Success**:
- [ ] 100% of users can update without breaking
- [ ] < 5% users report migration issues
- [ ] Auto-migration works for 95%+ projects
- [ ] Clear documentation for edge cases

**v2.5 Warning Success**:
- [ ] 80%+ users migrate to new commands before v3.0
- [ ] Clear timeline communicated
- [ ] Migration guide easily accessible

**v3.0 Transition Success**:
- [ ] < 10% users surprised by command removal
- [ ] Clear error messages for old commands
- [ ] Skills work seamlessly
- [ ] Positive user feedback on auto-invocation

---

## Related Tasks

- TASK-08: Skills enhancements (v2.1-v2.2 roadmap)
- TASK-07: Skills migration (v2.0 implementation)
- TASK-01: Session start PM integration

---

## Notes

- Migration must be **idempotent** (safe to run multiple times)
- Always preserve user data (configs, docs)
- Clear communication > forced migration
- Gradual deprecation > hard breaks
- Skills are better UX than commands (user will realize this)
- v3.0 breaking change justified by better experience