codebase-orientation

name	codebase-orientation
description	Use when the user asks to understand an unfamiliar repo, be onboarded, find entrypoints, map project structure, or identify where to change something. Produces a concise, evidence-backed mental model without writing project assets by default.

Codebase Orientation

Mission

Build a fast onboarding mental model for an unfamiliar repository. Optimize for structural insight, entrypoints, conventions, and the few files a newcomer should inspect first. Do not turn this into a full architecture-map generation unless the user asks for persisted architecture assets.

Operating Boundaries

• Keep the task read-only by default.
• Do not create hello-scholar/architecture/ unless the user explicitly asks for an architecture map or persisted viewer assets.
• Follow the native architecture boundary in ../references/native-boundaries.md; do not read .env secrets.
• Prefer code, manifests, tests, and config over README claims when they disagree.
• Separate confirmed, inferred, and unknown findings.
• Cite project-relative paths for every important conclusion.

Load References

Read ../references/native-boundaries.md, references/reconnaissance-checklist.md, and references/onboarding-output-examples.md before doing the scan. Use the checklist as the operating guide, not as background prose.

Workflow

1. Run a bounded reconnaissance pass.
   • Inspect manifests, README files, prompt/runtime files, top two directory levels, scripts, tests, and CI/tooling.
   • Ignore generated, vendored, cached, checkpoint, build, output, and large data directories.
   • Read selectively. Do not read every file unless the project is tiny.
   • Use the scan budget rules in reconnaissance-checklist.md.
2. Fingerprint the codebase.
   • Identify languages, frameworks, package managers, runtime hosts, CLIs, services, experiments, storage, and test runners.
   • Extract install, start, dev, test, build, lint, and format commands from manifests, scripts, docs, Makefiles, CI, or task runners.
   • Record the evidence path for each detection.
3. Find entrypoints and execution surfaces.
   • CLI: bin, package scripts, main, command routers.
   • Web/API: routes, controllers, handlers, middleware.
   • ML/research: train/eval scripts, configs, pipelines, artifacts.
   • Plugin/agent: catalogs, registries, command/skill/agent dispatch.
4. Map module boundaries.
   • Describe top-level directories by responsibility, not just by name.
   • Identify shared modules, state/config stores, and test contracts when they are central.
5. Trace one representative startup or request path when possible.
   • Keep the trace short and evidence-backed.
   • Mark gaps as unknown instead of inventing a call chain.
6. Classify optional project lenses only when signals are present.
   • CLI lens: command lifecycle and command surface.
   • Web/API lens: request lifecycle and route map.
   • ML/research lens: experiment workflow, data flow, evaluation flow, and artifact lineage.
   • Library lens: public API and extension boundaries.
   • Plugin/skill/agent lens: skill workflow, agent dispatch, and command routing.
7. Produce the onboarding guide directly in the response unless the user requested a file.

Output Contract

Use this shape:

1. TL;DR: 3 to 5 bullets on what the project is and how it runs.
2. Top-Level Directory Map: table with path, role, confidence, evidence.
3. Entrypoint Map: commands, scripts, runtime entry files, and what they dispatch to.
4. Module Boundary Map: core subsystems and how they relate.
5. Run / Test / Build: install, start, dev, test, build, lint, and env notes supported by evidence.
6. Startup Or Request Path: numbered path with file evidence.
7. State / Config / Test Contract: where state lives, how config is loaded, how tests verify behavior.
8. Relevant Lenses: only project-type lenses that are actually useful for this repository.
9. Next Files To Inspect: practical shortlist for likely follow-up work.
10. Unknowns: gaps, inferred claims, and files that should be checked next.

Quality Bar

• Make the guide scannable in about two minutes.
• Prefer 5 to 12 key concepts over a file inventory.
• Do not copy the README. Add structural insight the README does not already provide.
• Avoid vague labels such as utils or core unless the code evidence explains their role.
• Keep code snippets to short anchors only when they materially clarify the mental model.