Repo Onboarding Map

Repo Onboarding Map

Purpose

Create a reusable working map of the repository so future tasks start from a strong mental model instead of repeated rediscovery.

This skill is for first-pass understanding of a codebase:

• where execution starts
• how data moves
• how modules are separated
• what tests exist
• what parts are fragile
• what invariants matter

The goal is not exhaustive documentation. The goal is an execution-useful model of the repository.

Use when

Use this skill when the user wants to:

• understand a new repo quickly
• onboard into an unfamiliar codebase
• build a mental model before implementation
• find entry points and main execution paths
• understand module boundaries
• identify validation surface and risky areas
• record the result for later reuse

Typical trigger phrases:

• "разбери репозиторий"
• "построй карту репо"
• "хочу быстро понять этот проект"
• "сделай onboarding по этому repo"
• "map this codebase"
• "help me understand this repository"
• "show me entry points and data flow"

Do not use when

Do not use this skill for:

• implementing a feature
• creating an execution plan for a change
• debugging a failing module
• reviewing one PR or one diff
• explaining only one function or class
• generic architecture brainstorming without a concrete repository

Inputs

Expected inputs:

• the repository
• current working directory inside that repository
• any existing docs and instructions

Optional inputs:

• a user-stated area of focus
• issue text
• recent changes
• known pain points or risky modules

Outputs

Always produce:

1. a reusable repository map document
2. the document path
3. a concise summary for the user

The repo map should cover:

• project purpose
• top-level layout
• main entry points
• primary execution flows
• data flow
• module boundaries and responsibilities
• configuration surface
• test surface
• risky or complex areas
• important invariants
• recommended starting points for future tasks

Constraints

• Read the nearest AGENTS.md first and treat it as part of the repository source of truth.
• Prefer existing repository documentation conventions if present.
• Do not dump a directory tree or class inventory with no operational value.
• Keep the map reusable for future implementation, review, debugging, and planning tasks.
• Mark uncertainty clearly when execution flow or ownership is only inferred.

Procedure

1. Read repository guidance first. Start with:

   • AGENTS.md
   • README
   • top-level docs
   • package, build, or dependency manifests
   • top-level config files

2. Identify the repo shape. Determine:

   • language or languages
   • runtime or framework
   • main package or app structure
   • build system
   • deployment or execution style
   • test framework

3. Find the entry points. Locate:

   • CLI entry points
   • app bootstrap files
   • server startup paths
   • jobs, workers, or pipelines
   • notebooks or scripts, if they are first-class flows

4. Recover the main execution paths. Build a practical flow model:

   • what starts the system
   • what happens next
   • which modules own which stage
   • where external I/O happens
   • where state is read or written

5. Map module boundaries. For each major module or package, record:

   • responsibility
   • key interfaces
   • main upstream and downstream dependencies
   • whether it is stable, shared, or fragile

6. Map the test surface. Identify:

   • test directories and frameworks
   • cheap validation paths
   • smoke tests vs unit tests vs integration tests
   • obvious gaps in coverage, if visible

7. Identify risky areas. Flag code that is likely to be:

   • stateful
   • cross-cutting
   • performance-sensitive
   • migration-sensitive
   • weakly tested
   • tightly coupled
   • config-heavy
   • concurrency- or I/O-sensitive

8. Extract invariants. Record only invariants that materially affect safe future changes, for example:

   • API contracts
   • schema expectations
   • ordering assumptions
   • idempotency assumptions
   • naming or registration constraints
   • state transition rules

9. Write the repo map document. Prefer an existing docs convention if present. Otherwise write to one of:

   • docs/repo-map.md
   • docs/onboarding/repo-map.md
   • REPO_MAP.md

10. Keep the document concise and reusable. Include only what materially improves future implementation, review, debugging, or planning work.

Optional subagent use

For medium or large repositories, explicitly use exploration-oriented subagents before finalizing the map:

• one exploration pass for entry points and execution flow
• one exploration pass for tests, risky areas, and invariants

Use subagents only for bounded read-heavy analysis. Wait for their results, then merge them into one final repo map.

Do not use subagents for very small or highly local repositories.

Required document structure

The repo map document should contain:

• Title
• Repository purpose
• Tech stack and runtime shape
• Top-level layout
• Entry points
• Main execution flows
• Data flow
• Major modules and boundaries
• Config surface
• Test surface
• Risky areas
• Important invariants
• Recommended starting points for common tasks

See references/repo-map-template.md for the default structure. Use references/risk-checklist.md and references/invariant-checklist.md when the repository has unclear or cross-cutting surfaces.

Definition of done

• A reusable repo map document exists in the repository or repo docs area.
• Entry points and at least one main execution flow are identified.
• Major modules, test surface, risky areas, and invariants are documented when visible.
• The output is useful for future implementation work, not just for one chat reply.
• Uncertainty is explicit where the repository shape is ambiguous.

Final response format

Return a compact answer in this structure:

• Repo map document: <path>
• Repository purpose: ...
• Entry points: ...
• Main flow: ...
• Major modules: ...
• Test surface: ...
• Risky areas: ...
• Important invariants: ...
• Recommended next starting points: ...

Positive examples

Use this skill for:

• "разбери это репо"
• "хочу быстро понять кодовую базу"
• "сделай onboarding-map проекта"
• "map this repo before we change anything"
• "find entry points and data flow in this codebase"

Negative examples

Do not use this skill for:

• "почини баг"
• "сделай план рефактора"
• "оптимизируй этот модуль"
• "объясни только эту функцию"
• "закоммить и запушь изменения"