Help us improve
Share bugs, ideas, or general feedback.
From navigator
Loads the Navigator documentation navigator at session start to provide optimized project context. Useful when beginning work, resuming after a break, or checking project status.
npx claudepluginhub alekspetrov/navigator --plugin navigatorHow this skill is triggered — by the user, by Claude, or both
Slash command
/navigator:nav-startThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Load the Navigator documentation navigator to start your development session with optimized context.
Interactive hands-on onboarding for Navigator with two learning flows: Quick Start (~15 min) and Full Education (~45 min). Analyzes project stack and recommends relevant skills.
Reconstructs project context from AI agent session history, reporting workflow, open decisions, and interruptions to quickly orient on returning to a brownfield repo with multiple in-flight tracks.
Initializes Claude Code sessions by migrating legacy harness files to .claude-harness/, creating missing state files like memory rules and config, and preparing GitHub sync.
Share bugs, ideas, or general feedback.
Load the Navigator documentation navigator to start your development session with optimized context.
Invoke this skill when the user:
DO NOT invoke if:
/nav:start command this conversationBefore 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.
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:
Never block session start due to version check.
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:
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.
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.
Read the navigator file:
Read(
file_path: ".agent/DEVELOPMENT-README.md"
)
This is the lightweight index (~2k tokens) that tells you:
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(file_path: ".agent/.context-markers/{marker_file}").active file: rm .agent/.context-markers/.activeIf user declines (n):
.active fileRead 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+)Check if project config version matches plugin version:
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:
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.
Check if knowledge graph exists and is enabled:
if [ -f ".agent/knowledge/graph.json" ]; then
# Get graph stats
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/cache/navigator-marketplace/navigator}"
[ -d "$PLUGIN_DIR" ] || 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 (if auto_surface_relevant: true in config):
💡 Relevant Memories:
- PITFALL: "Auth changes often break session tests" (90%)
- PATTERN: "Always run unit tests before integration" (85%)
If graph doesn't exist:
📚 Knowledge Graph: Not initialized
Run "Initialize knowledge graph" to enable
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:
Verbosity (preferences.communication.verbosity):
concise: Keep responses brief, code-firstbalanced: Normal explanations (default)detailed: Thorough explanations with contextConfirmation threshold (preferences.communication.confirmation_threshold):
always: Show verification checkpoints for all skillshigh-stakes: Only for backend-endpoint, database-migration, frontend-component (default)never: Skip verification checkpointsFrameworks (preferences.technical.preferred_frameworks):
Corrections (corrections[]):
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
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.
Run the OpenTelemetry session statistics script:
# 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"
python3 "$PLUGIN_DIR/skills/nav-start/scripts/otel_session_stats.py"
This script:
Benefits of OTel integration:
Show the Navigator ASCII logo and session summary.
Display the logo using these exact ANSI color codes:
# Colors: Blue N, Red A, Blue V (Navigator arrow)
BLUE='\033[1;34m'
RED='\033[1;31m'
WHITE='\033[1;37m'
GRAY='\033[90m'
NC='\033[0m'
printf "${BLUE}███╗ ██╗${NC} ${RED} █████╗ ${NC}${BLUE}██╗ ██╗${NC}\n"
printf "${BLUE}████╗ ██║${NC} ${RED}██╔══██╗${NC}${BLUE}██║ ██║${NC}\n"
printf "${BLUE}██╔██╗ ██║${NC} ${RED}███████║${NC}${BLUE}██║ ██║${NC} ${WHITE}v6.0.0${NC}\n"
printf "${BLUE}██║╚██╗██║${NC} ${RED}██╔══██║${NC}${BLUE}╚██╗ ██╔╝${NC} ${GRAY}Knowledge Graph${NC}\n"
printf "${BLUE}██║ ╚████║${NC} ${RED}██║ ██║${NC}${BLUE} ╚████╔╝ ${NC}\n"
printf "${BLUE}╚═╝ ╚═══╝${NC} ${RED}╚═╝ ╚═╝${NC}${BLUE} ╚═══╝ ${NC}\n"
Then show the session info:
📖 Navigator: Loaded
🎯 PM: [PM tool or "Manual"]
✅ Optimization: Active
🧠 ToM: [Profile status from Step 5.6]
📚 Graph: [Knowledge graph status from Step 5.5]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 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
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔹 WORKFLOW ENFORCEMENT (MANDATORY)
Before responding to ANY task, show:
┌─────────────────────────────────────┐
│ WORKFLOW CHECK │
├─────────────────────────────────────┤
│ Loop trigger: [YES/NO] │
│ Complexity: [0.X] │
│ Mode: [LOOP/TASK/DIRECT] │
└─────────────────────────────────────┘
Loop triggers: "run until done", "do all", "keep going"
Task triggers: multi-file, refactor, new feature
Skipping this check = WORKFLOW VIOLATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔹 Navigator WORKFLOW REMINDER
1. Workflow enforcement
- ✅ ALWAYS show WORKFLOW CHECK on tasks
- Loop Mode: NAVIGATOR_STATUS each iteration
- Task Mode: Phase tracking (RESEARCH→COMPLETE)
2. Navigator-first loading
- ✅ Loaded: .agent/DEVELOPMENT-README.md
- Next: Load ONLY relevant task/system docs
3. Use agents for research
- Multi-file searches: Use Task agent (saves 60-80% tokens)
- Code exploration: Use Explore agent
4. Context management
- Run nav-compact skill after isolated sub-tasks
- Context markers save your progress
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[FIRST SESSION FEATURES DISPLAY - v5.6.0+]
Check if this is first session after install/update:
```bash
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/cache/navigator-marketplace/navigator}"
[ -d "$PLUGIN_DIR" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
FIRST_SESSION_MARKER=".agent/.features-shown-$(cat .agent/.nav-config.json | python3 -c "import sys,json; print(json.load(sys.stdin).get('version',''))" 2>/dev/null)"
if [ ! -f "$FIRST_SESSION_MARKER" ]; then
echo ""
python3 "$PLUGIN_DIR/skills/nav-features/functions/feature_manager.py" show --first-session
echo ""
echo "💡 Toggle features: 'show my features' or 'disable loop_mode'"
echo ""
touch "$FIRST_SESSION_MARKER"
fi
Shows feature table on:
Do NOT show if:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[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
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/cache/navigator-marketplace/navigator}"
[ -d "$PLUGIN_DIR" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
python3 "$PLUGIN_DIR/skills/nav-start/scripts/otel_session_stats.py"
Output: Formatted statistics with:
Error Handling:
This skill uses:
Fast-path source (v6.9.0+): SessionStart hook at hooks/nav_session_start.py
pre-loads all of the above into the session before the skill runs. See
nav-init Step 6 for how it's wired into .claude/settings.json.
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.
Session start is successful when:
This skill provides the same functionality as /nav:start command but with:
/ syntax)If user prefers manual invocation, they can still use /nav:start command (both work in hybrid mode).