# Map

Structural codebase index generator.

- Repository: https://github.com/SethGammon/Citadel (927 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add SethGammon/Citadel --skill map -g -a claude-code -y`
Codex: `npx skills add SethGammon/Citadel --skill map -g -a codex -y`
Cursor: `npx skills add SethGammon/Citadel --skill map -g -a cursor -y`
Gemini CLI: `npx skills add SethGammon/Citadel --skill map -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add SethGammon/Citadel`

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

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

The rest: https://github.com/SethGammon/Citadel/blob/HEAD/skills/map/SKILL.md