Docs

# Audit Orchestrator

> Run 20 specialized security audit skills against a Solidity codebase in parallel waves, producing a consolidated report with deduplicated findings.

The `/orc:audit` skill creates a team of 20 teammates organized across 5 sequential waves. Each teammate invokes one audit skill via the `Skill` tool and writes findings to `.audit-work/`. After all waves complete, the orchestrator synthesizes a single report with severity-normalized, deduplicated findings. This page covers:

- [How it works](#how-it-works) — wave execution model and team mechanics
- [Wave breakdown](#wave-breakdown) — what each wave does and why
- [Skill coverage matrix](#skill-coverage-matrix) — all 20 skills with vulnerability types
- [Running an audit](#running-an-audit) — invocation, output, and next steps
- [Architecture diagram](#architecture-diagram) — visual flow of the orchestration

***

## How it works

The audit orchestrator uses Claude Code's team coordination tools to run 20 audit skills in parallel bursts. A single team persists for the entire audit; teammates are spawned in waves of 3-5, each invoking one specialized skill.

|                        | Standalone Agent            | Teammate (with `team_name`)     |
| :--------------------- | :-------------------------- | :------------------------------ |
| **Skill access**       | Cannot invoke skills        | Full skill access               |
| **Coordination**       | None                        | Shared task list + messaging    |
| **Context**            | Isolated                    | Isolated (shared tasks only)    |
| **Use for**            | Simple one-off research     | Parallel skill invocation       |

The team constraint is why the audit uses `TeamCreate` + teammates rather than standalone `Agent()` calls — each teammate needs `Skill` tool access to invoke its assigned audit skill.

### Execution flow

1. **Validate target** — find `.sol` files, create `.audit-work/`
2. **Create team + 20 tasks** — all tasks created upfront via `TaskCreate`
3. **Waves 1-5** — spawn 3-5 teammates per wave in a single message, wait for completion via `TaskList`
4. **Synthesize report** — read all 20 `FINDINGS.md` files, deduplicate, normalize severity, write `REPORT.md`
5. **Shutdown** — broadcast shutdown, `TeamDelete`

Each teammate follows the same protocol:

```
1. TaskUpdate: claim task (status → in_progress)
2. mkdir -p .audit-work/{skill-name}
3. Skill("{skill-name}")
4. Write findings to .audit-work/{skill-name}/FINDINGS.md
5. TaskUpdate: complete (status → completed)
6. SendMessage to team lead: severity summary
```

***

## Wave breakdown

Waves run sequentially — all teammates in a wave must complete before the next wave launches. Within a wave, teammates run in true parallel (spawned in a single assistant message with `run_in_background: true`).

### Wave 1 — Recon (3 teammates)

Maps the attack surface and builds architectural context before domain-specific scanning begins.

| Teammate | Skill | Purpose |
| :------- | :---- | :------ |
| `w1-entry-points` | `entry-point-analyzer` | Map state-changing entry points by access level (public, admin, role-restricted) |
| `w1-audit-prep` | `audit-prep-assistant` | Pre-audit preparation: static analysis, documentation, dead code removal |
| `w1-context` | `audit-context-building` | Line-by-line architectural context: invariants, assumptions, execution flows |

### Wave 2 — Domain Scans A (5 teammates)

Core DeFi protocol vulnerabilities — lending, reentrancy, math, oracles, signatures.

| Teammate | Skill | Purpose |
| :------- | :---- | :------ |
| `w2-lending` | `audit-lending` | Lending/borrowing: premature liquidation, loan closure without repayment, dust griefing |
| `w2-reentrancy` | `audit-reentrancy` | ERC777 callback reentrancy, cross-function reentrancy, read-only reentrancy |
| `w2-math` | `audit-math-precision` | Division-before-multiplication, rounding to zero, decimal mismatches, unsafe downcasts |
| `w2-oracle` | `audit-oracle` | Stale prices, missing L2 sequencer checks, manipulable slot0, circuit breakers |
| `w2-signature` | `audit-signature` | Nonce replay, cross-chain replay, unchecked ecrecover, signature malleability |

### Wave 3 — Domain Scans B (5 teammates)

Staking, state validation, DEX slippage, liquidation incentives, auction manipulation.

| Teammate | Skill | Purpose |
| :------- | :---- | :------ |
| `w3-staking` | `audit-staking` | First depositor theft, reward dilution, flash deposit griefing, stale reward index |
| `w3-state` | `audit-state-validation` | Unchecked ownership transfers, unexpected inputs, missing access control, improper pause |
| `w3-slippage` | `audit-slippage` | Zero minAmountOut, block.timestamp deadlines, on-chain slippage calculation, sandwich attacks |
| `w3-liquidation` | `audit-liquidation` | Missing liquidation rewards, insufficient incentives for small positions, no bad debt handling |
| `w3-auction` | `audit-auction` | Self-bidding timer reset, sequencer downtime starts, insufficient length validation |

### Wave 4 — Domain Scans C (5 teammates)

Deep liquidation analysis (3 specialized skills), concentrated liquidity, and general-purpose scanning.

| Teammate | Skill | Purpose |
| :------- | :---- | :------ |
| `w4-liq-dos` | `audit-liquidation-dos` | Unbounded loops (OOG), data corruption, front-run blocking, callback reverts |
| `w4-liq-calc` | `audit-liquidation-calculation` | Incorrect reward decimals, excessive protocol fees, oracle sandwich self-liquidation |
| `w4-unfair-liq` | `audit-unfair-liquidation` | Missing L2 grace periods, interest while paused, cherry-picked collateral, no LTV gap |
| `w4-clm` | `audit-clm` | Missing TWAP checks, owner rug-pull via TWAP manipulation, stuck tokens from rounding |
| `w4-pashov` | `pashov-solidity-auditor` | Parallel vector-scan across 20+ attack categories with Slither integration |

### Wave 5 — Deep Analysis (2 teammates)

Token integration patterns and development best practices assessment.

| Teammate | Skill | Purpose |
| :------- | :---- | :------ |
| `w5-token` | `token-integration-analyzer` | ERC20/ERC721 conformity, 20+ weird token patterns (fee-on-transfer, rebasing, blocklists) |
| `w5-guidelines` | `guidelines-advisor` | Trail of Bits best practices: architecture, upgradeability, dependencies, testing |

### Excluded

`sc-auditor-security` has interactive user gates (Map-Hunt-Attack methodology with skeptic-judge verification) — run it separately via `/sc-auditor-security <path>` after the automated audit completes.

***

## Skill coverage matrix

Each skill targets a specific vulnerability domain. Not all skills produce findings on every codebase — a non-lending protocol will get "No relevant patterns found" from `audit-lending`.

| Skill | Domain | Key Vulnerabilities |
| :---- | :----- | :------------------ |
| `entry-point-analyzer` | Attack surface | Missing access control, publicly callable privileged ops |
| `audit-prep-assistant` | Preparation | Untested paths, dead code, missing documentation |
| `audit-context-building` | Architecture | Broken invariants, unvalidated preconditions |
| `audit-lending` | Lending | Premature liquidation, asymmetric pause, dust griefing |
| `audit-reentrancy` | Reentrancy | ERC777 callbacks, cross-function, read-only reentrancy |
| `audit-math-precision` | Arithmetic | Div-before-mul, rounding to zero, unsafe downcasts |
| `audit-oracle` | Oracles | Stale prices, no L2 sequencer check, manipulable slot0 |
| `audit-signature` | Signatures | Nonce replay, cross-chain replay, ecrecover zero address |
| `audit-staking` | Staking | First depositor theft, flash griefing, stale index |
| `audit-state-validation` | State | Unchecked ownership, unexpected inputs, missing ACL |
| `audit-slippage` | DEX/Swaps | Zero slippage params, sandwich attacks, fixed fee tiers |
| `audit-liquidation` | Liquidation | No rewards, insufficient incentives, no bad debt handling |
| `audit-auction` | Auctions | Self-bid timer reset, short auction seizure |
| `audit-liquidation-dos` | Liquidation DoS | Unbounded loops, callback reverts, conflicting guards |
| `audit-liquidation-calculation` | Liquidation math | Wrong reward decimals, excessive fees, oracle sandwich |
| `audit-unfair-liquidation` | Liquidation fairness | No grace period, interest while paused, no LTV gap |
| `audit-clm` | CLM | Missing TWAP, owner rug-pull, stuck tokens |
| `pashov-solidity-auditor` | General | 20+ vector categories with Slither + adversarial reasoning |
| `token-integration-analyzer` | Tokens | Fee-on-transfer, rebasing, blocklists, flash mint |
| `guidelines-advisor` | Best practices | Upgradeability, inheritance depth, test coverage |

***

## Running an audit

```bash
# Audit current directory
/orc:audit

# Audit specific project
/orc:audit ~/git/my-defi-protocol

# Audit subdirectory
/orc:audit src/contracts/
```

### Output structure

```
.audit-work/
├── entry-point-analyzer/FINDINGS.md
├── audit-prep-assistant/FINDINGS.md
├── audit-context-building/FINDINGS.md
├── audit-lending/FINDINGS.md
├── audit-reentrancy/FINDINGS.md
├── audit-math-precision/FINDINGS.md
├── audit-oracle/FINDINGS.md
├── audit-signature/FINDINGS.md
├── audit-staking/FINDINGS.md
├── audit-state-validation/FINDINGS.md
├── audit-slippage/FINDINGS.md
├── audit-liquidation/FINDINGS.md
├── audit-auction/FINDINGS.md
├── audit-liquidation-dos/FINDINGS.md
├── audit-liquidation-calculation/FINDINGS.md
├── audit-unfair-liquidation/FINDINGS.md
├── audit-clm/FINDINGS.md
├── pashov-solidity-auditor/FINDINGS.md
├── token-integration-analyzer/FINDINGS.md
├── guidelines-advisor/FINDINGS.md
└── REPORT.md              ← consolidated, deduplicated
```

### Report format

The synthesized `REPORT.md` contains:

- **Executive summary** — total findings, severity breakdown, most critical areas
- **Findings by severity** — Critical/High/Medium/Low with source skill, file:line, and fix
- **Coverage matrix** — which skills ran, finding counts per severity
- **Recon summary** — entry points and architectural context from Wave 1
- **Next steps** — checklist including `/sc-auditor-security` for interactive deep audit

### After the audit

1. Address **Critical** findings immediately
2. Review **High** findings for exploitability
3. Run `/sc-auditor-security <path>` for interactive deep audit with proof generation
4. Check individual `FINDINGS.md` files for skill-specific detail beyond the summary

***

## Architecture diagram

![Audit Orchestrator Flow](./diagrams/skill-audit.png)

The diagram shows the full orchestration: blue orchestrator at top, green recon wave, amber domain scan waves (3 waves of 5), purple deep analysis wave, and red report synthesis at bottom. Skills within each wave run in parallel; waves run sequentially.

***

## Execution rules

| Rule | Why |
| :--- | :-- |
| All teammates use `Skill` tool | Prevents SkillFlattening anti-pattern — skills contain domain knowledge |
| Spawn all wave teammates in one message | True parallel execution, not sequential |
| Max 5 teammates per wave | Diminishing returns + token cost beyond 5 |
| Wait between waves via `TaskList` | Verify completion before launching next wave |
| Use `Task` with `team_name` | Standalone `Agent()` cannot call skills |
| Shutdown before `TeamDelete` | Clean resource release |
| Deduplicate findings in report | Multiple skills may flag the same root cause |
| Normalize severity | Map each skill's scale to Critical/High/Medium/Low |

***

## Known limitations

### Recon output is not consumed by later waves

Wave 1 produces entry point maps and architectural context, but Waves 2-5 teammates never read these files. Domain-specific scans would produce higher-quality findings if they knew the architecture and entry points. For example, `audit-reentrancy` would benefit from knowing which functions are external entry points.

### No teammate failure recovery

If a teammate crashes mid-scan, the wave blocks indefinitely. There is no retry logic, timeout detection, or fallback to skip a failed skill and note the gap in the coverage matrix.

### No wave dependencies in task system

Wave ordering is enforced by the orchestrator's sequencing logic, not by `addBlockedBy` relationships in the task system. The tasks support dependency tracking, but the skill does not use it.

### Report synthesis is manual

The orchestrator reads all 20 `FINDINGS.md` files and manually deduplicates. For complex codebases with extensive findings, this could fill the context window. No deduplication strategy is formally defined.

## See also

- [Arch Skill](./008-arch-skill.md) — Rust project architect with similar wave pattern
- [Prototype Skill](./007-prototype-skill.md) — full-stack prototyping orchestrator
- [Skill Reference](./001-orc-skill-reference.md) — all orc skills overview