codebase-audit

bemgmt's avatarfrom bemgmt

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.

⭐0stars🔀1forks📁View on GitHub🕐Updated Jan 1, 2026
[Architecture Design]

When & Why to Use This Skill

The Codebase Audit skill provides an automated, evidence-based analysis of software repositories to map structure, dependencies, and risks. By integrating advanced tools like repomix, ctags, and git history analysis, it generates a comprehensive overview of system architecture and identifies quality hotspots. This skill is essential for technical due diligence, architectural reviews, and maintaining high-quality code standards in complex engineering environments.

Use Cases

  • New Developer Onboarding: Rapidly map out an unfamiliar codebase to understand its entry points, module relationships, and core logic without manual exploration.
  • Technical Debt & Risk Identification: Detect high-churn areas, oversized files, and untested modules to pinpoint technical debt and maintenance risks.
  • Security & Dependency Auditing: Analyze dependency manifests and data flows to identify potential security vulnerabilities or hidden environment assumptions.
  • Architectural Documentation: Automatically generate a structured summary of a repository's design to assist in system migrations or high-level design reviews.
namecodebase-audit
descriptionAudit 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

  1. List top-level structure (use ls, tree -L 3, rg --files).
  2. Identify entry points (search for main, CLI, or service starts).
  3. 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.