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:

```bash
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)

```bash
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)

```bash
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:

```bash
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:

```bash
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: