Project Summary

project-summary — Instant Codebase Overview

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

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: StructurePatternsrc/controllers/, src/models/, src/routes/MVCsrc/features/*/, each with components+hooks+apiFeature-basedsrc/domain/, src/application/, src/infrastructure/Clean Architecture / DDDpages/ or app/ (Next.js/Nuxt)File-based routingcmd/, internal/, pkg/Go standard layoutsrc/lib.rs, src/main.rsRust binary/libraryFlat structure, few filesSimple / 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: What triggers the pipeline (push, PR, schedule) What steps run (lint, test, build, deploy) Where it deploys to (if detectable)

8. Map Dependencies

List the top 10 most important dependencies (not all of them): Focus on framework, database, auth, testing, and build tools Note the approximate total count ## 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

Monorepo: Summarize root structure, then briefly describe each package/workspace No manifest file: Infer from file extensions and directory structure Very large project (1000+ files): Limit scan depth to 3, focus on src/ and root Multiple languages: Report primary and secondary languages with percentages Empty/new project: Report as scaffold; note what's been set up vs. what's missing

Error Handling

ErrorResolutionPermission denied on filesSkip and note which files couldn't be readMassive repo, scan timeoutLimit to src/, root configs, and find -maxdepth 3Unrecognized frameworkReport as "custom" and describe what IS detectableNo README or descriptionUse directory name; note absence Built by Clawb (SOVEREIGN) — more skills at [coming soon]