Skip to content
2 changes: 1 addition & 1 deletion plugins/claude-config/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
"name": "claude-config",
"version": "0.9.3",
"version": "0.10.0",
"description": "Four audit skills for a repo's Claude Code configuration: audit (settings.json / .mcp.json / hooks / plugins / permissions drift), audit-automation-gaps (evidence-gated verdicts on automation gaps), audit-permission-grants (allow-rule / allowed-tools grants for auto-mode durability and portability), and audit-instructions (locally-owned instruction surfaces vs current model capability — proposes removals/rewrites of instructions the model no longer needs).",
"author": {
"name": "Melodic Software",
Expand Down
43 changes: 43 additions & 0 deletions plugins/claude-config/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,49 @@
All notable changes to the `claude-config` plugin are documented here. Format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.

## [0.10.0]

### Added

- **`audit-instructions` checks I12–I14**, extending the existing `reference/criteria.md` catalog
rather than standing up a second one. Each row carries its must-not-flag cases, and the three new
official sources (CLI reference, subagents, skills) join the catalog's source list.
- **I12 — stale or misattributed harness-capability claim.** The subject is the product, not the
model, which separates it from I8. Detection needs an official page stating something incompatible
with the claim, or a failed reproduction — and each arm is bounded so the check cannot manufacture
findings. **Documentation silence is not drift**: pages are rewritten and condensed, and this
repository keeps empirical tests for behaviors the docs never specified. **A reproduction must
match every stated precondition** — version, OS, setting, account tier, feature flag, launch mode —
and a failure without them is inconclusive rather than a finding.
- **I13 — prose written on the assumption that an `@path` imported**, on a surface where `@` carries
no import meaning. The finding is the false premise, not the citation form: an inert `@path` is
still a legible path, so "follow `@reference/rules.md`" works and flagging it would report a
working instruction. Remediation rewrites the assertion into an explicit read, because swapping the
syntax alone leaves the claim false — no citation form imports anything on these surfaces.
- **I14 — an instruction to read a surface the main conversation already loads at startup.** Bounded
to the root `CLAUDE.md`, the user `CLAUDE.md` at the **resolved** `${CLAUDE_CONFIG_DIR:-~/.claude}`,
the root `CLAUDE.local.md`, unconditional project rules and managed policy files. Nested
`CLAUDE.md` and `CLAUDE.local.md` files and path-scoped rules load lazily and are exempt, as is any
read where **the file is the operation's subject** — the startup copy is a launch-time snapshot, so
cutting a pre-edit read produces a patch against stale content.

### Changed

- **Recheck triggers now watch every page in the catalog's source list**, not the three originally
named. Each check cites one of those pages, so a subset left the new harness-behavior rows
depending on pages nothing watched.
- **The surface partition no longer widens a row.** It said the full catalog applies on non-memory
surfaces while I13 and I14 declare narrower surface sets, so a lane could emit I14 findings on
prompt-type hooks and output styles the criterion excludes. Each row's own declaration bounds it.
- **The `description` carries the new checks' trigger vocabulary.** It framed the skill purely as
finding instructions the model no longer needs, and only the description is available during skill
selection — so a request about a stale harness claim, a non-loading `@path`, or a redundant
startup-surface read would not have selected the catalog that answers it.
- **`Authority` gloss restated descriptively.** It now reads "All fourteen checks are currently
`ANTHROPIC-DOCS`" — a statement about the catalog's present contents, not a rule. `TALK` and
`OPINION` stay reachable for a future row, and the axis stays a closed three-value set rather than
widening under every existing consumer.

## [0.9.3]

### Added
Expand Down
4 changes: 2 additions & 2 deletions plugins/claude-config/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,8 +72,8 @@ Audits instruction *content* against current model capability — a different qu
sibling audits (config-file correctness) and from `skill-quality:check` (structural lint) or
`docs-hygiene:compress` (token brevity). It sweeps the locally-owned surfaces (user + project
`CLAUDE.md`, `.claude/rules`, skill bodies, agent definitions, prompt-type hooks, output styles)
against an eleven-check catalog cited to current official prompting doctrine, running a fresh
read-only subagent per surface, then a fresh-context verify pass that re-judges every removal
against a fourteen-check catalog cited to current official prompting and harness doctrine, running
a fresh read-only subagent per surface, then a fresh-context verify pass that re-judges every removal
proposal before it is surfaced. Findings are tiered mechanical vs behavioral and delivered as a
report plus proposed diffs — report-only, never auto-applied. On memory-layer surfaces it runs only
the model-era checks and routes hygiene findings to the `claude-memory` plugin's `audit` skill (with
Expand Down
10 changes: 6 additions & 4 deletions plugins/claude-config/skills/audit-instructions/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: audit-instructions
description: "Audit locally-owned Claude Code instruction surfaces — user + project CLAUDE.md, .claude/rules, skill bodies, agent definitions, prompt-type hooks, output styles — for instructions current models no longer need: prior-model workarounds, over-prescriptive scaffolding, bare prohibitions, reasoning-echo directives, stale examples. Report-only: emits a findings report with proposed diffs, gated to the human, never auto-applied. Use when: 'after a model upgrade', 'are my instructions holding the model back', 'instructions the model no longer needs', 'too prescriptive', 'audit instructions', 'instruction audit'. Not a brevity pass and not memory-layer hygiene."
description: "Audit locally-owned Claude Code instruction surfaces — user + project CLAUDE.md, .claude/rules, skill bodies, agent definitions, prompt-type hooks, output styles — for instructions current models no longer need: prior-model workarounds, over-prescriptive scaffolding, bare prohibitions, reasoning-echo directives, stale examples — plus instructions that misstate Claude Code's own behavior, cite a file in a form that never loads, or re-read a surface already in context. Report-only: emits a findings report with proposed diffs, gated to the human, never auto-applied. Use when: 'after a model upgrade', 'are my instructions holding the model back', 'instructions the model no longer needs', 'too prescriptive', 'audit instructions', 'instruction audit', 'stale Claude Code behavior', 'outdated harness claim', 'my @path import is not loading', 'instruction re-reads CLAUDE.md'. Not a brevity pass and not memory-layer hygiene."
argument-hint: "[scope] — scope: claude-md|rules|skills|agents|hooks|output-styles|all (default: all)"
user-invocable: true
disable-model-invocation: false
Expand All @@ -17,7 +17,7 @@ doctrine, tiers it by how confident the evidence can be, and packages proposed r
rewrites as a human-gated diff — so instruction surfaces shrink as models get better instead of
only ever growing.

The check catalog — the eleven checks I1–I11, their evidence tier, authority tag, severity, and
The check catalog — the fourteen checks I1–I14, their evidence tier, authority tag, severity, and
Comment thread
kyle-sexton marked this conversation as resolved.
per-surface applicability — lives in [reference/criteria.md](reference/criteria.md). The
deterministic pre-scan is
`${CLAUDE_PLUGIN_ROOT}/skills/audit-instructions/scripts/instruction-scan.sh`.
Expand All @@ -39,15 +39,17 @@ concerns its siblings already cover — route rather than re-answer:
portability is `claude-config:audit-permission-grants`.

On **memory-layer surfaces** (CLAUDE.md, CLAUDE.local.md, `.claude/rules/`, `~/.claude/rules/`),
this skill runs only the model-era checks I6–I11. It never runs or reports the hygiene checks
this skill runs only the model-era checks I6–I12. It never runs or reports the hygiene checks
I1–I5 (line-necessity, length, placement, inferable content, rule-to-hook) on these surfaces —
that instruction-memory hygiene layer belongs to the `claude-memory` plugin. When that plugin is
installed, route memory-layer hygiene to its `audit` skill; when it is not installed, emit a single
one-line pointer to the official CLAUDE.md include/exclude guidance (recorded with I1–I5 in
[reference/criteria.md](reference/criteria.md)) so the operator knows where that audit lives — this
skill still does not perform it. Either way, no I1–I5 hygiene finding is ever produced here. On
**non-memory surfaces** (skill bodies, agent definitions, prompt-type hooks, output styles) the
full catalog I1–I11 applies — no incumbent auditor covers instruction content there.
catalog applies — no incumbent auditor covers instruction content there — **bounded by each row's
own surface declaration**, which is narrower than the partition for some checks. I13 and I14 name
their own surface sets and are not run outside them; this partition never widens a row.

**Upstream-owned surfaces are excluded from the editable set.** Installed plugin-cache content is
owned by the publishing repository, and a managed materialization is owned by whatever upstream
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,11 @@
"id": 2,
"name": "scope-boundary-routes-out",
"prompt": "/claude-config:audit-instructions is my CLAUDE.md too long, and can you prune the always-loaded hygiene lines out of it?",
"expected_output": "Recognizes memory-layer hygiene — line budget, whether CLAUDE.md is too long, pruning always-loaded content — as the claude-memory plugin's audit skill's concern. On memory-layer surfaces (CLAUDE.md, CLAUDE.local.md, .claude/rules) this skill runs only the model-era checks I6-I11 and routes the I1-I5 hygiene findings to claude-memory:audit when that plugin is installed, falling back to the official CLAUDE.md include/exclude guidance pointer when it is not, rather than answering the hygiene question itself.",
"expected_output": "Recognizes memory-layer hygiene — line budget, whether CLAUDE.md is too long, pruning always-loaded content — as the claude-memory plugin's audit skill's concern. On memory-layer surfaces (CLAUDE.md, CLAUDE.local.md, .claude/rules) this skill runs only the model-era checks I6-I12 and routes the I1-I5 hygiene findings to claude-memory:audit when that plugin is installed, falling back to the official CLAUDE.md include/exclude guidance pointer when it is not, rather than answering the hygiene question itself.",
"files": [],
"expectations": [
"Routes memory-layer hygiene (line budget, 'CLAUDE.md too long', pruning) to the claude-memory plugin's audit skill when installed",
"On memory-layer surfaces runs only the model-era checks I6-I11, not the I1-I5 hygiene checks",
"On memory-layer surfaces runs only the model-era checks I6-I12, not the I1-I5 hygiene checks",
"Falls back to the official CLAUDE.md include/exclude guidance pointer when claude-memory is not installed instead of silently skipping"
]
},
Expand Down
Loading
Loading