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