explore-codebase

name	explore-codebase
description	Systematically understand an unfamiliar codebase or feature area. Outputs a populated .ohc/PROJECT.md with stack, architecture, conventions, entry points, and gotchas. Run at project start or when entering new feature territory.
allowed-tools	Read Bash

Explore Codebase

Use when: new project, new feature area, or significant time since last session.

Reading Order

Stop when you can answer all output questions below.

Round 1 — Project meta (always read)

1. README.md — purpose, quick start, architecture overview
2. package.json / pyproject.toml / go.mod / Cargo.toml / pubspec.yaml / build.gradle — deps, scripts, version
3. .env.example — what environment the app expects
4. docker-compose.yml or Dockerfile — infrastructure shape
5. (Monorepo) pnpm-workspace.yaml / turbo.json / nx.json / lerna.json — workspace structure

Round 2 — Entry points

6. Main entry file (src/index.ts, main.py, cmd/main.go, lib/main.dart, MainActivity.kt, ContentView.swift)
7. Router / URL definitions (routes.ts, urls.py, router/index.ts)
8. Database schema (schema.prisma, drizzle.config.ts, models.py, migrations/)
9. (Mobile) App manifest (AndroidManifest.xml, Info.plist, app.json)

Round 3 — Tests

10. One complete test file — understand test style and patterns
11. Test configuration (jest.config.ts, pytest.ini, vitest.config.ts, flutter test, XCTest)

Round 4 — Spot checks (3 files minimum)

12. 3 representative source files — understand code style, patterns
13. CI configuration (.github/workflows/)

What to Extract

Write findings to .ohc/PROJECT.md:

• Tech stack: language, runtime (Node/Deno/Bun), framework, ORM, test runner, package manager, CI
• Monorepo: tool used, workspace layout, shared packages
• Entry points: main file, router file, config files, test directory
• Architecture: how data flows (client → API → service → DB or similar)
• Conventions: naming style, file structure, import style, error handling
• Gotchas: anything surprising, undocumented, or non-obvious

Run the Generator

# Node (preferred — zero Python dependency):
node skills/explore-codebase/scripts/generate-project-map.js

# Python fallback (if Node 18+ unavailable):
python3 skills/explore-codebase/scripts/generate-project-map.py

Auto-detects stack and fills the tech stack table in PROJECT.md.

Output

Tell user: "Exploration complete. PROJECT.md updated. Key findings: [top 3]"

See references/exploration-checklist.md for full checklist.