SethGammon/map

/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: "Index not found. Run node scripts/map-index.js --generate first."
• Binary or unsupported files: Silently skipped. Only files with recognized language extensions are indexed.
• Very large repos (10K+ files): The walker is iterative (stack-based), not recursive. No stack overflow risk. May take 5-10 seconds on first run.
• Windows paths: All stored paths use forward slashes for cross-platform consistency.

Exit Protocol

After generation:

Index written: <path>
  <file count> files, <edge count> dependency links
  <route count> routes, <verification command count> verification commands

After query:

Results for "<terms>" (<count> matches):
  Score  Role        Path
  -----------------------------------------------
  <results>

After stats: print the full statistics block.

After slice: output the formatted slice block ready for injection.

After stale check:

Map index is current.

or:

Map index is stale.
Changed: <paths>
Added: <paths>
Removed: <paths>

Reversibility: green — delete .planning/map/ to remove all generated artifacts; no source files modified.