---
name: repo-map
description: Build a lightweight map and project glossary before exploring an unknown repository or unfamiliar module. Use before broad code exploration, feature work in a new codebase, architecture orientation, or when the agent and user need shared vocabulary for key domain concepts, classes, types, entry points, responsibilities, and call relationships. Use CodeGraph when available.
---

# Repo Map

Build a compact, objective structure map and shared glossary before editing or deep-diving. This is orientation work, not a full audit or recommendation document.

## Output Contract

Respond in chat unless the user asks for a file. If saving, write `docs/analysis/repo-map.md` in the target repo.

Include:

- Component summary: 1-3 sentences about what the scoped component does.
- Project glossary: 8-20 repo-specific domain/code terms, with source paths.
- Working map: file structure, modules, key types, and core data/control flows.

Exclude subjective opinions, risks, recommendations, confidence ratings, open questions, and audit findings.

## Workflow

1. Resolve git roots first. If the working folder contains multiple child repos, map them separately.
2. Define scope from the user's feature, bug, file, symbol, or module. Do not read every file by default.
3. Inventory manifests, READMEs, tests, entry points, and domain-heavy filenames with `rg --files`.
4. Use CodeGraph when available for callers, callees, impact, and symbol lookup. Confirm important conclusions by reading files.
5. Identify boundary types: app roots, controllers, services, stores, reducers, models, protocols, dependency containers, API clients, persistence layers, and coordinators.
6. Build a small glossary from project usage, marking inferred terms explicitly.
7. Trace relationships from entry points to domain logic and persistence/API/UI boundaries.
8. Stop once the map is useful for the next task.

## References

Read `references/repo-map-workflow.md` for detailed root detection, CodeGraph, glossary, and relationship tracing rules.

Choose the closest format guide:

- `references/repo-map-web-example.md` - web frontend.
- `references/repo-map-backend-example.md` - backend service or worker.
- `references/repo-map-apple-example.md` - iOS, macOS, SwiftUI, UIKit, AppKit, XCTest.
- `references/repo-map-android-example.md` - Android, Gradle, Kotlin, Java, Compose, XML layouts.

## Rules

- Use this before broad exploration of an unknown repo or unfamiliar module.
- Keep the map small enough to guide action.
- Include concrete file/module paths when they clarify responsibility.
- Favor file/type names over architecture labels.
- Do not modify source files unless the user explicitly asks for implementation.
- If the map reveals a matching SOP or skill, mention it before continuing.