Deep Audit: Wave-Based Repo Orchestrator

Run up to 29 custom skills against a repo in 5 sequential waves, presenting results progressively. Wave 1 detects the tech stack. Waves 2-5 dispatch only the skills that match. Each wave completes and reports before the next begins.

The five waves are: Reconnaissance; Code Quality (code-review, anti-slop, anti-ai-prose, code-slimming); Domain-Specific (detected skills only); Security (security-audit then zero-day); and Docs & Hygiene (update-docs, roadmap, git).

After the waves, Steps 7-9 persist findings to docs/local/audits/DEEP-AUDIT.md, write DEEP-AUDIT-TASKS.md, and route SMALL audits to the task list or LARGE audits to a brainstorming skill or generated plans under docs/local/specs/ and docs/local/plans/.

For a quick 4-skill sweep, use full-review instead.

When to use

Major pre-release quality gate where you want every applicable audit lens
First audit of an unfamiliar codebase - understand what's there and what needs fixing
Periodic deep health check on a repo you maintain
Onboarding to a new project - the wave reports build a mental model fast

When NOT to use

Quick quality check on a PR or recent changes - use full-review (4 skills, parallel)
Single-dimension audit (e.g., only security or only code quality) - use the individual skill directly (security-audit, code-review, etc.)
Auditing the skill collection itself - use skill-creator (Mode 3)
Offensive security engagement or CTF - use lockpick directly
Live-system OS administration (running pacman/apt/dnf, fixing a NixOS rebuild, configuring SELinux on a host, debugging an OPNsense appliance) - use the matching distro/appliance skill directly (arch-btw, debian-ubuntu, rhel-fedora, nixos-btw, firewall-appliance). Repo-level audit of OS-related files (PKGBUILDs, debian/, *.spec, flake.nix, pf.conf, etc.) belongs in Wave 3 of this skill

AI Self-Check

Run after Step 9 completes, before concluding the session. Checks cover the full workflow (waves + persistence + routing), not just the wave dispatch phase.

Performance

Inventory first, then choose high-risk slices; avoid full exhaustive scans when focused evidence answers the question.
Run cheap global searches before expensive test suites or dynamic analysis.
Batch findings by subsystem and severity so review effort scales with risk.

Best Practices

State residual risk and skipped areas explicitly.
Separate confirmed findings from hypotheses and follow-up tasks.
Do not mutate the repo during an audit unless the user requested fixes.

Workflow

Step 0: Preflight

Gather context. Run in parallel (guard each with ; true):

Repo state: git rev-parse --show-toplevel and git rev-parse --short HEAD
Branch: git branch --show-current
File count: git ls-files | wc -l

If not a git repo: stop. The audits rely on git context.

Record preflight values. Default {scope} to "full codebase" unless the user specifies a narrower target.

Step 1: Reconnaissance (Wave 1)

Detect which Wave 3 skills apply by scanning for file patterns. Use the detection table and script in references/detection-patterns.md.

Run the detection script from the repo root. It outputs matched skill names, one per line. If the user specified a scope, pass it as the script's first argument to filter detection to that subtree (git ls-files -- path/to/scope instead of the full repo).

After detection, present the recon summary before proceeding. Compute {unmatched_skills} as the 20 Wave 3 candidates minus the matched set. Compute {count} by summing: 4 (Wave 2) + matched Wave 3 skills + 2 (Wave 4) + 3 (Wave 5). Example: if 6 Wave 3 skills match, count = 4 + 6 + 2 + 3 = 15.

In scoped mode, separate Wave 3 matches into two lines: skills matched by files within the scoped subtree, and skills matched only by repo-root manifests (potential false activations from workspace-root deps). Dispatch both sets - the invoked skill will report zero findings if its domain isn't actually in scope. The [root-manifest] separation is for user transparency, not gating.

If the user stated a priority (e.g., "security is top priority"), acknowledge it in the recon summary: "Security is prioritized - it runs in Wave 4 as designed; wave order is fixed because earlier waves feed context into security analysis." Do not reorder waves.

## Wave 1: Reconnaissance

Repo: {repo_name} @ {short_sha} ({branch})
Files: {file_count}
Scope: {scope}
Languages: {detected}

Skills that will run:
  Wave 2 (always): code-review, anti-slop, anti-ai-prose, code-slimming
  Wave 3 (detected): {scoped_matched_skills}
  Wave 3 (root-manifest only): {root_manifest_only_skills}    # scoped mode only; omit line if empty
  Wave 3 (skipped): {unmatched_skills}
  Wave 4 (always): security-audit, zero-day
  Wave 5 (always): update-docs, roadmap, git

Total agents: {count}

Concrete example for a Node+Postgres+Docker+K8s repo with i18n, frontend code, and GitHub Actions (9 Wave 3 skills matched out of 20):

Repo: myorg/api @ a3f91c2 (main)  |  Files: 412  |  Scope: full codebase
Languages: TypeScript, SQL, YAML

Wave 2 (always): code-review, anti-slop, anti-ai-prose, code-slimming
Wave 3 (detected): testing, command-prompt, databases, backend-api, frontend-design, localize, docker, kubernetes, ci-cd
Wave 3 (skipped): terraform, ansible, networking, ai-ml, mcp, arch-btw, debian-ubuntu, rhel-fedora, nixos-btw, firewall-appliance, virtualization
Wave 4 (always): security-audit, zero-day
Wave 5 (always): update-docs, roadmap, git

Total agents: 4 + 9 + 2 + 3 = 18

Step 2: Code Quality (Wave 2)

Dispatch 4 agents in parallel. All four run on every repo.

Agent type (critical for all waves): every agent MUST be dispatched as general-purpose (or equivalent full-access type). Do NOT use feature-dev:*, code-simplifier:*, or other restricted agent types - they lack Skill tool access and cannot invoke custom skills. The agent type controls tool access, not the audit topic.

Context block (passed to every agent in every wave - substitute all {placeholders} with actual preflight values before dispatching):

Context:
- Repo: {repo_root}
- Commit: {short_sha}
- Branch: {branch}
- Languages: {detected_languages}
- File count: {file_count}
- Scope: {scope}
- Audit: deep-audit wave {N}

Replace {N} with the current wave number (2, 3, 4, or 5).

Agents:

#	Skill	Prompt
1	`code-review`	Invoke the `code-review` skill via the Skill tool. Run a full code review on the codebase. Scope: {scope}. Return the complete report.
2	`anti-slop`	Invoke the `anti-slop` skill via the Skill tool. Audit the codebase for machine-generated patterns, over-abstraction, and code quality issues. Scope: {scope}. Return the complete report.
3	`anti-ai-prose`	Invoke the `anti-ai-prose` skill via the Skill tool. Audit all prose (docs, README, comments, docstrings, commit messages) for AI tells. Scope: {scope}. Return the complete report.
4	`code-slimming`	Invoke the `code-slimming` skill via the Skill tool. Audit the codebase for behavior-preserving code slimming, deduplication, and centralization opportunities. Scope: {scope}. Return the complete report.

Present Wave 2 results under:

## Wave 2: Code Quality

### Code Review
{agent 1 report verbatim}

### Slop Check
{agent 2 report verbatim}

### Prose Check
{agent 3 report verbatim}

### Slimming Check
{agent 4 report verbatim}

Step 3: Domain-Specific (Wave 3)

Dispatch only the skills whose detection patterns matched in Wave 1. All matched skills run in parallel.

Generic prompt template (used for most skills):

{context_block}

Invoke the `{skill_name}` skill via the Skill tool, then audit the codebase.
Scope: {scope}. Return the complete report.

Skill-specific overrides (use instead of the generic prompt):

Skill	Override
`testing`	Audit test quality, coverage gaps, flaky test patterns, and missing test scenarios. Do not write new tests - report only.
`command-prompt`	Audit shell scripts, dotfile config, and .env patterns for correctness, portability, and security.
`frontend-design`	Audit frontend UI/UX implementation, visual hierarchy, accessibility, responsive behavior, framework drift, and AI design tells. Do not redesign or edit - report only.
`localize`	Audit i18n completeness. Find hardcoded user-facing strings, validate locale catalogs, check for missing translations.
`ci-cd`	Audit pipeline config for security (SHA pinning, secret exposure), efficiency, and correctness.

All other skills use the generic prompt.

Present results:

## Wave 3: Domain-Specific [{N} of 20 skills matched]

### {Skill Display Name}
{report verbatim}
...

If zero skills matched, skip Wave 3: "Wave 3: skipped - no domain-specific patterns detected."

Step 4: Security (Wave 4)

Run sequentially. Security-audit first, zero-day second.

Agent 1: Security Audit

{context_block}

Invoke the `security-audit` skill via the Skill tool. Run a full security audit.
Scope: {scope}. Return the complete report including SECURITY-AUDIT.md content.

Wait for Agent 1 to complete. Extract the top findings (up to 10, one line each, highest severity first) for Agent 2's context. Include: severity, affected file/area, and a one-sentence description. Do not pass the full verbatim report. If security-audit returned zero findings, pass the string "No critical findings from security-audit - hunt broadly" so the zero-day agent has non-empty context.

Agent 2: Zero-Day Hunt

{context_block}

Invoke the `zero-day` skill via the Skill tool. Hunt for novel vulnerabilities
in the source code. Scope: {scope}.

Prior security-audit findings (for context, avoid duplicating these):
{security_audit_key_findings_summary}

Focus on what the standard audit missed: variant analysis on flagged patterns,
attack surface mapping, deeper inspection of auth/crypto/parsing/deserialization code.
Return the complete report.

Present results:

## Wave 4: Security

### Security Audit
{agent 1 report verbatim}

### Zero-Day Hunt
{agent 2 report verbatim}

SECURITY-AUDIT.md handling: the security-audit skill writes its report to SECURITY-AUDIT.md at the repo root by default. Step 7 relocates this file into docs/local/audits/SECURITY-AUDIT.md (which is gitignored via the docs/local/ entry). Users do not need to add a separate gitignore rule for the root-level file.

Step 5: Docs & Hygiene (Wave 5)

Dispatch three agents in parallel.

#	Skill	Prompt
1	`update-docs`	Invoke the `update-docs` skill via the Skill tool. Run a read-only audit. Find stale docs, instruction-file bloat, broken links, companion-file drift. Do NOT make changes or commit anything.
2	`roadmap`	Invoke the `roadmap` skill via the Skill tool. Audit ROADMAP.md (or equivalent) for drift, stale items, shipped-but-unchecked features, and completeness. If no roadmap exists, note the gap. Do NOT create one.
3	`git`	Invoke the `git` skill via the Skill tool. Audit git configuration, hooks, branch hygiene, signing setup, and commit message conventions. Do NOT make changes.

Present results:

## Wave 5: Documentation & Hygiene

### Docs Sweep
{agent 1 report verbatim}

### Roadmap Check
{agent 2 report verbatim}

### Git Hygiene
{agent 3 report verbatim}

Step 6: Final Summary

After Wave 5 - before the persistence work in Step 7 - present a brief priority-ordered summary to the user:


## Summary

**Critical** (act now):
- {highest severity findings across all waves}

**Important** (act soon):
- {medium severity findings}

**Minor** (when convenient):
- {low severity findings}

Waves completed: {N}/5 | Skills run: {N}/{total_matched} | Failed: {N}

Priority order: security fixes > correctness bugs > test gaps > slop/prose cleanup > code-slimming opportunities > domain-specific issues > doc updates > hygiene.

Step 7: Persist DEEP-AUDIT.md

Consolidate every wave's findings into a single durable report at docs/local/audits/DEEP-AUDIT.md. The terminal summary in Step 6 is ephemeral; this file is the source of truth that Step 8 and downstream planning work from.

Ensure docs/local/ is gitignored. Check .gitignore for an entry covering docs/local/. If missing, append exactly these two lines to the repo-root .gitignore:
```
# Local audit/spec/plan scratchpad (deep-audit output, not tracked)
docs/local/
```
Then verify:
```
git check-ignore -q docs/local/ && echo "gitignored" || echo "NOT gitignored"
```
Do not write any audit artifact until this check passes. Contents include unredacted security findings.
Create the target directory. mkdir -p docs/local/audits/.
Relocate any root-level SECURITY-AUDIT.md. If the security-audit skill wrote SECURITY-AUDIT.md to the repo root (its default), move it into docs/local/audits/. Do not leave two copies.
Write docs/local/audits/DEEP-AUDIT.md. Follow the DEEP-AUDIT.md template in references/report-templates.md (metadata header, headline verdict, scorecard, per-wave sections preserving native format). Overwrite any prior file.

Step 8: Generate DEEP-AUDIT-TASKS.md

Derive a phased, checkbox-tracked action list at docs/local/audits/DEEP-AUDIT-TASKS.md from DEEP-AUDIT.md content. This is the artifact users tick off during execution.

Follow the task-list template in references/report-templates.md: task entry format, priority markers (🔴🟡🔵), finding ID cross-references, the 12-phase ordering heuristic, and the trailing effort-rollup / minimum-release-cut sections.

Step 9: Route to planning

Assess the size and severity of DEEP-AUDIT-TASKS.md and announce the chosen path before acting.

SMALL (all three must hold): <=10 tasks AND <=2 phases AND zero Critical findings.

No execution plan needed.
Present the final summary + path to DEEP-AUDIT-TASKS.md. Work can start directly from the checkboxes.
Stop here.

LARGE (anything that fails the SMALL criteria - i.e., >10 tasks, OR >2 phases, OR any Critical finding):

An execution plan is warranted. Choose one of three strategies, in preference order:

9a. Brainstorming skill handoff (preferred when available). Scan the harness's available-skills list (commonly surfaced in a session <system-reminder>, a skill menu, or ls ~/.claude/skills/ / ls ~/.codex/skills/ equivalents) for any skill whose name or description matches *brainstorm*, *ideation*, or *explore* (common examples: superpowers:brainstorming, gsd-explore, brainstorm). If found, announce:

LARGE audit ({N} tasks, {M} phases). Recommend invoking {skill-name} with docs/local/audits/DEEP-AUDIT-TASKS.md as input to produce an execution master plan in docs/local/specs/ and per-phase plans in docs/local/plans/.

Do not auto-invoke. Brainstorming skills are interactive and the user must drive.

9b. Vanilla harness fallback (when no brainstorming skill is available). Generate the plan files directly from DEEP-AUDIT-TASKS.md. Follow the master-plan and per-phase templates in references/report-templates.md. Write:
- docs/local/specs/{YYYY-MM-DD}-audit-execution-master-plan.md
- docs/local/plans/{YYYY-MM-DD}-audit-phase-{NN}-{slug}.md per non-trivial phase (two-digit phase numbers)
Announce the write, then proceed - this path is mechanical, not interactive.

9c. Stop in headless / non-interactive mode. If the session cannot confirm user intent and no brainstorming skill is available, write the two audit files, announce the recommendation, and stop. The user will pick up in a follow-up session.

Never silently auto-invoke a skill. Never skip writing DEEP-AUDIT.md and DEEP-AUDIT-TASKS.md just because a LARGE plan is being generated - those two files are always produced first and are the input to any planning path.

Step 10: Handle Failures

Note which agent failed and why (timeout, skill not found, permission denied)
Present everything that completed successfully
Do not re-run failed agents unless asked
If a skill is not installed, skip it and note the gap in the wave report header. Do not substitute with a manual review - the value of this audit is in the custom skills themselves

If parallel execution is unavailable: run agents sequentially within each wave. Keep the wave order. Priority within a wave: security-related skills first, then by specificity (more targeted before more general).

If agent dispatch is unavailable: run each skill sequentially in the main conversation, one at a time. Present each result before invoking the next skill. This uses more context but preserves the wave ordering.

Reference Files

references/detection-patterns.md - Wave 3 file-pattern table, runnable detection script, and edge cases. Read before Step 1.
references/report-templates.md - templates for DEEP-AUDIT.md, DEEP-AUDIT-TASKS.md, and Step 9b plan files.
references/exclusions.md - skills deliberately excluded from wave dispatch and why.

Output Contract

See skills/_shared/output-contract.md for the full contract.

Skill name: DEEP-AUDIT
Deliverable bucket: audits
Mode: always-on. Every invocation emits the full contract -- boxed inline header, body summary inline plus per-finding detail in the deliverable file, boxed conclusion, conclusion table.
Deliverable path: docs/local/audits/deep-audit/<YYYY-MM-DD>-<slug>.md
Severity scale: P0 | P1 | P2 | P3 | info (see shared contract).

Related Skills

full-review - the quick 4-skill version (code-review, anti-slop, security-audit, update-docs). Use when speed matters more than depth.
code-review, anti-slop, anti-ai-prose, code-slimming - Wave 2 participants.
security-audit, zero-day - Wave 4 participants.
update-docs, roadmap, git - Wave 5 participants.
testing, command-prompt, databases, backend-api, frontend-design, localize, ai-ml, mcp, docker, kubernetes, terraform, ansible, ci-cd, networking, arch-btw, debian-ubuntu, rhel-fedora, nixos-btw, firewall-appliance, virtualization - Wave 3 candidates (conditional).
code-slimming - Wave 2 maintainability pass for behavior-preserving simplification, deduplication, and centralization opportunities.
skill-creator - audits the skill collection. This skill audits application repos.

Read references/exclusions.md before changing Wave 3 routing.

Rules

General-purpose agents only. Every subagent MUST be general-purpose. Restricted agent types cannot invoke custom skills via the Skill tool.
Custom skills only. Only invoke skills from the iuliandita/skills collection. No built-in reviewers, platform audit modes, or third-party skills. If a skill is unavailable, skip it rather than substituting a manual review.
Wave order is sacred. Execute waves 1-2-3-4-5 in sequence. Never reorder, skip, or merge waves. Within a wave, agents run in parallel (except Wave 4 which is sequential).
Present before proceeding. Each wave's results are shown to the user before the next wave starts. No buffering all results to the end.
Detection gates Wave 3. Only dispatch Wave 3 skills whose file patterns matched in the recon sweep. Do not run terraform on a repo with no .tf files.
Security is sequential. security-audit completes before zero-day starts. Zero-day receives security-audit findings as input context.
Read-only audit, with explicit artifact exceptions. No agent modifies source code, commits, or alters the repo's working tree. The only permitted writes are: (a) audit artifacts under docs/local/audits/ (DEEP-AUDIT.md, DEEP-AUDIT-TASKS.md, relocated SECURITY-AUDIT.md), (b) Step 9b plan files under docs/local/specs/ and docs/local/plans/, and (c) a one-line addition to .gitignore if docs/local/ is not already covered.
Preserve native formats. Each skill produces its own report format. Do not normalize, merge, or editorialize across reports. Cross-wave synthesis is allowed only in three specific places: the Step 6 terminal summary, the headline verdict + scorecard of DEEP-AUDIT.md, and the phased ordering of DEEP-AUDIT-TASKS.md. Everywhere else, native format is preserved verbatim.
Don't stack with full-review. This skill supersedes full-review's coverage. If the user asked for deep-audit, do not also invoke full-review.
Respect scope. When the user specifies a scope, pass it to every agent and filter detection patterns to that scope's file tree.
Always persist DEEP-AUDIT.md and DEEP-AUDIT-TASKS.md. These two files are mandatory output of every run, regardless of audit size or whether an execution plan is generated. Write them under docs/local/audits/. Ensure docs/local/ is in .gitignore first - these artifacts can contain sensitive security detail.
Brainstorming handoff is a recommendation, not an auto-invocation. If a brainstorming/ideation skill is present in the host harness, announce the recommended invocation and stop - the user drives that step. When no brainstorming skill exists, proceed directly to Step 9b plan-file generation (this is deterministic file writing, not skill invocation). Only in headless / non-interactive mode, when neither option is available, fall back to Step 9c (stop and let the user continue in a follow-up session).
Don't hardcode a specific brainstorming skill. The skill collection is tool-agnostic (Claude, Codex, Opencode, others). Match by pattern (*brainstorm*, *ideation*, *explore*) rather than by a single hardcoded name like superpowers:brainstorming.

deep-audit

Deep Audit: Wave-Based Repo Orchestrator

When to use

When NOT to use

AI Self-Check

Performance

Best Practices

Workflow

Step 0: Preflight

Step 1: Reconnaissance (Wave 1)

Step 2: Code Quality (Wave 2)

Step 3: Domain-Specific (Wave 3)

Step 4: Security (Wave 4)

Step 5: Docs & Hygiene (Wave 5)

Step 6: Final Summary

Step 7: Persist DEEP-AUDIT.md

Step 8: Generate DEEP-AUDIT-TASKS.md

Step 9: Route to planning

Step 10: Handle Failures

Reference Files

Output Contract

Related Skills

Rules

More from iuliandita/skills

databases

code-review

prompt-generator

skill-refiner

ci-cd

docker