| name | codebase-audit |
| description | Audit and map a codebase to understand structure, dependencies, and risks. Use when the user asks to audit a repo, understand architecture, or assess codebase quality or health. |
Codebase Audit
Overview
Create a fast, evidence-based map of the repo and highlight risk and quality hotspots.
Inventory
- List top-level structure (use
ls, tree -L 3, rg --files).
- Identify entry points (search for
main, CLI, or service starts).
- Capture dependency manifests (pyproject, package.json, requirements, go.mod).
Required Tool Pass (must run all tools)
Run every tool below and log its output. If any tool is missing, invoke action-gate to install it and block the audit until the full tool pass is complete.
- Use OS-appropriate installers via action-gate (apt/dnf/yum/pacman/brew/choco/scoop) and retry.
rg for search and inventory.tree -L 3 for structure.tokei (or scc or cloc) for LOC; choose one and run it.ctags or a tree-sitter indexer for symbol maps; choose one and run it.git log --stat for hotspots (if repo has history).repomap for a scoped module summary (install if missing).repomix for a full-repo map with ignores applied (install if missing).- Jina embeddings tooling for semantic clustering or duplication hints (install/configure if missing). If API key is required, stop and request it.
Repomap Scope Rules (required)
- Do not run repomap on the full repo if it times out; run it on scoped code folders (
scripts/, skills/, and other non-JS/JSX code dirs).
- If repomap throws tree-sitter query errors for JS/JSX, skip those folders and rely on
ctags for symbol mapping.
- If a target folder lacks
.gitignore, create a minimal .gitignore in that folder before running repomap.
Repomix Rules (required)
- Use repomix for the full-repo map and ensure
node_modules/ and large data dirs are ignored.
- Prefer a local
repomix.config.json or .repomixignore if present; otherwise, generate one (repomix --init) and add ignore patterns.
- Record the output file path and style used (markdown/json/plain).
Long-Run Handling
- If a tool is slow, use
timeout or run under tmux/nohup to avoid session loss. Do not treat this as a fix for tool errors.
Risk and Quality Checks
- Large files, high churn areas, and untested modules.
- Security and PII paths, data flow, and external integrations.
- Configuration, environment assumptions, and hidden dependencies.
Output
- Module map, key flows, and hotspots.
- Findings with severity and suggested next steps.
- Open questions to confirm architecture or intent.
- Note which tools were run vs unavailable.
Acceptance Criteria
- Full tool pass completed with outputs captured.
- Any missing tool is reported and blocks the audit until resolved.
- Environment-specific install commands are documented when blockers occur.
- Repomap outputs are produced for scoped folders, and repomix output is produced for the full repo.
