Help us improve
Share bugs, ideas, or general feedback.
From navigator
Automates Navigator plugin updates with version detection, conflict resolution, and post-update validation. Invoked when user mentions upgrading Navigator or getting new features.
npx claudepluginhub alekspetrov/navigator --plugin navigatorHow this skill is triggered — by the user, by Claude, or both
Slash command
/navigator:nav-upgradeThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Automate Navigator plugin updates with version detection, conflict resolution, and post-update validation.
Syncs a project's CLAUDE.md to the latest Navigator version while preserving customizations. Detects outdated versions via version markers or /nav: commands and migrates to natural language v3.1.
Upgrades Claude Code plugins by aligning skills, hooks, and patterns with latest capabilities and best practices. Use after updates, for modernization, or on user request.
Guided update assistant for the SDLC Wizard — reads installed version, checks npm CLI version, shows changelog, and walks through selective adoption of updates.
Share bugs, ideas, or general feedback.
Automate Navigator plugin updates with version detection, conflict resolution, and post-update validation.
Auto-invoke when user says:
6-Step Workflow:
/plugin update navigatorTime Savings: Manual update (10-15 min) → Automated (2 min)
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/alekspetrov/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):
• Multi-Claude agentic workflows
• 30% success rate (use for simple features)
• 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:
- Multi-Claude workflows
- Task agents in sub-Claude phases
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.
Scenario-based update strategy:
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):
• Multi-Claude agentic workflows
• 30% success rate (use for simple features)
• 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)
- Multi-Claude workflows
- Latest features
- 30% completion rate
- 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 alekspetrov/navigator
# Install specific pre-release version
# Note: /plugin update only fetches stable, must install specific version
git clone https://github.com/alekspetrov/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)
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/alekspetrov/navigator/issues
Automatic retry (once): If update fails, try uninstall/reinstall automatically:
/plugin uninstall navigator
/plugin marketplace add alekspetrov/navigator
/plugin install navigator
Execute: plugin_verifier.py
Verify:
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:
Claude Code caches skill paths at session start. Even successful updates require a restart to load new skills:
⚠️ RESTART REQUIRED
Plugin updated successfully to vX.Y.Z.
Claude Code caches skill paths at session start.
To use new/updated skills:
1. Close Claude Code
2. Reopen Claude Code
3. Run "nav start" to verify new version
Without restart:
- Old skill versions continue running
- New skills won't be available
- May see "skill not found" errors
This is a Claude Code behavior, not a Navigator issue. The plugin files update correctly, but the active session continues using cached skill paths from the old version.
After plugin update, automatically invoke: nav-sync-claude skill
🔄 Syncing project CLAUDE.md with updated plugin...
✓ Using template from GitHub (v4.3.0)
✓ Extracted customizations
✓ Generated updated CLAUDE.md
What happens automatically:
Template sync benefits:
User action required:
Review changes and commit:
git add CLAUDE.md
git commit -m "chore: update CLAUDE.md to Navigator v4.3.0"
See: nav-sync-claude skill for details.
.claude/settings.jsonv6.13.0+: Navigator's lifecycle hooks now ship with the plugin manifest
(.claude-plugin/plugin.json's top-level hooks field). Claude Code only
substitutes ${CLAUDE_PLUGIN_ROOT} for hooks declared in a plugin manifest,
so the prior approach (merging hooks into the project's .claude/settings.json)
produced broken commands like /hooks/X.py (empty expansion). Hooks ship
with the plugin from v6.13.0 onwards.
For existing installs, the old hook entries are duplicated in
.claude/settings.json and must be removed to prevent double-firing:
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/cache/navigator-marketplace/navigator}"
if [ ! -d "$PLUGIN_DIR" ]; then
PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
fi
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
Behavior:
hooks/ AND one of
the known Navigator hook names (nav_session_start, nav_pre_compact,
nav_post_compact, nav_workflow_state, nav_read_guard,
nav_task_graph_sync, nav_profile_sync, nav_commit_reminder,
token_monitor, workflow_enforcer)..pre-migrate.<timestamp> backup before any change.Fresh installs do not need this step — they never had hooks in
.claude/settings.json to begin with.
⚠️ RESTART REQUIRED to activate hooks from the plugin manifest.
Claude Code caches plugin hook definitions at session start.
Check if new features require setup:
# 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
If setup needed, show instructions:
⚠️ New Feature Requires Setup
The product-design skill (v3.4.0+) requires Python dependencies:
**One-time setup** (30 seconds):
```bash
cd ~/.claude/plugins/marketplaces/navigator-marketplace/skills/product-design
./setup.sh
What this installs:
After setup, use: "Review this Figma design: [URL]"
**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**:
"Set up visual regression for ProfileCard" "Add Chromatic to Button component" "Configure visual tests for Input, Card, Modal"
**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:
"Set up visual regression for [ComponentName]"
If you don't have Storybook:
```bash
npx storybook init
Then:
"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/alekspetrov/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)
---
## Future Enhancements
- Auto-update check on `nav-start` (opt-in)
- 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