Project Summary

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):

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:

| Structure | Pattern | |-----------|---------| | src/controllers/, src/models/, src/routes/ | MVC | | src/features/*/, each with components+hooks+api | Feature-based | | src/domain/, src/application/, src/infrastructure/ | Clean Architecture / DDD | | pages/ or app/ (Next.js/Nuxt) | File-based routing | | cmd/, internal/, pkg/ | Go standard layout | | src/lib.rs, src/main.rs | Rust binary/library | | Flat structure, few files | Simple / Script |

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

# Detect test framework
grep -l "jest\|vitest\|mocha\|pytest\|unittest\|cargo test\|go test" package.json pyproject.toml Cargo.toml Makefile 2>/dev/null
Find test files
find . -name "*.test.*" -o -name "*.spec.*" -o -name "test_*" -not -path '*/node_modules/*' 2>/dev/null | head -20

Report: test framework, test location, how to run tests, approximate test count.

7. Check CI/CD

If CI config exists, summarize:

8. Map Dependencies

List the top 10 most important dependencies (not all of them):

## Key Dependencies
| Package | Purpose |
|---------|---------|
| express | Web framework |
| prisma | Database ORM |
| jsonwebtoken | JWT authentication |
| jest | Testing framework |
| Total | 47 dependencies (12 dev) |

9. Output Structured Summary

# Project Summary: [name]
Description: [from package.json or README]
Language: TypeScript | Framework: Express.js | Runtime: Node.js 20
Architecture: MVC | Package Manager: pnpm
License: MIT
Quick Start
[install + run commands]
Structure
[architecture description + key directories]
Key Files
[table from Step 5]
Dependencies
[table from Step 8]
Testing
Framework: Jest
Run: pnpm test
Coverage: pnpm test -- --coverage
CI/CD
Platform: GitHub Actions
Triggers: Push to main, PRs
Pipeline: Lint → Test → Build → Deploy to Vercel
Notes
[Anything unusual or important — monorepo setup, required services, known issues from README]

Edge Cases

Error Handling

| Error | Resolution | |-------|-----------| | Permission denied on files | Skip and note which files couldn't be read | | Massive repo, scan timeout | Limit to src/, root configs, and find -maxdepth 3 | | Unrecognized framework | Report as "custom" and describe what IS detectable | | No README or description | Use directory name; note absence |

[install + run commands]

[Anything unusual or important — monorepo setup, required services, known issues from README] ```