---
name: scan
description: "Scan codebase and auto-populate CLAUDE.md with project context (services, ports, test commands, infrastructure). Usage: /scan [section]"
user-invocable: true
arguments: "<section>"
priority: 70
trigger: "scan codebase|scan project|populate claude.md|detect stack"
---

# Codebase Scanner

Scans the project and populates CLAUDE.md with structured sections that agents read at runtime. This is how generic agents learn your specific project.

## When This Runs

- **First install**: `install.sh --setup` triggers a scan automatically
- **On demand**: User runs `/scan` to refresh after codebase changes
- **Targeted**: `/scan services` to only update the Local Dev Services section

## What Gets Scanned

### 1. Local Dev Services

Detect running services and their configuration:

```bash
# Check for frontend frameworks
if [ -f "frontend/package.json" ] || [ -f "package.json" ]; then
    # Read scripts.dev from package.json
    # Detect framework: Next.js (port 3000), Vite (5173), CRA (3000), Vue (5173)
fi

# Check for backend frameworks
if [ -f "backend/requirements.txt" ] || [ -f "requirements.txt" ]; then
    # Detect FastAPI/Django/Flask
    # Default ports: FastAPI 8000, Django 8000, Flask 5000
fi
if [ -f "backend/pyproject.toml" ]; then
    # Read [tool.poetry] or [project] for framework hints
fi

# Check docker-compose.yml for service definitions
if [ -f "docker-compose.yml" ] || [ -f "docker-compose.yaml" ]; then
    # Extract service names, ports, build contexts
fi

# Check for Procfile (Heroku/Railway)
if [ -f "Procfile" ]; then
    # Extract web/worker commands
fi
```

Output the **Local Dev Services** table:

```markdown
## Local Dev Services

| Service  | Port | Directory | Start Command |
|----------|------|-----------|---------------|
| Frontend | 3000 | frontend/ | cd frontend && npm run dev |
| Backend  | 8000 | backend/  | cd backend && source .venv/bin/activate && uvicorn app.main:app --reload --port 8000 |
```

### 2. Test Commands

Detect test frameworks and commands:

```bash
# Python tests
# Look for: pytest.ini, setup.cfg [tool:pytest], pyproject.toml [tool.pytest]
# Check for: ruff.toml, .flake8, mypy.ini

# JavaScript/TypeScript tests
# Look for: jest.config.*, vitest.config.*, playwright.config.*, cypress.config.*
# Read package.json scripts: test, lint, type-check, build
```

Output the **Test Commands** table:

```markdown
## Test Commands

| What | Command | Directory |
|------|---------|-----------|
| Backend tests | pytest | backend/ |
| Backend lint | ruff check . | backend/ |
| Frontend tests | npm test | frontend/ |
| Frontend lint | npm run lint | frontend/ |
| Type check | npx tsc --noEmit | frontend/ |
| E2E tests | npx playwright test | frontend/ |
```

### 3. Infrastructure

Detect deployment configuration:

```bash
# Railway
[ -f "railway.json" ] || [ -f "railway.toml" ]

# Vercel
[ -f "vercel.json" ] || [ -f ".vercel/project.json" ]

# Fly.io
[ -f "fly.toml" ]

# AWS
[ -d ".aws" ] || [ -f "samconfig.toml" ] || [ -f "serverless.yml" ]

# Docker/Kubernetes
[ -f "Dockerfile" ] || [ -d "k8s" ]

# GitHub Actions
ls .github/workflows/*.yml 2>/dev/null
```

Output the **Infrastructure** table:

```markdown
## Infrastructure

| Platform | Service | Notes |
|----------|---------|-------|
| Railway | backend, frontend | Auto-deploy on push to main |
| GitHub Actions | CI/CD | Lint, test, deploy |

Health endpoints: /health, /api/health
```

### 4. Domain

Scan for domain entities and business rules:

```bash
# Look for model files
# SQLAlchemy: models/*.py, models.py
# Django: */models.py
# Prisma: prisma/schema.prisma
# TypeORM: entities/*.ts

# Look for enum/status definitions
# State machines, workflow logic
```

Output the **Domain** section:

```markdown
## Domain

{App name} is a {detected description} with the following core entities:
- {Entity1} (statuses: {enum values})
- {Entity2}

Business rules detected:
- {Rule from enum constraints, validators, etc.}
```

### Section 5: Environments

Detect project environments and populate the `## Environments` section in CLAUDE.md.

**Detection steps:**

1. Scan for `.env.*` files in project root:
   ```bash
   ls .env.* 2>/dev/null | grep -v '.env.example' | grep -v '.env.local'
   ```
   Extract environment names from suffixes (`.env.staging` → staging, `.env.production` → production).

2. Scan CI/CD configs for deploy targets:
   ```bash
   # GitHub Actions
   grep -r 'environment:' .github/workflows/*.yml 2>/dev/null | grep -oP 'environment:\s*\K\w+'
   ```

3. Scan deploy platform configs:
   - `railway.json` → Railway environments
   - `vercel.json` → preview + production
   - `fly.toml` / `fly.*.toml` → Fly.io environments
   - Terraform `environments/` directories

4. ALWAYS include `local` as `development` environment using data from Local Dev Services table.

5. For each environment, populate:
   - **Name**: environment identifier
   - **Type**: `development` | `staging` | `production` | `preview` | `canary`
   - **URL**: from env files, deploy config, or `<!-- TODO -->`
   - **Health**: from Infrastructure section health endpoints or `<!-- TODO -->`
   - **Deploy**: trigger method (manual, branch push, CI/CD)
   - **Branch**: associated git branch or `—`

**Output format in CLAUDE.md:**

```markdown
## Environments

| Name | Type | URL | Health | Deploy | Branch |
|------|------|-----|--------|--------|--------|
| local | development | http://localhost:{port} | /health | manual | — |
| {name} | {type} | {url} | {health} | {deploy} | {branch} |

Access notes: {platform details, env var file locations}
```

**If no remote environments detected:** Write only the local row with a comment:
```markdown
<!-- No remote environments detected. Run /calibrate for full discovery with platform MCP queries. -->
```

## How It Updates CLAUDE.md

1. Read existing CLAUDE.md
2. For each section being updated:
   - If the section exists with `<!-- TODO: -->` placeholders → replace with scanned data
   - If the section exists with real content → **DO NOT overwrite** (user has customized it)
   - If the section doesn't exist → append it
3. Write back the updated CLAUDE.md

**CRITICAL**: Never overwrite sections that the user has already filled in. Only populate empty/placeholder sections.

## Arguments

| User Input | Action |
|-----------|--------|
| `/scan` | Full scan — all 5 sections |
| `/scan services` | Only scan and update Local Dev Services |
| `/scan tests` | Only scan and update Test Commands |
| `/scan infra` | Only scan and update Infrastructure |
| `/scan domain` | Only scan and update Domain |
| `/scan environments` | Only scan and update Environments |

## If No CLAUDE.md Exists

Create one from the template at `~/.claude-agents/templates/CLAUDE.md.template`, then populate it with scanned data.

## Cost

Negligible — inline tools only (bash glob, grep, jq). Deterministic tech-stack detection. No agent spawns.