repo-atlas

Repo Atlas

Build an in-repo persistent context system so engineers and LLM agents can understand any codebase quickly with minimal searching.

Hard Constraints

• Do NOT change product/runtime behavior
• No paid/hosted tooling — everything lives in the repo
• Zero or minimal dependencies (Python 3 standard library only)
• All generated content must reflect real repo specifics, not generic filler

Workflow

Phase 1: Reconnaissance

Before writing anything, understand the repo:

1. Read the top-level directory structure
2. Identify the repo type (app, backend/API, library, monorepo, CLI, infrastructure)
3. Identify the primary language(s) and framework(s)
4. Find entrypoints, build configs, CI files
5. Read 5-10 key files to understand architecture patterns

Phase 2: Run the Generator Script

Copy scripts/generate_atlas.py (bundled with this skill) to the repo at scripts/atlas/generate_atlas.py. Then customize and run it:

1. Copy the script to the target repo
2. Review and adjust the configuration section at the top:
   • IGNORE_NAMES — add repo-specific directory names to ignore (exact segment match)
   • TREE_ANNOTATIONS — add short descriptions for key directories
   • ENTRYPOINT_NAMES — add framework-specific entry filenames
   • ENTRYPOINT_PATH_PATTERNS — add path-based patterns (fnmatch style, e.g., cmd/*/main.go)
   • ENTRYPOINT_CONTENT_MARKERS — add code markers that identify entry points
   • CONVENTIONAL_COMMITS — adjust if repo uses different commit conventions
   • CHANGELOG_DAYS — change the changelog lookback window (default: 14)
3. Run: python3 scripts/atlas/generate_atlas.py --write

This auto-generates:

• docs/atlas/repo-map.md — directory tree + entrypoints + file stats
• docs/atlas/08_CHANGELOG_LAST_14_DAYS.md — categorized recent commits

Phase 3: Enhance repo-map.md

After the script generates the skeleton, manually add these sections to repo-map.md:

Router Table — "Where to look for X" (10-15 rows):

## Where to Look for X

| Task | Start Here |
|------|-----------|
| Fix [domain concept] | `path/to/file.ext` |