| name | repo-map |
| description | Build an evidence-based map of an unfamiliar or large/legacy repository before you change it. Gathers cheap, deterministic CLI signals (git-history territory, a dependency graph, contributor history) OUTSIDE the model's context window, then has the agent interpret the evidence into one short, decision-oriented artifact — docs/architecture/repo-map.md (modules, entry points, dependency directions + cycles, coupling hotspots, sensitive areas / blast radius, who-to-ask, and explicit unknowns). Read-only: never modifies source. Detects the stack (JS/TS, Python) to pick the right dependency tool. Trigger phrases: "map this repo", "understand this codebase", "onboard me to this legacy project", "where is it risky to change", "/repo-map".
|
| argument-hint | [<subdir>] [--since <window>] [--out <path>] [--verify] |
| allowed-tools | ["Read","Write","Edit","Bash","Grep","Glob","AskUserQuestion","Agent","Skill"] |
/repo-map — Wide-Scan a repo into an evidence-based project map
This skill is for the brownfield moment: you (or an agent) land in a large or
unfamiliar codebase and need to know what's here, what's load-bearing, what's
active, and where a change is risky — before touching anything. The naive move
("agent, read the whole repo and explain the architecture") fails twice: it
doesn't fit a context window, and "lots of context" is not "good understanding"
(you get a flat, priority-less summary).
The method is Wide Scan: run cheap, deterministic CLI tools to collect
signals (they reduce noise outside the context window), then ask the agent to
interpret the evidence — not to read everything. The deliverable is one short,
decision-oriented artifact, docs/architecture/repo-map.md.
Inspired by the 2026 "Wide Scan" practice for AI-assisted legacy work; written
fresh for ai-devkit. The companion "Deep Focus" (single-feature trace + test
gaps + blast radius) is out of v1 — see Notes.
Read references/repo-map-schema.md (the locked artifact shape) and
references/signal-recipes.md (the per-stack CLI commands) before writing the map.
When to use, when to skip
Use when:
- You're onboarding to an existing/legacy repo and need a fast, honest mental model.
- You're about to refactor or add a feature and want the blast radius first.
- You want to decide where per-module
AGENTS.md / ownership boundaries belong
(feeds /agents-md).
Skip when:
- It's a small/greenfield project you already understand — a map is overhead.
- You need a feature-level deep dive (one data flow end-to-end) — that's Deep
Focus, not v1 here; use
/research or trace it manually.
- You want product scope/vision — that's
/discover + /product-spec.
Relationship to other skills & rules
/setup — provides the docs/architecture/ home the map is written to. If
docs/ is absent, this skill offers to delegate to /setup (Step 0)./implement — its references/runner-detection.md is the source of the
stack-marker → tool mapping this skill reuses for dependency tooling./research — downstream. The map's "sensitive areas / unknowns" are good
inputs to a focused research pass; a repo-map often precedes /research./agents-md — downstream. The map's module/ownership boundaries inform where
a per-module AGENTS.md earns its place (don't split by folder count — split by
ownership + real need).~/.claude/rules/ (read-only) — security.md governs the analysis itself:
this skill runs only read-only inspection commands and never executes the
target project's code. Do not modify rules.
Output language
The map and all comments are written in English (global policy,
~/.claude/CLAUDE.md §13). User-facing prompts may follow the user's language.
Initial Response
- Args given (
/repo-map src --since 18.months --verify): capture; jump to Step 0.
- No args: proceed to Step 0 and confirm scope interactively in Step 1.
Process
Step 0: Preconditions
git rev-parse --is-inside-work-tree 2>/dev/null
ls docs/architecture/ 2>/dev/null
- Not a git repo → much of the signal (territory, contributors) is unavailable;
tell the user and STOP (or continue structure-only if they insist).
docs/ absent → offer to delegate to /setup via the Skill tool; continue on return.- Detect the stack and its dependency-graph tool per
references/signal-recipes.md.
If the tool is missing, print the install hint and continue without auto-installing
(mirrors /e2e-run); the structure signal degrades to import-grep, noted as a gap.
Step 1: Scope (confirm before doing work)
Resolve and confirm: target (subdir or repo root), history window
(default 12 months), output path (default docs/architecture/repo-map.md).
AskUserQuestion:
- question: "Map over → ?"
header: "Map scope"
options:
- label: "Yes (Recommended)"
description: "Wide-scan over the last ; write ."
- label: "Change scope"
description: "Adjust target subdir / history window / output path."
- label: "Cancel"
description: "Exit without analysis."
multiSelect: false
Step 2: Gather signals (3 read-only subagents, in parallel)
Spawn one Agent per signal in a single message (keeps bulky tool output out
of the main context — each returns structured findings only). Commands per
references/signal-recipes.md.
Small repo? The fan-out exists to keep a large repo's tool output out of
the context window. For a small/solo codebase (a few dozen files, low commit
count) just run the recipes directly — spawning three subagents is overhead with
no fidelity gain. Use judgment: fan out when the signals would be large.
- territory — git-history: top-N most-changed dirs/files over the window
(filter lockfiles / generated / snapshots), quarterly breakdown (permanent
center vs change-campaign), co-change pairs (hidden coupling).
- structure — the stack's dependency grapher: entry points, layers, import
direction, cycles, coupling metrics (afferent
Ca, efferent Ce,
instability = Ce/(Ca+Ce)). Output to markdown/JSON first, not images.
- contributors — git-history grouped by area, bot/AI-agent commits filtered
→ who carries knowledge of each area (who to ask before a change).
Step 3: Synthesize — interpret evidence, don't dump it
Combine the three signal sets into the map per references/repo-map-schema.md.
Every claim cites its evidence (a commit, an import path, a file:line, a
co-change count). Record uncertainty explicitly as unknown / needs verification — static signals can't see runtime coupling (DI, dynamic imports,
feature flags, codegen, webhooks).
If --verify: confirm the load-bearing structural claims (e.g. "only here",
"always via X", call-site counts) with ast-grep, and confirm every ast-grep
zero with a plain grep (a wrong pattern returns a misleading zero). Reserve
this for the few claims a decision will rest on — it's not a full pass.
Step 4: Write the map
Write repo-map.md to the confirmed path. Collision handling (never clobber
silently): overwrite / write -v2 sibling / skip. Never modify source files —
this skill only reads.
Step 5: Hand off
═══════════════════════════════════════════════════════════
REPO MAPPED
═══════════════════════════════════════════════════════════
Target: <subdir | repo root> · window: <N months>
Stack: <js/ts | python | …> · dep tool: <name | grep-fallback>
Signals: territory · structure · contributors
Map: docs/architecture/repo-map.md
Unknowns: <count> open (need verification)
► Next: feed the map into /research (a flagged risk), /implement (blast radius),
or /agents-md (where a per-module AGENTS.md earns its place).
═══════════════════════════════════════════════════════════
STOP. Do not start refactoring or modify any source.
Critical guardrails
- Read-only — never execute or modify the target code. Only inspection
commands (
git log, dependency graphers in report mode, rg, ast-grep).
The map is the sole written artifact.
- Evidence over guess. "A label without evidence is a guess." Every
classification (core / load-bearing / volatile / sensitive) cites its evidence;
what you can't prove is an explicit
unknown, never a confident assertion.
- Reduce noise, then interpret. CLI tools run outside the context window and
return condensed results; the agent interprets the smaller, better data — it
does not "read the whole repo".
- Confirm scope before working. Step 1 is a gate — no large analysis before
the user confirms target / window / output.
- Never auto-install. A missing dependency-graph tool → print the install
hint and degrade gracefully (import-grep), noting the gap. Don't install.
- The map is short and decision-oriented. Not an essay, not a chat dump — it
answers "what's important, connected, active, and risky?", with unknowns named.
Notes
- Why three signals. Territory (git) shows where work actually happens;
structure (graph) shows how modules depend and where cycles/hubs are; contributors
(git) shows who holds tacit knowledge. A folder tree answers "what's here?"; the
map answers "what's important, connected, active, and risky?".
- Deep Focus is v1-excluded. Tracing one feature end-to-end (data flow + test
gaps + blast radius → a research doc) is a separate, heavier mode — a future
/repo-map --deep or a /research code-mode, to avoid overlap.
- Extensibility. v1 dependency tooling covers JS/TS + Python; a new stack is a
recipe block in
references/signal-recipes.md (grapher + flags + output format) —
the Process is unchanged.
- Output location. Default
docs/architecture/repo-map.md (living — refine as
understanding grows). Point it elsewhere with --out if you prefer a point-in-time
snapshot under docs/analyzes/.
