solidity-function-audit-team

What this skill does

# Function Audit (Agent Team)

## Purpose

Perform a comprehensive per-function audit using an agent team with human-in-the-loop review. Stage 0 captures design decisions interactively. Stages 1-3 use agent teams with inter-agent messaging and shared task list. Stage 4 presents findings for developer classification. Stage 5 re-evaluates disputed findings. The lead handles pre-flight, Stage 0, synthesis, Stage 4, and Stage 5 directly — only Stages 1-3 are delegated to teammates.

## Prerequisites

- `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` must be set in `.claude/settings.json` env or shell environment

---

## Pre-Flight Discovery (Lead Only)

### 0. Check for Previous Run
Check if `docs/audit/function-audit/` exists. If it does, ask the user:
- **Archive**: Rename to `docs/audit/function-audit-{YYYY-MM-DD-HHMMSS}/` (using current timestamp) and proceed fresh
- **Overwrite**: Delete contents and proceed
- **Cancel**: Stop execution

If the directory does not exist, proceed normally.

### 1. Identify Project Path
- Use `$ARGUMENTS` as the project path if provided, otherwise use the current working directory.
- Store as `PROJECT_PATH` for all subsequent steps.

### 2. Discover Contracts (lean — Grep only)
Use Glob for `src/**/*.sol` (excluding `src/artifacts/`) to find all source files. Then use Grep for `contract \w+` and `library \w+` to identify contract and library declarations. Do NOT Read entire source files — only Read a specific file when domain grouping is ambiguous (e.g., a function straddles two contracts). The goal is to know file paths + contract names, not to understand the code.

### 3. Discover Functions (lean — Grep only)
Use Grep for `function \w+\(` in each discovered .sol file to find all function declarations. Use Grep context flags (`-A 1` or `-B 1`) to determine visibility from the surrounding lines — do NOT Read full files:
- Collect all `external` and `public` functions
- Also collect `internal` functions (they are often where the real logic lives)
- Skip auto-generated getters and pure view helpers that just return a constant

### 4. Group Into Domains
Group functions into logical domains using these heuristics (in priority order):
1. **Shared modifiers**: Functions sharing the same access control modifier belong together
2. **Shared state writes**: Functions that write to the same state variables belong together
3. **Lifecycle stages**: Functions that form a sequence (request -> process -> claim) belong together
4. **Name prefixes**: Functions with common prefixes (deposit/withdraw, add/remove, register/deregister)

Target 4-10 domains of 3-15 functions each. If the contract has fewer than 15 functions total, use a single domain. If natural grouping exceeds 10 domains, merge the smallest related domains.

### 5. Create Output Directory
```
mkdir -p docs/audit/function-audit/{stage0,stage1,stage2,stage3,verification,review}
```

### 6. Preview Domains
Display to the user:
- Number of contracts found
- Number of functions found
- Domain groupings with function lists
- Proceed to Stage 0 for design decision capture before confirming

### 7. Collect Source File Paths
Build the list of all .sol source file paths (absolute paths) that teammates will need to read. Format as one absolute path per line when substituting into `{source_file_list}` placeholders in teammate prompts.

### 8. Detect Project Characteristics
Scan source files for DeFi-relevant patterns to condition Stage 2/3 prompts:
- **Token interfaces**: Grep for `ERC20`, `ERC721`, `ERC1155`, `ERC4626`, `IERC20`, `SafeERC20` → set `{has_tokens}` true/false
- **Proxy/upgrade patterns**: Grep for `UUPSUpgradeable`, `TransparentProxy`, `Initializable` → set `{has_proxies}` true/false
- **Oracle imports**: Grep for `AggregatorV3Interface`, `IOracle`, `TWAP` → set `{has_oracles}` true/false

---

## Session State Checkpoint

After each completed stage, write `{output_root}/stage-checkpoint.md` using the Write tool (full overwrite). Include:
- `PROJECT_PATH`, `OUTPUT_ROOT`
- `STAGE_STATUS`: key=value pairs for each stage (e.g., `preflight=complete stage0=complete stage1=pending`). Write as a standalone line starting with `STAGE_STATUS:` — this line is machine-parsed by the PreCompact hook.
- `DOMAINS`: one line per domain with slug, name, and function list
- `FLAGS`: `has_tokens`, `has_proxies`, `has_oracles`
- `PATHS`: `design_decisions_file`, `slither_file`, and all stage output file paths known so far
- After Synthesis: `FINDING_TOTALS` with severity counts
- After Stage 4: `REVIEW_RESPONSES_FILE` and `DISPUTED_COUNT`
- `TEAM_NAME`: `function-audit`

Before each stage, read the checkpoint file to confirm all paths and domain groupings. If state has been lost (e.g., after auto-compaction), recover via:
1. `Glob(pattern: "**/docs/audit/function-audit/stage-checkpoint.md")`
2. Read the file to restore all session state
3. Resume from the last completed stage

---

## Stage 0: Design Decisions (Lead Only — interactive)

Capture developer intent before the automated audit. Read `resources/REVIEW_PROMPTS.md` (Stage 0 section) for extraction patterns, confirmation script, and output format. Execute the three phases:

1. **Automated extraction**: Grep source files for NatSpec `@dev` comments, static analysis annotations, intent keywords, and code-level patterns (rounding, access control, upgrades, reentrancy, pausability)
2. **Interactive confirmation**: Present detections grouped by category, ask user to confirm/correct/add context per category
3. **Write output**: Write `docs/audit/function-audit/stage0/design-decisions.md`. Store path as `{design_decisions_file}` for Stage 2 and Stage 3 agent prompts.

### 8. Confirm with User

Display to the user:
- Number of contracts found, functions found, domain groupings
- Design decisions summary (categories and counts)
- Ask for confirmation before proceeding to Stage 1

---

## Slither Integration (Lead Only — between Stage 0 and Stage 1)

Run Slither static analysis if available. This is NOT a teammate — the lead does this directly.

1. Run `which slither` via Bash
2. If not found → display "Slither not detected. Install with `pip install slither-analyzer` for automated static analysis. Continuing without it." → set `{slither_file}` to empty → proceed
3. If found → run `slither . --json /tmp/slither-output.json --exclude-informational --filter-paths "test|script|lib|node_modules" 2>&1 || true`
4. Check if `/tmp/slither-output.json` exists and is non-empty (use Bash: `test -s /tmp/slither-output.json`)
5. If the file doesn't exist or is empty → display "Slither failed to analyze the project (likely a compilation or solc version issue). Continuing without it." → set `{slither_file}` to empty → proceed to Stage 1
6. If the file exists → Read it, map findings (High→HIGH, Medium→MEDIUM, Low→LOW, Informational→INFO), write to `docs/audit/function-audit/stage0/slither-findings.md`
7. Display summary: "Slither found N findings (H high, M medium, L low, I info)"
8. Store path as `{slither_file}` for teammate prompts

Write the initial session state checkpoint. Inform the user: "Checkpoint saved. You may run `/compact preserve audit stage status, domain groupings, and file paths` to free context before agent launch, or say proceed."

---

### 9. Plan Task IDs and Dependency Graph
Before creating tasks, plan out all task IDs and their dependencies:

```
Stage 1 (no deps — start immediately):
  T1: State Variable Map
  T2: Access Control Map
  T3: External Call Map

Stage 2 (blocked by all Stage 1 tasks):
  T4: Domain "{domain_1_name}"      | blockedBy: [T1, T2, T3]
  T5: Domain "{domain_2_name}"      | blockedBy: [T1, T2, T3]
  ...
  T(3+N): Domain "{domain_N_name}"  | blockedBy: [T1, T2, T3]

Stage 3 (blocked by all Stage 2 tasks):
  T(4+N): State Consistency         | blockedBy: [T4 .. T(3+N)]
  T(5+N): Math & Rounding           | blockedBy: [T4 .. T(3+N)]
  T(6+N): Reentrancy & Trust        | blockedBy: [T4 .. T(3+N)]
  T(7+N): Adversarial Se