/nav-sync-claude

name: nav-sync-claude
description: Sync project CLAUDE.md to the installed Navigator version, preserving customizations. Use when user says "sync CLAUDE.md", "update CLAUDE.md", or when detecting outdated Navigator configuration.
allowed-tools: Read, Write, Edit, Bash
version: 1.0.0

Navigator CLAUDE.md Updater Skill

Update project's CLAUDE.md to latest Navigator version (v3.1) while preserving project-specific customizations.

When to Invoke

Invoke this skill when the user:

• Says "update my CLAUDE.md", "migrate CLAUDE.md to v3"
• Says "update Navigator configuration", "fix my CLAUDE.md"
• Mentions outdated commands like "/nav:start" and wants to upgrade
• Complains that Claude doesn't understand Navigator workflow

**DO NOT invoke** if:

• CLAUDE.md already references v3.1 and natural language commands
• User is editing CLAUDE.md for project-specific reasons (not Navigator updates)
• Working on plugin's root CLAUDE.md (not user projects)

Execution Steps

Step 1: Detect Current CLAUDE.md Version

Check if CLAUDE.md exists and detect version:

if [ ! -f "CLAUDE.md" ]; then
  echo "❌ No CLAUDE.md found in current directory"
  echo ""
  echo "Run 'Initialize Navigator in this project' first."
  exit 1
fi

Use `version_detector.py` to analyze CLAUDE.md:

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-sync-claude/functions/version_detector.py" CLAUDE.md

This script checks for:

• Version markers (e.g., "Navigator Version: 3.1.0")
• Slash command references (`/nav:start`, `/nav:doc`, etc.)
• Skills vs commands language
• Natural language examples

**Outputs**:

• `outdated` - Has `/nav:` commands or v1/v2 markers
• `current` - Already v3.1 with natural language
• `unknown` - Can't determine (custom/non-Navigator file)

**If `current`**:

✅ CLAUDE.md is already up to date (v3.1)

No migration needed.

Exit successfully.

**If `unknown`**:

⚠️  CLAUDE.md doesn't appear to be a Navigator file

This might be a custom configuration. Manual review recommended.
Proceed with migration anyway? [y/N]

If user declines, exit. If accepts, continue.

Step 2: Backup Current CLAUDE.md

Always create backup before modifying:

cp CLAUDE.md CLAUDE.md.backup
echo "📦 Backup created: CLAUDE.md.backup"

Step 3: Extract Project-Specific Customizations

Use `claude_updater.py` to parse current CLAUDE.md:

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-sync-claude/functions/claude_updater.py" extract CLAUDE.md > /tmp/nav-customizations.json

This extracts, verbatim (multi-line values and bullets keep their line breaks):

• **Project name** (from title)
• **Project description** and **Core Principle** (from Context section)
• **Tech stack** (languages, frameworks)
• **Code standards** (every bullet the project lists, template defaults included;

a default the project removed stays removed)

• **Forbidden actions** (every bullet, same rule)
• **PM tool configuration** (Linear, GitHub, Jira, etc.)
• **Custom sections** (every `##` header not in the template) with the standard

section each one precedes, so generate puts it back in the same place

• **source_dir**: the directory CLAUDE.md was read from (the project root for

the liveness guard)

Step 4: Generate Updated CLAUDE.md

Apply latest template with extracted customizations:

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"
# Template fetching now automatic via get_template_path():
# 1. Tries GitHub (version-matched)
# 2. Falls back to bundled if offline
python3 "$PLUGIN_DIR/skills/nav-sync-claude/functions/claude_updater.py" generate \
  --customizations /tmp/nav-customizations.json \
  --template "$PLUGIN_DIR/templates/CLAUDE.md" \
  --output CLAUDE.md

Generate stamps `**Last Updated**` with today's date and `**Navigator Version**` with the installed plugin version (`--stamp-date` / `--stamp-version` override them). A dry run writes anywhere: `--output /tmp/CLAUDE.preview.md`. The hook-liveness guard checks the project root, never the output directory: `--project-root DIR`, else the `source_dir` that extract recorded, else the current directory. It exits 3 and leaves CLAUDE.md untouched when `.agent/.nav-runtime-state.json` is absent or older than 7 days.

**Template Source Priority**: 1. **GitHub** (version-matched): Fetches from `https://raw.githubusercontent.com/qf-studio/navigator/v{version}/templates/CLAUDE.md`

• Matches installed plugin version (e.g., v4.3.0)
• Always up-to-date with release
• Works with pre-releases

2. **Bundled** (fallback): Uses `templates/CLAUDE.md` from installed plugin

• Offline fallback
• Guaranteed availability

**What this does**: 1. Loads template (GitHub or bundled) 2. Replaces placeholders with extracted data 3. Preserves custom sections 4. Updates Navigator workflow to natural language 5. Removes slash command references 6. Adds skills explanation

Step 5: Show Diff and Confirm

Display changes for user review:

echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "📝 CHANGES TO CLAUDE.MD"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""

# Show unified diff
diff -u CLAUDE.md.backup CLAUDE.md || true

echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

Step 6: Verify and Commit

Show summary of changes