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 1: Check Navigator Version

Check if user is running latest Navigator version:

# Run version checker (optional - doesn't block session start)
if [ -f "scripts/check-version.sh" ]; then
  bash 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 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)

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:

# Get the skill's base directory (passed via SKILL_BASE_DIR)
SKILL_DIR="${SKILL_BASE_DIR:-$HOME/.claude/plugins/marketplaces/jitd-marketplace/skills/nav-start}"
python3 "$SKILL_DIR/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

Show this formatted summary:

╔══════════════════════════════════════════════════════╗
║                                                      ║
║  🚀 Navigator Session Started                             ║
║                                                      ║
╚══════════════════════════════════════════════════════╝

📖 Documentation Navigator: Loaded
🎯 Project Management: [PM tool or "Manual"]
✅ Token Optimization: Active

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 DOCUMENTATION LOADED (MEASURED)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Navigator (.agent/DEVELOPMENT-README.md):
  Size: [nav_bytes] bytes = [nav_tokens] tokens

CLAUDE.md (auto-loaded):
  Size: [claude_bytes] bytes = [claude_tokens] tokens

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total documentation:     [total_tokens] tokens
Available for work:      [available] tokens ([percent]%)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💡 On-demand loading strategy:
   Load task doc when needed:  +3-5k tokens
   Load system doc if needed:  +4-6k tokens
   Load SOP if helpful:        +2-3k tokens

   Total with all docs:        ~[total + 15]k tokens

   vs Traditional (all upfront): ~150k tokens
   Savings: ~[150 - total - 15]k tokens

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔹 Navigator WORKFLOW REMINDER

1. Navigator-first loading
   - ✅ Loaded: .agent/DEVELOPMENT-README.md
   - Next: Load ONLY relevant task/system docs

2. Use agents for research
   - Multi-file searches: Use Task agent (saves 60-80% tokens)
   - Code exploration: Use Explore agent
   - NOT manual Read of many files

3. Task documentation
   - After features: Use nav-task-manager skill
   - After bugs: Use nav-sop-creator skill

4. Context management
   - Run nav-compact skill after isolated sub-tasks
   - Context markers save your progress

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[MULTI-CLAUDE WORKFLOWS CHECK - v4.3.0+]

Check if multi-Claude workflows installed:
```bash
if ! command -v navigator-multi-claude.sh &> /dev/null; then
  echo ""
  echo "⚡ Multi-Claude Workflows Available (v4.3.0+)"
  echo ""
  echo "   Enable parallel AI execution for complex tasks."
  echo "   Status: Not installed"
  echo ""
  echo "   Install: 'Install multi-Claude workflows'"
  echo "   Learn more: See RELEASE-NOTES-v4.3.0.md"
  echo ""
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
fi

Only show this prompt:

• If plugin version >= 4.3.0
• If scripts not installed
• Once per session (set flag in memory)

Do NOT show if:

• Scripts already installed
• Plugin version < 4.3.0
• User explicitly dismissed before

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[If tasks found from PM tool, list them here]

[If no tasks found:] No active tasks found. What would you like to work on?

## Predefined Functions

### scripts/otel_session_stats.py

**Purpose**: Display real-time session statistics via OpenTelemetry

**When to call**: After loading navigator, before presenting session summary

**Requirements**:
- CLAUDE_CODE_ENABLE_TELEMETRY=1 (optional - shows setup if disabled)
- Metrics available from current session (shows waiting message if not)

**Execution**:
```bash
SKILL_DIR="${SKILL_BASE_DIR:-$HOME/.claude/plugins/marketplaces/jitd-marketplace/skills/nav-start}"
python3 "$SKILL_DIR/scripts/otel_session_stats.py"

Output: Formatted statistics with:

• Token usage breakdown (input/output/cache)
• Cache hit rate percentage
• Session cost in USD
• Active time
• Context availability

Error Handling:

• If OTel not enabled: Shows setup instructions
• If no metrics yet: Shows "waiting for export" message
• Never crashes - always displays helpful guidance

Reference Files

This skill uses:

• otel_session_stats.py: Real-time session stats via OpenTelemetry
• .agent/DEVELOPMENT-README.md: Navigator content
• .agent/.nav-config.json: Configuration
• .agent/.context-markers/.active: Active marker check

Error Handling

Navigator not found:

❌ Navigator not initialized

Run /nav:init to create .agent/ structure first.

PM tool configured but not working:

⚠️  [PM Tool] configured but not accessible

Check authentication or run setup guide.

Config file malformed:

⚠️  .agent/.nav-config.json is invalid JSON

Fix syntax or run /nav:init to regenerate.

Success Criteria

Session start is successful when:

• Navigator loaded successfully
• Token usage calculated and displayed
• PM tool status checked (if configured)
• User knows what to work on next
• Navigator workflow context set

Notes

This skill provides the same functionality as /nav:start command but with:

• Natural language invocation (no need to remember / syntax)
• Auto-detection based on user intent
• Composable with other Navigator skills

If user prefers manual invocation, they can still use /nav:start command (both work in hybrid mode).