ktg-plugin-marketplace/plugins/config-audit/CLAUDE.md

Config-Audit Plugin

Claude Code Configuration Intelligence — know if your configuration is correct, find what could improve it, fix it automatically.

What this plugin does

Analyzes and optimizes Claude Code configuration across three pillars:

• Health — Deterministic scanners verify correctness, consistency, and completeness
• Opportunities — Context-aware recommendations for features that could benefit your project
• Action — Auto-fix with backup/rollback

Commands

Core (just run /config-audit to get started)

Command	Description
/config-audit	Full audit with auto-scope detection (no setup needed)
/config-audit posture	Quick health scorecard (A-F grades, 7 quality areas)
/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 backup
/config-audit plan	Create action plan from audit findings
/config-audit implement	Execute plan with backups + auto-verify
/config-audit help	Show all commands

Additional

Command	Description
/config-audit drift	Compare current config against saved baseline
/config-audit plugin-health	Audit plugin structure, frontmatter, cross-plugin coherence
/config-audit discover	Run discovery phase only
/config-audit analyze	Run analysis phase only
/config-audit interview	Gather user preferences (opt-in)
/config-audit status	Show current session state
/config-audit cleanup	Clean up old sessions

Agents

Agent	Role	Model	Color	Tools
scanner-agent	Find config files	haiku	cyan	Read, Glob, Grep, Write
analyzer-agent	Generate report	sonnet	blue	Read, Glob, Grep, Write
planner-agent	Create action plan	opus	yellow	Read, Glob, Write
implementer-agent	Execute changes	sonnet	magenta	Read, Write, Edit, Bash, Glob
verifier-agent	Verify results	haiku	purple	Read, Glob, Grep
feature-gap-agent	Context-aware feature recommendations	opus	green	Read, Glob, Grep, Write

Deterministic Scanners

Node.js scanners (zero external dependencies), run via node scanners/scan-orchestrator.mjs <path>. Posture CLI: node scanners/posture.mjs <path> [--json] [--global] [--full-machine] [--output-file path]. Scanner CLI: node scanners/scan-orchestrator.mjs <path> [--global] [--full-machine] [--no-suppress].

Scanner	Prefix	Detects
claude-md-linter.mjs	CML	Structure, length, sections, @imports, duplicates, TODOs
settings-validator.mjs	SET	Schema, unknown/deprecated keys, type mismatches, permissions
hook-validator.mjs	HKV	Format, script existence, event validity, timeouts
rules-validator.mjs	RUL	Glob matching, orphan rules, deprecated fields, unscoped rules
mcp-config-validator.mjs	MCP	Server types, trust levels, env vars, unknown fields
import-resolver.mjs	IMP	Broken @imports, circular refs, deep chains, tilde paths
conflict-detector.mjs	CNF	Settings conflicts, permission contradictions, hook duplicates
feature-gap-scanner.mjs	GAP	25 feature checks across 4 tiers — shown as opportunities, not grades

Scanner Lib (scanners/lib/)

Module	Purpose
severity.mjs	Severity constants, risk scoring, verdict logic
output.mjs	Finding objects (CA-XXX-NNN format), scanner results, envelope
file-discovery.mjs	Config file discovery: single-path, multi-path (discoverConfigFilesMulti), full-machine (discoverFullMachinePaths)
yaml-parser.mjs	Frontmatter parsing, JSON parsing, @import/section extraction
string-utils.mjs	Line counting, truncation, similarity, key extraction
scoring.mjs	Area scoring, health scorecard, legacy utilization/maturity
backup.mjs	Backup creation, manifest parsing, checksum verification
diff-engine.mjs	Drift diffing: diffEnvelopes(), formatDiffReport()
baseline.mjs	Baseline save/load/list/delete for drift detection
report-generator.mjs	Unified markdown reports: posture, drift, plugin health
suppression.mjs	.config-audit-ignore parsing, finding suppression, audit trail

Action Engines (scanners/)

Module	Purpose
fix-engine.mjs	planFixes(), applyFixes(), verifyFixes() — 9 fix types
rollback-engine.mjs	listBackups(), restoreBackup(), deleteBackup()
fix-cli.mjs	CLI: node fix-cli.mjs <path> [--apply] [--json] [--global]
drift-cli.mjs	CLI: node drift-cli.mjs <path> [--save] [--baseline name] [--json]

Standalone Scanner

Module	Prefix	Purpose
plugin-health-scanner.mjs	PLH	Plugin structure, frontmatter, cross-plugin conflicts (runs independently)
self-audit.mjs	—	Runs all scanners + plugin health on this plugin itself

Knowledge Base (knowledge/)

File	Content
claude-code-capabilities.md	Feature register: 18 config surfaces, Anthropic guidance, relevance table
configuration-best-practices.md	Per-layer best practices
anti-patterns.md	Common mistakes mapped to scanner IDs
hook-events-reference.md	All 26 hook events with details
feature-evolution.md	Feature timeline for staleness detection
gap-closure-templates.md	Config-specific templates for closing gaps

Hooks

Event	Script	Purpose
PreToolUse	auto-backup-config.mjs	Auto-backup config files before Edit/Write
PostToolUse	post-edit-verify.mjs	Verify config files after Edit/Write, block on new critical/high
SessionStart	session-start.mjs	Checks for active (unfinished) sessions
Stop	stop-session-reminder.mjs	Reminds about current session phase

Suppressions

Create .config-audit-ignore at project root to suppress known findings:

CA-SET-003          # Exact ID
CA-GAP-*            # Glob pattern (all GAP findings)

Suppressed findings tracked in envelope's suppressed_findings for audit trail. Disable with --no-suppress.

Architecture

Workflow

/config-audit  →  discover + analyze (auto)  →  plan  →  implement  →  verify

Default: auto-detects scope from git context. Override with /config-audit full|repo|home|current. Delta mode: --delta (incremental).

Session Directory

~/.claude/config-audit/sessions/{session-id}/
├── scope.yaml, discovery.json, state.yaml
├── findings/, analysis-report.md, action-plan.md
├── backups/, implementation-log.md
└── interview.md (if interview run)

Finding ID Format

CA-{SCANNER}-{NNN} — e.g. CA-CML-001, CA-SET-003, CA-HKV-002, CA-RUL-005

Testing

node --test 'tests/**/*.test.mjs'

486 tests across 27 test files (10 lib + 16 scanner + 1 hook). Test fixtures in tests/fixtures/.

Gotchas

• Session directories accumulate — use /config-audit cleanup to manage
• Scanners run on Node.js >= 18 (uses node:test, node:fs/promises)
• Plugin CLAUDE.md files in node_modules should be excluded via scope