---
name: scorpio-project-map
description: Map a codebase's structure, tech stack, architecture patterns, and conventions into a reusable Project Context document. Use when onboarding to a new codebase, before feature planning, before code exploration, or when any skill needs project-level understanding.
---

# Project Mapper

A systematic methodology for understanding a codebase and producing a structured Project Context document. This document serves as shared context for other skills — eliminating redundant exploration and ensuring consistent understanding.

## When to Use

- **Before scorpio-roomba** — scorpio-roomba needs project context to explore intelligently
- **Before scorpio-feature-plan** — Replaces the manual "Explore" phase
- **Before scorpio-bug-investigate** — Provides codebase understanding for tracing issues
- **New project onboarding** — First thing to run when encountering an unfamiliar codebase
- **Context refresh** — Re-run periodically or after major architectural changes

## Mapping Phases

```
Phase 1: Structure   → Map directory tree, identify key areas
Phase 2: Stack       → Identify languages, frameworks, dependencies
Phase 3: Architecture → Discover patterns, layers, module organization
Phase 4: Context     → Read project docs, configs, and intent
Phase 5: Document    → Produce the Project Context file
```

## Phase 1: Structure

Map the project's directory layout and identify key areas.

### Exploration Steps

1. **Top-level survey** — List root directories and key files:
   ```
   Glob: "*"           → root files (package.json, tsconfig, etc.)
   Glob: "*/"          → root directories
   ```

2. **Source structure** — Map the main source directories:
   ```
   Glob: "src/**/"     → source directory tree
   Glob: "app/**/"     → app directory tree (Next.js, Rails, etc.)
   Glob: "server/**/"  → backend structure
   Glob: "client/**/"  → frontend structure
   ```

3. **Support structure** — Identify non-source areas:
   ```
   Glob: "test*/**/"   → test organization
   Glob: "docs/**/"    → documentation
   Glob: "scripts/**/" → build/deploy scripts
   Glob: ".github/**/" → CI/CD configuration
   ```

### Document Structure

```markdown
## Project Structure

### Root Layout
```
project/
├── src/              → [purpose: main source code]
├── tests/            → [purpose: test files]
├── docs/             → [purpose: documentation]
├── scripts/          → [purpose: build/deploy automation]
├── public/           → [purpose: static assets]
├── package.json      → [Node.js project config]
├── tsconfig.json     → [TypeScript config]
└── ...
```

### Key Directories
- `src/components/` — [N] React components, organized by [feature/type]
- `src/api/` — [N] API route handlers
- `src/services/` — Business logic layer
- `src/utils/` — Shared utility functions
- `src/types/` — TypeScript type definitions

### File Counts
- Source files: [N]
- Test files: [N]
- Config files: [N]
```

## Phase 2: Stack

Identify the technology stack from project configuration and source files.

### Detection Strategy

| Source | What to Read | What to Extract |
|--------|-------------|-----------------|
| `package.json` | dependencies, devDependencies | Frameworks, libraries, build tools |
| `requirements.txt` / `pyproject.toml` | dependencies | Python packages |
| `Cargo.toml` | dependencies | Rust crates |
| `go.mod` | require | Go modules |
| `Gemfile` | gems | Ruby dependencies |
| `tsconfig.json` / `jsconfig.json` | compilerOptions | TypeScript/JS configuration |
| `Dockerfile` / `docker-compose.yml` | images, services | Infrastructure stack |
| `.env.example` / `.env.sample` | variable names | External services used |
| CI config (`.github/workflows/`) | steps | Build/test/deploy pipeline |

### Document Stack

```markdown
## Technology Stack

### Languages
- **Primary**: [TypeScript 5.x / Python 3.12 / etc.]
- **Secondary**: [SQL / CSS / etc.]

### Frontend
- **Framework**: [React 18 / Vue 3 / Next.js 14 / etc.]
- **Styling**: [Tailwind CSS / CSS Modules / styled-components / etc.]
- **State Management**: [Redux / Zustand / Context / etc.]
- **Routing**: [React Router / Next.js App Router / etc.]

### Backend
- **Runtime**: [Node.js / Python / Go / etc.]
- **Framework**: [Express / FastAPI / Gin / etc.]
- **API Style**: [REST / GraphQL / tRPC / etc.]

### Data
- **Database**: [PostgreSQL / MongoDB / SQLite / etc.]
- **ORM**: [Drizzle / Prisma / SQLAlchemy / etc.]
- **Caching**: [Redis / in-memory / none]

### Infrastructure
- **Hosting**: [Vercel / AWS / Railway / etc.]
- **CI/CD**: [GitHub Actions / etc.]
- **Containerization**: [Docker / none]

### Key Dependencies
| Package | Version | Purpose |
|---------|---------|---------|
| [name] | [version] | [what it does in this project] |
| [name] | [version] | [what it does in this project] |

### Dev Tooling
- **Package Manager**: [npm / yarn / pnpm / pip / etc.]
- **Linter**: [ESLint / Ruff / etc.]
- **Formatter**: [Prettier / Black / etc.]
- **Test Framework**: [Jest / Vitest / pytest / etc.]
- **Build Tool**: [Vite / webpack / esbuild / etc.]
```

## Phase 3: Architecture

Discover how the codebase is organized architecturally.

### Pattern Detection

Read several representative source files to identify patterns:

| Pattern | How to Detect |
|---------|---------------|
| **MVC** | `models/`, `views/`, `controllers/` directories |
| **Feature-based** | Directories named by feature (`auth/`, `billing/`, `chat/`) containing mixed file types |
| **Layer-based** | Directories named by layer (`routes/`, `services/`, `storage/`) |
| **Clean Architecture** | `domain/`, `usecases/`, `infrastructure/`, `presentation/` |
| **Monorepo** | `packages/` or `apps/` with multiple `package.json` files |
| **Serverless** | `functions/` or `api/` with individual handler files |

### Convention Discovery

Read 3-5 source files from different areas to identify conventions:

```
Conventions to look for:
- File naming: camelCase, PascalCase, kebab-case, snake_case
- Export patterns: default export, named exports, barrel files (index.ts)
- Component patterns: functional components, hooks, props interfaces
- API patterns: route structure, middleware usage, error handling
- Test patterns: co-located vs. separate directory, naming convention
- Type patterns: interfaces vs. types, where definitions live
```

### Module Relationships

Identify how major modules relate to each other:

```
Grep: "import.*from" in src/  → map import relationships
Grep: "require(" in src/      → CommonJS imports
```

### Document Architecture

```markdown
## Architecture

### Pattern
**[Feature-based / Layer-based / MVC / etc.]**

[2-3 sentence description of how code is organized]

### Layer Map
```
[UI Layer]        → components, pages, layouts
    ↓ calls
[API Layer]       → route handlers, middleware, validation
    ↓ calls
[Service Layer]   → business logic, orchestration
    ↓ calls
[Data Layer]      → database queries, external API clients
```

### Module Map
| Module | Location | Responsibility | Depends On |
|--------|----------|----------------|------------|
| Auth | `src/auth/` | Authentication, sessions | Database, Config |
| Podcasts | `src/podcasts/` | Podcast CRUD, playback | Auth, Database, Storage |
| Users | `src/users/` | User profiles, settings | Auth, Database |

### Key Conventions
- **File naming**: [kebab-case for routes, PascalCase for components]
- **Exports**: [named exports, barrel files in each module]
- **API routes**: [RESTful, versioned under /api/v1/]
- **Error handling**: [centralized error middleware in server/middleware/]
- **Testing**: [co-located .test.ts files, Jest with React Testing Library]
- **Types**: [shared types in shared/types.ts, component props inline]
```

## Phase 4: Context

Read project documentation and configuration for intent and constraints.

### Files to Check

| File | What to Extract |
|------|----------------|
| `README.md` | Project purpose, setup instructions, contribution guidelines |
| `CLAUDE.md` | AI agent rules, project-specific conventions |
| `AGENTS.md` | Multi-agent coordination rules |
| `.env.example` | External services and configuration needed |
| `CONTRIBUTING.md` | Development workflow, PR process |
| `CHANGELOG.md` | Recent changes, project velocity |
| `LICENSE` | License type |
| `.gitignore` | What's excluded from version control |

### Document Context

```markdown
## Project Context

### Purpose
[1-2 sentences: what this project does and who it's for]

### Current State
- **Maturity**: [Prototype / MVP / Production / Maintenance]
- **Activity**: [Active development / Stable / Legacy]
- **Test Coverage**: [High / Medium / Low / None]
- **Documentation**: [Well documented / Partially / Sparse]

### Agent Rules (from CLAUDE.md / AGENTS.md)
- [Rule 1]
- [Rule 2]
- [Any project-specific conventions for AI agents]

### External Dependencies
- [Database: PostgreSQL on [host]]
- [Auth: Auth0 / Clerk / custom]
- [Storage: S3 / local filesystem]
- [APIs: Stripe, SendGrid, etc.]

### Security & Safety
- **Auth/authorization model**: [how access is enforced — e.g., Auth0 JWT + admin-role guards]
- **Input handling**: [where untrusted input enters and how it's validated/sanitized]
- **Secrets**: [how keys/secrets are stored and the rule — e.g., env vars only, never committed or logged]
- **Destructive-operation guardrails**: [stated rules — e.g., never drop/delete DB records directly; propose migrations for manual review; no force-push to protected branches]
- **Sensitive data**: [any PII / financial / regulated data handled, and the constraints around it]
- *(Document what the project actually does or states in `CLAUDE.md` / `AGENTS.md` / auth middleware / `.env.example`. Write "none stated" where absent — do not invent policy.)*

### Known Constraints
- [Any noted limitations, tech debt, or planned migrations]
```

## Phase 5: Document

Combine all phases into a single Project Context file.

### Output Location

```
docs/PROJECT-CONTEXT.md
```

Or if a `docs/` directory doesn't exist, place at the project root.

### Full Document Template

```markdown
# Project Context: [Project Name]

**Generated**: [date]
**Generator**: scorpio-project-map skill

---

## Project Structure
[Phase 1 output]

## Technology Stack
[Phase 2 output]

## Architecture
[Phase 3 output]

## Project Context
[Phase 4 output]

---

## Quick Reference

### Common Commands
| Action | Command |
|--------|---------|
| Install dependencies | [npm install / pip install -r requirements.txt] |
| Run dev server | [npm run dev / python manage.py runserver] |
| Run tests | [npm test / pytest] |
| Lint | [npm run lint / ruff check] |
| Build | [npm run build / etc.] |
| Type check | [npm run typecheck / mypy] |

### Entry Points
- **App entry**: [src/index.ts / src/main.py / etc.]
- **API entry**: [server/index.ts / app/main.py / etc.]
- **Config**: [src/config.ts / settings.py / etc.]
```

## Staleness and Refresh

The Project Context document can become stale as the codebase evolves.

### When to Refresh
- After major architectural changes
- After adding a new module or service
- After changing frameworks or key dependencies
- If the document is more than a few weeks old and active development is ongoing

### Partial Refresh
For minor updates, refresh only the affected section rather than re-running the full mapper.

## Scope Modes

### Full Map (default)
Map the entire project. Use for initial onboarding or periodic refresh.

### Focused Map
Map a specific area of the project:
```
"Map the authentication module" → Focus on src/auth/, related tests, and dependencies
"Map the API layer" → Focus on server/routes/, middleware, and service interfaces
```

Produces a scoped version of the same document format.

## What NOT To Do

- Do not make judgments about code quality (that's scorpio-roomba's job)
- Do not suggest improvements or changes (mapping only)
- Do not read every file — sample representative files to identify patterns
- Do not include code snippets in the output (structure and patterns only)
- Do not guess at purpose — if unclear, note it as "unclear purpose"
- Do not modify any project files

## Skill Chain

This skill provides foundational context for other skills:

```
scorpio-project-map ─┬─→ scorpio-roomba (codebase health scan)
                ├─→ scorpio-feature-plan (replaces Phase 1: Explore)
                ├─→ scorpio-bug-investigate (codebase understanding for tracing)
                └─→ Any skill needing project context
```