From c74feff3c90a74a30f0f98977d5fe4ebfe6f1bcf Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Wed, 8 Apr 2026 15:09:05 +0200 Subject: [PATCH] docs(config-audit): close 11 README gaps vs CLAUDE.md Add missing documentation: Skills section, Scanner Library, Knowledge Base, Action Engines, Testing instructions, Gotchas, Finding ID format, --delta and --full-machine CLI flags, agent tool grants column. Co-Authored-By: Claude Opus 4.6 --- plugins/config-audit/README.md | 115 ++++++++++++++++++++++++++++----- 1 file changed, 99 insertions(+), 16 deletions(-) diff --git a/plugins/config-audit/README.md b/plugins/config-audit/README.md index 143d68c..0a67ae4 100644 --- a/plugins/config-audit/README.md +++ b/plugins/config-audit/README.md @@ -22,14 +22,19 @@ A Claude Code plugin that checks configuration health, suggests context-aware im - [What Is This?](#what-is-this) - [The Configuration Problem](#the-configuration-problem) - [Quick Start](#quick-start) -- [The Feature Gap — Your Biggest Blind Spot](#the-feature-gap--your-biggest-blind-spot) +- [Feature Opportunities](#feature-opportunities--context-aware-recommendations) - [Workflow Examples](#workflow-examples) - [Commands](#commands) - [Deterministic Scanners](#deterministic-scanners) - [Agent Architecture](#agent-architecture) - [Hooks & Safety](#hooks--safety) +- [Skills](#skills) - [Suppressions](#suppressions) - [Examples & Self-Audit](#examples--self-audit) +- [Scanner Library](#scanner-library-scannerslib) +- [Knowledge Base](#knowledge-base-knowledge) +- [Testing](#testing) +- [Gotchas](#gotchas) - [Data Storage & Safety Guarantees](#data-storage--safety-guarantees) - [What This Plugin Does Not Cover](#what-this-plugin-does-not-cover) - [Version History](#version-history) @@ -128,18 +133,18 @@ Also **Grade A** — with only 3 opportunities remaining. This project has CLAUD ### Installation -Clone from the public repository: +Add the marketplace and browse plugins with `/plugin`: ```bash -git clone https://git.fromaitochitta.com/open/claude-code-config-audit.git +claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git ``` -Or add as a Claude Code plugin: +Or enable directly in `~/.claude/settings.json`: ```json { "enabledPlugins": { - "config-audit@plugin-marketplace": true + "config-audit@ktg-plugin-marketplace": true } } ``` @@ -263,7 +268,7 @@ Your team configuration changes over time. Track it: ### Scope -By default, `/config-audit` auto-detects scope from your git context. Override with: `/config-audit current`, `/config-audit repo`, `/config-audit home`, `/config-audit full`. +By default, `/config-audit` auto-detects scope from your git context. Override with: `/config-audit current`, `/config-audit repo`, `/config-audit home`, `/config-audit full`. Use `--delta` for incremental scanning (only new/changed findings). --- @@ -290,11 +295,11 @@ All tools work standalone — no Claude Code session needed: | Tool | Usage | |------|-------| -| **Posture** | `node scanners/posture.mjs [--json] [--global]` | +| **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]` | | **Self-audit** | `node scanners/self-audit.mjs [--json] [--fix]` | -| **Full scan** | `node scanners/scan-orchestrator.mjs [--global] [--no-suppress]` | +| **Full scan** | `node scanners/scan-orchestrator.mjs [--global] [--full-machine] [--no-suppress]` | --- @@ -302,14 +307,14 @@ All tools work standalone — no Claude Code session needed: Six specialized agents collaborate through the audit workflow, each matched to an appropriate model for cost and quality: -| Agent | Model | Role | -|-------|-------|------| -| **scanner-agent** | Haiku | Fast filesystem scanning, file discovery | -| **analyzer-agent** | Sonnet | Deep analysis, hierarchy mapping, conflict detection | -| **planner-agent** | Opus | Action plan generation with risk assessment | -| **implementer-agent** | Sonnet | Change execution with mandatory backups | -| **verifier-agent** | Haiku | Post-implementation verification | -| **feature-gap-agent** | Opus | Context-aware feature recommendations | +| Agent | Model | Role | Tools | +|-------|-------|------|-------| +| **scanner-agent** | Haiku | 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 | +| **feature-gap-agent** | Opus | Context-aware feature recommendations | Read, Glob, Grep, Write | ### Orchestration Flow @@ -349,8 +354,24 @@ All hooks are Node.js (`.mjs`) for cross-platform compatibility (macOS, Linux, W --- +## Skills + +| Skill | Trigger | Description | +|-------|---------|-------------| +| `config-hierarchy` | "CLAUDE.md hierarchy", "config file locations", "settings.json structure" | Comprehensive reference for Claude Code's configuration hierarchy — CLAUDE.md, settings.json, managed config, @imports, path-scoped rules | + +Skills activate automatically when your question matches their trigger patterns. + +--- + ## Suppressions +### Finding ID Format + +Every finding has a unique ID: `CA-{SCANNER}-{NNN}` — where `{SCANNER}` is the scanner prefix (see table above) and `{NNN}` is a sequential number. Examples: `CA-CML-001`, `CA-SET-003`, `CA-HKV-002`, `CA-RUL-005`. + +### Suppression + Some findings are expected — maybe you intentionally have a large CLAUDE.md, or a feature gap doesn't apply to your workflow. Create a `.config-audit-ignore` file to suppress them: ``` @@ -395,6 +416,68 @@ node scanners/self-audit.mjs --- +## Scanner Library (`scanners/lib/`) + +Shared modules used by all scanners — useful if you're reading the source or extending the plugin: + +| 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, full-machine | +| `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 | +| `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 + +| Module | Purpose | +|--------|---------| +| `fix-engine.mjs` | `planFixes()`, `applyFixes()`, `verifyFixes()` — 9 fix types | +| `rollback-engine.mjs` | `listBackups()`, `restoreBackup()`, `deleteBackup()` | +| `fix-cli.mjs` | CLI entry point for auto-fix | +| `drift-cli.mjs` | CLI entry point for drift detection | + +--- + +## Knowledge Base (`knowledge/`) + +Reference documents that inform the feature-gap agent and context-aware recommendations: + +| 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 | + +--- + +## Testing + +```bash +node --test 'tests/**/*.test.mjs' +``` + +486 tests across 27 test files (10 lib + 16 scanner + 1 hook). Test fixtures in `tests/fixtures/`. Requires Node.js 18+ (`node:test`). + +--- + +## Gotchas + +- **Session accumulation** — session directories at `~/.claude/config-audit/sessions/` grow over time. Use `/config-audit cleanup` to manage +- **Node.js version** — scanners require Node.js 18+ (uses `node:test`, `node:fs/promises`) +- **Plugin CLAUDE.md in node_modules** — these should be excluded via scope to avoid false positives + +--- + ## Data Storage & Safety Guarantees ### Where Data Lives