universal-agent-workflow-template / rules

---
description: "Full expert review protocol. 8-expert, 2-wave deliberation for comprehensive codebase and documentation review. Invoke before major milestones, after shipping feature clusters, or before staging/production deployment."
globs: []
alwaysApply: false
---

# Expert Review Protocol — 8-Expert, 2-Wave Deliberation

Standard quality gate for major milestones. Use when shipping a feature cluster, before production deployment, or after fixing SAST findings.

## When to Invoke

- After shipping a feature cluster (5+ features since last review)
- Before staging or production deployment
- After SAST/security findings are fixed
- At PM discretion for major milestones

## Wave 1: Security Focus (4 parallel subagents)

| Expert | Subagent Type | Focus Area |
|--------|--------------|------------|
| Red Team | `red-team` | Adversarial/offensive: injection surfaces, privilege escalation, logic errors, data leaks, attack paths |
| Security Hardener | `security-hardener` | Blue team/defensive: authorization, credential management, security controls, SAST patterns |
| Code Reviewer | `code-reviewer` | Static analysis: SQL injection, hardcoded secrets, path traversal, unsafe deserialization, type safety, file size |
| Data Flow Guardian | `data-flow-guardian` | Data integrity: authorization scoping, source of truth, transaction safety, PII handling |

## Wave 2: Architecture + Compliance (4 parallel subagents)

| Expert | Subagent Type | Focus Area |
|--------|--------------|------------|
| Solution Architect | `solution-architect` | Architecture compliance: layer rule violations, dependency direction, scope control, file size limits |
| Test Architect | `test-architect` | Coverage + gaps: test coverage for new features, missing edge cases, mock patterns |
| Compliance Auditor | `compliance-auditor` | Regulatory: data retention policies, audit logging, compliance control mapping |
| Infrastructure Engineer | `infrastructure-engineer` | Container + network: manifests, security hardening, container configuration |

## Wave 3: PM Synthesis (after Waves 1-2 complete)

1. Collect all findings from 8 experts
2. Deduplicate (multiple experts flagging the same issue = high confidence)
3. Identify compounding issues (fix A before wiring B)
4. Severity-rank: CRITICAL > HIGH > MEDIUM > LOW
5. Produce consolidated fix plan in batches:
   - **Batch 1** (PM direct): trivial fixes, doc corrections, 1-line changes
   - **Batch 2** (worker brief): code fixes requiring multiple files
   - **Batch 3** (worker brief): structural changes, test additions, quality cleanup
6. Target: 0 CRITICALs, 0 HIGHs remaining (true clean slate)

## Review Brief Format

Each expert receives a brief containing:

1. **Project overview** — 1 paragraph: what this project is, current stats (features, tests, files)
2. **Scope** — what changed since last review: features shipped, files changed, lines added, test count delta
3. **New source files** — full paths, line counts. Experts must read all new files in their domain.
4. **New test files** — full paths, test counts. Experts must read all new test files in their domain.
5. **Modified source files** — file path, change summary, which feature drove the change. Experts review diffs.
6. **Review checklist** — domain-specific checks tailored to the expert's focus area
7. **Known accepted risks** — decisions from prior reviews that should NOT be re-flagged
8. **Deliverable format** — severity, file:line, description, fix, final verdict

## Finding Format (all experts must use)

```
- **Severity:** CRITICAL / HIGH / MEDIUM / LOW
- **File:Line** (if code finding)
- **Description:** What's wrong (specific, not vague)
- **Fix:** Specific remediation (actionable, not "consider improving")

Final verdict: PROCEED / CONDITIONAL / BLOCK
```

## Execution Checklist

```
[ ] 1. PM writes review brief scoped to changes since last review
[ ] 2. PM launches Wave 1 (4 security-focused experts in parallel via Task tool)
[ ] 3. PM collects Wave 1 results
[ ] 4. PM launches Wave 2 (4 architecture/compliance experts in parallel via Task tool)
[ ] 5. PM collects Wave 2 results
[ ] 6. PM synthesizes: deduplicate, identify compounding issues, severity-rank
[ ] 7. PM produces batched fix plan (Batch 1/2/3)
[ ] 8. PM executes Batch 1 directly (trivial fixes)
[ ] 9. PM writes worker briefs for Batch 2 and Batch 3
[ ] 10. Workers implement fixes (commit, do NOT push)
[ ] 11. PM verifies git status, runs post-ship checklist, pushes
[ ] 12. Review results saved to a private review log outside the public repo, or to `docs/reviews/` if safe to publish
```