nav-start

What this skill does

# 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:

```bash
# 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:

```bash
# 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:

```bash
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`:

```bash
if [ -f ".agent/.context-markers/.active" ]; then
  marker_file=$(cat .agent/.context-markers/.active)
  echo "🔄 Active context marker detected!"
  echo ""
  echo "Marker: $marker_file"
  echo ""
  echo "This marker was saved during your last /nav:compact."
  echo "Load it to continue where you left off?"
  echo ""
  echo "[Y/n]:"
fi
```

If user confirms (Y or Enter):
- Read the marker file: `Read(file_path: ".agent/.context-markers/{marker_file}")`
- Delete `.active` file: `rm .agent/.context-markers/.active`
- Show confirmation: "✅ Context restored from marker!"

If user declines (n):
- Delete `.active` file
- Show: "Skipping marker load. You can load it later with /nav:markers"

### Step 5: Load Navigator Configuration

Read configuration:

```
Read(
  file_path: ".agent/.nav-config.json"
)
```

Parse:
- `project_management`: Which PM tool (linear, github, jira, none)
- `task_prefix`: Task ID format (TASK, GH, LIN, etc.)
- `team_chat`: Team notifications (slack, discord, none)
- `tom_features`: ToM configuration (if present, v5.0.0+)

### Step 5.1: Check Version Drift

**Check if project config version matches plugin version**:

```bash
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/cache/navigator-marketplace/navigator}"
[ -d "$PLUGIN_DIR" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
DRIFT_RESULT=$(python3 "$PLUGIN_DIR/skills/nav-start/functions/auto_updater.py" --check-drift 2>/dev/null || echo '{"has_drift": false}')
HAS_DRIFT=$(echo "$DRIFT_RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('has_drift', False))" 2>/dev/null)

if [ "$HAS_DRIFT" = "True" ]; then
  DRIFT_MSG=$(echo "$DRIFT_RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('message', ''))" 2>/dev/null)
  echo ""
  echo "⚠️  VERSION DRIFT DETECTED"
  echo "   $DRIFT_MSG"
  echo ""
fi
```

**Version drift occurs when**:
- Plugin updated but project config wasn't synced
- Manual plugin install without running nav-upgrade
- Project cloned with old config version

**Display warning if drift detected**:
```
⚠️  VERSION DRIFT DETECTED
   Project config (v5.5.0) behind plugin (v5.7.0). Run "update my CLAUDE.md" to sync.
```

This helps users understand why skills may behave unexpectedly.

### Step 5.5: Load Knowledge Graph (v6.0.0+) [EXECUTE]

**Check if knowledge graph