home / skills / velcrafting / codex-skills / cartographer

cartographer skill

safe

This skill generates a deterministic project map (Tree.txt and docs/PROJECT_MAP.md) for a repository to aid quick understanding without altering code.

npx playbooks add skill velcrafting/codex-skills --skill cartographer

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.9 KB

---
name: cartographer
description: Generate a deterministic project map (Tree.txt + docs/PROJECT_MAP.md) for a repo. Use only when explicitly invoked.
metadata:
  short-description: Repo map generator
  mode: write
  idempotent: true
---

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

```sh
python3 scripts/project_ops/cartographer.py --all

Overview

This skill generates a deterministic, reviewable map of a codebase and creates two primary artifacts: Tree.txt and docs/PROJECT_MAP.md. It focuses on representing what already exists without inventing architecture, intent, or behavior. Use it only when explicitly invoked to update or create the map files.

How this skill works

The script inspects the project root, applies stable exclude rules, and produces a curated tree listing with stable ordering and depth limits. It then generates an indexed PROJECT_MAP.md that links to key artifacts and governance files found in the codebase. Existing Tree.txt or docs/PROJECT_MAP.md are updated in place with minimal diffs to preserve history.

When to use it

After significant growth or restructuring of the codebase
When onboarding new contributors or agents to make structure discoverable
Before or after cross-cutting refactors to document current layout
Prior to publishing or reviewing governance and artifact inventories

Best practices

Run from the project root or pass an explicit path to avoid ambiguous results
Prefer deterministic flags (e.g., --all, --max-depth) to produce stable output
Do not modify application code; operate in read-only mode except for the two output files
Keep exclude rules consistent across runs to minimize diffs
Update existing Tree.txt and docs/PROJECT_MAP.md in place to preserve reviewability

Example use cases

Generate an authoritative Tree.txt and PROJECT_MAP.md after merging a large feature branch
Create a concise project index for new contributors during onboarding
Refresh maps before a governance review or release to ensure artifact coverage
Run before publicizing the codebase to provide a durable, reviewable snapshot

FAQ

Will the skill change source code?

No. It only writes Tree.txt and docs/PROJECT_MAP.md and avoids modifying application code.

Can it invent architecture or intent?

No. The output maps existing files and structure; it does not infer or create architecture or behavioral rules.