Audit Prep

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+7+8)
{
  printf 'framework: %s\nproject_dir: %s\n\n' "<fw>" "<dir>"
  cat {ref_path}/agents/infrastructure-agent.md
  echo ""
  cat {ref_path}/shared-rules.md
} > {bundle_dir}/agent-c.md

echo "=== Bundles ==="
wc -l {bundle_dir}/agent-*.md

Print: <project> | <framework> | <N> files, <M> lines

Turn 2 — Spawn

First, create 3 tasks so the user sees progress spinners:

Use TaskCreate for each, then immediately set all 3 to in_progress via TaskUpdate.

Then, in the SAME message, spawn 3 parallel Agent calls:

Agent A — Testing (Phases 1 + 2):

Read your full bundle at {bundle_dir}/agent-a.md.
Execute Phases 1 and 2 exactly as specified.
Output ONLY the PHASE/FAIL/PASS structured format from the shared rules.
Do NOT skip any phase. Do NOT add commentary or tables.

Agent B — Source Analysis (Phases 3 + 4 + 6):

Read your full bundle at {bundle_dir}/agent-b.md.
Execute Phases 3, 4, and 6 exactly as specified.
Use Grep and Read to analyze the source files listed in the bundle.
Do NOT read all source files at once — use targeted queries per check.
Output ONLY the PHASE/FAIL/PASS structured format from the shared rules.
Do NOT skip any phase. Do NOT perform vulnerability analysis.

Agent C — Infrastructure (Phases 5 + 7 + 8):

Read your full bundle at {bundle_dir}/agent-c.md.
Execute Phases 5, 7, and 8 exactly as specified.
Output ONLY the PHASE/FAIL/PASS structured format from the shared rules.
Do NOT skip any phase. Do NOT add commentary or tables.

As each agent completes, mark its task as completed via TaskUpdate.

Turn 3 — Score & Report

Parse each agent's output. For each phase, extract:

• PHASE N | line → phase number, name, score
• FAIL | lines → check name, deduction, file, then desc: and fix: on next lines
• PASS | lines → check name, optional note:

Validate: For each expected phase (1–8):

• Missing PHASE N marker → score = 0, add note "(not reported by agent)"
• Missing SCORE: → compute as 100 minus sum of extracted deductions
• No FAIL/PASS lines → flag "(no details reported)"

Compute weighted score:

Verdict: 90–100 Audit Ready | 75–89 Almost Ready | 50–74 Needs Work | <50 Not Ready Override: If Phase 1 (Coverage) score < 90, verdict CANNOT be "Audit Ready" — cap at "Almost Ready" and append "(coverage below 90%)".

Render the report as clean markdown using the format from the Report Format section. The banner is already visible from Turn 1 — do NOT re-print it here. In --report files, include the banner as an uncolored code block at the top.

For each phase, build a table with Status | Finding | Recommendation columns. FAIL rows get a specific recommendation. PASS rows get — in the recommendation column. Group related PASS items into single rows where natural (e.g., "No TODOs, console imports, or commented-out code").

End with the Score Summary table and Quick Wins table. Quick Wins = top 5 most impactful FAIL findings. Each shows the fix action and where to apply it.

If --report <path>: write the markdown to the specified file path. If --ci: JSON {"score": N, "verdict": "...", "phases": [...], "findings": [...]}.