jeremylongshore Audit
Multi-level code review. All agents inherit the session model. Reviewers bold-labeled; Workers plain.
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:plan 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. 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 | Workers | Reviewers | Notes |
|---|---|---|---|---|
| 1 — Resolve scope | — | — | — | Mechanical decision (exempt) |
| 2 — Gather context | 2a — Surface mapping | Searcher × 2 (glob + import-graph) | Reviewer | Parallel |
| 2 — Gather context | 2b — Semantic indexing | Searcher × 2 (type-system + symbol-graph) | Reviewer | Parallel |
| 2 — Gather context | 2c — Convention scan | Searcher × 1 (test patterns + lint config) | Reviewer | Justified single-angle |
| 2 — Gather context | 2d — Aggregate coverage gate | — | Reviewer verifies aggregate coverage | Standalone coverage gate |
| 3 — Review | 3a — L1+L2 (syntax/format/naming) | — | Domain specialist Reviewer × 2 (file groups, surface-matched) + Reviewer aggregates | Parallel pair dispatched as the matching domain specialists |
| 3 — Review | 3b — L3 (integration/security) | — | Reviewer × 2 — backend-reviewer + security-reviewer/vulnerability-reviewer + Reviewer aggregates | Parallel pair; security specialists web-research-first |
| 3 — Review | 3c — L4+L5 (perf/scale/a11y/UX) | — | Reviewer × 2 — performance-reviewer + accessibility-reviewer + Reviewer aggregates | Parallel pair dispatched as the matching specialists |
| 4 — Findings synthesis | 4a — Critical findings | Writer × 2 (evidence probe + impact analysis) | Reviewer | Parallel |
| 4 — Findings synthesis | 4b — Important findings | Writer × 2 (root-cause probe + fix-path analysis) | Reviewer | Parallel |
| 4 — Findings synthesis | 4c — Suggestions + observations | Writer × 2 (pattern analysis + praise identification) | Reviewer | Parallel |
| 4 — Findings synthesis | 4d — Memory feedback | Writer × 1 (anti-pattern curation) | Reviewer (dedup + compaction validation) | Atomic Worker→Reviewer; runs after 4a/4b/4c complete; with compaction pass when triggered |
| 5 — Severity reconciliation | — | — | 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 1through--level 5(default — L2)
Review Levels
Adapted from 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.
Flow
Step 1 — Resolve scope
Use the provided target or run git diff HEAD + git diff --staged. No agent dispatched (read-only git).
Targets accepted: a path/glob, an explicit file list, or a git range <base>..<head>. The range form is how a two-session handoff review runs — /hyperflow:handoff review <slug> reads the build's COMPLETION.md diff range and invokes audit as Skill audit "<base>..<head> level=<n>", so the review covers exactly the second session's commits (git diff <base>..<head>). See ../hyperflow/session-handoff.md.
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 a standalone aggregate coverage gate. The Searchers also record which surfaces the diff touches (frontend / api / db / devops / mobile / data-ml / security) — this drives the domain-specialist selection in Step 3 (../../agents/README.md).
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/usechains from touched files)
Then dispatch **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 **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 **Reviewer** — 2c convention scan coverage check. Verdict as above.
Step 2d — Aggregate coverage gate
After 2a + 2b + 2c complete, dispatch **Reviewer** — 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 sub-phase aggregator Reviewer before the next batch fires. Active sub-phases scale with --level: L1-L2 runs only 3a; L3 adds 3b; L4-L5 add 3c.
Specialist selection. Step 2 detects which surfaces the diff touches (frontend, api, db, devops, mobile,
data/ml, …). Step 3 dispatches each Reviewer as the matching domain specialist
(../../agents/README.md) — its charter + strict checklist injected, and (audit is a
gated flow) its web-research-first pass run for current best-practice / CVE currency. When the target has a
spec/task file, its Brain-decided Specialists roster seeds the selection.
Step 3a — L1+L2: syntax, formatting, naming
Dispatch two Reviewer agents in parallel over different file groups (split by directory or feature boundary),
each as the domain specialist matching that group's surface (frontend-reviewer / backend-reviewer /
api-reviewer / database-reviewer / devops-reviewer / mobile / data-ml-reviewer):
- Reviewer (domain specialist) — L1+L2 review, file group A (syntax errors, obvious bugs, formatting, naming conventions)
- Reviewer (domain specialist) — L1+L2 review, file group B (same checklist, different file group)
Then dispatch **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 — as the security specialists:
- Reviewer (
backend-reviewerorapi-reviewer) — L3 integration risks (cross-file consistency, API contract mismatches, race conditions, edge cases) - Reviewer (
security-reviewer+vulnerability-reviewer) — L3 security scan (hardcoded secrets, injection, path traversal, XSS, missing validation, known-CVE exposure — per security.md, web-research-first on current advisories)
If the security Reviewer emits SECURITY_VIOLATION: → halt immediately; skip the fix gate; surface the finding inline; user decides remediation.
Then dispatch **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 — as the matching specialists:
- Reviewer (
performance-reviewer) — L4+L5 performance and scalability (algorithmic complexity, memory, bundle size, adversarial load) - Reviewer (
accessibility-reviewer) — L4+L5 accessibility and UX (WCAG compliance, keyboard nav, screen-reader semantics, interaction design)
Then dispatch **Reviewer** — 3c aggregation to union the two verdicts. Verdict as above.
The Reviewer uses the 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/<YYYY-MM-DD-HHmm>-<scope-slug>.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.
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 **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 **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.mdper memory-system.md)
Then dispatch **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.mdif 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 itsfrequencycounter and updatelast 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:
## <pattern category> (e.g. Error handling, Naming, Dead code)
- <description> — first observed in audit <YYYY-MM-DD>, frequency: <count>, last seen: <YYYY-MM-DD>
Recommendation: <what workers should do to avoid this>
- Tag
anti-patterns.mdas#hotin 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.mdexceeds 50. - Any entry has
last seenmore than 6 months ago ANDfrequency == 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:
- 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. - Archive stale singletons. Entries where
frequency == 1ANDlast seenis older than 6 months move to.hyperflow/memory/archive/YYYY-MM.md(month derived from the entry'slast seendate), tagged with their source so they remain retrievable. This is the same shared monthly archive convention used by/hyperflow:cache compact— seeskills/cache/references/compaction.md. - Cap at 50 entries. If the file still exceeds 50 entries after merge and archive, evict the lowest-frequency entries. Tiebreak: oldest
last seenis 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. - Hot-tier is already wired.
anti-patterns.mdis permanently hot-tier (seememory-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 **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 **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: verdict is PASS with no [Critical] or [Important] entries (Suggestions-only or Praise-only). Stop after the one-line Audit clean — no fixes needed. summary.
Skip the gate also when: verdict is SECURITY_VIOLATION. Halt and let the user decide.
Otherwise, ask:
? Audit findings written to .hyperflow/audits/<timestamp>-<slug>.md — apply fixes?
Fix all (Recommended) — Critical + Important + Suggestions via /hyperflow:plan → /hyperflow:dispatch
Critical + Important — skip Suggestions, fix the rest
Critical only — fix the must-haves, defer the nice-to-haves
No, leave as-is — stop; you'll handle manually
Recommended option scales with finding mix:
- Any
[Critical]present →Fix all (Recommended)— Critical items can't be deferred - Only
[Important]+[Suggestions]→Critical + Important (Recommended) - Only
[Suggestions]→No, leave as-is (Recommended)— Suggestions are optional by definition; the gate fires but recommends skipping
On any "Fix …" choice:
- Build a spec file from the chosen findings at
.hyperflow/specs/audit-<YYYY-MM-DD>-<scope-slug>.md. Each finding becomes a numbered fix section with: file:line, the issue, the reviewer's suggested fix (or "design needed" if no Fix: was provided), and the commit message stub. The spec file is the chain-driving artefact; do NOT paste fix bullets into chat. - Invoke
Skillwithskill: planandargs: "session=one spec=.hyperflow/specs/audit-<YYYY-MM-DD>-<scope-slug>.md". /hyperflow:planwill decompose into batches;/hyperflow:dispatchwill execute them — same per-sub-task commit cadence and per-batch L1–L review as any other chain run.
On "No":
Print one line and stop:
Audit complete — N findings recorded, no fixes applied. Re-run /hyperflow:audit later or invoke /hyperflow:plan manually if you change your mind.
If AskUserQuestion cannot be presented as a popup, use the portable-surface fallback (Codex / OpenCode / Grok): print the fix gate as a Hyperflow Question chat block with numbered options, then stop and wait for the user's answer. If no interactive channel is available at all, print the findings and an error line — never silently auto-fix or silently exit.
Output Format
Two outputs per audit run:
1. The audit file at .hyperflow/audits/<YYYY-MM-DD-HHmm>-<scope-slug>.md — full structured review, formatted per ../hyperflow/artefact-format.md:
# Audit — <scope description>
## Status
| Field | Value |
|----------|------------------------------------------------------|
| Verdict | `<PASS \| NEEDS_FIX \| SECURITY_VIOLATION>` |
| Scope | `<files / range / commit>` |
| Level | L<n> |
| Findings | N Critical · N Important · N Suggestions · N Praise |
| Date | <YYYY-MM-DD HH:mm> |
## TL;DR
<2–3 sentences: the most important takeaway + the most important fix
to apply. The user reads this and decides whether to dig into the
findings list.>
## Findings
### [Critical] `<file>:<line>` — <one-line issue title>
**Issue:** <one paragraph: what's broken and why it's blocking>
**Fix:** <one paragraph: the recommended change, with the file:line
anchor and the suggested replacement>
**Why it matters:** <one sentence: the user-visible or system-level
consequence if shipped as-is>
### [Important] `<file>:<line>` — <one-line issue title>
...
### [Suggestion] `<file>:<line>` — <one-line improvement title>
...
### [Praise] `<file>:<line>` — <one-line note>
...
## Security scan (L3+ mandatory)
| Category | Result |
|-------------------|-----------------------|
| secrets | pass |
| injection | pass |
| path traversal | pass |
| DoS | pass | concerns |
| missing validation| pass | concerns |
## Cost
| Role | Agents | Tokens |
|-----------|-------:|---------:|
| Worker | 1 | ~Nk |
| Reviewer | 1 | ~Nk |
| **Total** | **2** | **~Nk** |
2. The chat summary — one short box that points at the file, NEVER the findings themselves:
── Audit Result ──────────────────────
Scope: <files / range>
Level: L<n>
Verdict: <PASS | NEEDS_FIX | SECURITY_VIOLATION>
Findings: 0 Critical · 4 Important · 4 Suggestions · 5 Praise
Written: .hyperflow/audits/<YYYY-MM-DD-HHmm>-<scope>.md
──────────────────────────────────────
Hand-off
- PASS (no findings worth fixing) — print
Audit clean. Suggest/hyperflow:deployif the user is ready to release. Do not auto-ship. - NEEDS_FIX — fix gate fires (Step 6). On
Yes …→ auto-chain to/hyperflow:plan. OnNo→ stop with findings printed. - SECURITY_VIOLATION — halt. Skip the fix gate. User decides remediation path.
Doctrine
Full rules in DOCTRINE.md. Output style in output-style.md. Per-step agent dispatching follows rule 12.
Overview
/hyperflow:audit runs a multi-level code review against uncommitted changes, a specific commit, branch, or PR. Searchers gather context; a standalone Reviewer produces verdicts at the chosen level (L1 quick scan to L5 exhaustive). On NEEDS_FIX, a structural gate asks the user whether to apply findings — Yes auto-chains to /hyperflow:plan, which decomposes the fix and then stops at its own build-location gate before any build starts; No leaves the diff alone.
Prerequisites
- Git repository with the change(s) to review present in the working tree, staged, or in history.
.hyperflow/cache optional but recommended (Layer 0 analysis improves reviewer context). Run/hyperflow:scaffoldfirst if missing.
Instructions
See Flow above — Steps 1-6 are the operational instructions. Summary:
- Resolve scope (target arg or
git diff HEAD). - Surface mapping + semantic indexing + convention scan (2a/2b/2c in parallel); aggregate coverage gate (2d).
- L1+L2 syntax/naming (3a) + L3 integration/security (3b) + L4+L5 perf/a11y (3c); each sub-phase Reviewer pair → aggregator.
- Findings synthesis: Critical (4a) + Important (4b) + Suggestions/memory (4c) — each sub-phase Writer pair → Reviewer.
- Severity reconciliation (atomic-exempt — single Reviewer consolidates Step 3 labels); print chat summary pointing at audit file.
- Fix gate fires on
NEEDS_FIXwith critical/important findings.
Output
See Output Format above for the exact block. Single review block per invocation; agent count line at the bottom shows the model/role split.
Error Handling
| Failure | Behavior |
|---|---|
| No diff to review (clean working tree, no target) | Print Nothing to review — clean working tree. Pass an explicit target. and stop. |
| Searcher returns no context (file gone, bad path) | Reviewer flags [Critical] — target unreachable and halts at Step 3. |
Reviewer emits SECURITY_VIOLATION (L3+ only) |
Skip Step 4 onward. Print finding. Do not fire fix gate. User decides remediation. |
AskUserQuestion popup unavailable (Codex / OpenCode / Grok) |
Print the fix gate as a Hyperflow Question chat block and wait for the user's answer. |
| No interactive channel at all | Print findings + an error line stating the fix gate could not fire. Never silently auto-fix or silently exit. |
| Reviewer disagrees with worker context (NEEDS_FIX on Step 2 coverage check) | Re-dispatch Searcher with the reviewer's gap list. Max 2 retries before surfacing the gap to user. |
Examples
Worked transcripts moved to examples.md so the SKILL body stays lean. The examples are illustrative — not load-bearing for behaviour. Read the companion file when you want to see end-to-end transcripts.
Resources
- DOCTRINE.md — orchestration rules (especially #8 structural gates, #12 per-step agents).
- review-levels.md — full checklist for L1-L5.
- reviewer-prompt.md — reviewer template.
- security.md — security scan policy (mandatory at L3+).
- memory-system.md — how patterns are persisted.
- output-style.md — label and table conventions.
Source: jeremylongshore/claude-code-plugins-plus-skills → plugins/ai-agency/hyperflow/skills/audit/SKILL.md