name: audit-project description: "Use when user asks to "review my code", "check for issues", "run code review", "analyze PR quality". Multi-agent iterative review that loops until all critical/high issues are resolved."
/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('@agentsys/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_INSTALL_PATH}}/lib/platform/detect-platform.js")
TOOLS=$(node "{{PLUGIN_INSTALL_PATH}}/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 (ifFILE_COUNT > 50) - •
database-specialist: Query optimization (ifHAS_DB=true) - •
api-designer: REST best practices (ifHAS_API=true) - •
frontend-specialist: Component design (ifHAS_FRONTEND=true) - •
backend-specialist: Service and domain logic (ifHAS_BACKEND=true) - •
devops-reviewer: CI/CD config (ifHAS_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
- •Auto-fixable (lint, formatting): Apply directly
- •Manual fix (code logic): Implement suggested fix
- •Design decision required: Flag as blocked and report to user
- •False positive: Mark and remove from review queue
Fix Order
- •Critical severity first
- •Then high → medium → low
- •Then by effort (small → large)
- •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_STATUS=$? # Overall status VERIFICATION_PASSED=$([ $TEST_STATUS -eq 0 ] && [ $LINT_STATUS -eq 0 ] && [ $BUILD_STATUS -eq 0 ] && echo "true" || echo "false")
Handle Failures
If verification fails:
- •Review recent changes (
git diff) - •Identify breaking fix
- •Rollback:
git restore <file> - •Document as "fix caused regression"
Phase 6: Iteration
const initialReview = /* results from Phase 2 review */;
const initialIssues = Array.isArray(initialReview?.issues) ? initialReview.issues : [];
let iteration = 1;
let remainingIssues = initialIssues;
while (remainingIssues.length > 0) {
const fixResult = applyFixes(remainingIssues);
const verifyResult = runVerification();
if (!verifyResult.passed) {
rollbackFailed(fixResult);
}
const reReviewResult = reReview(fixResult.changedFiles);
remainingIssues = reReviewResult.issues;
if (remainingIssues.length === 0) {
console.log("[OK] Zero issues remaining!");
break;
}
iteration++;
}
Quick Mode
If --quick flag: Single pass, findings only, no fixes.
Phase 6.5: Decision Gate (User)
After each iteration (or after re-review if issues remain), report the queue state and ask the user what to do next.
const openCount = remainingIssues.length;
console.log(`Open issues: ${openCount}`);
console.log(`Queue file: ${reviewQueuePath}`); // set in Phase 2 (audit-project-agents)
const decision = await request_user_input({
questions: [{
header: "Audit Decision",
question: "Review queue still open. What next?",
options: [
{ label: "Continue review", description: "Run another iteration" },
{ label: "Create issues", description: "Stop and create issues" },
{ label: "Update tech debt", description: "Stop and update TECHNICAL_DEBT.md" },
{ label: "Leave queue", description: "Stop and keep queue for resume" }
],
}]
});
const choice = decision[0];
if (choice === 'Continue review') {
// continue loop
} else if (choice === 'Create issues') {
// Create issues and remove queue file
} else if (choice === 'Update tech debt') {
// Update TECHNICAL_DEBT.md and remove queue file
} else if (choice === 'Leave queue') {
// Leave queue file for --resume
break;
}
Phase 7: Completion Report
# Project Review Complete
**Scope**: ${SCOPE} | **Framework**: ${FRAMEWORK}
**Iterations**: ${iteration} | **Duration**: ${duration}
## Summary
**Issues Found**: ${initialCount}
**Issues Fixed**: ${fixedCount}
**Remaining**: ${remainingCount}
## By Severity
- Critical: ${criticalFound} → ${criticalRemaining}
- High: ${highFound} → ${highRemaining}
- Medium: ${mediumFound} → ${mediumRemaining}
- Low: ${lowFound} → ${lowRemaining}
## Verification
- Tests: [OK]/[FAIL]
- Linter: [OK]/[FAIL]
- Build: [OK]/[FAIL]
## Files Changed
${FILE_COUNT} files modified
## Remaining Issues
[List of issues needing attention]
Phase 8: GitHub Issue Creation
See audit-project-github.md for:
- •Creating GitHub issues for deferred items
- •Security issue handling (no public issues)
- •TECHNICAL_DEBT.md cleanup
Error Handling
No Framework Detected
Framework detection failed, using generic patterns.
No Tests Available
No test suite detected. Skipping test-quality-guardian.
All Agents Failed
ERROR: All review agents failed. Try: --recent or specific path for smaller scope.
Usage Examples
/audit-project # Full review /audit-project --recent # Last 5 commits only /audit-project src/api # Specific path /audit-project --domain security # Security audit only /audit-project --quick # Fast feedback, no fixes /audit-project --create-tech-debt # Force tech debt file
Success Criteria
- •[OK] All agents completed review
- •[OK] Evidence-based findings (file:line provided)
- •[OK] Critical issues fixed or documented
- •[OK] Verification passes
- •[OK] TECHNICAL_DEBT.md updated (if enabled)
Begin Phase 1 now.