/nav-start

name: nav-start
description: Load Navigator documentation navigator when starting development session, resuming work, or beginning new feature. Use when user mentions starting work, beginning session, resuming after break, or checking project status.
allowed-tools: Read, Bash
version: 1.0.0

Navigator Navigator Skill

Load the Navigator documentation navigator to start your development session with optimized context.

When to Invoke

Invoke this skill when the user:

• Says "start my session", "begin work", "start working"
• Says "load the navigator", "show me the docs"
• Asks "what should I work on?"
• Mentions "resume work", "continue from where I left off"
• Asks about project structure or current tasks

**DO NOT invoke** if:

• User already ran `/nav:start` command this conversation
• Navigator already loaded (check conversation history)
• User is in middle of implementation (only invoke at session start)

Execution Steps

Step 0: Detect SessionStart Hook Injection (Fast Path) [v6.9.0+]

**Before doing anything else**, check whether the SessionStart hook has already injected Navigator context into this session. The hook emits a sentinel string on success:

<!-- nav-session-start-injected:v1 -->

**If the sentinel is present in your system context** (it appears inside a SessionStart system reminder block at the very top of the conversation):

→ **Fast path activated**. Do NOT execute Steps 1–7. The data those steps would Read is already in your context window. Skip directly to **Step 8 (Display Session Summary)** and render it using the injected data.

This eliminates ~6 Read tool invocations per session start and saves ~1.5-2k tokens of tool-call ceremony. The user-visible output must be **byte-identical** to the legacy path — they should not be able to tell which mode produced it.

**If the sentinel is absent** (legacy project without the hook, hook disabled in `.agent/.nav-config.json`, or hook crashed):

→ **Legacy path**. Execute Steps 1–7 as documented below. Same behavior as pre-v6.9.0.

**Detection rule of thumb**: If you can read the string `nav-session-start-injected` anywhere in the system reminders that opened this conversation, you are on the fast path.

---

Step 1: Check Navigator Version

Check if user is running latest Navigator version:

# Run version checker (optional - doesn't block session start)
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/cache/navigator-marketplace/navigator}"
[ -d "$PLUGIN_DIR" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
if [ -f "$PLUGIN_DIR/scripts/check-version.sh" ]; then
  bash "$PLUGIN_DIR/scripts/check-version.sh"

  # Note: Exit code 1 means update available, but don't block session
  # Exit code 0 means up to date
  # Exit code 2 means cannot check (network issue)
fi

**Version check behavior**:

• If update available: Show notification, continue session
• If up to date: Show ✅, continue session
• If cannot check: Skip silently, continue session

**Never block session start** due to version check.

Step 1.5: Auto-Update (if enabled)

If auto_update is enabled in config AND an update is available, automatically update Navigator:

# Resolve the installed plugin directory
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/cache/navigator-marketplace/navigator}"
[ -d "$PLUGIN_DIR" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"

# Run auto-updater
AUTO_UPDATE_RESULT=$(python3 "$PLUGIN_DIR/skills/nav-start/functions/auto_updater.py" 2>/dev/null)
AUTO_UPDATE_STATUS=$(echo "$AUTO_UPDATE_RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('status',''))" 2>/dev/null)

case "$AUTO_UPDATE_STATUS" in
  "updated")
    NEW_VERSION=$(echo "$AUTO_UPDATE_RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('new_version',''))" 2>/dev/null)
    REQUIRES_RESTART=$(echo "$AUTO_UPDATE_RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('requires_restart', False))" 2>/dev/null)
    echo "✅ Auto-updated Navigator to v$NEW_VERSION"
    if [ "$REQUIRES_RESTART" = "True" ]; then
      echo ""
      echo "⚠️  RESTART REQUIRED"
      echo "   Claude Code caches skill paths at session start."
      echo "   Restart Claude Code to load new skills from v$NEW_VERSION."
      echo ""
    fi
    ;;
  "up-to-date")
    # Silently continue
    ;;
  "failed")
    echo "⚠️  Auto-update failed. Run 'nav-upgrade' manually if needed."
    ;;
  "disabled"|"skipped")
    # Silently continue
    ;;
esac

**Auto-update behavior**:

• **If updated**: Show "✅ Auto-updated to vX.Y.Z" with restart prompt
• **If up-to-date**: Continue silently
• **If failed**: Show warning "⚠️ Auto-update failed, run nav-upgrade manually"
• **If disabled/skipped**: Continue silently

**IMPORTANT**: When `requires_restart: true`, display:

⚠️  RESTART REQUIRED
   Claude Code caches skill paths at session start.
   Restart Claude Code to load new skills from vX.Y.Z.

This informs users that mid-session updates require a restart to activate new skills.

**Never block session start** due to auto-update failure.

Step 2: Check Navigator Initialization

Check if `.agent/DEVELOPMENT-README.md` exists:

if [ ! -f ".agent/DEVELOPMENT-README.md" ]; then
  echo "❌ Navigator not initialized in this project"
  echo ""
  echo "Run /nav:init to set up Navigator structure first."
  exit 1
fi

If not found, inform user to run `/nav:init` first.

Step 3: Load Documentation Navigator

Read the navigator file:

Read(
  file_path: ".agent/DEVELOPMENT-README.md"
)

This is the lightweight index (~2k tokens) that tells you:

• What documentation exists
• When to load specific docs
• Current task focus
• Project structure overview

Step 4: Check for Active Context Marker

Check if there's an active marker from previous `/nav:compact`:

if [ -f ".agent/.context-markers/.active" ]; then