/full-audit — Multi-Agent Comprehensive Code Audit

Trigger & invocation

Activate when the user invokes the skill explicitly (/full-audit) or uses natural-language keywords for a comprehensive audit ("audit", "review", "audit completo", "analisi completa", "controlla il codice", "security check"). Supported forms:

• /full-audit → mode full su intero codebase
• /full-audit differential → audit del delta vs main
• /full-audit differential <base-branch> → delta vs branch specifico
• /full-audit differential HEAD~5 → delta degli ultimi 5 commit
• /full-audit targeted <path> → audit ristretto a <path> (es. src/auth/)
• Flag opzionali: --focus <area> o --skip <area> con area ∈ {security, bugs, flow, ux, types}

For natural-language requests without specific mode, default to full (or ask the user if scope is ambiguous — su codebase LARGE confirma prima).

Promotion history: v1 monolitica → v2 multi-agent il 2026-05-19. v1 archived in ~/.claude/skills/_archived/full-audit-v1/ come reference storico.

Overview

You are the Opus orchestrator of a multi-agent audit pipeline. You delegate vertical analysis to Sonnet specialist workers (one per audit dimension) and a Haiku baseline runner. You aggregate their outputs into a structured report.

Full design rationale: ~/.claude/skills/full-audit/PRP.md.

[Opus orchestrator]
  ├─ Phase A: Triage (codebase recon, mode parse, scope decision)
  ├─ Phase B: Baseline (1× Agent Haiku: linter/type-check/tests/dep-audit/git stats)
  ├─ Phase C: Specialist dispatch (N× Agent Sonnet in parallel, each invoking a vertical skill)
  ├─ Phase D: Aggregation (dedup, severity bump, priority score, narrative synthesis)
  └─ Phase E: Output (.audit/<timestamp>-<sha>.md + .json + INDEX.md append)

Procedure

Phase A — Triage (you, main context)

1. Parse arguments: extract mode and --focus/--skip flags.
2. Reconnaissance via Bash one-shots (output piccolo, mai dump grossi):
   • File count: find . -type f | wc -l (esclude .git, node_modules, dist, build)
   • Languages: identifica estensioni dominanti
   • Project type: presenza di package.json, pyproject.toml, go.mod, Cargo.toml
   • Workflows: presenza di .github/workflows/*.yml
   • Frontend: presenza di .tsx, .vue, .svelte, .jsx
3. Read CLAUDE.md nella project root se esiste → estrai sezione "Aree critiche" → critical_areas: [paths/keywords].
4. Decide codebase size:
   • SMALL: <500 file
   • MEDIUM: 500-2000 file
   • LARGE: >2000 file
5. Decide dispatch plan seguendo le routing rules (sotto). Per LARGE in mode full, applica risk-first: security-defaults + security-sharp-edges + bugs sempre full coverage, altri workers solo su entry point/core e su critical_areas.
6. Comunica il piano all'utente: 1 frase prima di partire. Esempio: "Avvio audit full su MEDIUM codebase (1247 file): 8 worker in parallelo (security×2, supply-chain, agentic-actions, bugs, flow, ux, types). Baseline in corso."

Phase B — Baseline (1× Agent Haiku)

Skip rule (v2.0.1): se mode == targeted AND scope_file_count < 50, Phase B può essere skippata. Imposta baseline: null + baseline_skipped_reason nel JSON aggregated. Negli altri casi (full / differential / targeted con ≥50 file), baseline sempre eseguita.

Se NON skippata: UNA singola chiamata Agent con subagent_type=general-purpose, model=haiku.

Prompt esatto: vedi references/worker_prompts.md#baseline. Sostituisci {project_root}, {languages} con i valori reali.

L'output (JSON) viene incluso come baseline_summary nei prompt dei worker in Phase C. Se skippato, passa baseline_summary: null ai worker.

Phase C — Specialist Dispatch (N× Agent Sonnet in parallel)

Per ogni worker nel dispatch plan, una Agent call con subagent_type=general-purpose, model=sonnet. TUTTE le call nella stessa response per parallelism massimo.

Prompt esatto per ciascun worker: references/worker_prompts.md (sezione "Generic worker template" + "Per-worker methodology").

Aspetta completamento di tutti i worker prima di passare a Phase D.

Phase D — Aggregation (you, main context)

Per ciascun worker output:

1. Parse + Schema Validation (v2.0.2):
   • Parse JSON. Se non parsabile → 1 retry con prompt: "Your previous response was not valid JSON. Return ONLY the JSON object matching the schema. Do not include any markdown fences, preamble, or explanation. Start the response with { and end with }."
   • Validate schema on each finding. Required fields: id, file, line_start (int), line_end (int), category, severity (UPPERCASE enum), confidence (lowercase enum), title, description, evidence, recommendation, scope_relation. Common aliases to detect (and reject): lines (string instead of line_start/line_end), fix (instead of recommendation), flow (extra field), missing evidence, missing scope_relation, severity lowercase, confidence UPPERCASE.
   • Se schema-non-conforming → 1 retry con prompt: "Your previous output used wrong field names or missing required fields. Required field names: line_start (int, not 'lines' string), line_end (int), recommendation (not 'fix'), evidence (use '(see referenced file)' if no snippet), scope_relation ('in_scope' default). Severity values must be UPPERCASE. Re-emit the JSON with correct field names per the schema. See references/worker_prompts.md#required-field-names-v202--critical for examples."
   • Se entrambi i retry falliscono → marca status: "partial" per quel worker e annota in workers_partial[]. Phase D normalizza manualmente i campi noti: lines: "X,Y" → line_start: X, line_end: Y; lines: "X" → line_start: X, line_end: X; fix → recommendation; default evidence: "(no snippet provided)", scope_relation: "in_scope"; severity to UPPERCASE.
   • Se il parsing JSON proprio fallisce dopo retry (non solo schema) → marca status: "failed", prosegui.

2. Dedup (v2.0.1: 2-pass):

   • Pass 1 (strict): raggruppa per chiave (file, line_start // 10, category). Cluster ≥2 da worker diversi → merge.
   • Pass 2 (semantic by domain): sui findings non ancora dedupplicati, raggruppa per (file, |line_start_a − line_start_b| ≤ 20, domain_of(cat_a) ∩ domain_of(cat_b) ≠ ∅). Cluster ≥2 da worker diversi → merge. Il domain_of() mapping è in references/json_schemas.md#category-domain-mapping — alcune category sono in più di un domain.

   Su ogni merge (Pass 1 o 2):

   • Mantieni severity più alta del cluster (originale, pre-bump)
   • Merge recommendation (set union, separator " / ")
   • Bumpa confidence a high
   • Imposta cross_validated_by: [worker1, worker2, ...]
   • Annota dedup_method: "strict" | "domain"

3. Scope relation classification (v2.0.1): per ogni finding (post-dedup), imposta scope_relation:

   • in_scope se file matcha uno dei scope_paths (prefix match)
   • out_of_scope_reachable altrimenti (il worker ha trovato un issue su file esterno seguendo riferimenti)

   I findings out_of_scope_reachable contribuiscono allo scoring globale (sono issue reali), ma il report MD li mostra in una sezione separata "Out-of-scope findings (reachable from scope)".

4. Severity bump da CLAUDE.md: per ogni finding, se file matcha un path/keyword in critical_areas:
   • MEDIUM → effective_severity = HIGH
   • HIGH → effective_severity = CRITICAL
   • LOW o CRITICAL → effective_severity = severity (LOW non bumpato, CRITICAL già al massimo)
   • Imposta severity_bumped: true/false, severity_bump_reason: "matched critical_area: <path>"
   • Bump max +1 anche se file matcha più aree critiche (no cascading)
5. Priority score (usa effective_severity):

   priority_score = effective_severity_rank × (blast_radius_hint || 1) × confidence_rank
   severity_rank:   CRITICAL=4, HIGH=3, MEDIUM=2, LOW=1
   confidence_rank: high=3, medium=2, low=1

6. Sort findings by priority_score desc.
7. Per-dimension scoring (su effective_severity):
   • Status (categorical):
     • FAIL se ≥1 CRITICAL o ≥5 HIGH
     • WARN se 1-4 HIGH o ≥15 MEDIUM
     • PASS altrimenti
   • Score numerico: max(0, 100 − #CRITICAL×30 − #HIGH×10 − #MEDIUM×3 − #LOW×0.5)
8. Overall status/score: stessa formula su tutti i findings aggregati.
9. Narrative synthesis: per ciascuna dimensione, 3-5 righe basate sui findings di quella dimensione (pattern emergenti, hotspot).

Phase E — Output (you, main context)

1. Crea .audit/ nel project root: mkdir -p .audit via Bash.
   • Subito dopo, verifica se .audit/ è in .gitignore: grep -q "^\.audit/" .gitignore 2>/dev/null. Se NON presente, stampa una nota in chat suggerendo a Tony di aggiungerla (.audit/<timestamp>-<sha>.json contiene code snippet in evidence che potrebbero includere dettagli di security issue — non committarli accidentalmente). NON modificare .gitignore automaticamente; solo segnala.
2. Genera timestamp e sha:
   • date -u +"%Y-%m-%d-%H%M" → es. 2026-05-19-1432
   • git rev-parse --short HEAD 2>/dev/null || echo "nogit" → es. abc1234
3. Write report markdown: .audit/<timestamp>-<sha>.md usando template in references/report_template.md.
4. Write JSON aggregated: .audit/<timestamp>-<sha>.json per lo schema in references/json_schemas.md#aggregated-output.
5. Append a .audit/INDEX.md (se non esiste, crea con header # Audit History\n):

   - 2026-05-19 14:32 | full | abc1234 | CRIT:3 HIGH:7 MED:12 LOW:18 | 2026-05-19-1432-abc1234.md

6. Print chat summary (5-10 righe): Executive summary + critical issues count + path al report. Se proposte fix concrete, suggerisci /verify dopo l'applicazione.

Routing rules

workers = []

if mode in [full, targeted]:
    workers += [security-defaults, security-sharp-edges, bugs, flow]
    if has_workflows:        workers += [agentic-actions]
    if has_manifest:         workers += [supply-chain]
    if has_frontend:         workers += [ux]
    if type_files >= 10:     workers += [types]
    if try_catch_count > 30: workers += [silent-failures]

if mode == differential:
    workers += [differential-security, bugs, tests, flow]  # flow scope = delta + 1 hop import
    delta_areas = analyze_delta()  # da git diff stat + path classification
    if 'auth' in delta_areas or 'secrets' in delta_areas:
        workers += [security-defaults, security-sharp-edges]
    if 'frontend' in delta_areas:        workers += [ux]
    if 'types' in delta_areas:           workers += [types]
    if 'error_handling' in delta_areas:  workers += [silent-failures]

if --focus X:  workers = filter_by_area(workers, X)
if --skip X:   workers = exclude_by_area(workers, X)

if codebase_size == LARGE and mode == full:
    workers = prioritize(security_always + critical_paths_only_for_others)

Mapping worker → area (per --focus / --skip):

• security: security-defaults, security-sharp-edges, supply-chain, agentic-actions, differential-security
• bugs: bugs, silent-failures
• flow: flow
• ux: ux
• types: types
• tests: tests

Failure handling

• Worker che fallisce (timeout, JSON malformato dopo retry, esecuzione fallita) → registralo in workers_failed[], prosegui con gli altri.
• Phase B baseline parzialmente fallita (es. test suite rotta) → log warning nel report, prosegui con baseline parziale.
• Zero findings totali da tutti i worker → report valido che dichiara "no significant issues found", PASS overall.
• Codebase non in repo git → ometti sha, branch, git baseline; usa nogit nel filename.
• Phase C: se più della metà dei worker fallisce → considera l'audit partial, annota chiaramente nel report.

Rules

1. Solo trigger esplicito /full-audit. Non attivare su keyword generiche.
2. Read-only: mai modificare codice durante l'audit. Le fix le applica Tony dopo.
3. Output strutturato sempre: MD + JSON. Niente flag --summary.
4. Parallel dispatch: lancia worker Phase C nella stessa response (parallel tool calls).
5. Modelli: Sonnet per worker, Opus solo per orchestrazione/synthesis, Haiku per baseline. Non spawnare worker Opus.
6. Aderisci agli schema JSON in references/json_schemas.md. Se un worker viola lo schema, retry con prompt stringente.
7. Tracciabilità: ogni finding deve avere file, line_start, line_end, worker (chi l'ha trovato).
8. Trasparenza severity bump: se severity_bumped: true, annota nel report con [HIGH ↑ from MEDIUM — critical area: <path>].
9. Non sintetizzare oltre i dati: la narrative synthesis riflette i findings, non aggiunge claim non supportati.
10. Suggerisci /verify solo se sono proposte fix concrete (non solo "consider refactoring X").
11. No nesting di full-audit: questa skill non deve mai invocare sé stessa.
12. Persisti l'artifact: se .audit/ non può essere scritto (permission denied, FS readonly), fallback a /tmp/.audit/ e segnalalo.

References

• ~/.claude/skills/full-audit/PRP.md — design rationale + decisioni risolte
• ~/.claude/skills/full-audit/references/worker_prompts.md — prompt templates per worker
• ~/.claude/skills/full-audit/references/json_schemas.md — schemi JSON (per-worker, baseline, aggregated)
• ~/.claude/skills/full-audit/references/report_template.md — template del report markdown