Context Navigator

Context Navigator

Context Navigator is an index system skill for Markdown-heavy workspaces. It can create a lightweight map for a messy folder, read an existing map without wasting context, validate index structure, and keep indexes current as the workspace grows.

The core promise: make folders AI-readable without turning every task into a recursive scan.

First Gate: Explicit Use and File Changes

If the user explicitly says to use this skill and the request may create, update, move, or delete files, do not start editing immediately.

First provide a concise plan that states:

• the chosen mode: Navigate, Bootstrap, Maintain, or Validate
• the workspace scope that will be touched
• the likely files or directories to inspect
• the likely files to create or update
• the validation command or review check to run

Then wait for the user's confirmation before modifying files. If the user already confirmed the plan or says to proceed, continue. Pure read-only Navigate work does not need this extra confirmation.

Workflow

1. Choose a mode: Navigate, Bootstrap, Maintain, or Validate.
2. Locate the smallest relevant workspace scope.
3. Prefer existing entry files before reading body documents.
4. Open or inspect only enough files to understand durable structure.
5. Create, update, or validate indexes only for important long-term folders.
6. Report what was planned or changed, what was read, what was skipped, and what remains a gap.

Modes

Trigger Thresholds

Use Bootstrap only when at least one of these is true:

• the user explicitly asks to bootstrap, organize, index, or make a Markdown workspace AI-readable
• the workspace has no durable root entry and has several long-term Markdown areas
• a folder mixes current authority, decisions, notes, reports, or archive material and future agents would not know where to start
• agents have already needed manual file listings to understand the same area

Use Maintain only when an existing index system is present and at least one of these is true:

• a durable document was added, moved, renamed, deleted, or archived
• an authority source or preferred entry file changed
• an index links to a missing path
• a child folder grew enough to need its own index
• the index schema or required sections fail validation

Do not trigger for vague phrases like "this repo is messy" unless the user also asks for docs/index organization or the workspace is clearly Markdown-heavy.

Request Types

Non-Markdown and Code Repository Boundary

For code-heavy repositories, this skill is a docs navigation layer, not a replacement for source analysis.

Prefer native code entry points for implementation work:

• README.md, package manifests, build config, and test config
• source entry files, route definitions, public APIs, and type definitions
• existing architecture docs or docs/INDEX.md only when they exist and are relevant

Do not generate indexes for every source directory. Create or maintain a docs index only when the repository has durable Markdown documentation, architecture notes, decisions, specs, runbooks, or project docs that future agents need to route through.

Index Priority

Prefer the smallest index that can route the task.

If several entry points exist, pick the one that most directly matches the user's wording. Do not widen the search just because more documentation exists.

Reading Protocol

1. Read the entry index and extract candidate paths, authority sources, and routing rules.
2. Select 1-3 candidate body files that directly answer the task.
3. Read those files in full.
4. If the answer is still under-supported, continue one level along the indexes.
5. Stop once the user-facing answer has enough evidence.

Bootstrap Protocol

When asked to create an index system, read references/bootstrap-workflow.md and references/index-template.md.

Default outputs:

• root CONTEXT.md for a workspace-level map, unless a root README.md or INDEX.md is clearly the better entry point
• INDEX.md for durable domains, docs folders, decision logs, or recurring note/report folders
• a final report listing created indexes, skipped folders, and remaining gaps

Do not index everything. Skip dependency folders, build outputs, generated exports, hidden internals, caches, temporary folders, and archives unless the user explicitly includes them.

Maintain Protocol

When asked to maintain indexes, read references/maintenance-rules.md.

Default behavior:

• identify the nearest existing CONTEXT.md, INDEX.md, or established README.md
• inspect only affected paths and their immediate parent index
• update routing, authority paths, gaps, and maintenance notes for durable doc changes
• remove or mark stale links when files moved or were archived
• run scripts/validate_indexes.py <workspace-root> when the workspace uses the schema

Never rebuild all indexes just because one route is stale.

Validation Protocol

When asked to validate or after Bootstrap/Maintain, run:

python scripts/validate_indexes.py <workspace-root>

The validator checks Context Navigator index files for required frontmatter, required sections, and broken local links. Treat failures as actionable schema issues. If fixing them would modify files and the user has not confirmed a change plan, present the plan first.

Report Format

When this skill is used for discovery, tracing, or synthesis, include a compact source note:

Read indexes: `CONTEXT.md`, `docs/INDEX.md`
Read full files: `docs/architecture.md`
Not expanded: `archive/`, unrelated app docs
Gaps: `docs/decisions/` has no `INDEX.md`

For tiny tasks, use a sentence instead of a block.

Guardrails

• Do not recursively read all Markdown files as the first move.
• Do not treat a file listing as an index unless no index exists.
• Do not build embeddings, a vector store, a database, or a custom search tool for the first pass.
• Do not open every related document merely because it is nearby.
• Do not cite "the docs" vaguely; name the indexes and full files you actually read.
• Do not convert temporary search results into authority. Authority comes from indexes or documents those indexes point to.

Creating Indexes

When asked to create or review indexes, read references/index-template.md. A durable index should explain:

• what the scope covers
• what is outside the scope
• where authority sources live
• how common tasks should route
• what not to read first
• how the index should be maintained

New or substantially rewritten indexes should use the context-navigator/v1 frontmatter schema from references/index-template.md. Existing legacy indexes can be maintained without bulk migration unless validation or user request requires schema adoption.

Reference Routing

Adjacent Patterns

• RAG and embeddings retrieve chunks; Context Navigator decides what source path the agent should follow.
• Codebase scanners generate maps; Context Navigator teaches the agent how to use and maintain maps.
• Obsidian links connect notes; Context Navigator defines what an AI should read first.
• AGENTS.md gives agent instructions; Context Navigator gives documentation navigation discipline.
• Subagents may help with large read-only audits, but this portable skill does not hide any required subagent path. If a local installation adds agents, document when to call them in the local wrapper or project instructions.