/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.