Cartographer
Goal
Produce a durable, reviewable map of the repo that helps humans and agents understand structure quickly, without inventing architecture or behavior.
Primary outputs:
Tree.txt(curated, deterministic tree)docs/PROJECT_MAP.md(index linking key artifacts)
This skill maps what exists. It does not decide how the system should work.
Non-negotiables
- Do not write outputs into
.codex/(runtime only). - Do not modify application code.
- Prefer deterministic output (stable ordering, stable excludes).
- Do not invent architecture, intent, or rules.
- If artifacts already exist, update them in place with minimal diff.
Inputs
- Target repo root (explicit or inferred)
- Default exclude rules (defined in script)
- Optional flags passed to the script:
--tree--map--all--max-depth <n>
Outputs
<repo>/Tree.txt<repo>/docs/PROJECT_MAP.md
Optional (future extensions, not required):
<repo>/docs/diagrams/system/*- Colocated
*.state-machine.md
When to use
- After significant repo growth or restructuring
- When onboarding new contributors or agents
- Before or after cross-cutting refactors
- Prior to publishing or reviewing governance artifacts
Do not use as a substitute for:
- ARCHITECTURE.md
- system diagrams
- decision records
Workflow
1) Preconditions (read-only)
- Identify repo root.
- Confirm the repo is not
.codex/itself. - Check whether
docs/exists (create only if needed for outputs).
2) Run the cartographer script
Execute from repo root or with an explicit path:
python3 scripts/project_ops/cartographer.py --all