Map Codebase
Invoke as /afk:map-codebase. Use it when you want a durable, reusable map of how an existing area of the codebase works as-is — "map the codebase", "document how auth is wired today", "survey this module" — persisted to brain/codebase/ for future sessions.
What it does
Map Codebase turns a read of one existing area into a durable, prescription-free note at brain/codebase/<area>.md, pinned to the git commit it was read at. The invariant it protects is document what IS, not what SHOULD BE: it records where code lives, how it flows, and the gotchas it carries, but recommends nothing. That neutrality is the whole point — an opinionated map serves one task and rots, while a descriptive one is reusable by every future task.
- Grounds in the brain first, then dispatches bounded read-only scouts in parallel (the same pattern
grilluses): a locator for where the area lives, an analyzer for how it flows, and a pattern scout for concrete conventions to mimic — each carrying the documentarian constraint verbatim. - Synthesizes and verifies the load-bearing claims against the actual files itself before they enter the map; a scout report is a lead, not a fact.
- Captures a commit pin (
git rev-parse --short HEAD, branch, covered paths) as the note's last line so a future reader can tell whether the map is stale. - Writes one area per file (
# <Area>, summary line, then## Map,## How it works,## Patterns in use,## Gotchas observed), deferring the write conventions to the brain skill.
It is the internal counterpart to research, which writes brain/sources/ for external prior art; map-codebase is internal-only (brain/codebase/). It is the deliberate producer of brain/codebase/ notes — reflect maintains them opportunistically between mapping passes. Once written, grill and the implement orchestrator read the map as observed ground before forming questions and contracts, scoping their own reading to the gaps and carrying its gotchas forward.