audit-project-agents — Claude Code command: multi-agent project review
audit-project-agents sends a whole codebase to specialised review agents, each on its own slice of files, and collects their findings in one queue.
MIT ★ 2,003 updated 2026-07-26
/plugin marketplace add composio-community/awesome-claude-plugins
/plugin install audit-project@awesome-claude-pluginsWhat audit-project-agents does
This is the coordination file for phase two of /audit-project. It maps reviewers to files: code-quality-reviewer takes every source file, security-expert handles auth, validation, endpoints and configs, performance-engineer follows hot paths and queries, test-quality-guardian checks tests and spots missing ones. Conditional agents join when the project shows a signal, including database-specialist for models and migrations, api-designer for routes, frontend-specialist for components, devops-reviewer for CI/CD and Dockerfiles.
A Node script seeds a review-queue-*.json file in the platform state directory, then agents launch in parallel through the Task tool. Each either appends JSONL to that queue or returns JSON to the parent, with file, line, severity, description, fix suggestion and confidence. RESUME_MODE=true makes the script reopen the newest queue file.
The seed script resolves the plugin root through @awesome-slash/lib/cross-platform and loads lib/platform/state-dir.js from it. No root means an error and exit code 1, so a broken install stops the phase before any agent runs. architecture-reviewer joins only once the project passes FILE_COUNT > 50; smaller repos never see it.
What it helps with
- run a full project review across parallel agents
- route security, performance and test checks to the right reviewer
- keep findings in a queue file and resume the audit later
- pull in database or API review only where the project needs it
- get findings back as JSON with severity and confidence
Example prompts for the agent
- Run
/audit-projectover the whole repo and merge what the agents find into one queue. - Resume the last audit with
RESUME_MODE=trueand pick up the newestreview-queue-*.json. - Only check security and tests this time, leave the other agents out.
How to install audit-project-agents
1Plugin marketplace
/plugin marketplace add composio-community/awesome-claude-plugins/plugin install audit-project@awesome-claude-plugins2Manually: put the files in place
.claude/commands/audit-project-agents.mdCall it with /audit-project-agents. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/audit-project-agents.mdCall it with /prompts:audit-project-agents. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/audit-project-agents.prompt.mdManually: put the files in place
.gemini/commands/audit-project-agents.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about audit-project-agents
How do I install audit-project-agents in Claude Code?
Add the marketplace with /plugin marketplace add composio-community/awesome-claude-plugins, then run /plugin install audit-project@awesome-claude-plugins. The command ships with the audit-project plugin.
What does audit-project-agents do?
It documents how the second phase of /audit-project splits work between review agents and what shape their findings come back in.
What has to be in place before the review starts?
The plugin root must resolve, because the queue script loads @awesome-slash/lib/cross-platform and lib/platform/state-dir.js from it. Without it the script exits with code 1.
Source text
audit-project-agents.md · MIT
# Phase 2: Multi-Agent Review - Reference
This file contains detailed agent coordination for `/audit-project`.
**Parent document**: `audit-project.md`
**Review Pass Definitions**: See `orchestrate-review` skill for canonical pass definitions (core + conditional). This command uses the same review passes but detects signals from project structure (not just changed files).
## Agent Specialization
### File Filtering by Agent
Each agent reviews only relevant files:
| Agent | File Patterns |
|-------|--------------|
| code-quality-reviewer | All source files (includes error handling) |
| security-expert | Auth, validation, API endpoints, config |
| performance-engineer | Hot paths, algorithms, loops, queries |
| test-quality-guardian | Test files + missing-test signals |
| architecture-reviewer | Cross-module boundaries, core packages |
| database-specialist | Models, queries, migrations |
| api-designer | API routes, controllers, handlers |
| frontend-specialist | Components, state management |
| backend-specialist | Services, domain logic, queues |
| devops-reviewer | CI/CD configs, Dockerfiles |
## Review Queue File
Create a temporary review queue file in the platform state dir. Review passes append JSONL or return JSON for the parent to write.
```javascript
const path = require('path');
const fs = require('fs');
const { getPluginRoot } = require('@awesome-slash/lib/cross-platform');
const pluginRoot = getPluginRoot('audit-project');
if (!pluginRoot) { console.error('Error: Could not locate audit-project plugin root'); process.exit(1); }
const { getStateDirPath } = require(`${pluginRoot}/lib/platform/state-dir.js`);
const stateDirPath = getStateDirPath(process.cwd());
if (!fs.existsSync(stateDirPath)) {
fs.mkdirSync(stateDirPath, { recursive: true });
}
function findLatestQueue(dirPath) {
const files = fs.readdirSync(dirPath)
.filter(name => name.startsWith('review-queue-') && name.endsWith('.json'))
.map(name => ({
name,
fullPath: path.join(dirPath, name),
mtime: fs.statSync(path.join(dirPath, name)).mtimeMs
}))
.sort((a, b) => b.mtime - a.mtime);
return files[0]?.fullPath || null;
}
function safeReadJson(filePath) {
try {
return JSON.parse(fs.readFileSync(filePath, 'utf8'));
} catch (error) {
console.warn(`Review queue unreadable: ${filePath}. Starting fresh.`);
return null;
}
}
const resumeRequested = typeof RESUME_MODE !== 'undefined' && RESUME_MODE === 'true';
let reviewQueuePath = resumeRequested ? findLatestQueue(stateDirPath) : null;
if (!reviewQueuePath) {
reviewQueuePath = path.join(stateDirPath, `review-queue-${Date.now()}.json`);
}
if (!fs.existsSync(reviewQueuePath)) {
const reviewQueue = {
status: 'open',
scope: { type: 'audit', value: SCOPE },
passes: [],
items: [],
iteration: 0,
updatedAt: new Date().toISOString()
};
fs.writeFileSync(reviewQueuePath, JSON.stringify(reviewQueue, null, 2), 'utf8');
} else if (resumeRequested) {
const reviewQueue = safeReadJson(reviewQueuePath) || {
status: 'open',
scope: { type: 'audit', value: SCOPE },
passes: [],
items: [],
iteration: 0,
updatedAt: new Date().toISOString()
};
reviewQueue.status = 'open';
reviewQueue.resumedAt = new Date().toISOString();
reviewQueue.updatedAt = new Date().toISOString();
fs.writeFileSync(reviewQueuePath, JSON.stringify(reviewQueue, null, 2), 'utf8');
}
```
## Agent Coordination
Use Task tool to launch agents in parallel:
```javascript
const agents = [];
const baseReviewPrompt = (passId, role, focus) => `Role: ${role}.
Scope: ${SCOPE}
Framework: ${FRAMEWORK}
Focus on:
${focus.map(item => `- ${item}`).join('\n')}
Write findings to ${reviewQueuePath} (append JSONL if possible). If you cannot write files, return JSON only.
Return JSON ONLY in this format:
{
"pass": "${passId}",
"findings": [
{
"file": "path/to/file.ts",
"line": 42,
"severity": "critical|high|medium|low",
"category": "${passId}",
"description": "Issue description",
"suggestion": "How to fix",
"confidence": "high|medium|low",
"falsePositive": false
}
]
}`;
// Always active agents
agents.push(Task({
subagent_type: "review",
prompt: baseReviewPrompt('code-quality', 'code quality reviewer', [
'Code style and consistency',
'Best practices violations',
'Potential bugs and logic errors',
'Error handling and failure paths',
'Maintainability issues',
'Code duplication'
])
}));
agents.push(Task({
subagent_type: "review",
prompt: baseReviewPrompt('security', 'security reviewer', [
'Auth/authz flaws',
'Input validation and output encoding',
'Injection risks (SQL/command/template)',
'Secrets exposure and unsafe configs',
'Insecure defaults'
])
}));
agents.push(Task({
subagent_type: "review",
prompt: baseReviewPrompt('performance', 'performance reviewer', [
'N+1 queries and inefficient loops',
'Blocking operations in async paths',
'Hot path inefficiencies',
'Memory leaks or unnecessary allocations'
])
}));
agents.push(Task({
subagent_type: "review",
prompt: baseReviewPrompt('test-coverage', 'test coverage reviewer', [
'New code without corresponding tests',
'Missing edge case coverage',
'Test quality (meaningful assertions)',
'Integration test needs',
'Mock/stub appropriateness',
HAS_TESTS ? 'Existing tests: verify coverage depth' : 'No tests detected: report missing tests'
])
}));
// Conditional agents
if (FILE_COUNT > 50) {
agents.push(Task({
subagent_type: "review",
prompt: baseReviewPrompt('architecture', 'architecture reviewer', [
'Module boundaries and ownership',
'Dependency direction and layering',
'Cross-layer coupling',
'Consistency of patterns'
])
}));
}
if (HAS_DB) {
agents.push(Task({
subagent_type: "review",
prompt: baseReviewPrompt('database', 'database specialist', [
'Query optimization and N+1 queries',
'Missing indexes',
'Transaction handling',
'Migration safety'
])
}));
}
if (HAS_API) {
agents.push(Task({
subagent_type: "review",
prompt: baseReviewPrompt('api', 'api designer', [
'REST best practices',
'Error handling and status codes',
'Rate limiting and pagination',
'API versioning'
])
}));
}
if (HAS_FRONTEND) {
agents.push(Task({
subagent_type: "review",
prompt: baseReviewPrompt('frontend', 'frontend specialist', [
'Component boundaries',
'State management patterns',
'Accessibility',
'Render performance'
])
}));
}
if (HAS_BACKEND) {
agents.push(Task({
subagent_type: "review",
prompt: baseReviewPrompt('backend', 'backend specialist', [
'Service boundaries',
'Domain logic correctness',
'Concurrency and idempotency',
'Background job safety'
])
}));
}
if (HAS_CICD) {
agents.push(Task({
subagent_type: "review",
prompt: baseReviewPrompt('devops', 'devops reviewer', [
'CI/CD safety',
'Secrets handling',
'Build/test pipelines',
'Deploy config correctness'
])
}));
}
```
## Finding Consolidation
After all agents complete:
```javascript
function consolidateFindings(agentResults) {
const allFindings = [];
for (const result of agentResults) {
const pass = result.pass || 'unknown';
const findings = Array.isArray(result.findings) ? result.findings : [];
for (const finding of findings) {
allFindings.push({
id: `${pass}:${finding.file}:${finding.line}:${finding.description}`,
pass,
...finding,
status: finding.falsePositive ? 'false-positive' : 'open'
});
}
}
// Deduplicate by pass:file:line:description
const seen = new Set();
const deduped = allFindings.filter(f => {
const key = `${f.pass}:${f.file}:${f.line}:${f.description}`;
if (seen.has(key)) return false;
seen.add(key);
return true;
});
// Sort by severity
const severityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
deduped.sort((a, b) => {
const aRank = severityOrder[a.severity] ?? 99;
const bRank = severityOrder[b.severity] ?? 99;
return aRank - bRank;
});
// Update queue file
const queueState = safeReadJson(reviewQueuePath) || {
status: 'open',
scope: { type: 'audit', value: SCOPE },
passes: [],
items: [],
iteration: 0,
updatedAt: new Date().toISOString()
};
queueState.items = deduped;
queueState.passes = Array.from(new Set(deduped.map(item => item.pass)));
queueState.updatedAt = new Date().toISOString();
fs.writeFileSync(reviewQueuePath, JSON.stringify(queueState, null, 2), 'utf8');
// Group by file
const byFile = {};
for (const f of deduped) {
if (!byFile[f.file]) byFile[f.file] = [];
byFile[f.file].push(f);
}
return {
all: deduped,
byFile,
counts: {
critical: deduped.filter(f => f.severity === 'critical' && !f.falsePositive).length,
high: deduped.filter(f => f.severity === 'high' && !f.falsePositive).length,
medium: deduped.filter(f => f.severity === 'medium' && !f.falsePositive).length,
low: deduped.filter(f => f.severity === 'low' && !f.falsePositive).length
}
};
}
```
## Queue Cleanup
After fixes and re-review, remove the queue file if no open issues remain:
```javascript
const queueState = safeReadJson(reviewQueuePath);
if (!queueState) {
return;
}
const openCount = queueState.items.filter(item => !item.falsePositive).length;
if (openCount === 0) {
if (fs.existsSync(reviewQueuePath)) {
try {
fs.unlinkSync(reviewQueuePath);
} catch (error) {
if (error.code !== 'ENOENT') {
throw error;
}
}
}
}
```
## Framework-Specific Patterns
### React Patterns
```javascript
const reactPatterns = {
hooks_rules: {
description: "React hooks must be called at top level",
pattern: /use[A-Z]\w+\(/,
context: "inside conditionals or loops"
},
state_management: {
description: "Avoid prop drilling, use context or state management",
pattern: /props\.\w+\.\w+\.\w+/
},
performance: {
description: "Use memo/useMemo for expensive computations",
pattern: /\.map\(.*=>.*\.map\(/
}
};
```
### Express Patterns
```javascript
const expressPatterns = {
error_handling: {
description: "Express routes must have error handling",
pattern: /app\.(get|post|put|delete)\(/,
check: "next(err) in catch block"
},
async_handlers: {
description: "Async handlers need try-catch or wrapper",
pattern: /async\s*\(req,\s*res/
}
};
```
### Django Patterns
```javascript
const djangoPatterns = {
n_plus_one: {
description: "Use select_related/prefetch_related",
pattern: /\.objects\.(all|filter)\(\)/
},
raw_queries: {
description: "Avoid raw SQL, use ORM",
pattern: /\.raw\(|connection\.cursor\(\)/
}
};
```
## Pattern Application
```javascript
function applyPatterns(findings, frameworkPatterns) {
if (!frameworkPatterns) return findings;
for (const pattern of Object.values(frameworkPatterns)) {
// Check each finding against framework patterns
for (const finding of findings) {
if (pattern.pattern.test(finding.codeQuote)) {
finding.frameworkContext = pattern.description;
}
}
}
return findings;
}
```
## Review Output Format
```markdown
## Agent Reports
### security-expert
**Files Reviewed**: X
**Issues Found**: Y (Z critical, A high)
Findings:
1. [Finding details with file:line]
2. [Finding details with file:line]
### performance-engineer
**Files Reviewed**: X
**Issues Found**: Y
Findings:
1. [Finding details with file:line]
[... per agent]
## Consolidated Summary
**Total Issues**: X
- Critical: Y (must fix)
- High: Z (should fix)
- Medium: A (consider)
- Low: B (nice to have)
**Top Files by Issue Count**:
1. src/api/users.ts: 5 issues
2. src/auth/session.ts: 3 issues
```
© Community · MIT · composio-community/awesome-claude-plugins