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)

1. 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` |

Map the top 10-15 tasks someone would do in this repo to specific files.

Danger Zones — fragile files/areas:

## Danger Zones

| File/Area | Why It's Fragile |
|-----------|-----------------|
| `path/to/file` | Reason |

Phase 4: Write Manual Atlas Docs

Create docs/atlas/ with these files. See references/atlas-templates.md for structure guidance on each.

| File | Content Source | |------|--------------| | 00_README.md | How to use the atlas + agent workflow conventions | | 01_ARCHITECTURE.md | Read entrypoints, DI setup, module boundaries | | 02_DOMAIN_MODEL.md | Read models/types, identify state machines | | 03_CRITICAL_FLOWS.md | Trace top 3-5 user flows through the code | | 04_STATE_SOURCES_OF_TRUTH.md | Identify all state stores (DB, cache, files, memory) | | 05_EXTERNAL_DEPENDENCIES.md | Read package manifests + integration code | | 06_GOTCHAS.md | Look for race conditions, init ordering, fragile patterns | | 07_TEST_MATRIX.md | Read test configs, describe how to run tests |

Each doc should be 50-150 lines with real paths, real code references, and real gotchas from the codebase. Not generic advice.

Phase 5: Add Agent On-Ramp

Add an atlas section to the repo's CLAUDE.md (or create one) with:

• A pointer to docs/atlas/ and its purpose
• A two-agent workflow: Agent A loads repo-map.md → domain-specific doc → source files → implements; Agent B reviews diffs against 06_GOTCHAS.md, verifies flows via 03_CRITICAL_FLOWS.md, and confirms tests per 07_TEST_MATRIX.md
• Working rules: read atlas before coding, verify critical flows after changes, update atlas docs when architecture changes, run make atlas-generate after structural changes

Phase 6: Add Build Targets

Add to Makefile (create if needed):

atlas-generate:
	python3 scripts/atlas/generate_atlas.py --write

atlas-check:
	python3 scripts/atlas/generate_atlas.py --check

If the repo uses package.json, also add to scripts:

"atlas:generate": "python3 scripts/atlas/generate_atlas.py --write",
"atlas:check": "python3 scripts/atlas/generate_atlas.py --check"

Phase 7: Verify

1. Run atlas-generate — must complete without errors
2. Run atlas-check — must exit 0 immediately after generation
3. Confirm every atlas doc has real file paths and repo-specific content
4. Confirm no runtime/product code was changed

Output Summary

After completing all phases, report:

• List of created files
• How to run atlas generation/check
• 10-line "How an agent should use this atlas" quick reference

Resources

• Generator script: See scripts/generate_atlas.py — copy to target repo and customize
• Doc templates: See references/atlas-templates.md for structure guidance on each manual doc

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cathrynlavery
• Source: cathrynlavery/repo-atlas
• License: MIT

Install and usage instructions live in the source repository linked above.