/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 records the file's layout verbatim, with fenced code blocks kept whole (a `# comment` inside a bash block is not a header):

• **title**: the first `#` header as written; **project_name** is the part before

` - Claude Code Configuration` when the title has that shape, else the whole title

• **preamble**: the text between the title and the first `##` header
• **sections**: every `##` section in order, `{"header", "body"}`, bodies byte for byte

(`###` subsections, fences and `---` rules included)

• **navigator_section**: the section Navigator owns — `## Navigator` when present, else

the section whose body carries the `**Navigator runtime**` paragraph; empty when none

• **has_context**: whether a `## Context` section exists
• **source_dir**: the directory CLAUDE.md was read from (the project root for

the liveness guard)

The flat lists stay for readers of the JSON and for hand-written customizations without a `sections` layout: **description**, **core_principle** and **tech_stack** (from Context), **code_standards** and **forbidden_actions** (every bullet, template defaults included; a default the project removed stays removed), **pm_tool**, and **custom_sections** with **custom_section_anchors** (every `##` header the lists do not render, with the standard section each one precedes).

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 placeholde