Codebase Audit Agent Skill

Codebase Audit → Issue → Worktree Fix → PR

End-to-end workflow: systematically review the entire codebase, report findings as GitHub issues, fix each issue in an isolated git worktree, and submit PRs — all in one session.

When to use this skill

Use this skill when you need to:

• Perform a full code review / audit of the codebase
• Proactively find security vulnerabilities, logic bugs, or code quality problems
• Turn code review findings into tracked GitHub issues
• Fix each issue in isolation (worktree per issue) and submit PRs
• Run a periodic codebase health check with automated follow-through
• Audit and fix dependency security vulnerabilities (Dependabot alerts / npm audit)

Do NOT use for:

• Reviewing or fixing a single known bug (use systematic-debugging or direct fix)
• Triaging existing open PRs (use pr-review-fix)
• Processing attribution issues (use mcp-attribution-worktree)
• Feature development or refactoring unrelated to audit findings

Workflow

Phase 1 — Review

• Read references/review-strategy.md for the review scope and checklist.
• Use the code-explorer subagent to read ALL source files in the target directory (default: mcp/src/).
• For each file, systematically check against the review checklist:
• Security: path traversal, injection, unvalidated input, hardcoded secrets, improper error exposure
• Error handling: missing try-catch, swallowed errors, error messages leaking internals
• Type safety: as any, unsafe casts, missing null checks
• Logic bugs: race conditions, incorrect conditionals, unreachable code
• Code quality: dead code, duplication, overly complex functions
• Resource leaks: unclosed connections, missing cleanup
• API design: inconsistent validation, missing required field checks
• Record every finding with: file path, line number(s), category, severity (Critical/High/Medium/Low), description, and suggested fix.
• Dependency scan: Read references/dependency-audit.md and run the Dependabot alert fetch + npm audit to discover vulnerable dependencies. Record each finding using the dependency-audit format.

Phase 2 — Analyze & Classify

• Read references/classification.md for severity definitions and grouping rules.
• Deduplicate findings — merge instances of the same pattern across files.
• Group findings into fix batches — related issues that should be fixed together in one PR.
• Assign severity and priority:
• P0 (Critical): Security vulnerabilities, data loss risks
• P1 (High): Logic bugs, error handling gaps that cause runtime failures
• P2 (Medium): Type safety, code quality issues affecting maintainability
• P3 (Low): Style, naming, minor cleanup
• Present a structured audit report to the user and wait for confirmation before proceeding.

Phase 3 — Create GitHub Issues

• Read references/issue-workflow.md for issue creation guidelines.
• For each fix batch (or individual Critical finding), create a GitHub issue:

   gh issue create --title "<type>(<scope>): <summary>" --body "<structured body>" --label "<severity>,<category>"

• Issue body must include: affected files, line numbers, problem description, expected behavior, and suggested fix approach.
• Link related issues when findings are connected.
• Present the created issues to the user.

Phase 4 — Worktree Fix

• Read references/worktree-fix.md for the isolation and fix procedure.
• For each issue (in priority order):

a. Create an isolated worktree and branch:

      git worktree add ../<repo>-audit-fix-<issue-number> -b fix/<slug>-<issue-number> origin/main

b. Work inside the worktree — never in the main checkout.

c. Implement the fix, keeping changes minimal and focused.

d. Verify locally: cd mcp && npm run build && npm run test

e. Commit with conventional-changelog format:

      git commit -m 'fix(<scope>): 🔒 <english description>

      Closes #<issue-number>'

f. Push and create PR:

      git push github fix/<slug>-<issue-number>
      gh pr create --title "fix(<scope>): 🔒 <summary>" --body "Closes #<issue-number>\n\n<description>" --base main

g. Remove the worktree after PR is created:

      cd <original-dir>
      git worktree remove ../<repo>-audit-fix-<issue-number>

• One worktree per issue. Never mix fixes across worktrees.
• Dependency fixes: For dependency vulnerability batches, follow references/dependency-audit.md Step 4. These can be grouped into a single PR since they modify package.json / package-lock.json.

Phase 5 — Verify & Report

• Read references/verification.md for the verification checklist.
• Check CI status for each PR:

   gh pr checks <number>

• If CI fails, re-enter the worktree, fix, and push again.
• Generate a final audit report summarizing:
• Total findings by category and severity
• Issues created (with links)
• PRs submitted (with links)
• Remaining items that need human decision

Routing

| Task | Read |

| --- | --- |

| What to review and how to check each category | references/review-strategy.md |

| Security severity classification (TSRC-style) | references/security-severity-checklist.md |

| How to classify, deduplicate, and batch findings | references/classification.md |

| How to create well-structured GitHub issues | references/issue-workflow.md |

| How to create worktrees and fix issues in isolation | references/worktree-fix.md |

| How to verify fixes and generate the final report | references/verification.md |

| How to audit and fix dependency vulnerabilities | references/dependency-audit.md |

Git safety rules

• Never force-push unless explicitly asked.
• Never amend commits that are already pushed.
• Always work inside the worktree, not the main checkout.
• Always verify build + test locally before pushing.
• One worktree per issue — never mix fixes.
• Clean up worktrees after PR creation.

Commit conventions

Follow the project's conventional-changelog format:

fix(<scope>): 🔒 <english description>

Closes #<issue-number>

Scope examples: security, deps, error-handling, type-safety, code-quality, cloudrun, database, functions

Minimum self-check

• Did I review ALL source files in the target scope, not just a sample?
• Did I categorize each finding with file, line, severity, and description?
• Did I present the audit report and get user confirmation before creating issues?
• Did I create a separate GitHub issue for each fix batch?
• Did I use an isolated worktree for each fix, not the main checkout?
• Did I verify build + test pass before pushing each fix?
• Did I clean up worktrees after creating PRs?
• Did I generate a final report with links to all issues and PRs?
• Did I check Dependabot alerts and npm audit for dependency vulnerabilities?
• Did I apply the correct fix strategy (upgrade / override / replace / dismiss) for each vulnerable dependency?