repo-atlas

name

repo-atlas

description

Build a persistent context system (atlas) for any repository — generates directory maps with entrypoints, documents architecture and module boundaries, traces critical flows, catalogs external dependencies, and creates agent-ready onboarding guides. Use when asked to create a repo map, generate codebase documentation for LLM agents, set up an atlas, or create onboarding docs. Also use when asked to 'map this repo', 'document this codebase', or 'create context docs'.

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

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