repo-onboarding

name: repo-onboarding description: Systematically map an unfamiliar codebase before changing it — entry points, build/test loop, conventions, data flow. Use when starting work in a repo you haven't seen, or asked "how does this codebase work?". version: 1.0.0 license: MIT keywords: [onboarding, codebase, exploration, architecture, conventions]

Resist editing until you can answer: how do I run it, how do I test it, where does the change go, and what style does this house write in?

Procedure (15 minutes, in order)

The README + manifest first. README.md, then the manifest (package.json / pyproject.toml / go.mod / Cargo.toml): name, scripts, dependencies. The scripts block is the repo telling you its verbs.
Find the entry points. bin/main fields, src/index.*, cmd/, __main__.py. Trace one request/command end-to-end at skim depth — names only, no line-reading.
Establish the test loop before touching anything. Run the test command; record how long it takes and whether it's green at HEAD. A red baseline changes everything you conclude later.
Map the directories (one line each, only top two levels). Mark the ones that are generated/vendored so you never read them again.
Sample the house style. Open the 2–3 most-recently-changed source files (git log --name-only -10): error handling pattern, naming, comment density, test structure. Your changes should be indistinguishable from these.
Find the seams. Where does config enter? Where is I/O isolated? What is the one module everything imports? That module is load-bearing — changes there need the most care.
Check the repo's own rules: CONTRIBUTING.md, CLAUDE.md, .github/ workflows (what CI actually enforces), lint configs.

Output

Write a short map (10–20 lines) before starting the actual task:

run:   npm start (src/cli.js)        test: npm test, ~6s, green at HEAD
flow:  cli.js → commands/* → store.js (all persistence) → index.json
style: ESM, no deps, errors thrown as plain Error, tests in test/*.test.js
care:  store.js is imported everywhere; schema changes ripple
rules: CI runs lint+test on 3 OS; commits are conventional

Keep it honest — list what you didn't look at, so later-you knows where the map has blank spots.