map
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.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 931
- Forks
- 84
01 前言 Front Matter
- 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.
- auto-trigger
- false
- last-updated
- 1774742400000
- user-invocable
- true
- trigger_keywords
- [ "map", "index codebase", "codebase map", "structural index", "scan codebase", "map stats", "map query" ]
03 SKILL.md 正文
/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:
- Walks the project tree (respects
.gitignore, skipsnode_modules,dist, etc.) - Extracts exports, imports, and symbols from each source file
- Infers a role for each file (component, hook, store, route, test, config, etc.)
- Builds a dependency graph from resolved import paths
- Records per-file SHA-256 hashes plus a whole-index source signature
- Extracts route-like paths and package verification scripts
- 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:
- Run
node scripts/map-index.js --slice "<scope terms>" --max-files 15 - 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 ===
- 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:
- Before spawning each wave, Fleet checks if
.planning/map/index.jsonexists - If it exists: Fleet runs a slice scoped to each agent's assigned domain
- The generated slice is prepended to the agent's context alongside CLAUDE.md and rules-summary.md
- If the index does not exist: Fleet proceeds without a map slice (no error)
Context injection order:
- CLAUDE.md content
.claude/agent-context/rules-summary.md- Map slice (scoped to agent's domain/direction)
- Campaign-specific direction and scope
- 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 viamkdirSync({ recursive: true }).- Index file missing when querying: Error message: "Index not found. Run
node scripts/map-index.js --generatefirst." - 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.
04 同仓库更多 Skills
workspace
Multi-repo campaign coordinator. Same lifecycle as fleet -- scope claims, discovery relay, wave-based execution -- but the unit of work is a repo, not a file. Coordinates campaigns across repositories with shared context.
wiki
Markdown-first knowledge base where the LLM acts as librarian. Ingests raw sources, compiles and interlinks topic files, self-maintains an index. No vector DB or embeddings required -- uses LLM-native navigation over structured markdown up to ~400K words.
watch
File sentinel that monitors the working directory for changes and marker comments, then auto-triggers appropriate skills. Poll-based via git diff against the last scan commit. Writes intake items for batch processing and routes marker actions through /do. Use for automatic reactions to file changes; do NOT use for one-off inspection or tasks needing human judgment per file.
verify
Self-test the Citadel hook pipeline from within a live session. Exercises real tool calls (Write, Edit, Bash, Read) and checks that hooks fired, telemetry accumulated, and no errors occurred. Reports HOOK HEALTH: PASS or HOOK HEALTH: FAIL with a per-hook breakdown.
unharness
Safely leave Citadel using the active adoption receipt. Produces a no-write, reviewable plan, preserves a portable archive, removes only exact owned material, and reports modified or externally registered surfaces as retained or unknown. Legacy installs must be imported before exact leave is claimed.
triage
GitHub issue and PR investigator. Pulls open issues/PRs, classifies them, searches the codebase for root cause or reviews contributed code, proposes fixes with file:line references, and optionally implements fixes. Use for investigating GitHub issues and reviewing PRs; do NOT use for general code review unrelated to GitHub issues.