Produce an onboarding map of this repository that lets a new engineer locate any entry point, install and run the project, and trace its main flow without reading every file. Work read-only: inspect files, run no build/install/test commands, and change nothing.
Method
Follow these steps in order. Prefer primary evidence (config, code, lockfiles) over READMEs, which drift.
- Identify the stack and layout. List the repo root. Read the package/manifest files that define it (
package.json,pyproject.toml,go.mod,Cargo.toml,pom.xml,Gemfile, etc.), the lockfile, and any monorepo/workspace config. Detect the language(s), package manager, and framework from these — do not assume. - Establish purpose. Read the README, top-level docs, and repo/package description. State what the project does and the problem it solves in your own words. If purpose is unstated, infer it from the public entry points and say you inferred it.
- Map the architecture. Use directory structure plus the manifest's declared entry points to identify the main modules/packages and their responsibilities. Determine dependency direction by scanning the import/require/use statements at each module's boundary — its package entry or index file, and a sample of files under it — for references that cross into sibling modules; the module doing the importing depends on the one imported. To stay bounded on large graphs, only resolve edges between the top-level modules you listed, not file-to-file. Name any layering this reveals (API / domain / data, UI / logic, etc.).
- Find the real entry points. Locate
main/bintargets,scriptsin the manifest, server bootstrap, CLI definitions, HTTP route roots, cron/queue workers, and framework conventions (pages/,app/,cmd/,src/index.*). Cite the exact file and symbol for each. - Trace one primary flow end to end. For a service/app, pick the most important request/command and follow it from entry point through the layers to its side effect (DB write, response, file, external call). For a library/framework with no single dominant flow, instead trace the main public API entry — the primary function/class exported from the manifest's declared entry — inward through the layers to what it returns or mutates. Record the ordered hops as
file:symbol → file:symbol. - Extract install/run/test the project's own way. Read scripts,
Makefile/Taskfile, CI workflows (.github/workflows, etc.), Dockerfiles, and.env.example. Report the exact documented commands — never invent them. Note required runtime versions, services (DB, cache, queue), and env vars. - Pick the reading path. Choose 3-6 files a newcomer should read first, ordered, each with a one-line reason.
Output format
Markdown, these sections in order:
- What & why — 2-4 sentences.
- Stack — language(s), package manager, framework, key libraries; each backed by the file that proves it.
- Architecture — module table (module | path | responsibility) plus a 3-6 line dependency/layering sketch.
- Entry points — bullet list, each
path:symbolwith what triggers it. - Primary flow — one traced path as an ordered
→chain. - Run it — install, run, test commands verbatim from source, plus required services/env.
- Start reading here — the ordered file list with reasons.
- Unknowns — anything you could not determine.
Rules
- Every path, command, and symbol must be copied from a file you actually read. Cite the source file for non-obvious claims.
- Never guess a command, port, or env var; if it is not written down, list it under Unknowns.
- Mark inferences as inferred; mark gaps explicitly rather than filling them plausibly.
- Do not execute, install, build, test, or modify anything. Read and report only.
- Skip generated/vendored trees (
node_modules,dist,build,vendor,target,.venv); read lockfiles for versions, not their contents wholesale. - Be concrete and dense. No filler, no restating these instructions.