Performs comprehensive codebase audit checking architecture, tech debt, security vulnerabilities, test coverage, documentation, dependencies, and maintainability. Use when auditing a project, assessing codebase health, running security scans, checking for vulnerabilities, reviewing code quality, analyzing tech debt, or asked to audit/analyze the entire codebase.
Audit the codebase like you're inheriting someone else's mess - be thorough and honest. No diplomacy, no softening. Focus on what actually matters: security holes, bugs, maintainability problems, and tech debt. If something is broken or badly done, say it.
Copy this checklist to track your progress:
Codebase Audit Progress:
- [ ] Step 1: Check available tools
- [ ] Step 2: Detect project type and run audits
- [ ] Step 3: Detect tech stack and framework patterns
- [ ] Step 4: Identify and document critical issues
- [ ] Step 5: Generate high-level findings summary
Start by checking what tools you have available:
command -v trufflehog
command -v npm # or pnpm, yarn, pip, cargo, etc.
If any expected tools are missing, list them in your output and ask the user if they want to continue without them. Don't let missing tools block the entire audit.
Figure out the package manager and run the right audit:
package-lock.json → npm audit --jsonpnpm-lock.yaml → pnpm audit --jsonyarn.lock → yarn audit --jsonrequirements.txt / poetry.lock → pip-audit --format json or safety check --jsonCargo.toml → cargo audit --jsongo.mod → go list -json -m all | nancy sleuth*.csproj → dotnet list package --vulnerable --include-transitiveSecret scanning: Need help with TruffleHog? Check references/secret-scanning.md for scanning both current files and git history.
Parse the JSON output from these tools and integrate what you find into the audit report.
TypeScript projects (if tsconfig.json exists):
strict mode is enabled (critical issue if it's false or missing)any is used explicitly (this defeats type safety)as or <Type> (suggest using type narrowing instead)Go projects (if go.mod exists):
go vet ./... and go build ./... to catch obvious issuesgo test -race -short ./... to detect data races_ := patterns) — every one is a potential silent failuregovulncheck ./... if availableOWASP Top 10 checks: See references/owasp-top-10.md for vulnerability patterns and detection commands. Report findings as critical with file:line, what the risk is, and how to fix it.
Accessibility checks: Check references/accessibility-checklist.md for a11y detection commands and testing procedures. Report these as important because they exclude real users from using the app.
Monitoring/Observability: Look for error tracking tools (Sentry, DataDog, NewRelic), structured logging libraries (winston, pino), health check endpoints, and watch out for console.logs making it to production. Report missing observability as important for production systems.
Figure out the tech stack: Need help identifying package managers, frameworks, cloud platforms, or IaC tools? See references/tech-stack-detection.md for the complete detection guide.
Build a summary that covers: language(s), framework, build tools, testing framework, cloud platform, IaC tools, and CI/CD platform.
Framework best practices:
Once you know what framework they're using, check the relevant patterns guide:
Performance testing (if Chrome MCP is available):
If this is a web app and you have access to chrome-devtools MCP:
Don't forget to also check the project structure, documentation quality, and CI/CD setup.
Surface these issues with full context right away - don't bury them:
Security (from tools + manual review)
TypeScript Configuration (if it's a TypeScript project)
any types being used (this defeats the whole point of TypeScript)Breaking Problems
Data Loss Risks
CI/CD Pipeline Security Check for pipeline config files and audit them for security issues:
ls .github/workflows/*.yml .github/workflows/*.yaml azure-pipelines.yml .gitlab-ci.yml 2>/dev/null
If pipeline files exist, see references/ci-cd-security.md for the full checklist. Key things to catch:
pull_request_target with checkout of PR code (secret exfiltration)run: blocksOrganize what you found into categories with counts and brief summaries. Need help with the full category breakdown? Check references/report-template.md.
Categories to cover:
For each one: give a brief assessment, count the major issues, and summarize the patterns you're seeing. Don't list every single detail here - that's what "Areas to Investigate" is for.
Structure your audit report like this (see references/report-template.md for examples):
When the user asks you to investigate a specific area:
Parse the JSON output from security tools and work the findings into your report:
If a tool fails to run, note it and keep going - don't let one tool failure block the entire audit.
Be brutally honest:
any defeats the whole point of TypeScript - call it out as breaking type safetyFocus and priority:
Context matters:
Tone:
Need more detailed guidance? Check these references:
Framework-specific patterns: