project-summary — Instant Codebase Overview

Generate a structured project summary for onboarding developers or providing context to agents.

Steps

1. Scan Project Root

Read these files first (all optional):

• package.json / pyproject.toml / Cargo.toml / go.mod / *.sln / *.csproj
• README.md — existing description
• LICENSE
• Dockerfile / docker-compose.yml
• .github/workflows/*.yml / .gitlab-ci.yml / Jenkinsfile
• tsconfig.json / babel.config.* / webpack.config.* / vite.config.*
• .eslintrc* / .prettierrc* / pyproject.toml [tool.ruff]

2. Detect Language & Framework

Primary language — count file extensions:

find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/target/*' -not -path '*/__pycache__/*' -not -path '*/.venv/*' | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -10
# Windows:
Get-ChildItem -Recurse -File -Exclude node_modules,.git,dist,target | Group-Object Extension | Sort-Object Count -Descending | Select-Object -First 10 Count,Name

Framework — check dependencies (see readme-generator skill for detection table).

3. Map Architecture

Identify the architecture pattern from directory structure:

4. Identify Entry Points

# Look for common entry points
ls -la src/index.* src/main.* app.* main.* index.* manage.py server.* 2>/dev/null
# Check package.json "main", "module", "bin", "scripts.start"
# Check Cargo.toml [[bin]] or src/main.rs
# Check pyproject.toml [project.scripts]

5. Catalog Key Files

List the most important files with one-line descriptions:

## Key Files
| File | Purpose |
|------|---------|
| `src/index.ts` | Application entry point |
| `src/routes/` | API route definitions |
| `src/models/` | Database models / schemas |
| `src/middleware/` | Express middleware (auth, logging) |
| `prisma/schema.prisma` | Database schema |
| `docker-compose.yml` | Local development services |
| `.github/workflows/ci.yml` | CI pipeline — test + lint + build |

Focus on files a new developer needs to know about. Skip generated files, configs that are self-explanatory, and boilerplate.

6. Document Test Setup