/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:-$(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 (