/codebase-overview

name: codebase-overview
description: "Systematic codebase exploration and architecture mapping."
user-invocable: false
allowed-tools:
  - Read
  - Write
  - Bash
  - Grep
  - Glob
  - Edit
  - Task
  - Skill
context: fork
routing:
  triggers:
    - "onboard to codebase"
    - "codebase structure"
    - "what does this project do"
    - "give me an overview"
    - "summarize this repo"
    - "understand this codebase"
  category: analysis
  pairs_with:
    - generate-claudemd

Codebase Overview Skill

Systematic 4-phase codebase exploration that produces an evidence-backed onboarding report. Phases run in strict order — DETECT, EXPLORE, MAP, SUMMARIZE — because later phases depend on context established by earlier ones. This skill accelerates reading the codebase but does not replace it.

Reference Loading Table

| Signal | Load These Files | Why | |---|---|---| | example-driven tasks, errors | `examples-and-errors.md` | Loads detailed guidance from `examples-and-errors.md`. | | language-specific discovery commands per exploration phase | `exploration-strategies.md` | Loads detailed guidance from `exploration-strategies.md`. | | writing the 12-section overview report | `report-template.md` | Loads detailed guidance from `report-template.md`. | | statistical rule discovery, Go pattern analysis, cartographer scripts | `statistical-three-lenses.md`, `statistical-metrics-catalog.md` | Measure-first analysis lenses and 100-metric catalog (from demoted codebase-analyzer). | | statistical analysis worked examples, phase banners, error catalog | `statistical-phase-details.md`, `statistical-analysis-examples.md` | Phase details and real-world analysis workflows (from demoted codebase-analyzer). |

Instructions

Execute all phases autonomously. Verify each gate before advancing. Consult `references/exploration-strategies.md` for language-specific discovery commands.

Before starting any exploration, read and follow any `.claude/CLAUDE.md` or `CLAUDE.md` in the repository root because project-specific instructions override default behavior.

This is a **read-only** skill — keep all project files unmodified because the goal is observation, not mutation. Likewise, leave application execution and test running to other skills because those are execution concerns outside this skill's scope. For deep domain analysis, route to a specialized agent instead.

> See `references/examples-and-errors.md` for worked examples and error handling procedures.

Sensitive-Files Guardrail

Check every file path against this list BEFORE reading because secrets leaked into exploration output are hard to retract and easy to miss. Skip silently without logging the file contents or path.

# Secrets and credentials
.env, .env.*, *.pem, *.key, credentials.json, secrets.*, *secret*, *credential*, *password*

# Authentication tokens
token.json, .npmrc, .pypirc

# Cloud provider credentials
.aws/credentials, .gcloud/, service-account*.json

Phase 1: DETECT

**Goal**: Determine project type, language, framework, and tech stack.

**Step 1: Examine root directory**

Start from the current working directory because that is the project the user is asking about.

ls -la

Identify configuration files that indicate project type:

• `package.json` -> Node.js/JavaScript/TypeScript
• `go.mod` -> Go
• `pyproject.toml`, `requirements.txt`, `setup.py` -> Python
• `pom.xml`, `build.gradle` -> Java
• `Cargo.toml` -> Rust
• See `references/exploration-strategies.md` for complete indicator table

Always detect project type before reading source files because framework context changes how you interpret code (e.g., a `models/` directory means something different in Django vs. Express).

**Step 2: Read primary configuration**

Based on detected type, read the main config file. Preference order:

• Python: `pyproject.toml` > `setup.py` > `requirements.txt`
• Node.js: `package.json`
• Go: `go.mod`

Extract: project name, dependencies, language version, build system, scripts/commands.

**Step 3: Identify frameworks and tooling**

ls -la manage.py next.config.js nuxt.config.js angular.json 2>/dev/null
ls -la Makefile Dockerfile docker-compose.yml 2>/dev/null
ls -la .github/workflows/ 2>/dev/null

**Step 4: Check for CLAUDE.md**

Read any `.claude/CLAUDE.md` or `CLAUDE.md` in the repository root. Follow its instructions throughout remaining phases.

**Step 5: Document findings**

Use the DETECT Results template from `references/examples-and-errors.md`.

**Gate**: Project type identified (language + framework). Tech stack documented. Build/run commands known. Proceed ONLY when gate passes — skipping this gate leads to wrong architectural assumptions downstream.

Phase 2: EXPLORE

**Goal**: Discover entry points, core modules, data models, API surfaces, configuration, and tests.

Explore only what is needed for the overview because speculative deep-dives waste tokens without proportional value. Limit to 20 files per category because representative samples are more useful than exhaustive coverage. If a category has more than 20 files, note the total count and state that you examined a representative sample.

On explicit user request, deep-dive into specific subsystems, generate architecture diagrams, include full file contents, export findings to a separate file, or analyze dependency vulnerability status. These are off by default because the standard overview does not require them.

**Step 1: Find entry points**

Use language-specific patterns from `references/exploration-strategies.md`. Read each entry point file to understand application bootstrapping.

For any language, look for:

• `main` functions or `__main__` modules
• Server/app initialization files
• CLI entry points declared in config

Config files alone are not enough to understand a project because they show dependencies, not architecture — always read entry points and core modules too.

**Step 2: Map directory structure**

find . -