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:

bash

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:

bash

python3 "$SKILL_BASE_DIR/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:

code

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

No migration needed.

Exit successfully.

If unknown:

code

⚠️  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:

bash

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:

bash

python3 "$SKILL_BASE_DIR/functions/claude_updater.py" extract CLAUDE.md > /tmp/nav-customizations.json

This extracts:

•Project name (from title)
•Project description (from Context section)
•Tech stack (languages, frameworks)
•Code standards (custom rules beyond Navigator defaults)
•Forbidden actions (project-specific restrictions)
•PM tool configuration (Linear, GitHub, Jira, etc.)
•Custom sections (anything not in Navigator template)

Step 4: Generate Updated CLAUDE.md

Apply latest template with extracted customizations:

bash

# Template fetching now automatic via get_template_path():
# 1. Tries GitHub (version-matched)
# 2. Falls back to bundled if offline
python3 "$SKILL_BASE_DIR/functions/claude_updater.py" generate \
  --customizations /tmp/nav-customizations.json \
  --template "$SKILL_BASE_DIR/../../templates/CLAUDE.md" \
  --output CLAUDE.md

Template Source Priority:

•
GitHub (version-matched): Fetches from https://raw.githubusercontent.com/alekspetrov/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
•
Bundled (fallback): Uses templates/CLAUDE.md from installed plugin
- •Offline fallback
- •Guaranteed availability

What this does:

•Loads template (GitHub or bundled)
•Replaces placeholders with extracted data
•Preserves custom sections
•Updates Navigator workflow to natural language
•Removes slash command references
•Adds skills explanation

Step 5: Show Diff and Confirm

Display changes for user review:

bash

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:

code

✅ CLAUDE.md Updated to v3.1

Key changes:
  ✓ Removed slash command references (e.g., /nav:start)
  ✓ Added natural language examples ("Start my Navigator session")
  ✓ Added skills architecture explanation
  ✓ Updated Navigator workflow section
  ✓ Preserved your project-specific customizations:
    - Tech stack: [list]
    - Code standards: [count] custom rules
    - Forbidden actions: [count] custom rules

Backup saved: CLAUDE.md.backup

Next steps:
  1. Review changes: git diff CLAUDE.md
  2. Test: "Start my Navigator session" should work
  3. Commit: git add CLAUDE.md && git commit -m "chore: update CLAUDE.md to Navigator v3.1"
  4. Remove backup: rm CLAUDE.md.backup

Rollback if needed: mv CLAUDE.md.backup CLAUDE.md

Step 7: Optional - Update .nav-config.json

If config exists, check version:

bash

if [ -f ".agent/.nav-config.json" ]; then
  version=$(jq -r '.version' .agent/.nav-config.json)
  if [ "$version" != "4.6.0" ]; then
    echo ""
    echo "💡 .nav-config.json is version $version"
    echo "   Update to 4.6.0? [Y/n]"
    read -r response

    if [[ "$response" =~ ^([yY][eE][sS]|[yY]|)$ ]]; then
      jq '.version = "4.6.0"' .agent/.nav-config.json > /tmp/nav-config.tmp
      mv /tmp/nav-config.tmp .agent/.nav-config.json
      echo "   ✓ Updated config to v4.6.0"
    fi
  fi
fi

Predefined Functions

functions/version_detector.py

Purpose: Detect CLAUDE.md version (outdated, current, unknown)

Usage:

bash

python3 version_detector.py CLAUDE.md

Output: Prints one of: outdated, current, unknown

Exit codes:

•0: Success (version detected)
•1: File not found
•2: Parse error

Detection logic:

•Check for version marker: Navigator Version: X.X.X
•Check for slash commands: /nav:start, /jitd:, etc.
•Check for natural language examples: "Start my Navigator session"
•Check for skills section

Heuristics:

•Has /nav: → outdated
•Version < 3.0 → outdated
•Version >= 3.0 + natural language → current
•No version + no Navigator markers → unknown

functions/claude_updater.py

Purpose: Extract customizations and generate updated CLAUDE.md

Usage:

bash

# Extract customizations
python3 claude_updater.py extract CLAUDE.md > customizations.json

# Generate updated file
python3 claude_updater.py generate \
  --customizations customizations.json \
  --template ../../templates/CLAUDE.md \
  --output CLAUDE.md

Extract mode outputs JSON:

json

{
  "project_name": "MyApp",
  "description": "Brief project description",
  "tech_stack": ["Next.js", "TypeScript", "PostgreSQL"],
  "code_standards": ["Custom rule 1", "Custom rule 2"],
  "forbidden_actions": ["Custom restriction 1"],
  "pm_tool": "github",
  "custom_sections": {
    "Deployment": "Custom deployment instructions..."
  }
}

Generate mode:

•Loads template
•Replaces [Project Name] with project_name
•Replaces [Brief project description] with description
•Replaces [List your technologies...] with tech_stack
•Appends custom code standards
•Appends custom forbidden actions
•Inserts custom sections at end

Error Handling

No CLAUDE.md found:

code

❌ No CLAUDE.md found in current directory

This project doesn't appear to have Navigator initialized.
Run "Initialize Navigator in this project" first.

Backup failed:

code

❌ Failed to create backup: CLAUDE.md.backup

Check file permissions and disk space.

Parse error:

code

❌ Failed to parse CLAUDE.md

The file might be corrupted or have unusual formatting.
Manual review required.

Backup saved at: CLAUDE.md.backup

Template not found:

code

❌ Navigator template not found

This might be a plugin installation issue.
Try reinstalling Navigator plugin: /plugin update navigator

Success Criteria

Migration is successful when:

• CLAUDE.md backed up successfully
• Version detected correctly
• Customizations extracted
• New file generated with v3.1 template
• Project-specific content preserved
• Diff shown to user for review
• Commit instructions provided

Rollback Procedure

If migration fails or user is unhappy:

bash

# Restore backup
mv CLAUDE.md.backup CLAUDE.md

# Or compare and manually fix
diff CLAUDE.md.backup CLAUDE.md

Notes

This skill:

•Preserves all customizations (tech stack, standards, restrictions)
•Non-destructive (always creates backup)
•Idempotent (running multiple times is safe)
•Transparent (shows diff before finalizing)

What gets updated:

•Navigator version marker
•Slash commands → natural language
•Workflow examples
•Skills vs commands explanation
•Token optimization strategy

What gets preserved:

•Project name and description
•Tech stack
•Code standards
•Forbidden actions
•PM tool configuration
•Custom sections

Related Skills

•nav-init: Initialize Navigator in new project (creates CLAUDE.md from scratch)
•nav-start: Start session (uses updated CLAUDE.md)
•nav-task: Task documentation (benefits from updated workflow)

Examples

Example 1: Simple Update

code

User: "Update my CLAUDE.md to v3.1"