codebase-survey

Extracts the language-level public API surface of a module — exported symbols, types, functions, classes, traits — using language-aware tooling first (cargo public-api, tsc --emitDeclarationOnly, go doc, pdoc) and import-grep as fallback. Returns a structured listing. Used during a per-module survey.

Computes inbound and outbound dependencies for a module by running the project's native dependency tooling (cargo tree, npm ls, pip-deptree, go mod graph, mvn dependency:tree, etc.). Returns a structured report. Skips cleanly if no native tool is available. Use during a per-module survey to populate the Dependencies section of CODEBASE.md.

Surveys CI/CD pipelines, container builds, deploy manifests, secrets handling, observability hooks, and logging libraries — without executing anything. Returns a structured inventory of what runs where and what watches it. Used during the per-module survey and the repo-level CODEBASE.md.

Discovers raw structural signals about an unknown codebase: build manifests, workspace declarations, top-level layout, and language mix. Returns a structured report. Does NOT infer module boundaries — that synthesis is left to the caller. Use for the first pass of a codebase survey.

Audits a module's test situation: discovers test files, runs the project's test runner in collect-only / list mode to count tests by layer (unit / integration / e2e), and surfaces coverage when readily available. Returns pyramid-shape numbers, not opinions about adequacy. Used during a per-module survey.

Cross-cutting architecture pass after per-module surveys are complete. Reads every <module>/CODEBASE.md and the top-level CODEBASE.md, looks for domain- boundary leaks, coupling hotspots, deviations between stated and actual architecture, and stack inconsistencies. Writes findings to docs/codebase/assessment.md with each finding tagged kind:rule or kind:observation, and synthesises docs/codebase/architecture.md, tech-stack.md, and operations.md from the same inputs. Run after the module burndown, before /codebase-derive-instructions.

Read the assembled codebase survey (CODEBASE.md files, docs/codebase/*.md, assessment findings) and produce a lean, source-anchored CLAUDE.md at the repo root plus one per module that has rules. Lifts kind:rule findings only; observations stay in assessment.md. Verifies length budgets, rule duplication, and code-style leaks before writing. If AGENTS.md exists at the repo root, derive into AGENTS.md instead and write a thin CLAUDE.md that imports it.

Bootstrap a codebase survey: delegate raw structural discovery to the structural-discovery subagent, synthesize the module map (judgment call — stays in the main session), then write the top-level CODEBASE.md plus per-module stub files. Run once per repository, before per-module deep-dives.

Deep-dive survey of one module. Spawns the dep-grapher, api-surface-extractor, wire-api-extractor, test-auditor, and ops-detective subagents in parallel, then assembles the module's CODEBASE.md from their reports. Idempotent — re-running rewrites the file. Trigger after /codebase-survey-init has produced module stubs, or whenever a single module needs a fresh detailed survey. Argument: the module path (relative to repo root).

Incremental refresh of an existing codebase survey. With no argument, each module is diffed from its own recorded surveyed_sha to HEAD. With a commit range or PR# argument, that range is used uniformly. Maps changed paths to affected module docs, dispatches narrowly-scoped subagents for only those modules, then bumps each touched module's surveyed_sha. Model-invocable so it can be wired to a post-merge hook later.