Navigator

Finish What You Start

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

What is Navigator?

Navigator is a Claude Code plugin that implements context engineering for AI-assisted development.

Instead of loading all your documentation upfront (and crashing at exchange 7), Navigator loads what you need, when you need it—keeping 94% of your context window available for actual work.

For developers using Claude Code who want sessions that finish features instead of crash mid-way.

The Loop You're Stuck In

You know the pattern:

Exchange 5:  Claude forgets your recent changes
Exchange 7:  Hallucinations start ("that function doesn't exist")
Exchange 8:  "Context limit reached"

Restart. Reload. Re-explain everything. Repeat.

You loaded 150k tokens of documentation "just in case."

You used 8k.

The rest? Noise drowning out signal.

Break The Loop

Navigator implements context engineering—load what you need, when you need it.

Result: Sessions that actually finish what they start.

And Your AI Gets Smarter

Navigator v5.0 adds Theory of Mind—Claude learns you.

nav-profile: Remembers your preferences across sessions

"Remember I prefer concise explanations"
→ Applied in future sessions
→ Auto-learns from corrections

nav-diagnose: Catches collaboration drift

Same correction twice → Quality check triggered
"You're not getting this" → Re-anchoring prompt

Loop Mode (v5.1): Run until done

"Run until done: add user authentication"
→ Structured completion with progress tracking
→ Dual-condition exit (heuristics + explicit signal)
→ Stagnation detection prevents infinite loops

Knowledge Graph (v6.0): Project memory that persists

"What do we know about auth?"
→ Unified search across tasks, SOPs, system docs
→ Experiential memory: patterns, pitfalls, decisions
→ Auto-surfaces relevant context on session start

Reply modes (v7.9): the reply shaped for you, switched by a sentence

"adhd mode on"
→ One next action first, bullets over prose, lists capped at five
→ Follows you across repos; "adhd mode off" ends it
→ STE mode (one idea per sentence, active voice) ships in v8.3.0

See Where You Are

Since v8 the workflow is enforced by a runtime that runs inside Claude Code, not by prose
in a config file. It gates task-shaped prompts, guards fan-out reads, records what each
turn finished, and writes one line to a reject log every time it says no. It also draws.

Type /nav and a pane opens beside your session:

A one-line status band above the prompt shows the phase, context fill and next action
without opening the pane. Requires Claude Code 2.1.287 or newer; older versions run the
same behaviors through the Python fallback, without the pane.

Same Workflows. More Capabilities.

Navigator is a superset. Everything you'd expect, plus context engineering.

Same foundation. Superior context management.

Proof, Not Promises

Not estimates. Verified via OpenTelemetry.

╔══════════════════════════════════════════════════════╗
║          NAVIGATOR EFFICIENCY REPORT                 ║
╚══════════════════════════════════════════════════════╝

📊 TOKEN USAGE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Your project documentation:     150,000 tokens
Loaded this session:             12,000 tokens
Tokens saved:                   138,000 tokens (92% ↓)

📈 SESSION METRICS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Context usage:                        35% (excellent)
Efficiency score:                  94/100 (excellent)

Check yours: type /nav for the live pane, or say "show my stats".

Quick Start

Install

# Claude Code plugin marketplace
/plugin marketplace add qf-studio/navigator
/plugin install navigator

# Restart Claude Code (2.1.287+ for the in-process runtime and the /nav pane)

Code intelligence (optional). Install a language-server plugin for your stack
(/plugin install pyright-lsp@claude-plugins-official, typescript-lsp, gopls-lsp, …;
the server binary must be on your PATH) and the research agent answers symbol questions
with go-to-definition, references and outlines instead of text search. Without one it
uses Grep exactly as before. Measured on this repo: a who-calls question went from 9
requests and 284k context tokens to 5 requests and 142k, with the complete call-site list.

Initialize

"Initialize Navigator in this project"

Start Every Session

"Start my Navigator session"

That's it. Navigator handles the rest.

Optional: Typed Prompt Judge

Navigator's loop-trigger, complexity and ambiguity detectors are keyword matchers. With a
TypeSafe key they get a typed judge behind them (v7.7.0): one
request per prompt, decisive answers override, everything else falls back to the keywords.
Measured on 60 labeled prompts, tier accuracy went from 38 to 53. Off by default because
the prompt text is sent to the API.

export TYPESAFE_API_KEY=...      # or: write it to ~/.config/typesafe/api_key (chmod 600)

Then say enable judge and verify with python3 hooks/nav_hook_lib/judge.py --check
from the plugin root. Setup and tuning: .agent/sops/integrations/typesafe-judge-setup.md.

What You Get

Skills that auto-invoke on natural language:

"Start my Navigator session"              → Session with 92% savings
"Create a React component for profile"    → Component + tests + styles
"Add an API endpoint for posts"           → Endpoint + validation + tests
"Create context marker: checkpoint"       → 97% context compression
"Run until done: add dark mode"           → Loop mode completion
"Deep research on WebGPU browser support"  → Cited report + graph memories
"Enable judge"                             → Typed Jev judgments behind the prompt gates
"adhd mode on"                             → Replies shaped for you, across repos
/nav                                       → Live pane: context, cost, rejects, next leg

No commands to memorize. Skills detect intent and execute.

Stop Restarting. Start Shipping.

Your sessions crash because context management is broken by default.

Navigator fixes this with context engineering—the same principles Anthropic recommends.

92% token savings. 20+ exchange sessions. Verified metrics.

/plugin marketplace add qf-studio/navigator
/plugin install navigator

Finish what you start.

Troubleshooting

Skill loads but prints docs instead of executing, or /nav is missing

claude plugin update navigator@navigator-marketplace

Then restart Claude Code. Outdated plugin version, or the pane needs 2.1.287+.

Links

• Docs site — guides, configuration, the /nav pane
• Documentation index
• Philosophy
• Release Notes
• GitHub
• QuantFlow Studio — the studio behind Navigator and Pilot

License

MIT License - See LICENSE

{
  "name": "navigator-marketplace",
  "displayName": "Navigator - Context-Efficient AI Development Framework",
  "owner": {
    "name": "QuantFlow Studio",
    "email": "aleks@quantflow.studio"
  },
  "metadata": {
    "description": "Context Engineering + Human-AI Collaboration Framework with Theory of Mind, Loop Mode, Task Mode, and Project Knowledge Graph",
    "version": "8.3.5",
    "breaking_changes": [
      "v6.16.0: New skill — nav-pilot, the Navigator→Pilot dispatch handoff. Navigator has authored Pilot-compatible task specs since v6.15.4, but the handoff stayed manual: a human ran `gh issue create --body-file .agent/tasks/TASK-XX.md`, had to remember the polling label, and pasted the resulting issue link back by hand. nav-pilot owns that one-way step — resolve a task doc (explicit TASK-XX or the active task), take its H1 as the issue title, show a pre-flight confirmation (ToM high-stakes checkpoint) with a --dry-run that prints the gh command without executing, run `gh issue create --label pilot --title <h1> --body-file <doc>` (repo defaults to the current git origin; override via pilot.repo), then record the issue URL into the doc's ## Refs and flip status to 🚀 Dispatched. Deliberately does NOT validate the doc — spec checking is Pilot's job (spec_validator regex ^##\\s+(Acceptance|Implementation|Context|Background|Approach|Design|Refs)\\b is an any-match structural check, and nav-task docs already pass). Polling label is deployment-configurable (default 'pilot') via a new pilot block in .nav-config.json. One-way by design: monitoring workers and pulling PR results back are out of scope. New files: skills/nav-pilot/SKILL.md, .agent/sops/integrations/pilot-handoff.md; registered in plugin.json. Pairs with nav-task (authors the spec) → nav-pilot (dispatches it). See TASK-54.",
      "v6.15.7: Corrected the plugin hook env-var name. Every Navigator lifecycle hook referenced ${CLAUDE_PLUGIN_DIR} — a variable Claude Code has never defined (the three real ones are CLAUDE_PLUGIN_ROOT, CLAUDE_PLUGIN_DATA, CLAUDE_PROJECT_DIR). The wrong name always expanded to empty, so the :-fallback always fired and every install since v6.13.0 resolved its hooks against the main-tracking marketplace checkout instead of the installed version. Invisible while main matched the release; it surfaced once they diverged — the published manifest still referenced token_monitor.py (retired on main by the v6.15.6 audit work), so the fallback path 404'd with a PostToolUse error on every tool call. Same class as the v6.14.0/v6.15.1 silent-fail saga (mem-036), which chased the symptom without finding this root cause. Fix: CLAUDE_PLUGIN_DIR -> CLAUDE_PLUGIN_ROOT across plugin.json (8 hook commands; marketplace path kept only as last-resort fallback), the 3 subprocess hooks (ROOT-first read, DIR back-compat), release_validator --verify-hooks, ~17 skill SKILL.md files, the migrate_hooks docstring, and mem-027. Historical references preserved (CHANGELOG, prior release notes, marketplace metadata, mem-036, the v6.14.0 guard quote). Verified: --verify-hook-paths 8/8, --verify-hooks 16/16 under set+unset ROOT, full make test green. First tagged release since v6.15.6, so it also publishes the audit-remediation batch wp1-wp11 (TASK-43..52 + TASK-25) that had accumulated unreleased on main. Restart Claude Code after upgrade to re-register the corrected manifest.",
      "v6.15.6: Critical hook-manifest fix. .claude-plugin/plugin.json still registered a PostToolUse(Bash) hook pointing at hooks/nav_commit_reminder.py — a file deleted in a2b4e59 (v6.15.5) when the commit-reminder probe was retired. That cleanup touched .claude/settings.json and templates/ but missed the canonical published manifest (plugin.json is what ships to every installed user; .claude/settings.json is only the dev backstop), so the local repo masked the regression. Effect on installed users: every Bash tool call invoked `python3 .../hooks/nav_commit_reminder.py` and failed with 'can't open file: No such file or directory' — a per-Bash-call error for 100% of users since v6.15.5/v6.13.0. Fix removes the dead PostToolUse(Bash) block from plugin.json (PostToolUse now: token_monitor on Edit|Write|Bash, nav_task_graph_sync + nav_profile_sync on Edit|Write). Also corrected .agent/DEVELOPMENT-README.md which still documented 'ten hooks' and listed nav_commit_reminder.py as live — now nine, table row removed, version refs synced to 6.15.6. Surfaced by a 10-dimension adversarially-verified project audit. Follow-up (not in this patch): add a release-time validator step asserting every hook command path in plugin.json resolves to an existing hooks/ file, so a deleted hook can never ship registered again.",
      "v6.15.5: Workflow Discipline section added to CLAUDE.md, codifying four interruption-reducing rules surfaced by the 2026-05-25 Claude Code Insights audit (428 messages, 25 sessions). Rules: (1) research before scaffolding — state phase in first message and wait for confirmation, (2) parallel for fan-out — dispatch N parallel Task agents up front when applying a pattern to N similar files (proven 41% line reduction in workshop restyle), (3) reframe don't re-litigate — drop rejected framings entirely from outputs, (4) state hypothesis before exploring — name suspected failure mode before tool use during debugging. Docs-only change, no code paths affected. Section inserted before existing ## Code Standards (~line 747). Also gitignores .agent/.marker-log (Navigator marker-creation log file that was being unnecessarily flagged as untracked in repo status output). Tests the post-bfe3b26 release.yml pipeline on a low-risk patch.",
      "v6.15.4: nav-task template upgraded to a Pilot-compatible superset shape. Renamed ## Implementation Plan → ## Implementation; added ## Acceptance Criteria (with - [ ] items), ## Out of Scope, ## Refs; dropped ## Success Metrics and ## Testing Plan (folded into Acceptance Criteria as concrete checkable outcomes). Updates both writers in lockstep — skills/nav-task/functions/task_formatter.py (the Python writer used by --title/--id CLI) and skills/nav-task/SKILL.md Step 3A create template (the LLM-instruction template Claude follows for natural-language invocation). Codifies the heading drift active task docs (TASK-37, TASK-40, TASK-example) had already converged on organically — ## Acceptance Criteria, ## Out of Scope, and ## References were emergent user behavior; the canonical template was the laggard. Pilot's spec_validator regex (^##\\s+(Acceptance|Implementation|Context|Background|Approach|Design|Refs)\\b at pilot/internal/adapters/github/spec_validator.go:22) matches four headings in the new template — gh issue create --body-file .agent/tasks/TASK-XX.md passes the structural check without any flag, and no 'pilot' label is required (the polling label is deployment-configurable, not a hardcoded constant). Preserved ## Verify and ## Done verbatim — verify_extractor.py:34,69 has hardcoded regex literals that would silently return empty results on rename. Kept ## Technical Decisions — task_to_graph.py:90-121 extracts decision memories from it. Dropped ## Dependencies and ## Completion Checklist — zero parsers depend on them and they're redundant with Done/Refs. Audit traced every parser before the rename: hooks are heading-agnostic, knowledge graph uses full-text keyword scan with no heading dependency, no test fixtures lock the old shape. Existing .agent/tasks/*.md docs unaffected — old docs remain fully readable; only new task docs (generated post-upgrade) use the new shape. Verified end-to-end: verify_extractor round-trips a freshly generated TASK-99 sample, extracting 3 commands and 4 done criteria correctly.",
      "v6.15.3: workflow_enforcer deadlock on question/non-task turns fixed. hooks/nav_workflow_state.py (Stop hook) previously stamped check_shown=false on every assistant turn missing the literal 'WORKFLOW CHECK' string — including AskUserQuestion-only turns and pure-text replies (session-start summaries, short clarifiers). When the next user prompt contained a Loop Mode trigger ('run until done', 'keep going', etc.), workflow_enforcer.py (UserPromptSubmit) exited 2 with only the three manual escape hatches as recovery. Reproduced in the wild: assistant asked a resume-or-review clarifier via AskUserQuestion, user declined, user typed 'Run until done via loop mode' → block. Fix: tristate check_shown — True when the CHECK block is present, False ONLY when the prior turn used a codebase-mutating tool (Edit, Write, MultiEdit, NotebookEdit, Bash, Task/Agent) without showing CHECK, None ('n/a') otherwise. nav_workflow_state.py now parses tool_use blocks from the transcript JSONL alongside text. workflow_enforcer.py already gates on 'check_shown is False', so None falls through to the soft-warn path cleanly with zero change to the enforcer. State file gains a tools_used field for transparency/debugging. Four-case smoke test passed: question-only turn → null, edit-without-check → false (still blocks), edit-with-check → true, pure-text-reply → null. End-to-end enforcer test confirmed null prompt exits 0, false prompt exits 2. No config changes required; existing strict_block=true continues to work as intended for genuine workflow violations.",
      "v6.15.2: Four v6.15.1 follow-ups landed: (1) nav-graph add-memory CLI no longer silently overwrites on-disk memory files. _next_memory_id now scans both graph nodes AND memories/**/mem-*.md on disk and takes the union max+1; --node-id from the CLI is honored when provided (was silently ignored, fell back to auto-assign); create_memory_file raises FileExistsError on collision instead of write_text'ing over the existing file. Caught when mem-034.md was nearly destroyed during v6.15.1 release work. (2) Graph reconciliation: mem-034 (UserPromptSubmit recursive-block pitfall) and mem-035 (PreToolUse silent stdout pitfall) added to graph — were on disk but never registered. Graph and disk now both at 36 memories with zero drift. (3) nav-release validator gains --verify-hooks mode: smoke-tests every plugin manifest hook command via bash with $CLAUDE_PLUGIN_DIR both bound and explicitly unset; flags the v6.14.0 regression signature (payload-emitting hook silently exits 0 with no stdout, no stderr). Coverage: SessionStart, PreCompact, PostCompact (HOOK_EMITS_PAYLOAD set); other events are silent-by-design and not flagged. Verified end-to-end — re-applying the v6.14.0 guard to SessionStart in a temp manifest is correctly caught as silent-fail. Would have caught v6.14.0 + v6.15.1 at release time. (4) skills/nav-sync-claude/skill.md renamed to SKILL.md for case consistency with all other skills; required git mv -f because macOS APFS is case-insensitive (core.ignorecase=true). Clears release_validator --verify-tag false-positive.",
      "v6.15.1: Two hook silent-fail fixes. (1) Three hook scripts (nav_session_start, nav_profile_sync, nav_task_graph_sync) had stale 'jitd-marketplace' hardcoded in their _resolve_plugin_dir fallback chains; renamed to 'navigator-marketplace' matching the current cache path. Tier 2/3 fallbacks were silently missing on every real install because the cache was renamed but these three scripts were missed during the marketplace rename (auto_updater and nav-sync-claude already used the correct name). (2) The v6.14.0 manifest-level shell guard ('if [ -n \"$CLAUDE_PLUGIN_DIR\" ]; then ... fi') silently no-opped every hook when the variable was unset — it protected workflow_enforcer from the v6.14.0 chicken-and-egg, but turned SessionStart, PreCompact, and seven other hooks into invisible no-ops in projects without a project-local .claude/settings.json backstop. Confirmed in the wild: a fresh Claude Code v2.1.142 session in a Nav-initialized project showed no SessionStart injection despite plugin and config being correct — the navigator source repo masked the bug via a project-local hook entry, gitnation-companion exposed it. Replaced the guard with shell parameter-expansion fallback ('${CLAUDE_PLUGIN_DIR:-$HOME/.claude/plugins/marketplaces/navigator-marketplace}/hooks/X.py'), which uses the env var when set and falls back to the flat marketplaces path otherwise — that path is maintained by Claude Code for every plugin install and contains all 10 hook scripts. No regression to the v6.14.0 fix: workflow_enforcer.py still receives a valid script path when CLAUDE_PLUGIN_DIR is unset and exits 0 on non-loop-trigger prompts. Smoke-verified: sentinel injection works with CLAUDE_PLUGIN_DIR both set and unset; workflow_enforcer exits 0 cleanly in the unset case. Missing path now produces a python stderr error instead of silent exit 0 — silent-fail mode eliminated.",
      "v6.15.0: nav-features exposes the full configurable surface. The feature table previously showed five entries and silently omitted eight features that already existed in .nav-config.json — including the v6.0.0 Knowledge Graph (knowledge_graph.enabled) and Multi-Agent orchestration (multi_agent.enabled), plus six lifecycle hooks (compact_hook, workflow_enforcer_hook, read_guard_hook, workflow_state_hook, task_graph_sync_hook, profile_sync_hook). All eight are now listed and toggleable via the nav-features skill. The install-check entry was renamed from multi_claude to multi_claude_scripts to disambiguate from the new multi_agent config flag — the former is a PATH-based shell-script presence check, the latter is a config-block toggle for the nav-multi skill; sharing the multi_claude name was actively misleading. Fixed simplification.default=False to True (it was already True in the shipping config and in CLAUDE.md; the default literal was just wrong, which only affected the fallback when the config section was missing). Widened the name column from 15 to 23 chars to fit workflow_enforcer_hook. SKILL.md sample output regenerated and supported-features list split into Core / Hooks / Install-based with a caution note on disabling guardrail hooks like workflow_enforcer_hook and read_guard_hook. No code paths beyond the FEATURES dict and table formatter changed; toggle round-trip verified clean for new entries. No backwards-compat shims — disabled features were never user-addressable, so renaming and adding are pure additions to the visible surface.",
      "v6.14.0: Defensive hook guards + two skill renames. (1) Every command in .claude-plugin/plugin.json's hooks field is now wrapped in 'if [ -n \"$CLAUDE_PLUGIN_DIR\" ]; then ... fi'. v6.13.0 moved hook distribution into the plugin manifest so ${CLAUDE_PLUGIN_DIR} would substitute correctly, but some installs still see the variable expand to empty when the plugin is registered but not fully loaded into the active session's plugin context. Because workflow_enforcer.py runs on every UserPromptSubmit, the unset variable became a hard block on every prompt INCLUDING /nav:init (chicken-and-egg: can't initialize Navigator to recover because the hook blocks the init command). The shell guard fails open (exit 0) when the variable is unset, runs normally when bound. All ten hooks across SessionStart, PreCompact, PostCompact, Stop, UserPromptSubmit, PreToolUse:Read, and three PostToolUse matchers got the guard. (2) nav-update-claude → nav-sync-claude (verb collision with nav-upgrade — one syncs CLAUDE.md, the other updates the plugin binary; nav-upgrade calls nav-sync-claude as Step 4) and nav-task-mode → nav-workflow (verb collision with nav-task — one manages .agent/tasks/ docs, the other is the workflow phase orchestrator). Zero functional overlap in either pair, naming was the entire problem. Clean rename, no backwards-compat aliases. Auto-invocation triggers unchanged. Live cross-refs in plugin.json, marketplace.json skills array, nav-upgrade, nav-simplify, DEVELOPMENT-README.md, current task docs, SOPs, knowledge graph, and mem-011 updated. Historical refs in CHANGELOG, prior release notes, .agent/tasks/archive/* left alone (renaming history would lie).",
      "v6.13.0: Hook distribution moved from user .claude/settings.json (via templates/claude-settings-hooks.json + settings_merger.py merge channel) to .claude-plugin/plugin.json's top-level `hooks` field — root cause of every fresh install's silent ${CLAUDE_PLUGIN_DIR} expansion failure (Claude Code only substitutes that var for hooks declared in a plugin manifest, not for hooks defined in a project's settings). Closes #9. hooks/workflow_enforcer.py re-wired from PreToolUse (matcher Edit|Write|Bash|Task) to UserPromptSubmit — the script reads stdin as if invoked under UserPromptSubmit, so under PreToolUse it always exited 0 and its blocking branch was unreachable since v6.11.1 (closes #8). Added PILOT_EXECUTOR env-var escape hatch in workflow_enforcer.py for autonomous-executor subprocess use cases (Pilot injects PILOT_EXECUTOR=1 in backend_claudecode.go). config_migrator.py CURRENT_VERSION now read at import from plugin.json via pathlib upward walk (was hardcoded \"5.7.0\" — every release left it stale); migration decision uses version_less_than() instead of != so newer configs are no-ops (closes #7). templates/claude-settings-hooks.json deleted. New skills/nav-upgrade/functions/migrate_hooks_out_of_settings.py removes the now-redundant Navigator hook entries from existing users' settings.json on next upgrade (conservative match: command must contain both hooks/ and one of 10 Navigator basenames; writes .pre-migrate.<ts> backup; idempotent). nav_commit_reminder.py registered in the plugin manifest's PostToolUse:Bash. settings_merger.py retained for non-hook keys (permissions, mcpServers). 25/25 tests green (11 settings_merger + 7 migrate_hooks + 7 config_migrator). Restart Claude Code after upgrade to register the new plugin-manifest hooks.",
      "v6.12.1: Course-correction patch for v6.12.0 after live verification revealed PreToolUse stdout AND hookSpecificOutput.additionalContext are silent to the model (mem-035 captures the finding); hooks/nav_read_guard.py upgraded with strict_block mode (default true) — at count >= escalate_threshold the hook now exits 2 with sentinel-wrapped <nav-read-guard-block>...</nav-read-guard-block> stderr that addresses the USER with four recovery options (use Task/Explore agent, split work across turns, raise threshold, disable strict); warn path switched from dead stdout to stderr; dead _emit() dual-channel function removed; counter IS the state-file ground truth that satisfies mem-027's three-condition gate (this hook writes the state file on prior invocations, so count >= threshold IS empirical confirmation of prior violations); new hooks/nav_commit_reminder.py PostToolUse Bash probe (20 lines, emits sentinel strings to both stderr and stdout to determine which channel surfaces — gates Opp 5 design for v6.12.2); .claude/settings.json synced with templates/claude-settings-hooks.json (was missing 5 of 7 lifecycle hooks — fresh plugin installs now get SessionStart, PreCompact, PostCompact, Stop, PreToolUse Read, PostToolUse task_graph_sync, PostToolUse profile_sync automatically); template corrected — workflow_enforcer.py moved from PreToolUse (where it would silently no-op since the hook reads data.get('prompt') which only exists on UserPromptSubmit) back to UserPromptSubmit; 6/6 read guard smoke-test scenarios green including strict_block on/off and recursive-trigger check; TASK-40 extended with v6.12.1 section",
      "v6.12.0: Phase 3 of TASK-38 hook-migration begins — new hooks/nav_read_guard.py (Opp 6) fires on PreToolUse Read, counts non-allowlisted .agent/ reads per turn in .agent/.nav-read-counter.json, warns at 3+ (suggest Task/Explore agent) and escalates at 5+ (name the bulk-load anti-pattern); allowlist exempts DEVELOPMENT-README.md, .nav-config.json, .user-profile.json, knowledge/graph.json (the legitimate nav-start surface); ships warn-only (exit 0 always) — a count alone fails mem-027's three-condition gate, blocking variant deferred until live telemetry shows warnings ignored; hooks/nav_workflow_state.py extended with _reset_read_counter() on Stop — counter clears between turns; dual-channel output for OQ-2 defensive (structured hookSpecificOutput.additionalContext + plain stdout); 7/7 smoke-test scenarios pass including recursive-trigger check (warn message contains no LOOP_TRIGGERS); follows-on hooks (Opp 5 commit reminder) target v6.12.1",
      "v6.11.2: workflow_enforcer UX fixes after live verification — stderr message rewritten to address the user, not Claude (UserPromptSubmit exit-2 blocks the prompt BEFORE the model runs, so any 'Action: emit X' addressed to Claude was dead text); stderr no longer quotes the matched LOOP_TRIGGERS phrase verbatim (Claude Code echoes blocked stderr into the next prompt's context, which would recursively re-trigger the block — observed live as nested blocks); messages now wrapped in <nav-workflow-block>...</nav-workflow-block> sentinel and the hook strips sentinel-wrapped sections from incoming prompts before matching, breaking the recursion loop; soft-warn stdout output is suppressed when the block fires (was leaking the trigger phrase via the 'LOOP MODE TRIGGER DETECTED' warning line); new user-actionable recovery instructions in the block message — three explicit options the user can take, none of which require the assistant to run; pitfall captured in mem-034 — 'UserPromptSubmit exit 2 bypasses the model + recursive-block via echoed trigger phrase'; 3/3 smoke-test scenarios pass including the explicit recursive-block case (re-feed block message → exit 0, sentinel stripped)",
      "v6.11.1: Phase 2 lifecycle hook (TASK-38) — first BLOCKING hook in Navigator; hooks/workflow_enforcer.py upgraded from soft-warn (exit 0) to hard-block (exit 2) when ALL three conditions match: (a) prompt contains a Loop Mode trigger ('run until done', 'do all', etc.), (b) .agent/.nav-workflow-state.json shows prior-turn check_shown=false, (c) workflow_enforcer_hook.strict_block=true (default); stderr message tells Claude exactly why it was blocked and how to recover (emit WORKFLOW CHECK then continue); missing state file falls back to soft-warn (Phase 1 projects unaffected); opt-out via strict_block=false; gated on Opp 2's state writer shipped in v6.11.0 — block fires only when state file empirically confirms violation, keeping false-positive rate near zero; 5/5 smoke-test scenarios pass; closes the 'model skips WORKFLOW CHECK ~30% of the time' gap that motivated the whole TASK-38 roadmap; architectural precedent: Navigator hooks may now block, but only when a deterministic state file confirms the violation occurred",
      "v6.11.0: Phase 1 lifecycle hooks (TASK-38) — three new silent side-effect hooks complete the v6.11 hook-migration roadmap; hooks/nav_task_graph_sync.py auto-upserts .agent/tasks/TASK-*.md writes into the knowledge graph via task_to_graph.py (Opp 4 — replaces the soft 'sync to graph' rule); hooks/nav_workflow_state.py fires on Stop, records check_shown/nav_status_shown/loop_phase to .agent/.nav-workflow-state.json (Opp 2 — silent infrastructure for the Phase 2 blocking workflow_enforcer); hooks/nav_profile_sync.py fires on Write to .user-profile.json, diffs corrections array against last_synced_count, runs correction_to_memory.py only when the array grew (Opp 3 — idempotent via .nav-profile-sync-state.json); zero injected tokens, pure correctness gains; all three opt-out via {hook}_hook.enabled: false; reuses task_to_graph.py + correction_to_memory.py existing CLIs; Q1 verified — add_node assigns by node_id, effectively upsert (no duplicates on rerun); all 11 settings_merger tests still pass; built on the v6.10.3 hardened merger surface",
      "v6.10.3: settings_merger safety pass — atomic writes (tempfile + os.replace, no partial-write corruption), --dry-run mode, stderr warning for non-list incoming hooks; nav-init Step 6 now detects foreign hooks pre-merge, surfaces them, and asks the user via AskUserQuestion before proceeding; both nav-init and nav-upgrade write timestamped backups (.pre-nav-init.{ts}, .pre-upgrade.{ts}) instead of a single overwriting .backup; new test_settings_merger.py covers 11 cases (fresh install, preserves user same/different event, idempotent rerun, dedupe, top-level keys, invalid JSON aborts, empty file aborts, non-list skip warning, dry-run no write, atomic write under failure) — all pass in <10ms; no new features, just hardening before TASK-38 widens the hook surface in v6.11",
      "v6.10.2: Auto-updater fix - SessionStart auto-update now refreshes the marketplace cache before running plugin update (Claude Code does not auto-refresh, so updates silently no-op when cache is stale); uses qualified plugin name navigator@navigator-marketplace instead of unqualified navigator (which Claude Code rejects with 'Plugin not found'); get_current_version parses Claude Code's multi-line plugin list output correctly (version is on a separate indented line from the plugin name); end-to-end verified - auto-updater now reports accurate status",
      "v6.10.1: Bug fixes for code generators + hook filename - frontend-component template no longer leaves bare interface identifier (PROPS_INTERFACE placeholder split into PROPS_INTERFACE_BLOCK for the interface body and PROPS_INTERFACE for the type reference); backend-endpoint template no longer leaks unevaluated JS ternary into generated routes (MIDDLEWARE_CHAIN replaced with pre-computed MIDDLEWARE_BLOCK); hooks/monitor-tokens.py renamed to hooks/token_monitor.py for naming consistency with other hooks (workflow_enforcer, nav_session_start, etc.) and to match the in-tree settings template; nav-loop test_exit_gate.test_empty_dict assertion synced with TOTAL_INDICATORS=6 (was stale at 5)",
      "v6.10.0: PreCompact + PostCompact hooks for compact-resilient markers - new hooks/nav_pre_compact.py writes .agent/.context-markers/before-compact-{manual,auto}-{ts}.md before any compact (fires on both manual /compact AND silent auto-compact, closing the data-loss window users previously had); hooks/nav_post_compact.py appends Claude Code's official compact_summary to that marker after compact completes; nav-compact skill Step 0 detects the hook and skips manual marker creation when installed (single source of truth); reuses skills/nav-marker/functions/marker_compressor.py heuristic algorithm + nav_session_start.py utilities; opt-out via compact_hook.enabled: false; fully backward compatible - skill falls back to legacy manual marker flow when hook absent; ~35k tokens saved per session start (v6.9.0) PLUS zero state loss across compacts (v6.10.0) = closed session lifecycle loop",
      "v6.9.0: SessionStart hook for zero-Read context injection - new hooks/nav_session_start.py emits navigator+marker+config+graph+profile+tasks payload via Claude Code's SessionStart additionalContext, eliminating ~6 Read calls per session start (~35k tokens saved per session); nav-start adds Step 0 sentinel detection for fast-path rendering; new settings_merger.py provides idempotent .claude/settings.json merging that preserves user-defined hooks; templates fix CLAUDE_PROJECT_ROOT (non-existent) → CLAUDE_PROJECT_DIR (actual CC env var); opt-out via session_start_hook.enabled: false; fully backward compatible - skill falls back to Read-based path when sentinel absent",
      "v6.8.0: nav-simplify ROI scoring (TASK-37 implementation) - cost/benefit gate now ships; simplification.scoring.mode='roi' opts in to ROI-based file gating (skip/suggest/apply); new cost_analyzer.py adds touch_lines/file_loc/recency/import_refs cost signals; benefit composed of issue_density + severity_impact + active_diff; backward compatible (complexity_score unchanged, default mode stays 'complexity'); 20 unit tests cover scoring math and gate logic",
      "v6.7.0: Release workflow hardening + nav-simplify ROI design - Replaced softprops/action-gh-release@v2 with native gh release create (uses runner-provided GitHub CLI, closes the last Node.js 20 deprecation warning); design pass for nav-simplify complexity-cost scoring captured in TASK-37 (cost/benefit ROI gate to prevent churn-for-churn's-sake simplifications, opt-in via simplification.scoring.mode)",
      "v6.6.0: Release hygiene + Loop Mode flexibility - GitHub Actions bumped to checkout@v5 and softprops/action-gh-release@v2 (Node.js 24 ready, ahead of June 2026 deprecation); iteration_approval='periodic' cadence now parameterized via loop_mode.periodic_interval (default 3, configurable for overnight runs); nav-multi documents branch-per-run convention (nav-multi/{SESSION_ID}) for parallel workflow safety",
      "v6.5.0: Execution-layer parity completion - new execution_to_graph.py mirrors research_to_graph.py; all 5 code-writing skills (frontend-component, backend-endpoint, database-migration, backend-test, frontend-test) emit execution_summary JSON for graph ingestion; Phase 0 (knowledge graph check) added as Step 0 in code-writing skills; code_analyzer.py auto-detects indent unit (fixes 4-space false positives); backend-test and frontend-test expanded from stubs to working skills with Phase 0 + framework detection + generation + verification + summary",
      "v6.4.0: Execution-layer parity pass - workflow_enforcer hook wired (was dead code); test skill trigger phrases ('add test', 'test this', 'test this component') now route correctly; nav-simplify detects autonomous context and skips when auto_apply=false instead of pausing; nav-loop phase_detector/exit_gate share TOTAL_INDICATORS=6 / COMPLETE_THRESHOLD=4 constants; stagnation_detector --autonomous flag emits AUTO-DIVERSIFY instead of PAUSE; nav-multi SESSION_ID appends PID to prevent collisions; 12 new execution-layer concept aliases (execution, implementation, autonomous, verify, orchestration, etc.); $SKILL_BASE_DIR removed from nav-simplify",
      "v6.3.0: Structured research output + autonomous loop mode - navigator-research agent emits research_findings JSON ingested via research_to_graph.py; Loop Mode adds iteration_approval + never_pause_on_stagnation for overnight runs; new ANTI-PATTERN #9 (Context Flooding); 4 nav-graph reliability fixes (memory ID collision, file backing, concept aliases, batch I/O)",
      "v6.1.0: Multi-Agent Production - parallel Claude agents with visual dashboard; nav-multi skill for natural language trigger; 5 role templates (orchestrator, implementer, tester, reviewer, documenter); reliability fixes for research tasks",
      "v6.0.0: Project Knowledge Graph - unified search across tasks, SOPs, system docs; experiential memory (patterns, pitfalls, decisions, learnings); auto-surfaces relevant context on session start",
      "v5.9.0: Workflow Enforcement - mandatory WORKFLOW CHECK block, Loop/Task Mode detection, complexity scoring, hook-based enforcement",
      "v5.8.0: Auto-Update Project Sync - auto-update now syncs project config, version drift detection, restart prompt after mid-session updates",
      "v5.7.0: Feature Management - nav-features skill for viewing/toggling features, first-session feature display on install/update",
      "v5.6.0: Task Mode - unified workflow orchestration, auto-detects complexity, defers to skills or provides phase guidance (nav-task-mode skill)",
      "v5.5.0: Auto-Update on Session Start - automatic plugin updates when newer version detected, zero friction for daily releases",
      "v5.4.0: Code Simplification Integration - nav-simplify skill, Multi-Claude simplifier role, autonomous completion integration, Loop Mode VERIFY phase",
      "v5.3.0: Task Verification Enhancement - Verify/Done sections, verify_extractor.py, multi-Claude Review integration",
      "v5.2.0: 'Finish What You Start' positioning - README rewrite, benefit-first documentation",
      "v5.1.0: Loop Mode - structured completion signals, dual-condition exit gates, stagnation detection (nav-loop skill)",
      "v5.0.0: Theory of Mind features - nav-profile, nav-diagnose, verification checkpoints",
      "v4.7.0: Interactive onboarding skill (nav-onboard) with hands-on learning",
      "v4.6.0: Native agents, token monitoring hooks, architecture optimization",
      "Added retry logic, timeout monitoring, state persistence, and workflow resume",
      "New scripts: sub-claude-monitor.sh, resume-workflow.sh",
      "Enhanced marker verification with central logging",
      "v4.3.1: Fixed template drift and professional pre-release upgrade flow",
      "nav-update-claude now fetches templates from GitHub (version-matched)",
      "nav-upgrade presents interactive pre-release choice",
      "Zero template drift - CLAUDE.md always matches plugin version",
      "v4.3.0: Multi-Claude agentic workflow automation (experimental)",
      "Added automated multi-Claude orchestration scripts for parallel execution",
      "Task agents enabled in sub-Claude phases for 60-80% token savings",
      "Failure reporting and recovery guidance for sub-Claude sessions",
      "v4.0.0: Major transformation - Tool to complete framework",
      "Added comprehensive education layer (learning guides, interactive examples, decision frameworks)",
      "Philosophical foundation documented (context efficiency manifesto, patterns, anti-patterns)",
      "Real metrics validation (nav-stats skill with efficiency scoring)",
      "v3.0.0: Removed all slash commands (/nav:*)",
      "Use natural language: 'Start my Navigator session'"
    ]
  },
  "plugins": [
    {
      "name": "navigator",
      "source": "./"
    }
  ]
}