From 1f4bbd3b52ebe13ef8f008a991317f473ef32a66 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Sun, 19 Apr 2026 22:55:26 +0200 Subject: [PATCH] docs(config-audit): update README for v4.0.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Version badge 3.1.0 → 4.0.0, scanners 8 → 9, commands 16 → 17 - New /config-audit tokens row in commands table - TOK scanner row in deterministic scanners table - Token Hotspots CLI in CLI tools list - scanner-agent + verifier-agent rows updated to Sonnet - Orchestration ASCII diagram updated (haiku → sonnet) - v4.0.0 entry added to version history Co-Authored-By: Claude Opus 4.7 --- plugins/config-audit/README.md | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/plugins/config-audit/README.md b/plugins/config-audit/README.md index 656c0d1..ef6d296 100644 --- a/plugins/config-audit/README.md +++ b/plugins/config-audit/README.md @@ -6,16 +6,16 @@ *AI-generated: all code produced by Claude Code through dialog-driven development. [Full disclosure →](../../README.md#ai-generated-code-disclosure)* -![Version](https://img.shields.io/badge/version-3.1.0-blue) +![Version](https://img.shields.io/badge/version-4.0.0-blue) ![Platform](https://img.shields.io/badge/platform-Claude_Code_Plugin-purple) -![Scanners](https://img.shields.io/badge/scanners-8-cyan) -![Commands](https://img.shields.io/badge/commands-16-green) +![Scanners](https://img.shields.io/badge/scanners-9-cyan) +![Commands](https://img.shields.io/badge/commands-17-green) ![Agents](https://img.shields.io/badge/agents-6-orange) ![Hooks](https://img.shields.io/badge/hooks-4-red) -![Tests](https://img.shields.io/badge/tests-522+-brightgreen) +![Tests](https://img.shields.io/badge/tests-498+-brightgreen) ![License](https://img.shields.io/badge/license-MIT-lightgrey) -A Claude Code plugin that checks configuration health, suggests context-aware improvements, and auto-fixes issues — `CLAUDE.md`, `settings.json`, hooks, rules, MCP servers, `@imports`, and plugins. 7 quality scanners for correctness, context-aware feature recommendations, auto-fix with backup/rollback. Zero external dependencies. +A Claude Code plugin that checks configuration health, suggests context-aware improvements, and auto-fixes issues — `CLAUDE.md`, `settings.json`, hooks, rules, MCP servers, `@imports`, and plugins. 8 quality scanners for correctness, context-aware feature recommendations, auto-fix with backup/rollback, plus an Opus-4.7-aware Token Hotspots scanner. Zero external dependencies. --- @@ -50,7 +50,7 @@ Claude Code reads instructions from at least 7 different file types across multi This plugin provides three layers of configuration intelligence: -- **Health** — 7 deterministic scanners verify correctness across every configuration file, catching broken imports, deprecated settings, conflicting rules, format errors, and permission contradictions +- **Health** — 8 deterministic scanners verify correctness across every configuration file, catching broken imports, deprecated settings, conflicting rules, format errors, permission contradictions, and Opus-4.7-era token waste - **Opportunities** — context-aware recommendations for Claude Code features that could benefit your specific project, backed by Anthropic's official guidance - **Action** — auto-fix with mandatory backups, syntax validation, rollback support, and a human-in-the-loop workflow for anything non-trivial @@ -248,7 +248,8 @@ Your team configuration changes over time. Track it: | Command | Description | |---------|-------------| | `/config-audit` | Full audit with auto-scope detection (no setup needed) | -| `/config-audit posture` | Quick health scorecard: A-F grades across 7 quality areas | +| `/config-audit posture` | Quick health scorecard: A-F grades across 8 quality areas (incl. Token Efficiency) | +| `/config-audit tokens` | Opus-4.7-aware token hotspots — ranked by estimated waste, with 4-pattern findings | | `/config-audit feature-gap` | Context-aware feature recommendations grouped by impact | | `/config-audit fix` | Auto-fix deterministic issues with backup + verification | | `/config-audit rollback` | Restore configuration from a previous backup | @@ -276,7 +277,7 @@ By default, `/config-audit` auto-detects scope from your git context. Override w ## Deterministic Scanners -8 Node.js scanners that perform structural analysis an LLM cannot reliably do: schema validation, circular reference detection, import resolution, conflict detection across scopes. Zero external dependencies. +9 Node.js scanners that perform structural analysis an LLM cannot reliably do: schema validation, circular reference detection, import resolution, conflict detection across scopes, and Opus-4.7-aware token-cost analysis. Zero external dependencies. **Why deterministic?** LLMs are powerful at understanding intent and context. But they cannot reliably validate JSON schemas, detect circular `@import` chains, or catch that your global `settings.json` contradicts your project-level one. These scanners fill that gap — fast, repeatable, and zero false positives on structural issues. @@ -290,6 +291,7 @@ By default, `/config-audit` auto-detects scope from your git context. Override w | `import-resolver.mjs` | IMP | Broken @imports, circular references, deep chains, tilde path issues | | `conflict-detector.mjs` | CNF | Settings contradictions across scopes, permission conflicts, hook duplicates | | `feature-gap-scanner.mjs` | GAP | 25 feature checks — shown as opportunities, not grades | +| `token-hotspots.mjs` | TOK | Cache-breaking volatile content, redundant tool permissions, deep import chains, sonnet-era setups | ### CLI Tools @@ -300,6 +302,7 @@ All tools work standalone — no Claude Code session needed: | **Posture** | `node scanners/posture.mjs [--json] [--global] [--full-machine] [--output-file path]` | | **Fix** | `node scanners/fix-cli.mjs [--apply] [--json] [--global]` | | **Drift** | `node scanners/drift-cli.mjs [--save] [--baseline name] [--json]` | +| **Tokens** | `node scanners/token-hotspots-cli.mjs [--json] [--global] [--output-file path]` | | **Self-audit** | `node scanners/self-audit.mjs [--json] [--fix]` | | **Full scan** | `node scanners/scan-orchestrator.mjs [--global] [--full-machine] [--no-suppress]` | @@ -311,11 +314,11 @@ Six specialized agents collaborate through the audit workflow, each matched to a | Agent | Model | Role | Tools | |-------|-------|------|-------| -| **scanner-agent** | Haiku | Fast filesystem scanning, file discovery | Read, Glob, Grep, Write | +| **scanner-agent** | Sonnet | Fast filesystem scanning, file discovery | Read, Glob, Grep, Write | | **analyzer-agent** | Sonnet | Deep analysis, hierarchy mapping, conflict detection | Read, Glob, Grep, Write | | **planner-agent** | Opus | Action plan generation with risk assessment | Read, Glob, Write | | **implementer-agent** | Sonnet | Change execution with mandatory backups | Read, Write, Edit, Bash, Glob | -| **verifier-agent** | Haiku | Post-implementation verification | Read, Glob, Grep | +| **verifier-agent** | Sonnet | Post-implementation verification | Read, Glob, Grep | | **feature-gap-agent** | Opus | Context-aware feature recommendations | Read, Glob, Grep, Write | ### Orchestration Flow @@ -327,12 +330,12 @@ Six specialized agents collaborate through the audit workflow, each matched to a | +-----------+ +---------+ +-------v---+ +-----------+ | Discover | --> | Analyze | --> | Plan | --> | Implement | -| (haiku) | | (sonnet)| | (opus) | | (sonnet) | +| (sonnet) | | (sonnet)| | (opus) | | (sonnet) | +-----------+ +---------+ +-----------+ +-----+-----+ | +-----v-----+ | Verify | - | (haiku) | + | (sonnet) | +-----------+ ``` @@ -410,7 +413,7 @@ node scanners/posture.mjs examples/optimal-setup/ ### Self-Audit: Scanning the Scanner -The plugin runs all 8 scanners on itself via `self-audit.mjs`. Current result: **Grade A, score 98, 0 real findings.** Test fixtures and example files are automatically excluded from scoring — a security plugin that ships deliberately broken examples shouldn't fail its own audit. +The plugin runs all 9 scanners on itself via `self-audit.mjs`. Current result: **Grade A, score 98, 0 real findings.** Test fixtures and example files are automatically excluded from scoring — a security plugin that ships deliberately broken examples shouldn't fail its own audit. ```bash node scanners/self-audit.mjs @@ -527,6 +530,7 @@ This plugin is cautious by design — configuration files are important, and a b | Version | Date | Highlights | |---------|------|-----------| +| **4.0.0** | 2026-04-19 | Opus 4.7 era: new TOK scanner (cache-breaking volatile content, redundant tool permissions, deep import chains, sonnet-era setups), `/config-audit tokens` command, Token Efficiency 8th quality area, scanner-agent + verifier-agent migrated haiku → sonnet. 498+ tests | | **3.1.0** | 2026-04-14 | New `/config-audit whats-active` — read-only inventory of active plugins, skills, MCP, hooks, CLAUDE.md for a repo, with token estimates. 522 tests | | **3.0.1** | 2026-04-04 | Cross-platform fix: Windows path separators. 486 tests | | **3.0.0** | 2026-04-04 | Health redesign: quality-only grades, context-aware opportunities (replaces utilization/maturity/segment), Anthropic guidance. 482 tests |