andrem-sec/project-scan

Project Scan Skill

Reads the current codebase and auto-populates context/project.md. Run once on setup, re-run when the project's structure changes significantly.

What Claude Gets Wrong Without This Skill

Without a scan, context/project.md stays as a template. Every skill that reads it gets nothing useful. The context layer is only as good as the data in it.

Detection Protocol

Stack Detection

Check for manifest files in order:

| File | Indicates | |------|-----------| | package.json | Node.js — check dependencies for framework (next, express, fastapi via py) | | pyproject.toml / setup.py / requirements.txt | Python — check for FastAPI, Django, Flask, etc. | | go.mod | Go — check module name and key imports | | Cargo.toml | Rust | | pom.xml / build.gradle | Java/Kotlin | | Gemfile | Ruby | | composer.json | PHP | | *.csproj | .NET/C# |

Read the manifest. Extract: language, framework, key dependencies (non-obvious ones only — not lodash, not requests).

Entry Points

| Stack | Look For | |-------|---------| | Node.js | "main" in package.json, src/index.ts, app.ts, server.ts | | Python | main.py, app.py, __main__.py, manage.py (Django) | | Go | cmd/*/main.go, main.go | | Rust | src/main.rs, src/lib.rs |

Read the entry point file. Note what it initializes.

Module Mapping

List directories at the top level of src/, lib/, app/, pkg/, or equivalent. For each:

• Read the directory listing
• If there's an index.ts, __init__.py, or equivalent, read the first 20 lines
• Write a one-line description of what that module does

Cap at 10 modules. If there are more, note the count and describe the most significant.

Infrastructure Detection

| File/Pattern | Indicates | |-------------|-----------| | docker-compose.yml | Local Docker services — read service names | | Dockerfile | Containerized deployment | | .github/workflows/ | GitHub Actions CI | | *.tf files | Terraform infrastructure | | k8s/ or kubernetes/ | Kubernetes deployment | | .env.example | Read to understand required environment variables |

Existing Docs

Read README.md (first 50 lines). Extract anything that describes architecture, constraints, or setup requirements not already captured.

Output Format

Write directly to context/project.md, replacing template placeholders. Do not append — overwrite the template sections with real data.

Sections to populate:

• Identity — name, type (derived from stack), status (assume "active development" unless README says otherwise)
• Tech Stack — language, framework, database (from docker-compose or env vars), infrastructure
• Architecture — 2-3 sentences from README + entry point reading
• Current State — leave "In Progress" and "Known Issues" blank for user to fill — note this
• Do Not — leave blank for user to fill — note this

After Writing

State: "context/project.md populated. Please review and fill in:

• Current State → In Progress and Known Issues
• Do Not → approaches specific to this project
• Constraints → anything that can't be changed"

Anti-Patterns

Do not guess at framework from file extensions alone. Read the manifest.

Do not list every dependency — only the non-obvious ones that shape how the project works.

Do not overwrite anything the user has already filled in. If a section has real content (not template placeholder text), preserve it.

Mandatory Checklist

1. Verify at least one manifest file was read (not guessed from extensions)
2. Verify entry points were read, not just listed
3. Verify key modules have one-line descriptions from reading, not inference
4. Verify context/project.md was written (not just displayed in chat)
5. Verify user was told which sections still need manual input