project-work/.codex/skills/codebase-overview/skill.md

name, description

name

description

codebase-overview

Deeply explores a codebase or folder to understand its purpose, architecture, and connectivity, then writes a comprehensive OVERVIEW.md file to the project root. Use this skill whenever the user says "prime on", "understand the app", "document the codebase", "create an overview", "what does this app do", or asks for an OVERVIEW.md or similar documentation of a project. Trigger even if the user just says "prime" in the context of an active codebase. This skill is the right choice any time the user wants a durable, readable summary of how a project is structured and connected.

Codebase Overview Skill

If OVERVIEW.md already exists: read it and stop. Do not read any other files, do not explore the directory tree, do not check git history. Just read OVERVIEW.md and summarize its contents to the user. That is the complete task.

If OVERVIEW.md does not exist: deeply explore the current working directory (or a path the user specifies), extract the most salient facts about the codebase, and write them to OVERVIEW.md in the project root.

The goal is a document a new developer could read on day one to understand what the app does, how it's structured, what it connects to, and where the interesting parts are. Be specific and factual — avoid vague summaries. If you find a concrete detail (a database URL format, an API endpoint, a notable architectural pattern), include it.

Exploration strategy

Use the tools available to you to explore in parallel where possible. Here's what to look for:

Start with the high-level anchors:

• package.json / Cargo.toml / pyproject.toml / go.mod — dependencies, scripts, metadata
• README.md if it exists — stated purpose
• Main entry point (e.g. src/main.tsx, app.py, cmd/main.go, index.js)
• Build/config files (e.g. vite.config.*, webpack.config.*, docker-compose.yml, .env.example)

File and directory structure:

• Walk the top 2–3 levels of the directory tree
• Identify major groupings (e.g. routes/, components/, api/, db/, services/)
• Note any monorepo structure (workspaces, packages/, apps/)

Tech stack:

• Framework(s) and runtime
• Language(s)
• Build tooling
• Test framework

Integrations:

• Third-party APIs and SDKs (look for imports, env var names, config keys)
• Authentication providers
• Analytics, monitoring, feature flags
• Payment processors, messaging services, etc.

Database and data layer:

• ORM or query library in use
• Database type (Postgres, MySQL, SQLite, MongoDB, etc.)
• Schema files or migration directories
• Connection config (env var names, config files)

Connectivity and configuration:

• .env.example or similar — what env vars are expected
• API proxy config (e.g. Vite's server.proxy, nginx config)
• Port numbers, base URLs, service addresses
• Any hardcoded endpoints or service URLs in source

Architecture patterns:

• State management approach
• Routing strategy
• Notable design patterns (e.g. provider pattern, command/event bus, repository pattern)
• Anything non-obvious that would trip up a new developer

OVERVIEW.md format

Write the file to the project root. Use this structure, but adapt section depth and detail to what's actually present — don't include empty sections:

# [App/Project Name] — Overview

> One-sentence description of what this app does and who uses it.

## Purpose

2–4 sentences on the domain, user-facing purpose, and any important context
(e.g. "phase 0 of a migration from Preact to React").

## Tech Stack

| Layer | Technology |
|-------|-----------|
| ... | ... |

## Directory Structure

Brief annotated tree of the top 2–3 levels. Only include directories and files
that are meaningful — skip `node_modules`, lockfiles, build output, etc.

## Architecture

Key architectural patterns, data flow, and anything non-obvious. This section
is where you explain the *how* rather than just listing what exists.

## Integrations

For each external service or API: what it is, what it's used for, and where
in the codebase it appears.

## Database & Data Layer

ORM/library, database type, schema location, migration approach, connection config.
If there's no database, say so (e.g. "Frontend-only — no database layer").

## Connectivity & Configuration

Expected environment variables, API proxy setup, service endpoints, ports.
Use a table or list with variable name + purpose.

## Key Entry Points

The files a new developer should read first to understand how the app boots
and how requests/events flow through it.

## Notes & Gotchas

Anything that would surprise a new developer: non-standard patterns, in-progress
migrations, known tech debt worth knowing about, Preact internals being used, etc.

Quality bar

• Be specific. "Uses Postgres via Drizzle ORM, schema defined in packages/db/schema.ts" is better than "uses a database."
• If something is unclear (e.g. you can see a dependency but can't find where it's used), say so briefly rather than omitting it.
• Keep the file readable — a developer should be able to scan it in 5 minutes.
• Don't reproduce large code blocks; reference file paths instead.
• After writing the file, confirm to the user what was created and where.