# Repo Atlas

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

- **Type:** Skill
- **Install:** `agentstack add skill-cathrynlavery-repo-atlas-repo-atlas`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [cathrynlavery](https://agentstack.voostack.com/s/cathrynlavery)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [cathrynlavery](https://github.com/cathrynlavery)
- **Source:** https://github.com/cathrynlavery/repo-atlas

## Install

```sh
agentstack add skill-cathrynlavery-repo-atlas-repo-atlas
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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):
```markdown
## 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:
```markdown
## 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):

```makefile
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:
```json
"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](https://github.com/cathrynlavery)
- **Source:** [cathrynlavery/repo-atlas](https://github.com/cathrynlavery/repo-atlas)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-cathrynlavery-repo-atlas-repo-atlas
- Seller: https://agentstack.voostack.com/s/cathrynlavery
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.