| name | primer |
| description | Orient in an unfamiliar codebase by inspecting repository instructions, structure, documentation, manifests, key files, Git state, and recent work. Use when starting work, switching repositories, or needing a concise architecture overview. |
Codebase Primer
Build enough context to work safely without reading the repository exhaustively.
Phase 1: Inspect Current State
Read repository instructions in scope, then inspect:
git status --short --branch
git log --oneline -20
git remote -v
rg --files
Use a shallow tree when available and exclude generated dependency, cache, and
build directories. If the request names a subdirectory, focus there while noting
its relationship to the broader repository.
Phase 2: Read Documentation
Read in this order, stopping when sufficient context is available:
- Agent instructions such as
AGENTS.md, CLAUDE.md, and scoped equivalents.
README.md, contribution guides, and architecture documentation.
- Dependency and build manifests such as
package.json, pyproject.toml,
go.mod, Cargo.toml, and Makefile.
Read instruction files fully. Scan manifests for commands and important
dependencies rather than reading lockfiles or generated output.
Phase 3: Identify Architecture
Identify:
- project type and primary languages;
- major directories and ownership boundaries;
- entry points and important data flows;
- build, test, lint, and CI systems;
- schemas, shared types, and configuration;
- the smallest set of core implementation files needed to explain the system.
Prefer targeted reads. Note large files without loading them completely unless
the active task requires it.
Phase 4: Assess Active Work
If the working tree is dirty, inspect git diff --stat and the relevant diffs
without reverting them. Use recent commits to identify the current development
focus. Surface uncertainty and repository risks instead of guessing.
Output
## Primer Report: <project>
### Overview
- Type, purpose, languages, and frameworks
### Architecture
- Major directories, boundaries, entry points, and data flows
### Development
- Runtime, dependencies, build, test, lint, and CI commands
- Repository rules that affect the requested work
### Key Files
| File | Purpose |
|---|---|
### Current State
- Branch and working tree
- Recent development focus
- Risks, unknowns, and likely next investigation
Keep the report concise and evidence-based. Do not infer unsupported commands or
architecture.