Nav Upgrade

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"

python3 "$PLUGIN_DIR/skills/nav-upgrade/functions/migrate_hooks_out_of_settings.py" \
    .claude/settings.json

# Output:
#   ✓ Backup written → .claude/settings.json.pre-migrate.<timestamp>
#   ✓ Removed N Navigator hook entries (commands path matched)
#   ✓ Preserved K unrelated user hooks

⚠️  RESTART REQUIRED to activate hooks from the plugin manifest.
   Claude Code caches plugin hook definitions at session start.

# Check for skills with setup requirements
if [ -f "$NAVIGATOR_PATH/skills/product-design/setup.sh" ]; then
  # Check if venv exists
  if [ ! -d "$NAVIGATOR_PATH/skills/product-design/venv" ]; then
    echo "⚠️  product-design skill requires setup"
    NEEDS_SETUP=true
  fi
fi

⚠️  New Feature Requires Setup

The product-design skill (v3.4.0+) requires Python dependencies:

**One-time setup** (30 seconds):
```bash
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
cd "$PLUGIN_DIR/skills/product-design"
./setup.sh

**Record setup needed in TodoWrite** for tracking.

---

### Step 7: Feature Discovery

**Show new features** available in updated version.

**For v3.3.0 update**:
````markdown
🎉 Navigator v3.3.0 Update Complete!

## New Features Available

### visual-regression Skill (NEW)
Set up Storybook + Chromatic in 5 minutes instead of 2-3 hours.

**Usage**:

**What it does**:
✅ Generates Storybook stories with all variants
✅ Configures Chromatic/Percy/BackstopJS
✅ Creates CI workflows (GitHub Actions, GitLab CI)
✅ Adds accessibility tests

**Complete Design Pipeline** (v3.2 + v3.3):
1. "Review this design from Figma" (v3.2)
2. Implement components
3. "Set up visual regression" (v3.3 NEW)
4. Automated visual testing in CI

### Updated Skills Count
- **17 total skills** (was 16)
- 10 core Navigator skills
- 7 development skills

### Integration
visual-regression integrates with product-design skill for complete design→code→testing workflow.

## Try It Now

If you have Storybook in this project:

If you don't have Storybook:
```bash
npx storybook init

"Set up visual regression for [ComponentName]"

---

## Predefined Functions

### functions/version_detector.py

**Purpose**: Detect current and latest Navigator versions

**Usage**:
```bash
python3 functions/version_detector.py
```

**Output**:
```json
{
  "current_version": "3.2.0",
  "latest_version": "3.3.0",
  "update_available": true,
  "release_url": "https://github.com/qf-studio/navigator/releases/tag/v3.3.0",
  "changes": {
    "new_skills": ["visual-regression"],
    "updated_skills": ["product-design"],
    "new_features": ["Multi-tool VR support", "CI workflows"],
    "breaking_changes": []
  }
}
```

### functions/plugin_updater.py

**Purpose**: Execute plugin update with retry logic

**Usage**:
```bash
python3 functions/plugin_updater.py --target-version 3.3.0
```

**Actions**:
1. Execute `/plugin update navigator`
2. If fails, retry with uninstall/reinstall
3. Verify update succeeded
4. Return status

### functions/plugin_verifier.py

**Purpose**: Verify update completed successfully

**Usage**:
```bash
python3 functions/plugin_verifier.py --expected-version 3.3.0
```

**Checks**:
- Plugin version matches expected
- New skills exist in filesystem
- Skills registered in plugin.json
- Skills are invokable (test invocation)

---

## Error Handling

### Update Failed: Network Error

```
❌ Update failed: Could not connect to plugin marketplace

Fix:
1. Check internet connection
2. Try again in a few minutes
3. Manual update: /plugin uninstall navigator && /plugin install navigator
```

### Update Failed: Permission Denied

```
❌ Update failed: Permission denied

Fix:
1. Close Claude Code
2. Check ~/.config/claude/plugins/ permissions
3. Restart Claude Code
4. Try update again
```

### Verification Failed: Skills Not Found

```
⚠️ Update completed but new skills not found

Fix:
1. Restart Claude Code (required for skill reload)
2. Verify: /plugin list
3. Test: "Set up visual regression for Button"
```

Automatically prompt user to restart.

### CLAUDE.md Update Conflicts

```
⚠️ CLAUDE.md update has conflicts with your customizations

Options:
[1] Keep my customizations (merge new features)
[2] Use new template (lose customizations)
[3] Show me the diff first

Reply with choice
```

Let user decide how to handle conflicts.

---

## Upgrade Paths

### From v3.0.x to v3.3.0

**Changes**:
- +2 skills (nav-markers in v3.1, visual-regression in v3.3)
- OpenTelemetry integration (v3.1)
- Product design skill (v3.2)
- Visual regression skill (v3.3)

**Breaking changes**: None (fully backward compatible)

### From v3.1.x to v3.3.0

**Changes**:
- Product design skill (v3.2)
- Visual regression skill (v3.3)
- Updated skills count (17 total)

**Breaking changes**: None

### From v3.2.x to v3.3.0

**Changes**:
- Visual regression skill
- Integration with product-design workflow
- Updated skills count (17 total)

**Breaking changes**: None

---

## Post-Update Checklist

After upgrade, verify:

- ✅ `/plugin list` shows new version
- ✅ CLAUDE.md updated with new patterns
- ✅ New skills auto-invoke on natural language
- ✅ Existing skills still work
- ✅ No conflicts in project configuration

**If all checked**: Update successful!

---

## Rollback

If update causes issues:

```
"Rollback Navigator to v3.2.0"
```

This will:
1. Uninstall current version
2. Install specific version from marketplace
3. Update CLAUDE.md to match
4. Verify rollback succeeded

---

## Integration Points

### With nav-sync-claude

After plugin update, automatically invokes `nav-sync-claude` to sync project configuration.

### With nav-start

After update, `nav-start` shows new features available in session statistics.

### With nav-init

If upgrading before project initialization, suggests running `nav-init` with latest features.

---

## Examples

### Example 1: Simple Update

```
User: "Update Navigator"

→ Detects: v3.2.0 → v3.3.0 available
→ Updates plugin
→ Updates CLAUDE.md
→ Shows: "visual-regression skill now available"
→ Suggests: "Set up visual regression for [Component]"
```

### Example 2: Already on Latest

```
User: "Update Navigator"

→ Detects: Already on v3.3.0
→ Shows new features available
→ Suggests trying visual-regression if not used yet
```

### Example 3: Update with Restart Required

```
User: "Update Navigator"

→ Updates plugin
→ Verification: Skills not found (needs restart)
→ Prompts: "Please restart Claude Code to complete update"
→ After restart: Verification succeeds
```

---

## Best Practices

1. **Update regularly**: Check for updates monthly
2. **Read release notes**: Understand new features before using
3. **Test new skills**: Try new features in test project first
4. **Report issues**: File GitHub issues for update problems
5. **Backup CLAUDE.md**: Keep backup before update (auto-created)

---

## Version History

- **v1.0.0**: Initial nav-upgrade skill (Navigator v3.3.1)

---

## Session-start notice (v8)

Since v8.0.0 the Navigator mod checks the latest GitHub release at session start (on by
default via `auto_update.enabled`, at most every `check_interval_hours`, never under Pilot)
and shows the update command. It never updates by itself; this skill, nav-start Step 1.5
and `claude plugin update navigator@navigator-marketplace` do.

## Future Enhancements

- Changelog display in CLI
- Update notifications for major versions
- Automated migration scripts for breaking changes

---

**Last Updated**: 2025-10-21
**Skill Type**: Core Navigator
**Auto-Invocation**: Yes