/map

name: map
license: MIT
description: >-
  Structural codebase index generator. Builds a compact JSON map of files,
  exports, imports, dependency graph, and roles. Queryable by keyword. Injected
  into fleet agents as context slices to reduce token usage on code navigation.
user-invocable: true
auto-trigger: false
trigger_keywords:
  - map
  - index codebase
  - codebase map
  - structural index
  - scan codebase
  - map stats
  - map query
last-updated: 2026-03-29

/map -- Codebase Intelligence

Orientation

Use `/map` when:

• Starting work on an unfamiliar codebase (build the index first)
• A fleet or archon campaign needs agents to know "what files matter for X"
• You want a quick structural overview (stats, roles, dependency graph)
• You need to find files related to a keyword without exploratory reads

Do not use `/map` for:

• Reading file contents (use Read)
• Searching for string patterns inside files (use Grep)
• Single-file edits where you already know the path

Commands

| Command | Behavior | |---|---| | `/map` | Generate or refresh the index (skips if cache is fresh) | | `/map --force` | Rebuild the index even if cache is fresh | | `/map query <terms>` | Search the index for files matching keywords | | `/map stats` | Print summary statistics (files, lines, languages, roles) | | `/map slice <terms>` | Output a compact context slice for agent injection | | `/map stale` | Detect added, changed, or removed indexed source files |

Protocol

Step 1: GENERATE INDEX

Run the index generator:

node scripts/map-index.js --generate --root .

Add `--force` if the user requested a fresh rebuild or if the index is stale.

The generator: 1. Walks the project tree (respects `.gitignore`, skips `node_modules`, `dist`, etc.) 2. Extracts exports, imports, and symbols from each source file 3. Infers a role for each file (component, hook, store, route, test, config, etc.) 4. Builds a dependency graph from resolved import paths 5. Records per-file SHA-256 hashes plus a whole-index source signature 6. Extracts route-like paths and package verification scripts 7. Writes the index to `.planning/map/index.json`

**Supported languages:** TypeScript, JavaScript, Python, Go, Rust.

**Cache behavior:** The index is cached for 5 minutes. Subsequent runs within that window exit immediately unless `--force` is passed.

If `.planning/map/` does not exist, the generator creates it automatically.

Step 2: QUERY (when user provides search terms)

node scripts/map-index.js --query "<terms>"

The query engine scores files by:

• Path match: +3 per term
• Export match: +5 per term
• Symbol match: +2 per term
• Role match: +1 per term

Results are sorted by score and capped at 20 files (configurable with `--max-files`). Output is budget-capped at 8000 characters to stay injection-safe.

Step 3: STATS (structural overview)

node scripts/map-index.js --stats

Outputs: file count, line count, export count, dependency edge count, route count, package script count, verification command count, breakdown by language, and breakdown by role.

Step 4: SLICE (agent context injection)

When another skill or orchestrator needs a map slice for agent injection:

1. Run `node scripts/map-index.js --slice "<scope terms>" --max-files 15` 2. Inject the generated compact block:

=== MAP SLICE: <terms> ===
Generated: <timestamp>
Verification: npm run test | npm run typecheck
<score> <role>  <path>  [<top exports>]  (<lines>L)
...
=== END MAP SLICE ===

3. The calling skill injects this block into the agent's prompt alongside CLAUDE.md and rules-summary.md

**Token budget:** A 15-file slice is typically 800-1200 tokens. This replaces 2000-5000 tokens of exploratory Glob/Grep results that agents would otherwise spend finding relevant files.

Step 5: STALENESS CHECK

Before injecting an existing map into a long-running campaign, run:

node scripts/map-index.js --stale

The command exits `0` when the map is current and `2` when indexed source files were added, changed, or removed. Refresh with:

node scripts/map-index.js --generate --force --root .

Fleet Integration

Fleet agents receive map slices automatically when `/map` index exists:

1. Before spawning each wave, Fleet checks if `.planning/map/index.json` exists 2. If it exists: Fleet runs a slice scoped to each agent's assigned domain 3. The generated slice is prepended to the agent's context alongside CLAUDE.md and rules-summary.md 4. If the index does not exist: Fleet proceeds without a map slice (no error)

**Context injection order:** 1. CLAUDE.md content 2. `.claude/agent-context/rules-summary.md` 3. **Map slice** (scoped to agent's domain/direction) 4. Campaign-specific direction and scope 5. Discovery briefs from previous waves

Contextual Gates

**Disclosure:** "Generating codebase map. Creates `.planning/map/index.json`." **Reversibility:** green — creates `.planning/map/index.json` only; undo by deleting `.planning/map/`. **Trust gates:**

• Any: generate index, query, stats, slice.

Quality Gates

• Index must generate without errors on any supported project
• Query must return results sorted by relevance score
• Stats output must be human-scannable in under 5 seconds
• Slice output must stay under 2000 tokens for a 15-file result
• Index must handle 100K+ line repos without hanging (iterative walker, no recursion limits)
• Cache must prevent redundant regeneration within the TTL window
• Stale checks must detect added, changed, and removed indexed source files
• Slice output must include relevant verification commands when package scripts exist

Fringe Cases

• **No source files found**: Generator writes an empty index (`fileCount: 0`). Query returns no results. Not an error.
• **`.planning/` does not exist**: Generator creates `.planning/map/` automatically via `mkdirSync({ recursive: true })`.
• **Index file missing when querying**: Error message: "I