# auditor-skill — Agent Orchestration

This skill audits with a small team of subagents (see `agents/`) and, when available,
orchestrates Trail of Bits execution tooling vendored at `vendor/trailofbits`.

**Bundled paths.** Every bundled path — scripts, tools, templates, `vendor/trailofbits`, corpus files — is relative to the auditor-skill installation root, never to the working directory, which is usually the audited repository. Command and agent text writes that root as `${CLAUDE_PLUGIN_ROOT}` for what it runs, the skill body as `${CLAUDE_SKILL_DIR}`; corpus files they name by a relative path are read from that root too, and in a file read later, use the absolute root you were given (`OUTPUT-RULES.md` Rule 11e).

## Flow (full audit)

0. **Pre-scan (optional, deterministic).** If `tools/auditor-tools/` is built, `audit-scan` emits the instruction/constraint/PDA/arithmetic map at ~$0 and `audit-mem warm --program-id <id>` loads prior invariants + open false-positive rulings (Rule 11d: from an in-tree `.audit-memory/` only if the auditor created it and `GIT_NO_LAZY_FETCH=1 git --no-pager -c core.fsmonitor=false --icase-pathspecs ls-files -- .audit-memory` prints nothing and exits 0, checked before `mkdir -p .audit-memory && printf '*\n' > .audit-memory/.gitignore` and before every `audit-mem` use; any output, in any letter case, or any error means a fresh store outside the tree, passed as `--db <path outside the tree>`) — seeding `context-builder` with a map instead of a blank repo, and letting `vuln-hunter` auto-suppress findings that carry a prior `FALSE_POSITIVE` ruling (`audit-mem check`). Falls back to the grep walk if the toolchain is absent. See [references/orchestration/pre-scan.md](references/orchestration/pre-scan.md).
1. **`context-builder`** (sonnet) — Phase 0 setup + Phase 0.5 context reconstruction. No verdicts; understanding only.
1b. **`threat-modeler`** (opus) — from the context worksheets + `audit_<n>/intake.md`, emits `audit_<n>/threat-model.md` (asset inventory · actor×capability · trust boundaries) that hands the reviewers attacker goals and seeds report §4.4/§4.6/§4.7. When a bootstrap trigger fires (prior audit or incident, fork provenance, prior audits/incidents next to the target), the bundled collector (`<auditor-skill root>/scripts/threat-model/collect.sh`, never a `scripts/` path relative to the audited repo) first gathers history and prior reports offline into `audit_<n>/bootstrap/`; the agent stays read-only and cites that evidence per goal. No verdicts.
2. **`vuln-hunter`** (opus) — item-by-item walk against in-scope checklists + phase-triggered vectors. Every finding with N ≥ 6 must pass the Rule 5b gate. Delegates SAST / harnesses to Trail of Bits when present (see `references/orchestration/boundary-map.md`).
3. **`economic-analyst`** (opus) — checklist 06 + economic vectors; drives `/economic-sim` (Surfpool mainnet-fork) to quantify profitability for High/Critical economic findings.
4. **`peer-reviewer`** (opus) — independent reconciliation on top-severity findings (N≥8, contested N≥7): re-derives from the code (reusing the context worksheets), delegates to Trail of Bits `fp-check` (local) and `second-opinion` when present — `second-opinion` sends the selected code to an external LLM CLI (OpenAI Codex or Google Antigravity / Gemini), disclosed in the report per `OUTPUT-RULES.md` Rule 11b; emits CONFIRM / DISPUTE / DOWNGRADE. *(Neodyme independent dual-review.)*
5. **`audit-reporter`** (sonnet) — deterministic assembly: Scope Coverage, findings, Phase 4.5 maturity scorecard, remediation roadmap → `audit_<n>/REPORT.md`.

Between review and reconciliation, **`/triage`** batch-dedups the candidate set (root-cause + `audit-mem` suppression/regression), re-applies Rule 5b, and splits real findings from Notes & Nitpicks. On demand for High/Critical findings, **`poc-engineer`** + **`patch-engineer`** (via `/poc` / `/patch`, or `/audit-cycle --with-poc`) emit executable PoCs + verified fix patches (see [references/orchestration/poc-harness.md](references/orchestration/poc-harness.md)).

Cheap lanes: `/quick-scan` and `/diff-audit` skip the full item-by-item walk.

Post-incident: **`/auditor:hunt`** (no alert) and **`/auditor:respond`** (lead in hand) hand all reading and analysis of the incident corpus to the **`incident-responder`** (opus; Read/Grep/Glob/Bash/Write/Edit, no sub-agents) — hypothesis ledger, query-don't-read; the commands spawn `context-builder` for source confirmation and `poc-engineer` for the local PoC; it proposes and never acts on-chain. Its tool list has no MCP tools, so it cannot call a signing or transfer tool. The commands themselves run in your session, where every connected MCP server stays callable; they call no MCP tool. Before a live incident, disconnect or deny write-capable MCP servers (for example, tools that transfer or stake). Its `Bash` can still run the `solana` CLI, which signs with the local default keypair, so the agent never runs a subcommand that signs or sends, and only `OUTPUT-RULES.md` Rule 11a isolated mode with no keypair mounted confines it. Contract: [references/detection-response/README.md](references/detection-response/README.md).

Every agent that builds or runs target code — `poc-engineer`, `patch-engineer`, Trail of Bits harnesses — uses the execution mode recorded at intake (`OUTPUT-RULES.md` Rule 11a); any outside service it contacts is listed in the report (Rule 11b).

Full-lifecycle flows: **`/audit-cycle`** (fully automated → client report) and **`/audit-assist`** (human-in-the-loop, iterative); **`/re-audit`** for fix-review. See [references/audit-lifecycle/methodology.md](references/audit-lifecycle/methodology.md).

## Trail of Bits (vendored submodule)

Trail of Bits provides tool **execution** auditor-skill cannot do in prose (CodeQL/Semgrep taint, fuzzing, coverage, mutation, IR-level zeroize/constant-time analysis). It is a **reference, not a copy** — CC-BY-SA stays with Trail of Bits; auditor-skill's own corpus is MIT. Methodology patterns re-implemented natively are credited in `ATTRIBUTION.md`. If the submodule is not initialized, subagents fall back to native grep checks and say so in the report. The pinned commit is the one README.md names; it moves only through the review in CONTRIBUTING.md §5.