audit-agent-onboarding

Auditing agent onboarding files

Static + cross-reference linter for instruction-file smells. Read-only: this

skill never writes files. It produces a findings report; applying fixes is

update-agent-onboarding's job (content) or the user's (structure).

Announce at start: "Using audit-agent-onboarding to lint the onboarding files."

Usage: audit-agent-onboarding [--stats]

--stats: compression receipts

Read .aiboarding/state.json:receipts and render a table: file, level, bytes and

lines before/after, percent saved, measured-at. Label token figures approximate

when the receipt does (they are byte/4 estimates unless a real tokenizer produced

them). Since instruction files load every session, per-session savings compound -

present "per-session saved × sessions" only as a clearly labeled estimate. For each

receipt, render optional high_consequence_regions evidence as location, category,

outcome (preserved or rewritten), and explicit opt-in status, without instruction

text. Render an empty array as none; when field is absent, render not recorded.

Keep existing level, byte, line, date, and token output unchanged. Then stop.

Evidence-aware audit

Run .aiboarding/tools/audit-onboarding-evidence <repo-root> first (fallback:

the plugin's templates/tools/audit-onboarding-evidence). Capture its lines and

exit status. Exit 0 means no computed FAIL; 1 means computed validation FAIL;

2 is an operational error: stop and report tooling failure, never render it as an

audit finding. Do not write onboarding files in either case.

Each finding has independent severity (FAIL, WARN, INFO) and provenance

(computed, inferred). Preserve validator provenance and render one report

ordered FAIL, WARN, INFO. Never upgrade model judgment to computed.

| Category | Evidence |

| --- | --- |

| Local size budget; Codex project-chain budget; wrapper integrity | Computed |

| Stale commands | Mixed: validator only for explicit paths, package scripts, Make/Just targets; infer unresolved context-dependent cases |

| Duplication; contradictions; vague commands; missing sections; skill leakage; lint leakage; rules extraction candidates; unsafe content | Inferred |

Then review inferred categories and unresolved command references across AGENTS.md,

CLAUDE.md, and .claude/rules/*.md:

1. Duplication - imported or README content restated meaningfully.
2. Contradictions - instructions whose scope or intent conflicts.
3. Stale commands - only commands validator cannot prove absent.
4. Vague commands - imperative guidance lacking usable invocation.
5. Missing sections - absent guardrail or verification guidance, not headings alone.
6. Skill/lint leakage and rules extraction candidates - ownership and scope need judgment.
7. Unsafe content - secrets and destructive-command framing need context; do not quote secrets.

Report

Output findings ordered FAIL → WARN → INFO, each with provenance, file, location,

one-line rationale, and concrete fix. Example:

FAIL [computed] wrapper-integrity CLAUDE.md:1 — missing @AGENTS.md import; add it.
WARN [computed] size-budget AGENTS.md:1 — 24001 bytes > budget 24000; compress it.
WARN [inferred] vague-commands AGENTS.md:8 — "run tests" lacks invocation; name command.

End with one-line verdict and handoff: content fixes → offer

update-agent-onboarding (approval gate applies); compression fixes →

compress-onboarding. Suggestions are never auto-applied.