/audit-prep

name: audit-prep
description: >
  Prepare Solidity projects for a security audit — test coverage, test quality, NatSpec docs,
  code hygiene, dependency health, best-practice enforcement, deployment readiness, and project
  documentation checks. Generates a scored Audit Readiness Report and optionally runs static analysis.
  Trigger on: "prepare for audit", "audit readiness", "pre-audit check", "audit prep", "NatSpec check",
  or any request to review a Solidity codebase before a security review.

Solidity Audit Preparation — Orchestrator

Orchestrate a parallelized audit-prep pipeline. Do NOT perform analysis — discover files, dispatch agents, compile the scored report.

Modes

• **Default:** full pipeline, all 8 phases + static analysis offer.
• **Single phase:** `coverage` | `quality` | `docs` | `hygiene` | `deps` | `practices` | `deploy` | `context`
• **`scan`:** static analysis only.
• **`--fix`:** auto-apply fixes (NatSpec stubs, console removal, pragma locking, SafeERC20 wrapping).
• **`--report <path>`:** write markdown report to file (no ANSI codes).
• **`--no-scan`:** skip static analysis offer.
• **`--scanner <tool>`:** run specific tool without prompting.
• **`--diff <ref>`:** scope to files changed since git ref.
• **`--ci`:** JSON output. Exit 0 if score >= threshold (default 75, `--min-score N`).

Report Format

Clean markdown. Each phase = one table with Status, Finding, and Recommendation columns. Score summary at the end. When rendered via `--report`, produces a polished `.md` file.

The report has these sections in order: 1. Header (project, framework, scope) 2. Phase 1–8, each as a titled section with a results table 3. Score summary table 4. Quick Wins table

Banner

Print the banner from the end of this file before doing anything else — in every mode (full pipeline, single phase, scan, fix). Always use this exact banner. Never generate, invent, or substitute a different banner. Also include it at the top of `--report` markdown files.

Phase section template

## 1. Test Coverage

| Status | Finding | Recommendation |
|--------|---------|----------------|
| FAIL | Compiler warning — unused param in ConfigProvider:288 | Remove or rename the unused parameter |
| PASS | 4/4 contracts have test files | — |
| PASS | Branch coverage: 95.93% | — |

• **Status**: `PASS` or `FAIL`
• **Finding**: concise description of what was checked and the result
• **Recommendation**: specific action to fix (only for FAIL rows; use `—` for PASS)

Score summary

## Score Summary

| Phase | Score |
|-------|-------|
| 1. Test Coverage | 87/100 |
| 2. Test Quality | 85/100 |
| ... | ... |
| **Overall** | **82/100 — Almost Ready** |

Quick Wins

## Quick Wins

| # | Action | Location |
|---|--------|----------|
| 1 | Create deployment scripts | scripts/deploy.ts |
| 2 | Create SECURITY.md with trust assumptions | project root |
| 3 | Add more assertions to thin tests | test/ |

No deduction numbers, no weights, no `[-N]` annotations. The report should read like a professional checklist a dev team can hand to their lead.

Execution

Turn 0 — Banner & Project Selection

First, read the VERSION file and the skill's references path in parallel:

• **Read:** `VERSION` file from this skill's base directory
• **Glob:** `**/references/shared-rules.md` — extract `{ref_path}` (the references/ directory)

Then print the banner (from the end of this file), followed by asking the user where the project is:

{
  "question": "Where is the project you want to prepare for audit?",
  "header": "Project",
  "multiSelect": false,
  "options": [
    {
      "label": "Current directory",
      "description": "Use the current working directory"
    },
    {
      "label": "Local path",
      "description": "Enter a path to a local project"
    },
    {
      "label": "GitHub repo",
      "description": "Enter a GitHub URL — will clone into a temp directory"
    }
  ]
}

If **Current directory**: use the cwd as `{project_dir}`. If **Local path**: user provides a path, use it as `{project_dir}`. If **GitHub repo**: clone with `git clone <url> /tmp/audit-prep-<repo-name>` and use that as `{project_dir}`.

Turn 1 — Discover & Prepare

Make these **parallel tool calls** in ONE message: a. **Bash:** detect framework — check for `foundry.toml`, `hardhat.config.js`, `hardhat.config.ts` b. **Bash:** find in-scope `.sol` files. Exclude `test/`, `script/`, `lib/`, `node_modules/`, `interfaces/`, `mocks/`. Check both `src/` and `contracts/`. If `--diff <ref>`, use `git diff --name-only <ref> -- '*.sol'`. c. **Bash:** find test files — `find test/ -name '*.sol' -o -name '*.ts' -o -name '*.js'` d. **Bash:** count total lines in scope — `wc -l` on discovered source files g. **Bash:** `mkdir -p .audit-prep` -> `{bundle_dir}` = `.audit-prep` (project-relative, so agents can read it) h. **ToolSearch:** `mcp__sc-auditor` (for scan menu in Turn 4)

Then create agent bundles in a **single Bash call**:

# File list (one per line)
printf '%s\n' <in-scope-files> > {bundle_dir}/files.txt

# Agent A — Testing (Phases 1+2)
# Gets: framework, project dir, test metadata, source file list, instructions
{
  printf 'framework: %s\nproject_dir: %s\n\n' "<fw>" "<dir>"
  echo "# Test files:"
  for f in <test-files>; do
    printf '%s (%s lines)\n' "$f" "$(wc -l < "$f")"
  done
  echo ""
  echo "# In-scope source files:"
  cat {bundle_dir}/files.txt
  echo ""
  cat {ref_path}/agents/testing-agent.md
  echo ""
  cat {ref_path}/shared-rules.md
} > {bundle_dir}/agent-a.md

# Agent B — Source Analysis (Phases 3+4+6)
# NO SOURCE CODE — agent uses Grep/Read directly on project files
{
  printf 'project_dir: %s\n\n' "<dir>"
  echo "# In-scope source files:"
  cat {bundle_dir}/files.txt
  echo ""
  cat {ref_path}/agents/source-analysis-agent.md
  echo ""
  cat {ref_path}/shared-rules.md
} > {bundle_dir}/agent-b.md

# Agent C — Infrastructure (Phases 5+