/audit-project-agents

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.

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:

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', [
      'Qu