arthai-marketplace

/scan

Scan codebase and auto-populate CLAUDE.md with project context (services, ports, test commands, infrastructure).

Synopsis

/scan [section]

When to use it

• After installing the toolkit, to fill CLAUDE.md’s <!-- TODO --> placeholders with real project data
• After codebase changes (new service, new test framework, new deploy target), to refresh a section
• Not for: deep pattern learning, MCP/agent recommendations, or knowledge-base seeding — that’s /calibrate. Rule of thumb: /scan fills in factual tables (ports, commands, configs) by reading files directly; /calibrate goes further, using an agent to learn coding conventions and recommend tools. New to a project? Run /onboard first — it calls /scan for you automatically.

Quickstart

/scan

What you’ll see: a full scan of all five sections — Local Dev Services, Test Commands, Infrastructure, Domain, and Environments — written into CLAUDE.md as structured tables. Sections with real content (no <!-- TODO --> placeholders) are left untouched; sections that still contain any <!-- TODO --> markers get replaced with scanned data.

Examples

/scan                # full scan — all 5 sections
/scan services       # only Local Dev Services (ports, start commands)
/scan tests          # only Test Commands (test/lint/type-check per directory)
/scan infra          # only Infrastructure (deploy platforms, health endpoints)
/scan domain         # only Domain (core entities, business rules)
/scan environments   # only Environments (local/staging/production table)

What it does

1. Detects local dev services — reads package.json scripts, Python framework files, docker-compose.yml, and Procfile to build the services table (service, port, directory, start command).
2. Detects test commands — finds pytest/ruff/mypy configs and package.json test/lint/type-check scripts, and writes the Test Commands table.
3. Detects infrastructure — looks for platform configs: railway.json or railway.toml, vercel.json or .vercel/project.json, fly.toml, .aws directory or samconfig.toml or serverless.yml, Dockerfile or k8s/, and GitHub Actions workflows — plus health endpoints.
4. Detects the domain — scans model files (SQLAlchemy, Django, Prisma, TypeORM) and enum/status definitions to summarize core entities and business rules.
5. Detects environments — derives environments from .env.* files, CI deploy targets, and platform configs; always includes a local development row. Each row gets name, type, URL, health endpoint, deploy trigger, and branch (with <!-- TODO --> where undiscoverable).
6. Updates CLAUDE.md safely — replaces only sections that are missing or still contain any <!-- TODO --> placeholders (even partially-filled ones). Sections with real, user-written content and no remaining <!-- TODO --> markers are never overwritten. If no CLAUDE.md exists, one is created from the toolkit template first.

There are no confirmation prompts — the scan is deterministic file detection with no agent spawns, and it only fills empty/placeholder sections.

Output & artifacts

• CLAUDE.md — created or updated in the project root with the scanned section tables
• No other files touched; results are immediately readable by every agent and skill

Troubleshooting

Problem / Note	Fix
A section didn’t update	It already has real content with no remaining <!-- TODO --> markers — scan never overwrites fully customized sections; update it by hand or delete the section and re-run
Only see the local row in Environments?	This is expected when no platform configs were detected — check for railway.json/railway.toml, vercel.json/.vercel/project.json, fly.toml, .aws/samconfig.toml/serverless.yml, or run /calibrate for full discovery via platform MCP queries
Wrong port or start command detected	Edit the table directly in CLAUDE.md — your value then sticks (scan won’t touch it again, as long as no <!-- TODO --> markers remain in that row)
<!-- TODO --> markers remain after scanning	Those fields couldn’t be detected from files (e.g. staging URLs) — fill them in manually

Related

• /calibrate — the deep version: patterns, recommendations, knowledge base (runs /scan first when CLAUDE.md is empty)
• /onboard — runs /scan for greenfield projects
• /setup — project bootstrap; its claude-agents module uses /scan to populate CLAUDE.md