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 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen
parent
a6aada851f
commit
c74feff3c9
1 changed files with 99 additions and 16 deletions
|
|
@ -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 <path> [--json] [--global]` |
|
||||
| **Posture** | `node scanners/posture.mjs <path> [--json] [--global] [--full-machine] [--output-file path]` |
|
||||
| **Fix** | `node scanners/fix-cli.mjs <path> [--apply] [--json] [--global]` |
|
||||
| **Drift** | `node scanners/drift-cli.mjs <path> [--save] [--baseline name] [--json]` |
|
||||
| **Self-audit** | `node scanners/self-audit.mjs [--json] [--fix]` |
|
||||
| **Full scan** | `node scanners/scan-orchestrator.mjs <path> [--global] [--no-suppress]` |
|
||||
| **Full scan** | `node scanners/scan-orchestrator.mjs <path> [--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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue