audit

Full-sweep audit of .claude/ config + all plugins/*/ files: agents, skills, rules, settings.json, hooks. Spawns foundry:curator per-file, aggregates system-wide for cross-file issues — infinite loops, inventory drift, missing permissions, interop breaks. Reports findings; fix level chosen from follow-up gate.

• $ARGUMENTS: optional — parse --flags first, then resolve remaining tokens as scope

  Flags (order independent, any combination with scope):

  • --local — audit source tree (plugins/*/) not user setup (.claude/ + installed cache); plugin-dev workflows where local edits not yet installed; sets LOCAL_MODE=true
  • --upgrade — fetch latest Claude Code docs, filter new features by genuine value, apply: config changes (apply + correctness check), capability changes (calibrate before → apply → calibrate after → accept if Δrecall ≥ 0 and ΔF1 ≥ 0). Skip to Mode: upgrade. Mutually exclusive with --adversarial and --efficiency — error if combined with either.
  • --adversarial (alias: --challenge) — adversarial review of all agents + skills in scope using foundry:challenger (Phase A) + Codex adversarial pass (Phase B); surfaces issues beyond standard per-file audit; see Mode: adversarial. Mutually exclusive with --upgrade only; combinable with --efficiency.
  • --efficiency — cost and efficiency sweep: model tier validation, token bloat detection, unbounded spawn patterns, cross-file boilerplate duplication, missing model declarations, dead model specs, bin/ extraction candidates (Check 33). Generates prioritized cost-reduction plan with estimated savings. Detection only — run /distill executables to act on extraction candidates. Skip to Mode: efficiency. Mutually exclusive with --upgrade only; combinable with --adversarial.
  • --skip-gate — suppress follow-up gate (for automation pipelines)

  Legacy positional tokens (fix, upgrade, adversarial, challenge, ab, apply, fast, full) — hard error: print migration hint and stop. Example: "fix medium removed — run /audit and pick fix level from gate, or pass --upgrade / --adversarial as flags."

  Scope tokens (positional, space-separated — resolve each token before Step 2):

  • No scope: full sweep — sources per --local: without --local covers .claude/agents/, .claude/skills/, .claude/rules/, hooks, settings, ~/.claude/plugins/cache/ installed; with --local covers plugins/*/agents/, plugins/*/skills/ + .claude/ secondary
  • agents — restrict sweep to agent files only
  • skills — restrict sweep to skill files only
  • rules — restrict sweep to rule files only
  • communication — restrict sweep to communication governance files: rules/communication.md, rules/quality-gates.md, TEAM_PROTOCOL.md, skills/_shared/file-handoff-protocol.md
  • setup — restrict to system-config files: settings.json, permissions-guide.md, hooks, MEMORY.md, README.md, plugin integration, post-install user state (Checks 1–11, 30, I1, I2, I3); Step 3: setup SKILL.md only (one foundry:curator spawn); Checks I1–I3 read ~/.claude/ not .claude/
  • plugin — plugin integration only: codex plugin (Check 7), foundry plugin + init validation (Check 8, including 8g); Step 3: setup SKILL.md only (one foundry:curator spawn)
  • plugins — full audit of all plugins: per-file audit of every plugins/*/agents/*.md and plugins/*/skills/*/SKILL.md + integration checks (7, 8) per plugin
  • plugins <name> — same as plugins scoped to one plugin: plugins/<name>/agents/*.md + plugins/<name>/skills/*/SKILL.md + integration checks; <name> must match dir under plugins/ (e.g. plugins foundry, plugins oss, plugins research)
  • <plugin-name> — tier 2 shorthand: bare plugin dir name (e.g. oss, foundry, research, develop, codemap) auto-resolved when token matches dir under plugins/; equivalent to plugins <name>; no plugins prefix needed
  • <agent-name> — tier 3: name matches plugins/*/agents/<name>.md or .claude/agents/<name>.md; runs agent checks only (Checks 14a, 14b, 15, 19, 20, 17, 12, 13, 25, 22, 26, 29); one file in Step 3
  • <skill-name> — tier 3: name matches plugins/*/skills/<name>/SKILL.md or .claude/skills/<name>/SKILL.md; runs skill checks only (Checks 14a, 14b, 15, 21, 17, 12, 23, 22, 13, 24, 25, 26, 27, 28, 29); one file in Step 3
  • Multiple scope tokens — space-separated, any combo; scope = union of resolved file sets: agents skills, oss research, shepherd curator, review resolve; check list = union (de-duplicated)

  Scope token resolution (each remaining token after flag-strip, resolved before Step 2): (1) reserved keywords (agents, skills, rules, communication, setup, plugin, plugins) → use as-is; (2) matches dir under plugins/<token>/ → tier 2; (3) matches agent file in plugins/*/agents/<token>.md or .claude/agents/<token>.md → tier 3 agent; (4) matches skill dir plugins/*/skills/<token>/ or .claude/skills/<token>/ → tier 3 skill; (5) no match → error and stop

  Valid combinations: scope tokens + flags mix freely: foundry --local, foundry --adversarial, agents skills --local, oss research --adversarial, foundry --efficiency, plugins --efficiency, foundry --adversarial --efficiency, plugins --local --adversarial --efficiency. --upgrade mutually exclusive with --adversarial and --efficiency — error if combined with either. --local compatible with all. When --adversarial and --efficiency both present: run adversarial Phases A–C then efficiency Phases A–C sequentially; merge findings; single follow-up gate.

MONITOR_INTERVAL=300 # 5 minutes between polls HARD_CUTOFF=900 # 15 minutes of no file activity → declare timed out EXTENSION=300 # one +5 min extension if output file explains delay BATCH_SIZE=5 # max files per foundry:curator spawn in Step 3; keep small to avoid context compaction ADVERSARIAL_BATCH_SIZE=2 # adversarial phases (A, A-prime) use smaller batches for deeper per-file attention; override with --batch-size N

Task hygiene:

_FS=$(python "${CLAUDE_PLUGIN_ROOT:-plugins/foundry}/bin/resolve_shared_path.py" foundry skills/_shared 2>/dev/null || echo "plugins/foundry/skills/_shared")  # timeout: 5000

Read $_FS/task-hygiene.md — follow task hygiene protocol. Read $_FS/preflight-helpers.md — defines preflight_ok() and preflight_pass() used in Pre-flight checks below.

Orchestration contract: orchestrator is thin coordinator — issues Glob/Grep for inventory, spawns agents, reads JSON envelopes, aggregates findings. Must NOT read agent/skill/rule file bodies directly. Inline read of non-template file = protocol violation; causes context overflow at scale.

Task tracking: TaskCreate for each major phase; mark status live:

• Phase 1: setup + collect (Pre-flight + Steps 1–2) → in_progress on start, completed when file list ready
• Phase 2: per-file audit (Step 3) → in_progress on agent launch, completed when all reports received
• Phase 3: system-wide checks (Step 4) → in_progress on start, completed when all checks done
• Phases 2 and 3 launch simultaneously — mark both in_progress same update; independent, must not serialize
• Phase 4: aggregate + fix (Steps 5–10) → in_progress, completed when fixes land; do NOT mark completed until EITHER: (a) follow-up gate fires (Step 7) AND fixes applied or user chose skip; OR (b) --skip-gate active — gate suppressed, complete after Step 5 aggregation; Step 5 aggregation alone does NOT complete Phase 4 in normal mode
• Phase 5: final report (Step 11) → in_progress, completed before output
• On loop retry or scope change → new task; do not reuse c