@arthai/agents 1.0.0

package/skills/scan/SKILL.md

@@ -0,0 +1,232 @@
+---
+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>"
+---
+
+# 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.