alekspetrov/navigator/nav-start

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:-$(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"
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)

Run exactly this one command. It reads auto_update from the project config, checks the latest release, and updates the plugin only when one is available. It prints one JSON object.

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-start/functions/auto_updater.py"

Report only what that JSON says. Never write an update line from memory or a template:

• "status": "updated" → `✅ Navigator updated from <current_version> to <new_version>. Restart

Claude Code to load it.` (values copied from the JSON)

• "status": "failed" → ⚠️ <message>. Update by hand: claude plugin update navigator@navigator-marketplace
• "up-to-date", "disabled", "skipped", or the command did not run → say nothing about updates

Since v8 the Navigator mod also shows a read-only toast at session start when a newer release exists (TASK-81). It never updates by itself; this step and claude plugin update do.

Never block session start because of this step.

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

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"
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 exists and is enabled:

if [ -f ".agent/knowledge/graph.json" ]; then
  # Get graph stats
  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"
  GRAPH_STATS=$(python3 "$PLUGIN_DIR/skills/nav-graph/functions/graph_manager.py" --action stats --graph-path .agent/knowledge/graph.json 2>/dev/null)
  echo "$GRAPH_STATS"
fi

Display graph summary in session output:

📚 Knowledge Graph: Active
   Nodes: {total_nodes} | Memories: {memory_count}
   Concepts: {concept_count} indexed

Surface relevant memories (v6.17.0+: injected automatically): The SessionStart hook now enforces auto_surface_relevant — when the sentinel is present (fast path), a ## Relevant Memories block is already in your context, produced by memory_recall.py --auto (concepts from open task nodes + active marker, resolved memories excluded). Render it as:

💡 Relevant Memories:
   - PITFALL: "Auth changes often break session tests" (90%)
   - PATTERN: "Always run unit tests before integration" (85%)

Legacy path only (sentinel absent): run the recall CLI manually:

python3 "$PLUGIN_DIR/skills/nav-graph/functions/memory_recall.py" \
  --auto --agent-dir .agent --graph-path .agent/knowledge/graph.json \
  --limit 5 --format compact

Empty output → omit the block. Disable via knowledge_graph.auto_surface_relevant: false in .agent/.nav-config.json (max_session_memories caps the count).

If graph doesn't exist:

📚 Knowledge Graph: Not initialized
   Run "Initialize knowledge graph" to enable

Step 5.6: Load User Profile (ToM - Bilateral Modeling) [EXECUTE]

IMPORTANT: This step MUST be executed, not just documented.

Check if user profile exists:

if [ -f ".agent/.user-profile.json" ]; then
  echo "📋 User profile found"
else
  echo "No user profile. Using defaults."
fi

If profile exists, READ IT NOW:

Read(
  file_path: ".agent/.user-profile.json"
)

After reading, APPLY these preferences for the session:

1. Verbosity (preferences.communication.verbosity):

• concise: Keep responses brief, code-first
• balanced: Normal explanations (default)
• detailed: Thorough explanations with context

1. Confirmation threshold (preferences.communication.confirmation_threshold):

• always: Show verification checkpoints for all skills
• high-stakes: Only for backend-endpoint, database-migration, frontend-component (default)
• never: Skip verification checkpoints

1. Frameworks (preferences.technical.preferred_frameworks):

• Remember for code generation suggestions
• E.g., ["react", "express"] → prefer these in examples

1. Corrections (corrections[]):

• Review recent patterns to avoid repeating mistakes
• E.g., "REST endpoints use plural nouns" → apply immediately

Display profile summary in session output:

🧠 Theory of Mind: Active
   Profile: Loaded ({corrections_count} corrections, {goals_count} goals)
   Verbosity: {verbosity}
   Checkpoints: {confirmation_threshold}

If profile doesn't exist:

🧠 Theory of Mind: Active (no profile yet)
   Say "save my preferences" to create one

Step 6: Check PM Tool for Assigned Tasks

If PM tool is Linear:

# Check if Linear MCP available
# Try to list assigned issues

If PM tool is GitHub:

gh issue list --assignee @me --limit 10 2>/dev/null

If PM tool is none: Skip task checking.

Step 7: Display Session Statistics (OpenTelemetry)

Run the OpenTelemetry session statistics script:

# Resolve the installed plugin directory
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-start/scripts/otel_session_stats.py"

This script:

• If OTel enabled: Shows real-time metrics from Claude Code
• Real token usage (input/output/cache)
• Cache hit rate (CLAUDE.md caching performance)
• Session cost (actual USD spent)
• Active time (seconds of work)
• Context availability
• If OTel disabled: Shows setup instructions
• If no metrics yet: Shows "waiting for export" message

Benefits of OTel integration:

• Real data (not file-size estimates)
• Cache performance validation
• Cost tracking for ROI measurement
• Official API (won't break on updates)

Step 8: Display Session Summary