git:20260710.47b8db6 to git:20260710.355dbf7

---

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

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

- **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:

```markdown

# 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, same as

every other skill here.

4. Note that `feature` and `bugfix` will now read this file at the start of

their runs — the map pays off downstream.

**Auto mode (under autopilot):** the draft→approve gate becomes

write-and-log — the map is written and stamped, the run's `log.md` records

what was generated and why, and committing still follows the run's charter.

On **REFRESH**: diff the map's claims against the current tree — flag sections

whose cited files moved, changed shape, or vanished; regenerate only those;

re-stamp. Don't rewrite what's still true.

## Guardrails

- **A wrong map is worse than none.** A confident-but-stale line actively

degrades the agent's reasoning. Every claim cites a file that exists; when

unsure, leave it out and say so.

- **Never write or commit unprompted.** The output modifies the user's repo;

draft → approve → write, and commit only on an explicit yes. (In auto

mode, the autopilot charter is the prompt — the write is logged, not asked.)

- **Navigate, don't index.** Keyless by design — grep/glob/read/LSP, no

embeddings to leak or go stale. Re-derived-but-fresh beats cached-but-wrong.

- **Evidence is a path.** No landmark, convention, or command without a locator

or the command itself. The map is a set of verifiable pointers, not prose.

- **Respect what's there.** An existing AGENTS.md/CLAUDE.md is updated, not

bulldozed; manual edits by the user are preserved.