cartography

name	cartography
description	Repository understanding and hierarchical codemap generation. Use when mapping an unfamiliar codebase, creating repository documentation, or refreshing codemap.md files after structural changes.

Cartography Skill

You help users understand and map repositories by creating and maintaining hierarchical codemap.md files.

This skill is the preferred user-facing surface for repository mapping. Treat pantheon_repo_map and pantheon_code_map as low-level building blocks used by this workflow, not as dedicated slash-command UX.

The bundled script scripts/cartographer.mjs provides upstream-style incremental state tracking. In this pi port, the state file lives at .pi/cartography.json.

When to Use

• User asks to understand or map a repository
• User wants codebase documentation or an architecture atlas
• Starting work on an unfamiliar codebase
• Structural changes have made existing codemaps stale

Workflow

Step 1: Check existing state

First inspect whether the repository already has:

• .pi/cartography.json
• a root codemap.md
• directory-level codemap.md files
• an AGENTS.md section that points future agents at the codemap

If .pi/cartography.json exists, prefer incremental refreshes over full rewrites.

Step 2: Initialize if needed

If .pi/cartography.json does not exist, initialize cartography state with the bundled script.

Resolve the script path relative to this skill directory and run a command like:

node ./scripts/cartographer.mjs init \
  --root . \
  --include "src/**/*.ts" \
  --include "extensions/**/*.ts" \
  --include "bin/*.mjs" \
  --include "package.json" \
  --exclude "tests/**" \
  --exclude "**/*.test.*" \
  --exclude "node_modules/**" \
  --exclude "dist/**"

This creates:

• .pi/cartography.json
• a root codemap.md atlas template
• empty codemap.md files for tracked folders
• an idempotent AGENTS.md ## Repository Map section if it is missing

Step 3: Scope the mapping surface

Map core code and configuration only.

Prefer including:

• source directories (src/, app/, packages/*/src/, extensions/, bin/)
• key manifests and config (package.json, tsconfig.json, pyproject.toml, Cargo.toml, go.mod)
• major integration boundaries and entrypoints

Exclude unless the user explicitly asks otherwise:

• tests (tests/, __tests__/, *.test.*, *.spec.*)
• docs-only areas (docs/, most *.md files besides codemaps/AGENTS/README when relevant)
• generated/build output (dist/, build/, coverage/, .next/, target/)
• dependencies (node_modules/)
• translations, snapshots, fixtures, and vendored assets

Step 4: Detect changes when state exists

If .pi/cartography.json already exists, run the bundled script before editing codemaps:

node ./scripts/cartographer.mjs changes --root .

Use the reported affected folders to scope your refresh. The workflow should also ensure the root atlas template and AGENTS.md repository-map section still exist. After updating codemaps, persist the new snapshot:

node ./scripts/cartographer.mjs update --root .

Step 5: Gather repository signals

Use the low-level mapping primitives:

1. pantheon_repo_map

   • gather tree shape
   • identify key files and top directories
   • understand repository boundaries

2. pantheon_code_map

   • gather entrypoints
   • inspect import edges and hotspots
   • identify important symbols, directory roles, and cycles

Also use direct file reads for the most important entrypoints before writing codemaps.

Step 6: Create or update directory codemaps

For each important mapped directory, create or refresh that directory's codemap.md.

Keep each directory codemap concise and technical. Prefer sections like:

• Responsibility
• Key Files
• Design / Patterns
• Flow
• Integration Points

Document:

• what the directory is for
• how control/data moves through it
• what other modules depend on it
• what patterns or boundaries are important

Step 7: Finalize the root atlas

Create or update the root codemap.md as the master entry point.

It should usually include:

• repository purpose / responsibility
• system entry points
• a directory map table linking to subdirectory codemap.md files
• key architecture notes and integration boundaries

Prefer relative links to sub-maps.

Step 8: Register the codemap in AGENTS.md

Ensure AGENTS.md in the repo root contains a ## Repository Map section pointing agents to codemap.md.

If the section already exists, do not duplicate it.

Recommended section:

## Repository Map

A full codemap is available at `codemap.md` in the project root.

Before working on any task, read `codemap.md` to understand:
- project architecture and entry points
- directory responsibilities and design patterns
- data flow and integration points between modules

For deep work on a specific folder, also read that folder's `codemap.md`.

Codemap Quality Bar

Use precise technical language.

Capture:

• Responsibility — what architectural role the directory/module plays
• Patterns — factories, adapters, registries, middleware, orchestration layers, etc.
• Flow — how requests, data, or control move through the area
• Integration points — imports, consumers, adapters, hooks, APIs, CLIs, background jobs

Avoid:

• line-by-line paraphrase
• exhaustive file dumps
• vague summaries like “handles stuff” or “contains utilities”

Output Shape

Typical outputs from this skill are:

• .pi/cartography.json
• root codemap.md
• selected directory codemap.md files
• optional AGENTS.md repository-map section update

Be incremental and idempotent: refresh stale maps, preserve useful existing material, and avoid duplicate sections.