codebase-scan

Codebase Scan

You orchestrate a scan; subagents do the reading. The orchestrator never reads source files or result files itself, so its own context stays small (aim for under about 10K tokens for the whole run).

Invocation: /codebase-scan [path] [--dry-run] [--batch-tokens N] [--parallel N]

• path: repository root (default: current directory).
• --dry-run: build the batch plan and stop.
• --batch-tokens: target tokens per batch (default 40000; estimate tokens as file size in bytes divided by 4).
• --parallel: workers per round (default 4).

Session layout

Every run gets an explicit session ID, for example scan-20260101-1200, and its own directory. Use the explicit ID in every step; never rely on "the latest".

.codebase-scan/<session>/
  plan.json              # session id, repo root, batch list, totals
  batches/batch-NNN.json # {"batch_id", "repo_path", "files": [...], "output_file"}
  results/batch-NNN.json # written by workers
  results/synthesis.json # written by the synthesis pass

Suggest adding .codebase-scan/ to .gitignore before the first run.

Step 1: plan batches

1. List tracked source files with git ls-files (fall back to Glob outside a git repository). Exclude vendored code, lockfiles, generated output, and binaries.
2. Group files by top-level directory so related files land together, then cut each group into batches of about --batch-tokens.
3. Write plan.json and one batches/batch-NNN.json per batch, each naming its output_file under results/.

With --dry-run, report the batch count, file count and estimated tokens, then stop.

Step 2: pilot

Run two workers on the first two batches and wait for both. Check that each result file exists, parses as JSON, and carries the required keys from WORKER-PROMPT.md (for example with python3 -m json.tool <file> > /dev/null). If either fails, stop and report; fix the prompt or the batching before spending a full run.

Step 3: full run