/map

name: map
description: >-
  Codebase orientation for an unfamiliar or large repo — "map this before I
  work in it." Fans out read-only Explore sub-agents that navigate the code
  (keyless — grep/glob/read, no embeddings to go stale) along the order that
  matters: entry points, build/test/lint commands, architecture and key
  abstractions, conventions and gotchas, test layout. Distills the findings
  into a lean AGENTS.md at the repo root — the cross-tool standard file many
  agents auto-load — where every claim points to a real file and nothing
  survives that isn't load-bearing. Human-in-the-loop: it drafts, you approve,
  and it never writes or commits into your repo without an explicit yes. Stamps
  the map with date + commit so /map refresh regenerates only what went stale.
  Use before working in a repo you or the agent don't know — e.g. "/map",
  "/map the auth subsystem", "generate an AGENTS.md", "/map refresh". Run it
  upstream of feature or bugfix; for the end-of-session shipping gate use done.

map — orient the agent to an unfamiliar codebase

`/map` — map the whole repo into a lean AGENTS.md at its root `/map <subsystem>` — deep-map one area, into a scoped section `/map refresh` — re-check an existing map and update only what went stale

Answer one question: **what would a competent engineer need to know before touching this repo — and nothing more?** The strongest lever in agentic coding isn't a smarter model, it's better orientation: an agent that knows the entry points, the build commands, and the load-bearing conventions makes the right change; one that guesses edits the wrong layer.

Step 0 — Scope, and respect what exists

First, look before generating:

• **Existing agent files?** Check for `AGENTS.md`, `CLAUDE.md`, `.cursor/rules`,

`.github/copilot-instructions.md`. If one exists, this is a **REFRESH**, not a fresh write — read it, and update in place rather than duplicating. If a `CLAUDE.md` already carries the knowledge, offer to have `AGENTS.md` `@import` it instead of restating it. If the existing map carries a stamp and HEAD has moved past it, state the drift in one line when naming the mode — "map is N commits behind (touched: X, Y)" via `git rev-list --count` + `git diff --stat` over `<stamped-commit>..HEAD` — and offer the refresh unless this run already is one. A stamp that no longer resolves (rebase, shallow clone) is itself the staleness signal: report it and offer a fresh map. Staleness surfaces at every touch, never only when someone remembers `/map refresh`.

• **Size the repo** (`git ls-files | wc -l`, top-level layout) to scale the

fan-out: a small repo maps in one pass inline; a large or polyglot one gets the full parallel sweep below.

• **A subsystem argument** (`/map the payment flow`) narrows every step to that

area and produces a scoped section, not a whole-repo rewrite.

State which mode you picked (NEW / REFRESH / FOCUS) and why.

Step 1 — Fan out along the read-first order

Dispatch read-only **Explore** sub-agents — one per lens — navigating by `grep`/`glob`/`read` and following imports (no embeddings, no pre-index; always fresh). This is the order practitioners converge on; run the lenses concurrently:

1. **Entry points & structure** — how does execution start (`main`, routes, CLI, handlers)? Top-level module/package layout and what each directory is *for*. 2. **Build / test / lint commands** — the knowledge no amount of code-reading reveals cheaply: the exact commands, from `package.json` scripts, `Makefile`, `pyproject.toml`, CI config. This is the single highest-value section. 3. **Architecture & key abstractions** — the main entities/types, the layers and their boundaries, how data flows through, the 3–5 files that matter most. 4. **Conventions & gotchas** — patterns the repo follows that deviate from the language default; footguns; "don't touch X"; implicit invariants a newcomer would break. 5. **Tests & fixtures** — how tests are organized, where fixtures/factories live, the command that runs a single test.

**Lossless hand-off:** each sub-agent writes its full findings to `out/map/.work/<lens>.md` and returns a compact summary; you synthesize from the files, not the relay. **Every finding names a file path** — a landmark without a locator is a guess, and a guess in a map is worse than a blank.

Step 2 — Distill to a LEAN AGENTS.md

Now cut. A bloated agent file gets *ignored* — the failure this skill must not cause. For every candidate line apply the litmus test: **would removing it make the agent make a mistake?** If not, cut it. Keep:

• What can't be guessed from reading code (commands, non-obvious conventions,

gotchas, the "why" behind a structure).

Drop:

• Anything a `read` of the code trivially reveals, generic best-practices,

restated language docs, and prose where a file path would do.

Prefer signatures and paths over paragraphs. Target well under ~200 lines — shorter is stronger. Structure:

# AGENTS.md
<!-- mapped 2026-07-09 @ <commit sha> · regenerate with /map refresh -->

## What this is
<one paragraph: what the project does, its shape>

## Build, test, run
<the exact commands — the part no one can guess>

## Architecture
<layers, key abstractions, data flow — each with a file path>

## Conventions & gotchas
<the load-bearing, non-default rules; the footguns>

## Landmarks
<entry points, core files, where tests/fixtures live — as paths>

Step 3 — Approve, then write (never unprompted)

This file lands in **the user's repo**, so nothing is written without a yes:

1. Show the full drafted `AGENTS.md` in chat and invite edits — cuts as much as additions. 2. On approval, write it to the repo root (or update the existing file), stamped with today's `date +%F` and the current commit sha. 3. **Offer, don't perform, the commit** — draft a message per the repo's convention, but committing and pushing wait for an explicit yes, sa