---
name: pan-map
description: "Topical: bootstrap or refresh Overdeck codebase map files for project orientation before planning"
---

# Overdeck Codebase Map

Use this skill when a project needs durable orientation files before or during planning. There is no pan map CLI verb; the deliverable is committed markdown under `.overdeck/context/codebase/`.

## Goal

Create or refresh these four files:

- `.overdeck/context/codebase/architecture.md` — subsystems, entry points, data flow, key directories.
- `.overdeck/context/codebase/conventions.md` — naming, style, test placement, idioms agents must imitate.
- `.overdeck/context/codebase/concerns.md` — cross-cutting traps, async-only rules, known footguns, hazard list.
- `.overdeck/context/codebase/stack.md` — languages, frameworks, package manager, build/test commands, versions.

Each file should be an orientation digest, not full documentation:

- Keep each file to roughly 150 lines or fewer.
- End each file with exactly one `<!-- last-verified: YYYY-MM-DD -->` line. The line holds only the date, never issue ids or other text; provenance belongs in commit messages. `npm run lint:last-verified` fails any other form. A union merge of concerns.md can leave a second one mid-file; delete it.
- Prefer stable facts and conclusions over broad file listings.
- Correct a stale statement whenever you find one, and leave the date unchanged. Change the `last-verified` date only when you re-verify the whole file with this workflow, so parallel PRs do not all edit the same line.

## Workflow

1. Read existing `.overdeck/context/codebase/` files if present.
2. Explore only enough code to confirm architecture, conventions, concerns, and stack.
3. Write or refresh all four files together so they stay internally consistent.
4. Commit the map with the project changes that introduced or refreshed it.

Planning agents consume these files first and refresh them during discovery when they find stale content.