Navigator: Finish What You Start

Sessions that last. AI that learns. Features that ship.

Why This Exists

The problem: AI coding sessions crash at exchange 5-7. Context window fills with documentation you never use.

Navigator's solution: Context engineering — load what you need, when you need it. 150k → 12k tokens (92% reduction).

Result: Sessions go 20+ exchanges. Features actually ship.

Proven: OpenTelemetry-verified, not estimates. Session efficiency scores 94/100.

Version history: see CHANGELOG.md for the full release log, or releases/ for per-version notes.

Core Principle

Context engineering beats bulk loading.

Not "load everything just in case." Not "better safe than sorry." Strategic loading saves 92% of context for actual work.

New to this approach? Read the philosophy:

• .agent/philosophy/CONTEXT-EFFICIENCY.md - Why Navigator exists
• .agent/philosophy/ANTI-PATTERNS.md - Common mistakes (upfront loading, etc.)
• .agent/philosophy/PATTERNS.md - What works and why

Navigator Runtime (v8)

Navigator's workflow is enforced by a hook runtime, not by prose in this file. As of v8.0.0 that runtime is a Claude Code mod: one in-process TypeScript module (hooks/hooks.json → hooks/mod/register.tsx) that runs every op on Claude Code 2.1.287 or newer. The v7 Python dispatcher (hooks/nav_dispatch.py → nav_hook_lib.runtime) stays registered as the fallback: on older Claude Code, where an organization's policy blocks mods, or when an op crashes three times in a session, Python runs that op instead. The mod announces what it owns in NAVIGATOR_MOD_OWNS; the Python dispatcher skips owned ops in one place and exits immediately when it owns nothing to do. Both share one state file, .agent/.nav-runtime-state.json, so an op handed across sees the same state.

Each behavior is an op with a config off-switch in .agent/.nav-config.json:

stop_completion.continue_enabled, tier1.enabled and judge.enabled ship OFF (new blocking or outbound features seed off). Setting PILOT_EXECUTOR disables interactive/blocking behavior in both runtimes (one policy point each: nav_hook_lib.config.is_pilot_executor, hooks/mod/lib/config.ts isPilotExecutor).

What the mod adds beyond v7: /nav, a pane of cards: context (fill, compact verdict, trend), session (this session only: cost, tokens and cache hit, then its commits, lines and active time, and its tokens/min sparkline, from the local Prometheus of .agent/grafana/ when it answers, dashboard.enabled; else Claude Code's own numbers; -- and this session not in prometheus when Prometheus has no series for this session after two turns, TASK-102/104), reads (fan-out verdict), the typed judge's verdict on the last prompt and what Navigator did with it (j: the session tally and the last decisions, y/x label the latest into ~/.config/navigator/judge-labels.json for scripts/judge_eval.py), next (the current leg as a press that submits it, with an ETA from the pace so far), memories with pinning, reads and tasks behind d, the reject log behind l (3 rejects + 14:03 stop_completion under reads; .agent/.nav-rejects.jsonl, one JSON line per read-guard deny, prompt-gate block or stop-gate block, written by both runtimes, TASK-88), and marker/compact buttons (below 72 columns the three top cards stack and the button row wraps); a status band above the prompt (phase · context · next action); a Pilot custom theme (/theme → Pilot); and a read-only update notice. Parity with the Python ops is asserted byte for byte by generated fixtures (scripts/gen_mod_data.py, make mod-test).

The sections below describe those behaviors so humans and models know what to expect. This text is documentation, not the mechanism.

Session Start

"Start my Navigator session" remains the friendly way to begin: it loads .agent/DEVELOPMENT-README.md (docs index, ~2k tokens) and current task context (~3k). Session context is injected at session start — enforced by session_start (hook runtime); this text is documentation, not the mechanism. The same op writes the plugin root to ~/.config/navigator/plugin-root, which every skill reads because the Bash tool never sees CLAUDE_PLUGIN_ROOT (TASK-97, v8.3.3).

Workflow Gating

Task-shaped prompts are scored for loop triggers ("run until done", "keep going", "iterate until") and complexity (>= 0.5 → Task Mode; below → direct execution). The v6 "show a WORKFLOW CHECK block before every task" mandate is retired; gating happens on UserPromptSubmit — enforced by prompt_gate (hook runtime); this text is documentation, not the mechanism.

Documentation Loading

Read .agent/DEVELOPMENT-README.md first, then lazy-load task/system/SOP docs on demand: ~12k tokens per session vs ~150k loading everything. Fan-out manual Reads that should be Task agents are guarded on PreToolUse — enforced by read_guard (hook runtime); this text is documentation, not the mechanism.

Update docs as you go: "Archive TASK-XX documentation" after a feature, "Create an SOP for debugging [issue]" after solving something novel.

Autonomous Task Completion

When implementation is complete, Navigator's finish protocol runs without human prompts: simplify (if enabled), commit, archive the plan, close the ticket (if configured), create a completion marker, suggest compact. Exceptions that ask first: secrets in uncommitted files, multiple unrelated tasks touched, failing tests. Completion indicators are recorded on Stop — enforced by stop_state (hook runtime); this text is documentation, not the mechanism. When indicators show unfinished work and no explicit exit signal is present, one continuation may be forced (capped by stop_completion.max_continues, off by default, always off under PILOT_EXECUTOR) — enforced by stop_completion (hook runtime); this text is documentation, not the mechanism.

Loop Mode

"Run until done: ..." activates structured iteration: NAVIGATOR_STATUS blocks, progress phases (INIT → RESEARCH → IMPL → VERIFY → COMPLETE), and stagnation detection. The v6 dual-condition exit rules are no longer prose mandates: exit evaluation reuses the exit_gate.evaluate_exit indicator vocabulary and runs on Stop — enforced by stop_state and stop_completion (hook runtime); this text is documentation, not the mechanism. Configuration and full behavior: loop_mode block + skills/nav-loop/SKILL.md.

Intent Briefs

Ambiguity ≠ complexity. Ambiguous task-shaped prompts get a NAV-BRIEF injection (plus relevant knowledge-graph memories) prompting a one-screen intent brief — Goal / Scope / Approach / Limits / Verify / Won't do / Contradiction — with max 2 open questions before files change. Contradiction is the optional TRIZ row ("improving X worsens Y", usually none); when declared, prior resolutions are queried from the knowledge graph before Approach is filled (brief_hook.contradiction_field toggles the row). On substantial tasks a declared contradiction hands off to nav-triz, which drafts three candidates from different separation modes and recommends one (skills/nav-triz/SKILL.md). Injection happens on UserPromptSubmit — enforced by prompt_brief (hook runtime); this text is documentation, not the mechanism. Passthrough: "just do it", "quick fix", "skip the brief". Full behavior: skills/nav-brief/SKILL.md.

Tier-1 Instant Answers

A narrow exact-match command set (nav stats, show features, list markers, graph health, nav version) can be answered deterministically with zero model invocation — enforced by prompt_tier1 (hook runtime); this text is documentation, not the mechanism. Off by default; toggle per rule via tier1.rules.

Smart Compact

Compact after an isolated sub-task, a docs update, or a task switch; not mid-feature or mid-debug. Context markers are captured around compaction — enforced by compact_marker (hook runtime); this text is documentation, not the mechanism.

Features Beyond the Runtime

Theory of Mind (v5.0.0)

Bilateral modeling from Riedl & Weidmann 2025: verification checkpoints on high-stakes skills, preference learning (nav-profile), quality-drop detection (nav-diagnose), intent-capturing markers (nav-marker). Configure via the tom_features block.

Code Simplification (v5.4.0)

Clarity over brevity, functionality preserved absolutely: flatten nested ternaries, early returns, descriptive names. Runs post-implementation before commit, during Loop Mode VERIFY, or on demand ("simplify this code"). Configure via the simplification block.

Auto-Update (v5.5.0)

How updates work (TASK-81, v8): Navigator never updates itself from a hook. At session start the mod compares its own version with the latest GitHub release (at most every auto_update.check_interval_hours, never under Pilot) and shows a notice with the command: claude plugin update navigator@navigator-marketplace. "Start my Navigator session" runs the nav-start skill, whose Step 1.5 calls auto_updater.py once and reports its JSON. Restart Claude Code after an update; it caches skill paths at session start. A session with CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC refuses every plugin fetch, so the notice never fires there unless auto_update.curl_fallback: true repeats the same GET through curl (TASK-98; ships off, usually set in .nav-config.local.json).

Task Mode (v5.6.0)

Substantial work (complexity >= 0.5, no matching skill) gets phase guidance: RESEARCH → PLAN → IMPL → VERIFY → COMPLETE. Skills keep their own workflows (Task Mode defers); trivial tasks run direct. Activation scoring runs at prompt time — enforced by prompt_gate (hook runtime); this text is documentation, not the mechanism.

Project Knowledge Graph (v6.0.0)

One query interface across tasks, SOPs, system docs, markers, and experiential memories: "What do we know about auth?", "Remember this pitfall: ...". Configure via the knowledge_graph block; details in skills/nav-graph/SKILL.md.

TRIZ Divergent Solving (v7.1.0 – v7.2.0)

Decisions may carry the contradiction they resolved (--action contradictions lists them). When a brief declares a contradiction on a substantial task, or you ask "find a better solution for X", nav-triz drafts three candidates from different separation modes, each with a named downside, and recommends one. Details: skills/nav-triz/SKILL.md.

Deep Research (v7.3.0 – v7.4.0)

"Deep research on X" runs a web research pipeline in subagents: three-lens search plan, parallel fetchers into fenced source notes, one writer, one adversarial critic, one patcher limited to Read+Edit, then a deterministic ship gate before typed Key findings become graph memories with URLs as evidence, each tagged with its fetch date and content-hash prefix so a later reader can tell which page version supported the claim. Every source carries the search lens that found it (canonical, breadth, adversarial, gap) into the Sources table, and no finding may rest on a single breadth source. Reports are answer-first: a fixed Summary block (Answer, bullets, counter-position), an At-a-glance table for comparisons, one section per item, and a paragraph cap the gate enforces (reference/REPORT-FORMAT.md). Ships OFF (deep_research.enabled); runs live under .agent/research/<slug>/. For codebase questions use the navigator-research agent. Details: skills/nav-deep-research/SKILL.md.

Code Intelligence (v7.5.0)

When a language-server plugin from the official marketplace is enabled (pyright-lsp, typescript-lsp, gopls-lsp, …), navigator-research uses the LSP tool for symbol questions — references, definition, outline, hover — and falls back to Grep when the tool is absent. Nothing bundled, no config key: the plugin's presence is the toggle. Measured on this repo (TASK-76): a who-calls question dropped from 9 requests / 284k context tokens to 5 / 142k with the complete call-site list; convention questions are unaffected. scripts/agent_tool_counts.py gives real per-tool counts from a transcript.

Typed Prompt Judge (v7.7.0)

The loop-trigger, complexity and ambiguity scorers are keyword matchers, and they misfire on text that merely contains a trigger phrase (a pasted report header reading "Loop mode" put a session into Loop Mode on 2026-09-19). With judge.enabled, one request per prompt to a typed-decision model (TypeSafe Jev, POST /v1/systemone) answers eight questions at once: is this a task, does it ask for autonomous iteration, complexity on a four-level rubric, ambiguity on three, and whether scope / limits / approach / verification are stated. Each axis overrides its heuristic only when decisive (noul outside the [noul_low, noul_high] band, score confidence at min_confidence or above); undecided axes, timeouts, a missing key or any error leave the heuristic in charge, byte for byte. Measured on 60 labeled prompts (TASK-79): tier accuracy 38 → 53 of 60, task-shapedness 43 → 54, at ~0.7 s and ~$0.00003 per prompt. Ships OFF: the prompt leaves the machine (secret-redacted, head-capped to max_state_chars). Enable with "enable judge"; the key comes from TYPESAFE_API_KEY or ~/.config/typesafe/api_key, never from the committed config. Verify with python3 hooks/nav_hook_lib/judge.py --check; session start names the key source or warns when none is found. Setup SOP: .agent/sops/integrations/typesafe-judge-setup.md. Replay the eval with scripts/judge_eval.py.

Reply Modes: ADHD and STE (v7.9.0, v8.3.0)

Per-person switches that shape replies. Each mode is one row in a table (hooks/nav_hook_lib/reply_modes.py, mirrored in hooks/mod/lib/reply_modes.ts) and one op serves them all. Say <key> mode on, <key> mode off or <key> mode at any prompt: the hook answers with zero model turn and writes ~/.config/navigator/<key>-mode.json, so the switch follows you across repos and takes effect on the next prompt without a restart. While on, that mode's rule block rides every prompt as injected context; while off it exists nowhere in the context. Subagents never see it. A repo can pin a mode with <key>_mode.on: true|false (shared or .local); null defers to the person; <key>_mode.enabled: false hides the mode entirely.

• ADHD (adhd mode on): reply shape. One next action first, time-critical items first with the deadline in bold, bullets over prose, lists capped at five, numbered steps with "step k of n", no preamble, one sub-two-minute closing action.
• STE (ste mode on, use ste): sentence style from ASD-STE100 Simplified Technical English, Part 1 only. One idea per sentence, 20 words for instructions, imperative instructions, active voice, present tense, no gerunds, no noun clusters, full sentences. The controlled dictionary is not applied.

When both are on, the blocks stack in table order: shape first, sentences inside it. Enforced by prompt_modes (hook runtime); this text is documentation, not the mechanism. Design: .agent/tasks/TASK-82-adhd-mode.md, .agent/tasks/TASK-93-reply-modes-ste.md.

Agents vs Skills - Token Optimization Strategy

• Agents = research and exploration (separate context, 60-80% token savings): multi-file searches, unfamiliar code, pattern discovery.
• Skills = execution and consistency (predefined functions/templates): features following patterns, boilerplate, project conventions.
• Model: the bundled research agents (navigator-research, task-planner, the deep-research fetcher) declare model: sonnet in their frontmatter, so read-only exploration runs on the current Sonnet (resolved to Sonnet 5.5 on Claude Code 2.1.284); the deep-research writer, critic and patcher stay on Opus.

Prefer a Task agent over manually Reading many files (fan-out Reads are guarded — enforced by read_guard (hook runtime); this text is documentation, not the mechanism). With an LSP plugin installed the research agent uses LSP for symbol questions and Grep otherwise (agents/navigator-research.md, Phase 1.5).

Workflow Discipline

• Research before scaffolding: For new projects/features, state phase (research / design / decomposition / implementation) in your first message and wait for confirmation before writing code.
• Parallel for fan-out: When the task is "apply pattern to N similar files", dispatch N parallel Task agents up front — do not start sequentially and wait to be corrected. (Proven: workshop restyle = 41% line reduction.)
• Reframe, don't re-litigate: When the user corrects with "No X, we are doing Y", drop X entirely from outputs. Do not include the rejected framing in new artifacts.
• State hypothesis before exploring: For debugging, name the suspected failure mode and the file/artifact you'll inspect first. If the user pinned a specific failure, do not wander into adjacent systems.

Code Standards

• Architecture: KISS, DRY, SOLID principles
• Components: Framework best practices
• TypeScript: Strict mode (if applicable), no any without justification
• Line Length: Max 100 characters
• Testing: High coverage (backend 90%+, frontend 85%+)

Repository policy (plain repo etiquette, not runtime-enforced):

• No Claude Code mentions in commits/code
• No package.json modifications without approval
• Never commit secrets/API keys/.env files
• Don't delete tests without replacement

The v6 "Forbidden Actions" mandate list (skip-workflow-check, ignore-loop-triggers, load-all-docs, etc.) is retired: those behaviors are config policy now — enforced by prompt_gate and read_guard (hook runtime); this text is documentation, not the mechanism.

Development Workflow

1. Start Session → session context injected (session_start op)
2. Select Task → Load task doc (.agent/tasks/TASK-XX.md)
3. Research → Task agent for multi-file searches
4. Plan → TodoWrite for complex tasks
5. Implement → Follow patterns, write tests
6. Verify → Run tests, confirm functionality
7. Simplify → Code clarity improvements (if enabled)
8. Complete → Commit, document, close ticket, create marker
9. Compact → Clear context for next task

Documentation System

.agent/
├── DEVELOPMENT-README.md      # Navigator (always load first)
├── tasks/                     # Implementation plans
├── system/                    # Architecture docs
└── sops/                      # Standard Operating Procedures
    ├── integrations/
    ├── debugging/
    ├── development/
    └── deployment/

Load strategy: navigator (~2k) + current task (~3k) + system doc as needed (~5k) + SOP if required (~2k) ≈ 12k tokens, vs ~150k loading everything.

Natural language commands:

• "Initialize Navigator in this project" (first-time setup)
• "Start my Navigator session" (begin work)
• "Archive TASK-XX documentation" (after feature)
• "Create an SOP for debugging [issue]" (after solving issue)
• "Create context marker [name]" (save point)
• "Clear context and preserve markers" (compact)

Slash commands (legacy, still work): /nav:init, /nav:start, /nav:marker, /nav:compact

Project Management Integration (Optional)

Supported: Linear (MCP), GitHub Issues (gh), Jira (API), GitLab (glab), or none. If configured: read ticket → plan in .agent/tasks/ → implement → update system docs → archive + close on completion → notify team chat.

Commit Guidelines

• Format: type(scope): description
• Reference ticket: feat(feature): implement X TASK-XX
• No Claude Code mentions
• Concise and descriptive

Configuration

Navigator config in .agent/.nav-config.json (minimal subset shown; the live file also carries tom_features, loop_mode, task_mode, knowledge_graph, and the *_hook toggle blocks; missing blocks default safe via nav_hook_lib.config.DEFAULTS). Personal overrides go in .agent/.nav-config.local.json (gitignored, merged last: DEFAULTS < shared < local); nav-features disable <feature> --local writes there:

{
  "version": "7.0.0",
  "project_management": "none",
  "task_prefix": "TASK",
  "task_id_source": "local",
  "team_chat": "none",
  "auto_load_navigator": true,
  "compact_strategy": "conservative",
  "simplification": { "enabled": true, "trigger": "post-implementation", "scope": "modified" },
  "auto_update": { "enabled": true, "check_interval_hours": 1, "curl_fallback": false },
  "dispatcher": { "enabled": true },
  "tier1": { "enabled": false, "rules": {} },
  "stop_completion": { "enabled": false, "continue_enabled": false, "max_continues": 2,
                       "require_marker_after_task_doc": true },
  "reject_log": { "enabled": true },
  "deep_research": { "enabled": false },
  "judge": { "enabled": false, "model": "jev-latest", "timeout_ms": 1500 }
}

Success Metrics

• Context efficiency: <70% token usage typical, <12k tokens loaded, 10+ exchanges without compact, zero session restarts mid-feature.
• Documentation: 100% features have task docs, 90%+ integrations have SOPs, system docs updated within 24h, zero repeated mistakes.
• Productivity: 10x more work per token, docs found within 30 seconds, new developers productive in 48 hours.

For complete Navigator documentation: See .agent/DEVELOPMENT-README.md

Last Updated: 2026-11-01 Navigator Version: 8.4.12