Skip to Content
ReferencePlugin Operations

Plugin Operations & Release

Installing, updating, and (for maintainers) releasing the Navigator plugin.

Install & update

Navigator is a Claude Code plugin installed from its marketplace:

# Add the marketplace (first time only)
/plugin marketplace add qf-studio/navigator
 
# Install
/plugin install navigator
 
# Update to the latest stable version
claude plugin update navigator

After any update, a restart is required. Claude Code caches skill paths at session start, so the running session keeps using the old version until you close and reopen Claude Code. Without a restart you may see stale skills or “skill not found” errors — this is Claude Code behavior, not a Navigator fault.

Session start tells you when a newer release exists and shows this command (auto-update); it never installs it for you.

Automates the upgrade flow instead of running the steps by hand. Triggers: “update Navigator”, “upgrade Navigator plugin”, “get latest Navigator version”.

It walks a multi-step workflow:

  1. Detect version — compares the installed version against latest stable (and pre-release, if any).
  2. Update plugin — runs /plugin update navigator; falls back to uninstall/reinstall if the update fails.
  3. Verify — confirms the new version and that new skills are registered.
  4. Sync CLAUDE.md — delegates to nav-sync-claude (below).
  5. Migrate legacy hooks — removes duplicate hook entries from .claude/settings.json (hooks now ship in the plugin manifest).
  6. Feature discovery — surfaces what is new in the version.

It also handles rollback (“rollback Navigator to vX.Y.Z”).

Updates a project’s CLAUDE.md to match the installed Navigator version while preserving your customizations. Triggers: “sync CLAUDE.md”, “update CLAUDE.md”.

The flow is non-destructive and idempotent:

  • Backs up to CLAUDE.md.backup before any change.
  • Extracts project-specific content (name, tech stack, code standards, forbidden actions, PM tool, custom sections).
  • Regenerates from the version-matched template (fetched from GitHub, with a bundled fallback when offline).
  • Shows a diff for review, then provides commit instructions.
  • Migrates .agent/.nav-config.json, adding any missing config sections.

Your customizations are preserved; only Navigator-managed sections (workflow, version marker, command examples) are rewritten.

Validates plugin integrity and publishes a release to the marketplace. This is for Navigator maintainers, not end users. Triggers: “release plugin”, “publish navigator”, “create release”.

Validation runs before anything is published:

python3 functions/release_validator.py --check-all     # skills exist + committed, versions consistent
python3 functions/release_validator.py --verify-hooks  # smoke-test manifest hook commands
python3 functions/release_validator.py --verify-dispatcher    # every hook routes through nav_dispatch.py; every registry op committed + importable (v8.3.5)
python3 functions/release_validator.py --verify-conformance   # harness-conformance results exist for the Claude Code version (v8.3.5)

Release publication is owned by CI: the skill pushes commits and a vX.Y.Z tag, and .github/workflows/release.yml creates the GitHub release from the tag. Running gh release create locally is explicitly avoided — it races the workflow. After tagging, the run is watched to completion and the tag is verified to contain all referenced skills.

Slash CommandsPerformance & Benchmarks