/audit-project

description: Multi-agent code review with iterative improvement
argument-hint: "[scope] [--recent] [--domain AGENT] [--quick] [--create-tech-debt] [--resume]"
allowed-tools: Bash(git:*), Bash(node:*), Read, Write, Edit, Glob, Grep, Task, AskUserQuestion

/audit-project - Multi-Agent Code Review

Comprehensive code review using specialized AI agents with iterative improvement.

Quick Reference

| Phase | Description | Details | |-------|-------------|---------| | 1 | Context & Agent Selection | This file | | 2 | Multi-Agent Review | See `audit-project-agents.md` | | 3-4 | Tech Debt & Fixes | This file | | 5-6 | Verification & Iteration | This file | | 7 | Completion Report | This file | | 8 | GitHub Issues | See `audit-project-github.md` |

Arguments

Parse from $ARGUMENTS:

• **Scope**: Path to review (default: `.`) or `--recent` (last 5 commits only)
• **--domain AGENT**: Review with specific agent only (e.g., `--domain security`)
• **--quick**: Single pass, no iteration (fast feedback)
• **--create-tech-debt**: Force create/update TECHNICAL_DEBT.md
• **--resume**: Resume from existing review queue file

Resume Mode

If `--resume` is provided, reuse the most recent review queue in the platform state dir. Otherwise create a new queue file. See `audit-project-agents.md` for queue handling.

Phase 1: Context Gathering

Platform Detection

# Get plugin root using Node.js helper
PLUGIN_ROOT=$(node -e "const { getPluginRoot } = require('@awesome-slash/lib/cross-platform'); const root = getPluginRoot('audit-project'); if (!root) { console.error('Error: Could not locate audit-project plugin root'); process.exit(1); } console.log(root);")
PLATFORM=$(node "$PLUGIN_ROOT/lib/platform/detect-platform.js")
TOOLS=$(node "$PLUGIN_ROOT/lib/platform/verify-tools.js")

PROJECT_TYPE=$(echo $PLATFORM | jq -r '.projectType')
PACKAGE_MGR=$(echo $PLATFORM | jq -r '.packageManager')

# Detect framework
FRAMEWORK="unknown"
if [ "$PROJECT_TYPE" = "nodejs" ]; then
  [ -n "$(jq -e '.dependencies.react' package.json 2>/dev/null)" ] && FRAMEWORK="react"
  [ -n "$(jq -e '.dependencies.express' package.json 2>/dev/null)" ] && FRAMEWORK="express"
elif [ "$PROJECT_TYPE" = "python" ]; then
  grep -q "django" requirements.txt 2>/dev/null && FRAMEWORK="django"
  grep -q "fastapi" requirements.txt 2>/dev/null && FRAMEWORK="fastapi"
fi

RESUME_MODE=$([ "${ARGUMENTS}" != "${ARGUMENTS%--resume*}" ] && echo "true" || echo "false")

Project Analysis

FILE_COUNT=$(git ls-files | wc -l)
TEST_FILES=$(git ls-files | grep -E '(test|spec)\.' | wc -l)
HAS_TESTS=$( [ "$TEST_FILES" -gt 0 ] && echo "true" || echo "false" )
HAS_DB=$(grep -rq -E "(Sequelize|Prisma|TypeORM)" . 2>/dev/null && echo "true" || echo "false")
HAS_API=$(grep -rq -E "(express|fastify|@nestjs)" . 2>/dev/null && echo "true" || echo "false")
HAS_FRONTEND=$( [ "$(git ls-files | grep -E '\.(tsx|jsx|vue|svelte)$' | wc -l)" -gt 0 ] && echo "true" || echo "false" )
HAS_BACKEND=$(grep -rq -E "(express|fastify|@nestjs|koa|hapi)" . 2>/dev/null && echo "true" || echo "false")
if [ -d ".github/workflows" ] || [ -f ".gitlab-ci.yml" ] || [ -f ".circleci/config.yml" ] || \
  [ -f "Jenkinsfile" ] || [ -f ".travis.yml" ] || [ -f "azure-pipelines.yml" ] || \
  [ -f "bitbucket-pipelines.yml" ]; then
  HAS_CICD="true"
else
  HAS_CICD="false"
fi

Agent Selection

**Always Active:**

• `code-quality-reviewer`: Code quality, error handling, maintainability
• `security-expert`: Security vulnerabilities, auth, input validation
• `performance-engineer`: Performance bottlenecks, algorithms, memory
• `test-quality-guardian`: Test coverage and quality (reports missing tests)

**Conditional:**

• `architecture-reviewer`: Design patterns (if `FILE_COUNT > 50`)
• `database-specialist`: Query optimization (if `HAS_DB=true`)
• `api-designer`: REST best practices (if `HAS_API=true`)
• `frontend-specialist`: Component design (if `HAS_FRONTEND=true`)
• `backend-specialist`: Service and domain logic (if `HAS_BACKEND=true`)
• `devops-reviewer`: CI/CD config (if `HAS_CICD=true`)

Phase 2: Multi-Agent Review

See `audit-project-agents.md` for detailed agent coordination.

**Review queue:** Write findings to a temporary queue file in the platform state dir and keep it updated until all issues are resolved. Remove the file when the queue is empty.

Finding Format (Required)

Every finding MUST include:

• **File:Line**: Exact location (e.g., `src/auth/session.ts:42`)
• **Severity**: critical | high | medium | low
• **Category**: From agent domain
• **Description**: What's wrong and why
• **Code Quote**: 1-3 lines showing issue
• **Suggested Fix**: Specific remediation
• **Effort**: small | medium | large

Example Finding

### Finding: Unsafe SQL Query
**Agent**: security-expert
**File**: src/api/users.ts:87
**Severity**: critical
**Code**:
```typescript
const query = `SELECT * FROM users WHERE id = ${userId}`;

**Fix**: Use parameterized queries. **Effort**: small

## Phase 3: Tech Debt Documentation

If TECHNICAL_DEBT.md exists or `--create-tech-debt`:

```markdown
# Technical Debt

Last updated: $(date -I)

## Summary
**Total Issues**: X | Critical: Y | High: Z | Medium: A | Low: B

## Critical Issues
[Grouped by severity with file:line, description, fix, effort]

## Progress Tracking
- [ ] Issue 1
- [ ] Issue 2

Phase 4: Automated Fixes

Fix Strategy

1. **Auto-fixable** (lint, formatting): Apply directly 2. **Manual fix** (code logic): Implement suggested fix 3. **Design decision required**: Flag as blocked and report to user 4. **False positive**: Mark and remove from review queue

Fix Order

1. Critical severity first 2. Then high → medium → low 3. Then by effort (small → large) 4. Then batch by file

Phase 5: Verification

# Run tests
[ -n "$TEST_CMD" ] && $TEST_CMD
TEST_STATUS=$?

# Run linter
[ -n "$LINT_CMD" ] && $LINT_CMD
LINT_STATUS=$?

# Run build
[ -n "$BUILD_CMD" ] && $BUILD_CMD
BUILD_S