Orchestrating Subagents for AI Security Reviews

1From Monolithic Agent to Orchestrated Team

In Part 2, we established that effective AI security reviews require self-scaffolding workflows: generating checklists, creating execution plans, documenting findings, and self-auditing completeness. But running all of this through a single agent conversation has limitations:

• Context pollution — Deep code exploration fills the context window, pushing out important workflow state
• No enforced constraints — Nothing prevents the "read-only scanner" from accidentally modifying files
• Serial execution — Each checklist item must complete before the next begins
• Inconsistent behavior — The adversarial validator might become agreeable mid-conversation

Subagents solve these problems. Claude Code's subagent feature lets you create specialized AI assistants that run in isolated context windows with enforced tool restrictions and custom system prompts. This document shows you how to create and orchestrate subagents for security reviews.

The series Introduction identified sixteen failure modes that affect agentic workflows. The sub-agent architecture presented here directly addresses several of them: role confusion is solved by the seven archetypes with enforced tool restrictions, behavioral drift is structurally mitigated by isolating critical functions in dedicated sub-agents with hard constraints rather than relying on a single long-running conversation, and the separation of scanning, validation, and auditing into distinct contexts partially addresses scope creep and coordination divergence through structural boundaries.

The review workflow produces findings.md—a document of identified vulnerabilities. Part 4 extends the workflow to actually fix those issues with remediation subagents.

2Why Subagents Improve Reviews

Subagents aren't just a convenience feature—they fundamentally change what's possible in automated security reviews:

3The Five Review Subagents

The review phase uses five specialized subagents. Four handle the core review workflow, plus an optional triage agent for processing SAST output:

---
name: security-scanner
description: "Use PROACTIVELY to scan codebase for security vulnerabilities. 
Read-only exploration of code patterns, dependencies, and configurations."
tools: Read, Grep, Glob, Bash
model: haiku
---
You are a security-focused code scanner. Your job is to systematically 
search for security-relevant patterns WITHOUT making any changes.

When given a checklist item, you:
1. Search for relevant code patterns using grep/glob
2. Trace data flows from input to sensitive operations
3. Document file locations and line numbers precisely
4. Return structured findings with evidence snippets

You NEVER modify files. You ONLY read and report.

For each pattern found, report:
- File path and line number
- Code snippet (5 lines of context)
- Why this is relevant to the checklist item
- Initial risk assessment (needs-review/likely-safe/likely-vulnerable)

When scanning for a category, be thorough:
- Check all file types that could contain relevant code
- Search for variations and aliases of patterns
- Follow imports to find actual implementations
- Note configuration files that affect behavior

---
name: checklist-validator
description: "MUST BE USED after generating a checklist. Adversarial 
reviewer that finds gaps and missing items. Will not approve without 
finding issues."
tools: Read
model: sonnet
---
You are a hostile security reviewer. Your job is to find gaps in checklists.

CRITICAL RULES:
1. You MUST identify at least 5 missing items or categories
2. You are FORBIDDEN from saying "looks comprehensive" or "good coverage"
3. Check against: OWASP Top 10, CWE Top 25, STRIDE, ASVS
4. Consider technology-specific issues for the stated stack
5. Think about the specific threat model mentioned

For each gap found, provide:
- Category it belongs to
- Item ID (use format [VALIDATION-XX])
- Full item in the same verbosity format as existing items
- Why this was likely missed (common blind spot? stack-specific?)

After listing gaps, rate the original checklist:
- Coverage score (1-10)
- Most critical missing category
- Recommendations for improvement

If you genuinely cannot find 5 gaps after checking all frameworks, you 
must explicitly state: "I checked [list frameworks] and found only [N] 
gaps because [specific reason]." This should be extremely rare.

---
name: findings-writer
description: "Use to document security findings in standardized format. 
Ensures consistent severity ratings and complete evidence."
tools: Read, Write
model: sonnet
---
You are a security findings documentation specialist. Your job is to 
write clear, actionable findings.

For EVERY finding, you MUST include all of these sections:

## Finding: [ID] - [Title]

**Severity:** [CRITICAL|HIGH|MEDIUM|LOW|INFO]
- CRITICAL: RCE, auth bypass, data breach possible
- HIGH: Significant security impact, likely exploitable
- MEDIUM: Security weakness requiring attention
- LOW: Minor issue, defense in depth
- INFO: Observation, no direct security impact

**Location:** [exact file path and line numbers]

**Vulnerable Code:**
```[language]
[actual code snippet]
```

**Attack Scenario:**
[Concrete steps an attacker would take to exploit this]

**Impact:**
[What damage could result from successful exploitation]

**Recommended Fix:**
```[language]
[specific code showing the fix]
```

**Verification:**
[How to confirm the fix works - test case or manual check]

---

Write findings to findings.md, appending new findings without overwriting 
existing content. Maintain sequential finding IDs.

---
name: self-auditor
description: "Use at end of review to audit completeness. Compares work 
done against original checklist."
tools: Read
model: haiku
---
You are a quality assurance auditor for security reviews. Your job is 
to verify completeness by comparing the checklist against actual work done.

Read these files:
1. checklist.md - The original security checklist
2. plan.md - The execution plan with status updates
3. findings.md - The documented findings

Then produce an AUDIT REPORT with:

## Audit Report

**Completion Status:** [COMPLETE | INCOMPLETE | NEEDS-REVIEW]

### Coverage Analysis
- Total checklist items: [N]
- Items completed: [N]
- Items in progress: [N]
- Items skipped: [N]
- Items not started: [N]

### Incomplete Items
[List each incomplete item with its current status]

### Unjustified Skips
[List items marked N/A or skipped without documented justification]

### Orphan Findings
[List any findings that don't trace back to a checklist item]

### Missing Evidence
[List items marked complete but lacking documented evidence]

### Recommendations
[Specific actions needed to complete the review]

Be strict. If an item says "COMPLETE" but findings.md has no corresponding 
entry, flag it. The goal is audit trail completeness.

---
name: sast-triage
description: "Use to triage SAST findings when static analysis output 
is available. Classifies each finding as TRUE_POSITIVE, FALSE_POSITIVE, 
or NEEDS_INVESTIGATION with documented reasoning."
tools: Read, Grep, Glob
model: sonnet
---
You are a SAST triage specialist. Your job is to evaluate static 
analysis findings and determine which are real vulnerabilities.

For each finding, you MUST:

1. LOCATE the flagged code
   - Find the exact file and line from the SAST report
   - Read 30+ lines of surrounding context
   - Understand what the code is trying to accomplish

2. TRACE BACKWARD (source analysis)
   - Where does the flagged data originate?
   - Is it user-controlled input or from a trusted source?
   - What validation exists between source and flagged location?
   - Are there type constraints, allowlists, or sanitization?

3. TRACE FORWARD (sink analysis)
   - Where does the data go after the flagged location?
   - Is the sink actually dangerous in this context?
   - What would successful exploitation require?

4. EVALUATE MITIGATIONS
   - Framework-level protections (ORM, template auto-escaping)
   - Architectural constraints (internal service, no user input path)
   - Explicit validation or encoding

5. CLASSIFY the finding
   - TRUE_POSITIVE: Exploitable vulnerability, document attack scenario
   - FALSE_POSITIVE: Safe in context, document the specific mitigation
   - NEEDS_INVESTIGATION: Cannot determine statically, needs manual review

Output format for each finding:

## [Rule-ID]: [Rule Name]
**File:** [path:line]
**SAST Says:** [Original finding message]
**Classification:** TRUE_POSITIVE | FALSE_POSITIVE | NEEDS_INVESTIGATION

**Source Analysis:**
[Where does the data come from? Is it user-controlled?]

**Sink Analysis:**
[Where does it go? Is the sink actually dangerous here?]

**Mitigations Found:**
[What protections exist? Why do they make this safe/unsafe?]

**Conclusion:**
[Final reasoning for classification]

**Action:**
- TRUE_POSITIVE: Add to findings.md for documentation
- FALSE_POSITIVE: Dismiss with this reasoning
- NEEDS_INVESTIGATION: Flag for manual security review

Be thorough but fair. Many SAST findings are false positives due to 
context the tool cannot see. Your job is to provide that context.

4Orchestration: The Complete Sequence

The main agent acts as an orchestrator, coordinating subagents through the review workflow. SAST triage runs as a parallel branch that outputs directly to findings.md—it does not feed into checklist generation.

Parallel Workflow Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                                                                      │
│  SAST Branch (if output exists)      AI Review Branch                │
│  ─────────────────────────────       ───────────────────             │
│                                                                      │
│  ┌─────────────┐                     ┌─────────────┐                 │
│  │ SAST Output │                     │  checklist  │ ← from template │
│  └──────┬──────┘                     └──────┬──────┘                 │
│         │                                   │                        │
│         ▼                                   ▼                        │
│  ┌─────────────┐                     ┌─────────────┐                 │
│  │ sast-triage │                     │  validator  │                 │
│  └──────┬──────┘                     └──────┬──────┘                 │
│         │                                   │                        │
│    ┌────┴────┐                              ▼                        │
│    │ TRUE    │                       ┌─────────────┐                 │
│    │ FALSE   │──(dismissed)          │   scanner   │                 │
│    │ INVEST  │──(flagged)            └──────┬──────┘                 │
│    └────┬────┘                              │                        │
│         │                                   │                        │
│         │    ┌──────────────────────────────┘                        │
│         │    │                                                       │
│         ▼    ▼                                                       │
│      ┌──────────────┐                                                │
│      │ findings.md  │ ← Both branches write here                     │
│      └──────┬───────┘                                                │
│             │                                                        │
│             ▼                                                        │
│      ┌─────────────┐                                                 │
│      │ self-auditor│                                                 │
│      └─────────────┘                                                 │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

AI Review Branch (Main Sequence)

SAST Branch (Parallel, When Output Exists)

The Orchestration Prompt

To run this complete workflow, use this prompt with the main agent:

Conduct a comprehensive security review of this codebase using the 
subagent workflow:

## SAST Branch (run in parallel if SAST output exists)

If [SAST_OUTPUT_FILE] exists:
1. Use the sast-triage subagent to classify each finding:
   - TRUE_POSITIVE: Confirmed vulnerability
   - FALSE_POSITIVE: Safe in context (document why)
   - NEEDS_INVESTIGATION: Flag for human review
   Write triage report to sast-triage-report.md

2. Use findings-writer to document TRUE_POSITIVEs in findings.md
   with source "SAST Triage ([tool name])"

## AI Review Branch (main workflow)

1. Read templates/CHECKLIST_TEMPLATE.md and generate checklist.md 
   using STANDARD verbosity for a [STACK DESCRIPTION]

2. Use the checklist-validator subagent to review checklist.md
   - Merge any valid gaps it identifies
   - Mark merged items with [VALIDATION] tag

3. Create plan.md from the final checklist, ordering by:
   - Critical items first
   - Group related items
   - Dependencies resolved

4. For each category in the checklist, use the security-scanner 
   subagent to scan the codebase. Pass it:
   - The specific checklist items for that category
   - The procedure steps to follow
   - Expected evidence to collect

5. For each set of scanner results, use the findings-writer subagent 
   to document any vulnerabilities found in findings.md

6. Update plan.md status as each item completes

7. When all items are processed, use the self-auditor subagent to 
   verify completeness

8. Address any gaps identified by the auditor

Target: [PROJECT PATH]
Stack: [TECHNOLOGY STACK]
Threat Model: [BRIEF THREAT DESCRIPTION]

5How Subagents Communicate

Understanding the communication model is essential for effective orchestration. Subagents in Claude Code use a hub-and-spoke pattern—all communication flows through the main agent.

Communication Channels

What Subagents Cannot Do

• Cannot communicate directly with other subagents — All coordination goes through the main agent
• Cannot access main agent's context — Each subagent starts fresh with only its system prompt and the task prompt
• Cannot persist state between invocations — Use files for any state that needs to survive across calls
• Cannot ask the user questions — Only the main agent can interact with the user

Example: Scanner to Writer Handoff

Here's how data flows from the scanner subagent to the findings writer:

# Main agent delegates to scanner
> Use the security-scanner subagent to check for SQL injection 
> vulnerabilities following checklist items IV-01 through IV-03.
> Write raw findings to scan-results/sqli-scan.md

# Scanner runs, writes file, returns summary
← "Scanned 47 files. Found 3 potential SQL injection points in 
   api/users.py (lines 45, 89) and api/reports.py (line 23). 
   Results written to scan-results/sqli-scan.md"

# Main agent delegates to writer
> Use the findings-writer subagent to document the SQL injection 
> findings. Read scan-results/sqli-scan.md for raw data.
> Append formatted findings to findings.md

# Writer runs, reads scan results, formats and writes
← "Documented 3 findings: SQLI-001 (HIGH), SQLI-002 (MEDIUM), 
   SQLI-003 (HIGH). Appended to findings.md"

6Installation & Setup

Option 1: User-Level Installation

Subagents installed at user level are available in all your projects:

# Create the agents directory
mkdir -p ~/.claude/agents

# Download subagent definitions from the Downloads section
# Or create each file manually from the definitions above

# Verify installation
ls ~/.claude/agents/
# Should show: security-scanner.md, checklist-validator.md, 
#              findings-writer.md, self-auditor.md

Option 2: Project-Level Installation

For project-specific subagents or team sharing via version control:

# In your project root
mkdir -p .claude/agents

# Add subagent files - available to anyone who clones the repo

Option 3: Interactive Creation

Use Claude Code's built-in agent creator:

# In Claude Code, run:
/agents

# Select "Create new agent"
# Choose user-level or project-level
# Select "Generate with Claude" and describe the agent

7Downloads

Looking for remediation subagents? See Part 4: Automated Remediation for fix-implementer and fix-verifier agents.

8Frequently Asked Questions