# Audit

> |

- **Type:** Skill
- **Install:** `agentstack add skill-jeremylongshore-claude-code-plugins-plus-skills-audit`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jeremylongshore](https://agentstack.voostack.com/s/jeremylongshore)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jeremylongshore](https://github.com/jeremylongshore)
- **Source:** https://github.com/jeremylongshore/claude-code-plugins-plus-skills/tree/main/plugins/ai-agency/hyperflow/skills/audit
- **Website:** https://tonsofskills.com

## Install

```sh
agentstack add skill-jeremylongshore-claude-code-plugins-plus-skills-audit
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Audit

Multi-level code review. Dispatcher — Opus 4.8 (thinking-tier). Workers — Sonnet 4.6.

This skill exercises **Layer 3 (Orchestrator)** and **Layer 9 (Security)**. After the review prints, a **fix gate** asks the user whether to apply the findings — on `Yes`, audit auto-invokes `/hyperflow:scope` with the findings as the spec, which then chains to `/hyperflow:dispatch`.

## Iron Rules

**Failure recovery (DOCTRINE rule 14).** Worker errors, malformed output, NEEDS_REVISION verdicts, and gate failures in every Step follow the canonical policy in [`skills/hyperflow/failure-recovery.md`](../hyperflow/failure-recovery.md). Audit-specific exception: a failed Reviewer at L1/L2 escalates to an L3+ Reviewer at the same severity level rather than aborting — audit exists to catch issues, so a Reviewer failure is best resolved by a more thorough Reviewer, not by stopping the chain.

## Per-Step Agent Map (DOCTRINE rule 12)

| Step | Sub-phase | Worker tier | Thinking tier | Notes |
|---|---|---|---|---|
| 1 — Resolve scope | — | — | — | Mechanical decision (exempt) |
| 2 — Gather context | 2a — Surface mapping | Searcher × 2 (glob + import-graph) | Sonnet Reviewer | Parallel |
| 2 — Gather context | 2b — Semantic indexing | Searcher × 2 (type-system + symbol-graph) | Sonnet Reviewer | Parallel |
| 2 — Gather context | 2c — Convention scan | Searcher × 1 (test patterns + lint config) | Sonnet Reviewer | Justified single-angle |
| 2 — Gather context | 2d — Aggregate coverage gate | — | **Reviewer** (Opus) verifies aggregate coverage | Thinking-tier coverage gate |
| 3 — Review | 3a — L1+L2 (syntax/format/naming) | — | **Reviewer** (Opus) × 2 (different file groups) + Sonnet Reviewer aggregates verdicts | Parallel Opus pair; justified single-tier (Opus are the workers at L1-L2) |
| 3 — Review | 3b — L3 (integration/security) | — | **Reviewer** (Opus) × 2 (integration + security) + Sonnet Reviewer aggregates verdicts | Parallel Opus pair; justified single-tier (L3 requires thinking-tier) |
| 3 — Review | 3c — L4+L5 (perf/scale/a11y/UX) | — | **Reviewer** (Opus) × 2 (perf/scale + a11y/UX) + Sonnet Reviewer aggregates verdicts | Parallel Opus pair; justified single-tier (L4-L5 requires thinking-tier) |
| 4 — Findings synthesis | 4a — Critical findings | Writer × 2 (evidence probe + impact analysis) | Sonnet Reviewer | Parallel |
| 4 — Findings synthesis | 4b — Important findings | Writer × 2 (root-cause probe + fix-path analysis) | Sonnet Reviewer | Parallel |
| 4 — Findings synthesis | 4c — Suggestions + observations | Writer × 2 (pattern analysis + praise identification) | Sonnet Reviewer | Parallel |
| 4 — Findings synthesis | 4d — Memory feedback | Writer × 1 (anti-pattern curation) | Sonnet Reviewer (dedup + compaction validation) | Atomic Worker→Reviewer; runs after 4a/4b/4c complete; with compaction pass when triggered |
| 5 — Severity reconciliation | — | — | Sonnet Reviewer reconciles severity labels from Step 3 sub-phases | Atomic-exempt per DOCTRINE 12.2.8 — reads existing Step 3 labels; no Workers needed |
| 6 — Fix gate | — | — | — | `AskUserQuestion` only (exempt — structural gate) |

## Approval Gates

| Gate | When | Format |
|---|---|---|
| Fix gate | Step 6, after NEEDS_FIX or PASS-with-suggestions | `AskUserQuestion` — fix all / criticals only / no |
| Hard halt | Any `SECURITY_VIOLATION` from the reviewer | Stop, surface the finding; no fix gate |

## Inputs

- **Target** — file path, line range, commit SHA, branch, or PR number provided by the user
- **Default (no target)** — `git diff HEAD` + `git diff --staged`
- **Level flag** — `--level 1` through `--level 5` (default — L2)

## Review Levels

Adapted from [review-levels.md](references/review-levels.md):

| L | Name | Checks |
|---|------|--------|
| 1 | Quick | Syntax, obvious bugs, formatting |
| 2 | Standard | L1 + spec compliance, naming, edge cases |
| 3 | Thorough | L2 + cross-file consistency, integration risks, security |
| 4 | Deep | L3 + architecture, scalability, accessibility |
| 5 | Exhaustive | L4 + adversarial probing, perf profiling, alternatives |

Security scan (hardcoded secrets, injection, path traversal, XSS, missing validation) is mandatory at L3+. See [security.md](references/security.md).

## Flow

### Step 1 — Resolve scope

Use the provided target or run `git diff HEAD` + `git diff --staged`. No agent dispatched (read-only git).

### Step 2 — Gather context

Sub-phases 2a, 2b, 2c run in parallel (P1). Step 2 output is the union of their worker outputs plus three sub-phase Reviewer verdicts, handed to an Opus aggregate coverage gate.

#### Step 2a — Surface mapping

Dispatch two Searcher agents in parallel:
- Searcher — glob discovery (file extensions, directory tree, entry points)
- Searcher — import-graph traversal (follow `import`/`require`/`use` chains from touched files)

Then dispatch `Sonnet Reviewer — 2a surface mapping coverage check`. Verdict ∈ {`PASS`, `NEEDS_REVISION`, `ESCALATE`}. On `NEEDS_REVISION`, re-dispatch only 2a.

#### Step 2b — Semantic indexing

Dispatch two Searcher agents in parallel:
- Searcher — type-system probe (interface/schema definitions relevant to changed symbols)
- Searcher — symbol-graph probe (callsites, usages, exported references of changed symbols)

Then dispatch `Sonnet Reviewer — 2b semantic indexing coverage check`. Verdict as above.

#### Step 2c — Convention scan

Dispatch one Searcher agent (single-angle justified — test patterns and lint config are a single orthogonal corpus with no independent axis to fan out across):
- Searcher — convention scan (existing test patterns, lint rules, naming conventions, code-style config)

Then dispatch `Sonnet Reviewer — 2c convention scan coverage check`. Verdict as above.

#### Step 2d — Aggregate coverage gate

After 2a + 2b + 2c complete, dispatch `**Reviewer** (Opus) — verifying aggregate context coverage` to confirm the combined surface covers all subsystems relevant to the diff. On coverage gap: re-dispatch the affected sub-phase (max 2 retries); surface gap to user if retries exhausted.

### Step 3 — Review

Sub-phases 3a, 3b, 3c run in parallel (P1) — each ends with a Sonnet sub-phase aggregator before the next batch fires. Active sub-phases scale with `--level`: L1-L2 runs only 3a; L3 adds 3b; L4-L5 add 3c.

#### Step 3a — L1+L2: syntax, formatting, naming

Dispatch two Reviewer agents in parallel over different file groups (split by directory or feature boundary):
- **Reviewer** (Opus) — L1+L2 review, file group A (syntax errors, obvious bugs, formatting, naming conventions)
- **Reviewer** (Opus) — L1+L2 review, file group B (same checklist, different file group)

Then dispatch `Sonnet Reviewer — 3a aggregation` to union the two verdicts and deduplicate overlapping findings. Verdict ∈ {`PASS`, `NEEDS_REVISION`, `ESCALATE`}. On `NEEDS_REVISION`, re-dispatch only 3a.

#### Step 3b — L3: integration, security (L3+ only)

Dispatch two Reviewer agents in parallel over different concern dimensions:
- **Reviewer** (Opus) — L3 integration risks (cross-file consistency, API contract mismatches, race conditions, edge cases)
- **Reviewer** (Opus) — L3 security scan (hardcoded secrets, injection, path traversal, XSS, missing validation — per [security.md](references/security.md))

If the security Reviewer emits `SECURITY_VIOLATION:` → halt immediately; skip the fix gate; surface the finding inline; user decides remediation.

Then dispatch `Sonnet Reviewer — 3b aggregation` to union the two verdicts. Verdict as above.

#### Step 3c — L4+L5: performance, scalability, accessibility, UX (L4+ only)

Dispatch two Reviewer agents in parallel:
- **Reviewer** (Opus) — L4+L5 performance and scalability (algorithmic complexity, memory, bundle size, adversarial load)
- **Reviewer** (Opus) — L4+L5 accessibility and UX (WCAG compliance, keyboard nav, screen-reader semantics, interaction design)

Then dispatch `Sonnet Reviewer — 3c aggregation` to union the two verdicts. Verdict as above.

The Reviewer uses the [reviewer-prompt.md](references/reviewer-prompt.md) template with the diff, level definition, and any applicable spec. Each sub-phase produces structured `[Critical] / [Important] / [Suggestions] / [Praise]` findings that feed into Step 4.

### Step 4 — Findings synthesis

Write the full structured audit to `.hyperflow/audits/-.md`. Sub-phases 4a, 4b, 4c run in parallel (P1), each authoring a section of the audit file. The audit file also receives a memory-append section per [memory-system.md](references/memory-system.md).

#### Step 4a — Critical findings

Dispatch two Writer agents in parallel:
- Writer — evidence probe (trace each Critical finding back to the diff line; confirm reproducibility)
- Writer — impact analysis (articulate user-visible / system-level consequence for each Critical finding)

Then dispatch `Sonnet Reviewer — 4a critical findings review` to verify each Critical entry has a confirmed fix path and no false positives. Verdict ∈ {`PASS`, `NEEDS_REVISION`, `ESCALATE`}.

#### Step 4b — Important findings

Dispatch two Writer agents in parallel:
- Writer — root-cause probe (trace each Important finding to its origin; confirm it's not a symptom of a Critical)
- Writer — fix-path analysis (propose the recommended change per finding, with file:line anchors)

Then dispatch `Sonnet Reviewer — 4b important findings review`. Verdict as above.

#### Step 4c — Suggestions, observations, and memory append

Dispatch two Writer agents in parallel:
- Writer — pattern analysis (identify Suggestion-level improvements; extract reusable patterns for memory)
- Writer — praise identification (flag genuinely well-done decisions; append durable patterns to `.hyperflow/memory/learnings.md` per [memory-system.md](references/memory-system.md))

Then dispatch `Sonnet Reviewer — 4c suggestions + memory dedup check` to ensure no duplicate memory entries land and no Suggestions are mis-classified as Important. Verdict as above.

#### Step 4d — Memory feedback (runs after 4a/4b/4c complete)

After the audit file is written, curate recurring problem patterns into `.hyperflow/memory/anti-patterns.md` so future audit runs and workers benefit from accumulated findings. This is an atomic Worker→Reviewer pair.

Dispatch one Writer agent:
- Writer — anti-pattern curation (read `.hyperflow/memory/anti-patterns.md` if it exists; extract up to 3 new entries from the `[Critical]` and `[Important]` findings produced in 4a/4b; append or update the file)

**Curation rules the Writer must follow:**
- Only `[Critical]` and `[Important]` findings are eligible — Suggestions and Praise are excluded.
- Before writing, read the existing `anti-patterns.md`. If a matching pattern already exists, increment its `frequency` counter and update `last seen`. Do not create a duplicate entry.
- Limit: max 3 new pattern entries per audit run. When more than 3 eligible findings exist, prioritize by breadth — multi-file findings before single-file findings.
- Append entries in this format:

```markdown
##  (e.g. Error handling, Naming, Dead code)
-  — first observed in audit , frequency: , last seen: 
  Recommendation: 
```

- Tag `anti-patterns.md` as `#hot` in the session memory index so workers load it at session start alongside other hot-tier files.

**Compaction pass (runs after the Writer appends new entries, not before):**

New findings always land first. After the append, the Writer checks whether compaction is needed. Compaction is triggered when ANY of the following is true:

- Total entry count in `anti-patterns.md` exceeds 50.
- Any entry has `last seen` more than 6 months ago AND `frequency == 1` (stale singleton — never reinforced).
- File line count meets or exceeds the `memory.compactionThreshold` (default 300, from `~/.hyperflow/config.json`).

When triggered, the Writer runs these actions in order:

1. **Merge duplicates.** Entries in the same category with similar wording are merged into one. Combined `frequency` = sum of the merged entries; `last seen` = most recent of the merged entries. Wording is taken from the higher-frequency entry.
2. **Archive stale singletons.** Entries where `frequency == 1` AND `last seen` is older than 6 months move to `.hyperflow/memory/archive/YYYY-MM.md` (month derived from the entry's `last seen` date), tagged with their source so they remain retrievable. This is the same shared monthly archive convention used by `/hyperflow:cache compact` — see `skills/cache/references/compaction.md`.
3. **Cap at 50 entries.** If the file still exceeds 50 entries after merge and archive, evict the lowest-frequency entries. Tiebreak: oldest `last seen` is evicted first. **Never evict entries derived from `[Critical]` findings** — the highest-severity patterns are exactly the ones that must keep surfacing; if eviction is needed and only Critical-sourced entries remain over the cap, leave the file over-cap and note it for the next compaction. Evicted entries move to the same shared monthly archive.
4. **Hot-tier is already wired.** `anti-patterns.md` is permanently hot-tier (see `memory-system.md`). The post-compaction file is injected automatically at the next session start. No manual hot-tier refresh is needed.

If compaction was triggered but none of the three actions has anything eligible to do (e.g. the line-count threshold tripped on a verbose but already-deduped ≤50-entry file), the Writer skips the rewrite — no no-op compaction dispatch. If compaction was not triggered at all, the Writer skips this block entirely and proceeds to the Reviewer.

Then dispatch `Sonnet Reviewer — 4d anti-pattern dedup and compaction check` to verify: no duplicate entries landed, frequency counters are accurate, only Critical/Important findings were promoted, the new-entry count does not exceed 3, and — when compaction ran — no critical entries were dropped without archiving and the archive sidecar was written correctly. Verdict ∈ {`PASS`, `NEEDS_REVISION`}. On `NEEDS_REVISION`, the Writer re-reads the file and corrects the specific violation (max 1 retry before surfacing inline).

### Step 5 — Severity reconciliation (atomic-exempt per DOCTRINE 12.2.8)

Dispatch one `Sonnet Reviewer — severity reconciliation` to consolidate the `[Critical] / [Important] / [Suggestion] / [Praise]` labels already emitted by Step 3 sub-phases (3a/3b/3c). No Workers are dispatched: the Reviewer reads existing Step 3 labels and resolves any conflicts across sub-phases (e.g. a finding flagged `[Important]` in 3a and `[Critical]` in 3b resolves to `[Critical]`). Verdict ∈ {`PASS`, `NEEDS_REVISION`}. On `NEEDS_REVISION`, the Reviewer annotates the specific conflict; the orchestrator applies the resolution inline (no re-dispatch).

After Step 5 completes, the orchestrator writes the graded findings into the audit file (Step 4 section headers get severity labels applied) and prints the chat summary (file-first, DOCTRINE rule 8):

```
── Audit Result ──────────────────────
Scope:    main..HEAD (13 files)
Level:    L3
Verdict:  NEEDS_FIX
Findings: 0 Critical · 4 Important · 4 Suggestions · 5 Praise
Written:  .hyperflow/audits/2026-05-16-1730-memory-compaction.md
─────────────────────────────────────
```

No `[Critical]` / `[Important]` body lines in chat. The user opens the file (or the chat host previews it). For `PASS`-clean runs (no Critical/Important), print just the one-line `Audit clean — no fixes needed.` and still write the file with the praise + suggestions list (so the audit history is preserved). Skip the file write only on `SECURITY_VIOLATION` — those need immediate eye-level surfacing; print the finding inline and halt.

### Step 6 — Fix gate (STRUCTURAL GATE · DOCTRINE rule 8)

After the summary prints, the audit skill **MUST** ask the user via `AskUserQuestion` whether to apply the findings. Per DOCTRINE rule 8, this gate always fires when findings exist — autonomy directives do NOT skip it. Defaulting silently is a doctrine violation.

**Skip the gate only when:** v

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jeremylongshore](https://github.com/jeremylongshore)
- **Source:** [jeremylongshore/claude-code-plugins-plus-skills](https://github.com/jeremylongshore/claude-code-plugins-plus-skills)
- **License:** MIT
- **Homepage:** https://tonsofskills.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jeremylongshore-claude-code-plugins-plus-skills-audit
- Seller: https://agentstack.voostack.com/s/jeremylongshore
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.