map git:20260709.74ebd99A

Immutable. This exact content is served forever at /api/v1/blob/320c844d12227ff7.

---
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. This skill produces that
orientation as a durable, shared file — not ephemeral context that dies with
the session.

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

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.
- **Lean or it's ignored.** The litmus test is non-negotiable — bloat is the
  documented reason agent files stop being followed. Cut ruthlessly.
- **Never write or commit unprompted.** The output modifies the user's repo;
  draft → approve → write, and commit only on an explicit yes.
- **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.