| name | audit |
| description | Deep code-audit recipe: discover files in a target → review each (LLM, cached) → partition by
component → executive digest with hotspots and recurring patterns. A layer-3 recipe over /agentflow:pipe
(the 6-stage pipeline and caching are detailed in the body).
USE when the user asks to "review / audit / find bugs across" a folder, repo, or glob and wants a
persisted, structured report — and the target is large enough (≥ ~10 files) that per-file parallelism
plus a digest beats reading inline.
DON'T use for a few named files (read them inline), exploratory questions ("what does this do?"), or
generic per-item work that isn't a code review (→ /agentflow:foreach).
Not a `/`-menu command — it's the shipped `workflows/audit/` recipe: reach it by asking ("audit src
for bugs"), or run it directly with `/agentflow:run-workflow workflows/audit/WORKFLOW.md`.
|
| allowed-tools | Bash, Read, Write, Edit, Glob, Grep, Agent |
| argument-hint | --target <path> [--file-glob "**/*.cs"] [--exclude <globs>] [--run-id NAME] |
| user-invocable | false |
/agentflow:audit
Make it visible: the moment you start, say so in one line (skill + run-id) so it's clear an Agent Flow
run is happening; /agentflow:board then lists every run on disk — the audit trail.
You are the orchestrator of a /agentflow:audit recipe. Your job is to construct a 6-stage pipeline.json, hand it to /agentflow:pipe, and let the framework drive execution. The recipe itself adds no new primitives.
Step 0 — Resolve config + compute manifest hash for the run-id
Read ${CLAUDE_PLUGIN_ROOT}/skills/audit/defaults.md. Apply override priority CLI > defaults.
Required: --target <path>. If missing → ask via AskUserQuestion or abort with a clear message.
Manifest hash (forces a new run when source files change):
- List all files under
<target> matching <file_glob> and not <file_exclude>
- For each: take
(rel_path, mtime_ns) — fast, no byte reads
- Sort by rel_path
manifest_hash = sha256(joined entries)[:16]
Run-id derivation (when --run-id is NOT provided):
audit-<8 char hash> where the hash is sha256(target + glob + review_model + manifest_hash)[:8]- This way: same content → same run-id (resume works), changed content → new run-id (fresh run).
Echo the resolved config + run-id in one line. If target has > 200 files, ask for confirmation (cost/duration warning).
Step 1 — Working dirs
Create .agentflow/audit/<run-id>/ (recipe scratch) and .agentflow/pipe/<run-id>/ (pipeline state).
Step 2 — Resolve the discover params
The 6-stage structure is shipped as a self-contained, human-readable workflow-file at
${CLAUDE_PLUGIN_ROOT}/workflows/audit/WORKFLOW.md (this is the canonical, reusable
artifact — you do NOT hand-build a stages.json). Its discover stage runs the sibling
discover.mjs via {{workflow.dir}} (so the whole workflows/audit/ folder is movable);
the script emits a /agentflow:foreach-compatible items array with a per-file content_hash
(for the review --cache).
Per-invocation inputs are declared params, passed to init with --param (no env exports):
target (required) — the directory to auditglob (default **/*) — comma-separated include globs, e.g. **/*.csexclude (default empty) — comma-separated exclude globs
To tune the review/digest models or group depth, copy the whole workflows/audit/ folder into your
project's workflows/ and edit the --model / --method-config values in its WORKFLOW.md; pass that
copy's WORKFLOW.md to --workflow.
Step 3 — (the pipeline is the workflow-file)
No stages.json to build. The workflow-file already wires the 6 stages with declarative
templates ({{stages.<name>.run_id}}, {{stages.<name>.result_pointer}}, {{run.dir}},
{{params.*}}), resolved by /agentflow:pipe at tick time. The stages are: discover (bash) →
review (/agentflow:foreach, --kind code-review --cache) → build-group-input (json) →
partition (/agentflow:group path-prefix) → build-digest-inputs (json) → digest (/agentflow:reduce, markdown).
Step 4 — Validate and init the pipe
node "${CLAUDE_PLUGIN_ROOT}/dist/state/pipe.js" init <run-id> \
--workflow "${CLAUDE_PLUGIN_ROOT}/workflows/audit/WORKFLOW.md" \
--param target="<resolved-target-path>" \
[--param glob="**/*.cs"] [--param exclude="<globs>"] \
[--no-stop-on-failure if user passed --keep-going] \
[--force if --run-id was explicitly provided and overrides existing]
/agentflow:pipe init automatically runs schema validation on every primitive stage's init_args (catches typos in flags / bad kind values / missing required configs BEFORE the pipeline starts). A clear error listing surfaces here, not mid-run.
Step 5 — Drive the pipe
Use pipe drive (NOT manual tick + execute loops) — it auto-runs every bash stage and every deterministic primitive stage (in this recipe: discover, build-group-input, partition, build-digest-inputs) without your involvement, stopping ONLY when an Agent dispatch is needed (review and digest stages).
node "${CLAUDE_PLUGIN_ROOT}/dist/state/pipe.js" drive <run-id>
Output is JSON:
{"action": "needs_agent", "cmd": "foreach", "suggested_child_run_id": "...", "init_args": [...]} — you must init the child + run the dispatch loop + advance, then call drive again.{"action": "done", "result_pointer": "..."} — pipeline complete, surface the digest.{"action": "failed", ...} — surface the error.
When needs_agent for /agentflow:foreach review:
- Run the child init:
node "${CLAUDE_PLUGIN_ROOT}/dist/state/foreach.js" init <suggested_child_run_id> <init_args...> --force
- Record in pipe:
node "${CLAUDE_PLUGIN_ROOT}/dist/state/pipe.js" start-primitive-child <run-id> --child-cmd foreach --child-run-id <suggested>
- Follow
/agentflow:foreach SKILL.md Step 4 dispatch loop: status → claim → split into chunks → fan-out parallel Agents in ONE message → complete-batch each result file.
- After every Agent return, record token usage:
node "${CLAUDE_PLUGIN_ROOT}/dist/state/foreach.js" budget-add <enum-run-id> --tokens <total_tokens> --model <review_model> so the budget aggregates correctly.
- When
complete-batch reports run_status: done, call drive again — it advances past the review stage, auto-runs the bash bridges + group, and stops at digest.
When needs_agent for /agentflow:reduce digest:
- Init the reduce child + record + materialize (the reduce SKILL covers Steps 2-4).
- Dispatch ONE digest agent (no fan-out for /agentflow:reduce).
- After Agent returns:
state/reduce.js budget-add for the tokens, then state/reduce.js complete <child-id> --output-path ./<run-id>-audit.md — write the digest to a visible file in the
workspace root (e.g. audit-3f2a-audit.md), not buried under .agentflow/.
- Call
drive once more → returns done.
Step 6 — Final report
When drive returns done:
Read the first 30 lines of result_pointer (the digest markdown) and surface inline.- Run
node "${CLAUDE_PLUGIN_ROOT}/dist/inspect.js" budget <run-id> and surface the total cost.
- Run
node "${CLAUDE_PLUGIN_ROOT}/dist/inspect.js" tree <run-id> for the full child tree breakdown.
- Suggest follow-ups (e.g. "to refine the auth component, run
/agentflow:foreach --kind audit --model opus --items <groups.json filtered>").
Important rules
- Idempotence: re-running with the same
--run-id (or the same --target if run-id is auto-derived) resumes. With the manifest hash in run-id derivation: a file content change → new run-id → fresh run. Pure resume of a half-completed run uses the SAME run-id.
- No file modification: this recipe is read-only on the target. The digest lands as a visible
./<run-id>-audit.md in the workspace; internal state lives under .agentflow/audit/<run-id>/,
.agentflow/pipe/<run-id>/, .agentflow/foreach/<run-id>-s1-foreach/, .agentflow/group/<run-id>-s3-partition/,
.agentflow/reduce/<run-id>-s5-digest/.
- Incremental re-runs: with
--cache on the review stage, files whose content_hash matches a prior cached result are skipped (no agent dispatch). Hits saved under .agentflow/cache/foreach-code-review/.
- Validate then drive: trust the dry-run validation
/agentflow:pipe init performs. Catches recipe typos before any agent dispatch.
Quick example
/agentflow:audit --target examples/fake-repo
Expected on the bundled fake-repo (8 files, 4 components, 6 with intentional bugs):
- stage discover finds 8 .cs files (each with sha256 content_hash)
- stage review dispatches /agentflow:foreach (sonnet, conc=4, --cache) → 6 bug reports + 2 clean
- stage build-group-input materializes the run reference
- stage partition runs /agentflow:group path-prefix depth=1 → 4 groups (auth, billing, api, data)
- stage build-digest-inputs materializes the reduce inputs
- stage digest dispatches /agentflow:reduce (opus, markdown) → executive report
- Final digest written to a visible
./<run-id>-audit.md in the workspace
Re-running the same command without changing fake-repo: the same run-id is regenerated, all 8 review items become cache hits → no agent dispatch for review → only the digest runs again (still costs ~$0.10 for the opus call). If you change one file, only that file dispatches a new review agent.
