alekspetrov/navigator/nav-release

Navigator Release Skill

Validate plugin integrity and release to marketplace with all safety checks.

Why This Exists

After v5.1.0 incident where nav-profile was referenced in plugin.json but never committed, causing install failures. This skill ensures:

• All referenced skills exist and are committed
• Version consistency across all files
• Tag created AFTER all commits
• Post-release verification

When to Invoke

Auto-invoke when:

• User says "release plugin", "publish navigator"
• User says "create release", "deploy new version"
• User says "release vX.Y.Z"

DO NOT invoke if:

• Just committing changes (no release)
• Updating documentation only
• Testing locally

Execution Steps

Step 1: Pre-Release Validation [CRITICAL]

Run validation script:

python3 functions/release_validator.py --check-all

This validates:

1. All skills in plugin.json exist
2. All skill files are committed (not untracked)
3. Version consistency across files
4. No uncommitted changes in skills/

If validation fails: STOP and fix issues before proceeding.

Step 1.5: Hook Smoke Test [STRONGLY RECOMMENDED for any release touching hooks or plugin.json]

Run hook smoke-test:

python3 functions/release_validator.py --verify-hooks

This executes every plugin manifest hook command via bash twice — once with $CLAUDE_PLUGIN_ROOT bound to the repo under release, once with it unset and HOME pointed at a tmp dir whose .claude/plugins/marketplaces/navigator-marketplace links to the repo, so the manifest fallback path is what resolves (TASK-99). NAVIGATOR_MOD_OWNS and PILOT_EXECUTOR are scrubbed from both runs; inside a Claude Code session the mod's ownership list would otherwise make the Python dispatcher exit silently and fake the v6.14.0 signature. It detects the v6.14.0 silent-fail signature: a payload-emitting hook (SessionStart, PreCompact, PostCompact) that exits 0 with no stdout and no stderr.

Other hook events (Stop, UserPromptSubmit, PreToolUse, PostToolUse) are silent by design — they're state-writers or blocking-only — so quiet exit 0 there is correct behavior and is not flagged.

Expected output on a healthy release:

Hook smoke-test: 20/20 passed, 0 failed
 
  ✓  SessionStart       [set  ] exit=0 out=10353B err=0B
  ✓  SessionStart       [unset] exit=0 out=10353B err=0B
  ✓  PreCompact         [set  ] exit=0 out=2B err=87B
  ✓  PreCompact         [unset] exit=0 out=2B err=87B
  ...

Regression output (what v6.14.0 would have shown):

  ❌ SessionStart       [unset] silent exit 0 — payload-emitting hook produced no output
     python3 "${CLAUDE_PLUGIN_ROOT:-...}/hooks/nav_session_start.py"

If `--verify-hooks` fails: STOP. The hook command in plugin.json is broken in the CLAUDE_PLUGIN_ROOT-unset case. Fix the command (typically a fallback-path expansion issue) and re-run before proceeding.

Also run the two static runtime gates (both are CI steps in release.yml since TASK-99):

python3 functions/release_validator.py --verify-dispatcher          # every manifest hook routes through nav_dispatch.py; every registry op has a committed, importable hooks/ops/<name>.py
python3 functions/release_validator.py --verify-conformance           # a harness-conformance results file exists for `claude --version` (CI passes the pinned version)

Background: this check was added in v6.15.2 after v6.14.0 shipped a shell guard (if [ -n "$CLAUDE_PLUGIN_DIR" ]; then ... fi) that silently no-opped every hook when the variable was unset. The bug masked itself for two releases because the navigator source repo had a project-local .claude/settings.json backstop. Other Nav-initialized projects (no backstop) got zero injection with zero error signal. See mem-036 and releases/RELEASE-NOTES-v6.15.1.md / v6.15.2.md.

Step 2: Display Validation Results

Show validation summary:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
NAVIGATOR RELEASE VALIDATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
Skills Check:
  [x] nav-loop          ✓ exists, committed
  [x] nav-profile       ✓ exists, committed
  [x] nav-diagnose      ✓ exists, committed
  ...
 
Version Check:
  plugin.json:      5.1.0 ✓
  marketplace.json: 5.1.0 ✓
  CLAUDE.md:        5.1.0 ✓
  README.md:        5.1.0 ✓
 
Git Status:
  Uncommitted skills: 0 ✓
  Untracked skills:   0 ✓
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
VALIDATION: PASSED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 3: Confirm Version

Ask user to confirm version:

Ready to release Navigator vX.Y.Z
 
This will:
1. Commit any pending changes
2. Push to origin/main
3. Create and push git tag vX.Y.Z
4. CI workflow (.github/workflows/release.yml) publishes the GitHub release from the tag
 
Proceed? [Y/n]

Step 4: Execute Release

If confirmed, run release sequence:

# 1. Commit if needed
git add .
git commit -m "chore(release): prepare vX.Y.Z" || true
 
# 2. Push to origin
git push origin main
 
# 3. Create and push tag — this triggers .github/workflows/release.yml,
#    which creates the GitHub release from releases/RELEASE-NOTES-vX.Y.Z.md.
git tag -a vX.Y.Z -m "Navigator vX.Y.Z: [description]"
git push origin vX.Y.Z

Do NOT run `gh release create` locally. The workflow owns release publication. Local creation races the workflow and historically caused "release with the same tag name already exists" CI failures.

Step 5: Post-Release Verification

Wait for the Publish Release workflow and verify it succeeded:

# Watch the most recent run; exits non-zero if it fails.
gh run watch --exit-status "$(gh run list --workflow=release.yml --limit=1 --json databaseId --jq '.[0].databaseId')"
 
# Confirm the release is published
gh release view vX.Y.Z --json tagName,name,isDraft,assets

If the workflow fails, inspect with gh run view --log-failed and fix before retrying — do NOT fall back to gh release create locally.

Verify tag contains all skills:

python3 functions/release_validator.py --verify-tag vX.Y.Z

Clear local cache (for testing):

rm -rf ~/.claude/plugins/cache/navigator-marketplace/

Instruct user to test:

Release complete! To verify:
 
1. Run: /plugin install navigator
2. Check plugin list shows vX.Y.Z
3. Verify no errors in plugin details
 
If errors occur, see: .agent/sops/deployment/plugin-release.md

Step 6: Update Installed Plugin + Sync Docs Site

claude plugin update navigator && claude plugin list | grep -A1 navigator@   # then restart

The docs site is a separate repo (qf-studio/navigator-docs, local ~/Projects/startups/navigator-site, live at https://navigator.quantflow.studio on AWS); it does not update itself. Bump lib/version.ts, add/adjust content/skills/*.mdx and content/reference/nav-config-schema.mdx for anything new, bun run build, commit and push main, then push a prod-<VERSION>-$(date +%s) tag: "Build image" publishes the image to GHCR and "Deploy QuantFlow AWS" rolls it to ECS and invalidates CloudFront. Confirm the live version string at navigator.quantflow.studio. Full procedure: .agent/sops/development/release-workflow.md Step 7.

Predefined Functions

functions/release_validator.py

Validates plugin integrity before release:

# Check all skills exist and are committed
python3 functions/release_validator.py --check-all
 
# Verify specific version
python3 functions/release_validator.py --check-version 5.1.0
 
# Verify tag contents
python3 functions/release_validator.py --verify-tag v6.15.2
 
# Smoke-test plugin manifest hook commands (v6.15.2+)
python3 functions/release_validator.py --verify-hooks
 
# Python fallback runtime: dispatcher routing + registry ops exist, committed, import (TASK-99)
python3 functions/release_validator.py --verify-dispatcher
 
# Harness-conformance results exist for a Claude Code version (default: `claude --version`)
python3 functions/release_validator.py --verify-conformance 2.1.287

Error Handling

Missing skill detected:

❌ VALIDATION FAILED
 
Missing skills:
  - skills/nav-profile/ (referenced in plugin.json but not found)
 
Fix: Create the skill or remove from plugin.json

Uncommitted skills detected:

❌ VALIDATION FAILED
 
Uncommitted skills:
  - skills/nav-loop/ (modified)
  - skills/nav-profile/ (untracked)
 
Fix: git add skills/ && git commit -m "Add missing skills"

Version mismatch detected:

❌ VALIDATION FAILED
 
Version mismatch:
  plugin.json:      5.1.0
  marketplace.json: 5.0.0  ← MISMATCH
  CLAUDE.md:        5.1.0
 
Fix: Update marketplace.json to 5.1.0

Success Criteria

Release is successful when:

• [ ] All skills validated (exist + committed)
• [ ] Version consistent across all files
• [ ] Hook smoke-test passes (--verify-hooks reports zero failures)
• [ ] Git tag created after all commits
• [ ] Publish Release workflow run completes successfully
• [ ] GitHub release published with notes asset attached
• [ ] Test installation succeeds (no errors)

Quick Reference

# Full release with validation
"Release Navigator v5.2.0"
 
# Just validate (no release)
"Validate plugin for release"
 
# Fix after failed release
"Fix release tag v5.1.0"

Related

• SOP: .agent/sops/deployment/plugin-release.md
• Config: .claude-plugin/plugin.json
• Marketplace: .claude-plugin/marketplace.json