/nav-upgrade

name: nav-upgrade
description: Automates Navigator plugin updates. Detects current version, updates plugin, verifies installation, updates project CLAUDE.md, and validates new features. Auto-invoke when user mentions upgrading Navigator or getting new features.
allowed-tools: Bash, Read, Write, Edit, TodoWrite
version: 1.0.0

Navigator Upgrade Skill

Automate Navigator plugin updates with version detection, conflict resolution, and post-update validation.

When to Invoke

Auto-invoke when user says:

• "Update Navigator"
• "Upgrade Navigator plugin"
• "Get latest Navigator version"
• "Update to Navigator v3.3.0"
• "Install new Navigator features"
• "Check for Navigator updates"

What This Does

**6-Step Workflow**: 1. **Version Detection**: Check current Navigator version vs latest 2. **Plugin Update**: Execute `/plugin update navigator` 3. **Verification**: Confirm update succeeded 4. **CLAUDE.md Update**: Update project configuration (via nav-sync-claude) 5. **Hooks Setup**: Install/update token monitoring hooks in project 6. **Feature Discovery**: Show new features available

**Time Savings**: Manual update (10-15 min) → Automated (2 min)

---

Prerequisites

• Navigator plugin installed
• Project initialized with Navigator
• Internet connection for plugin update

---

Workflow Protocol

Step 1: Version Detection

**Execute**: `version_detector.py`

**Check both stable and pre-release versions**:

# Current installed version
grep '"version"' .claude-plugin/plugin.json

# Get all releases (including pre-releases)
curl -s https://api.github.com/repos/qf-studio/navigator/releases

# Parse:
# - Latest stable (prerelease: false)
# - Latest pre-release (prerelease: true)
# - Compare with current version

**Output scenarios**:

**Scenario 1: Stable update available**

{
  "current_version": "4.0.0",
  "latest_stable": "4.2.0",
  "latest_prerelease": null,
  "recommendation": "update_to_stable"
}

**Scenario 2: Pre-release available (user on stable)**

{
  "current_version": "4.0.0",
  "latest_stable": "4.0.0",
  "latest_prerelease": "4.3.0",
  "recommendation": "offer_prerelease_option"
}

**Present choice**:

✅ You're on the latest stable version (v4.0.0)

⚡ Experimental version available: v4.3.0

New in v4.3.0 (Experimental):
• Knowledge graph with experiential memories
• PM integration with ticket closing

Options:
[1] Stay on stable v4.0.0 (recommended)
[2] Try experimental v4.3.0 (early adopter)

Your choice [1-2]:

**Scenario 3: Already on latest (stable or pre-release)**

✅ You're on v4.3.0 (latest experimental)

Latest stable: v4.0.0
Status: You're ahead of stable (testing experimental features)

New features in your version:
- Knowledge graph with experiential memories

Skip to Step 5 (Feature Discovery).

**Scenario 4: On pre-release, newer stable available**

⚠️  You're on v4.3.0 (experimental)
Latest stable: v4.6.0

Recommendation: Update to stable v4.6.0
Experimental features from v4.3.0 are now stable.

---

Step 2: Plugin Update

**Scenario-based update strategy**:

Scenario 2: Pre-release Available (User on Stable)

When pre-release detected, present choice using AskUserQuestion tool:

✅ You're on latest stable version (v4.0.0)

⚡ Experimental version available: v4.3.0

New in v4.3.0 (Experimental):
• Knowledge graph with experiential memories
• PM integration with ticket closing

**Question**: Which version would you like?

**Options**:
[1] **Stay on stable v4.0.0** (recommended)
    - Production-ready
    - No experimental features
    - Most reliable

[2] **Try experimental v4.3.0** (early adopter)
    - Latest features
    - Help test new functionality

Your choice?

**If user chooses [1] (Stay stable)**:

✓ Staying on v4.0.0 (latest stable)

No action needed. Run nav-upgrade again when you're ready to try experimental features.

**If user chooses [2] (Try experimental)**:

# Uninstall current version
/plugin uninstall navigator

# Add marketplace (if not already added)
/plugin marketplace add qf-studio/navigator

# Install specific pre-release version
# Note: /plugin update only fetches stable, must install specific version
git clone https://github.com/qf-studio/navigator.git /tmp/navigator-v4.3.0
cd /tmp/navigator-v4.3.0
git checkout v4.3.0

# Install from local checkout
/plugin install /tmp/navigator-v4.3.0

**Then verify installation**:

/plugin list | grep navigator
# Should show: navigator (v4.3.0)

Scenario 1: Stable Update Available

**Execute**: `/plugin update navigator`

**Monitor output**:

Updating navigator...
✅ Navigator updated to v4.2.0

**If update fails**:

❌ Update failed: [error message]

Troubleshooting:
1. Restart Claude Code
2. Try: /plugin uninstall navigator && /plugin install navigator
3. Check internet connection
4. Report issue: https://github.com/qf-studio/navigator/issues

**Automatic retry** (once): If update fails, try uninstall/reinstall automatically:

/plugin uninstall navigator
/plugin marketplace add qf-studio/navigator
/plugin install navigator

---

Step 3: Verification

**Execute**: `plugin_verifier.py`

**Verify**: 1. Plugin version matches latest 2. New skills registered in plugin.json 3. Skills are invokable

**Test new skills** (v3.3.0 example):

# Test that visual-regression skill exists
ls ~/.config/claude/plugins/navigator/skills/visual-regression/SKILL.md 2>/dev/null || echo "Skill not found"

**Output**:

✅ Update Verification

Version: v3.3.0 ✅
New Skills Registered: visual-regression ✅
Skills Invokable: ✅

Update successful!

**If verification fails**:

⚠️ Update completed but verification failed

Issue: visual-regression skill not found
Fix: Restart Claude Code to reload skills

After restarting, verify:
"Set up visual regression for Button"

Prompt user to restart Claude Code.

**IMPORTANT - Restart Required After All Updates**: