docs(readme): bring the first screen up to the org repo-standard
repo-standard v0.1.1 gate reported 5 ERROR + 5 WARN + 1 SKIP. All ERROR fixed, every WARN decided: ERROR (fixed) - HEADING-MISSING x3: added `## Install`, renamed "What This Plugin Does Not Cover" -> `## Non-goals`, "Version History" -> `## Changelog`. - INSTALL-NO-CLI: `marketplace add` now followed by the actual CLI command `claude plugin install config-audit@ktg-plugin-marketplace`. The `enabledPlugins` JSON stays beside it as the second form. - README-DESC: opening line is now the published forge/plugin.json description verbatim, so description == catalog == README. WARN (fixed) - README-H1: `# Config-Audit Plugin for Claude Code` -> `# config-audit`. - BADGE-STATIC-CLAIM: dropped the static `tests-1441` badge — it asserted a run nothing verifies, and it was stale (real count 1477). The Testing section now carries the measured number plus the fact that no CI runs it. self-audit --check-readme skips absent badges, still PASS. - LINK-NON-REPO: `open/claude-code-llm-security` -> `open/llm-security` (the org's rename). SKIP (fixed, closes catalog's coord message) - LINK-OUTSIDE-REPO README:7: the `../../README.md` disclosure link was a monorepo leftover pointing outside the repo at an anchor that never existed. Replaced with the inline text the polyrepo migration intended. Also removed the "What's New in v5.4.0" section: 24 lines of release notes as the first TOC entry on a v5.13.0 repo, duplicating the v5.4.0 row in the changelog table it sat above. Gate re-run: 0 ERROR, 11 checks passed. Full suite 1477/1477. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011oUzeHA1Kmi2z8ug83PzbS
This commit is contained in:
parent
d68b2152e3
commit
1b49bcc766
1 changed files with 36 additions and 60 deletions
96
README.md
96
README.md
|
|
@ -1,10 +1,12 @@
|
|||
# Config-Audit Plugin for Claude Code
|
||||
# config-audit
|
||||
|
||||
> Know if your configuration is correct. Find what could improve it. Fix it automatically.
|
||||
Multi-agent workflow for analyzing, reporting, and optimizing Claude Code configuration across your entire machine
|
||||
|
||||
Know if your configuration is correct. Find what could improve it. Fix it automatically.
|
||||
|
||||
> **Solo-maintained, fork-and-own.** This plugin is a starting point, not a vendor product. Issues are welcome as signals; pull requests are not accepted. See [GOVERNANCE.md](GOVERNANCE.md) for the full model and what upstream provides.
|
||||
|
||||
*AI-generated: all code produced by Claude Code through dialog-driven development. [Full disclosure →](../../README.md#ai-generated-code-disclosure)*
|
||||
*AI-generated: all code produced by Claude Code through dialog-driven development. Every change is human-directed, reviewed, and validated before commit.*
|
||||
|
||||
|
||||
|
||||
|
|
@ -12,16 +14,36 @@
|
|||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
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. 16 deterministic scanners across 10 quality areas, context-aware feature recommendations, auto-fix with backup/rollback, a prompt-cache-aware Token Hotspots scanner with optional API-calibrated `--accurate-tokens` mode, plus cache-prefix stability, dead-tool, cross-plugin collision, output-style, and always-loaded agent-listing-budget detection. Zero external dependencies.
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git
|
||||
claude plugin install config-audit@ktg-plugin-marketplace
|
||||
```
|
||||
|
||||
Or enable directly in `~/.claude/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"enabledPlugins": {
|
||||
"config-audit@ktg-plugin-marketplace": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed
|
||||
- Node.js 18+ — the scanners also run standalone from a clone, with no other dependencies
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [What's New in v5.4.0](#whats-new-in-v540)
|
||||
- [What Is This?](#what-is-this)
|
||||
- [The Configuration Problem](#the-configuration-problem)
|
||||
- [Quick Start](#quick-start)
|
||||
|
|
@ -39,38 +61,13 @@ A Claude Code plugin that checks configuration health, suggests context-aware im
|
|||
- [Testing](#testing)
|
||||
- [Gotchas](#gotchas)
|
||||
- [Data Storage & Safety Guarantees](#data-storage--safety-guarantees)
|
||||
- [What This Plugin Does Not Cover](#what-this-plugin-does-not-cover)
|
||||
- [Non-goals](#non-goals)
|
||||
- [config-audit vs. the built-in /doctor](#config-audit-vs-the-built-in-doctor)
|
||||
- [Version History](#version-history)
|
||||
- [Changelog](#changelog)
|
||||
- [License](#license)
|
||||
|
||||
---
|
||||
|
||||
## What's New in v5.4.0
|
||||
|
||||
**Plugin-hygiene & settings-validation hardening.** Three additive findings extend the plugin and
|
||||
settings surfaces — no new scanner, so the count stays **13**:
|
||||
|
||||
- **PLH plugin-folder shadowing** (`CA-PLH-015`) — flags a `plugin.json` component-path key in the
|
||||
*replaces* set (`commands`/`agents`/`outputStyles`) that points at a custom path while the
|
||||
default folder of that name still exists, so the folder is silently ignored (dead config).
|
||||
Mirrors Claude Code's own warning in `/doctor`, `claude plugin list`, and the `/plugin` detail
|
||||
view. `skills` is excluded (it *adds to* the default scan, never shadows), as are
|
||||
`hooks`/`mcpServers`/`lspServers` (own merge rules); a custom path resolving *into* the default
|
||||
folder is not flagged.
|
||||
- **PLH `skills:`-array validation** (`CA-PLH-016`) — validates each `plugin.json` `skills` entry
|
||||
(string or array) resolves to an existing directory inside the plugin root; flags `non-string`,
|
||||
`escapes-root`, `not-found`, and `not-a-directory` entries. Mirrors `claude plugin validate`.
|
||||
- **SET `autoMode` structure + dead-config** — checks that `autoMode` is an object whose only keys
|
||||
are `environment`/`allow`/`soft_deny`/`hard_deny`, each a string array (the literal `"$defaults"`
|
||||
is valid); unknown sub-keys and wrong types are flagged (medium). Separately, `autoMode` placed
|
||||
in **shared** project settings (`.claude/settings.json`) is flagged as dead config (low) —
|
||||
Claude Code's classifier does not read it there.
|
||||
|
||||
All three extend existing PLH and SET scanners. `--json` and `--raw` output remain byte-stable.
|
||||
|
||||
---
|
||||
|
||||
## What Is This?
|
||||
|
||||
Claude Code reads instructions from at least 7 different file types across multiple scopes: `CLAUDE.md`, `settings.json`, `.claude/rules/`, `hooks.json`, `.mcp.json`, `.claudeignore`, and `settings.local.json`. Each can exist at project level, user level, or both. Plugins add more. The system is powerful — but nobody tells you what you're using wrong, what you're missing, or what's silently conflicting.
|
||||
|
|
@ -155,28 +152,7 @@ Also **Grade A** — with only 3 opportunities remaining. This project has CLAUD
|
|||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed
|
||||
- Node.js 18+ (for standalone CLI tools)
|
||||
|
||||
### Installation
|
||||
|
||||
Add the marketplace and browse plugins with `/plugin`:
|
||||
|
||||
```bash
|
||||
claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git
|
||||
```
|
||||
|
||||
Or enable directly in `~/.claude/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"enabledPlugins": {
|
||||
"config-audit@ktg-plugin-marketplace": true
|
||||
}
|
||||
}
|
||||
```
|
||||
Install first — see [Install](#install) above.
|
||||
|
||||
### First Scan
|
||||
|
||||
|
|
@ -631,7 +607,7 @@ the finding, and the reason precision-over-recall is the only defensible tuning.
|
|||
node --test 'tests/**/*.test.mjs'
|
||||
```
|
||||
|
||||
1168 tests across 67 test files (22 lib + 35 scanner + 1 hook + 1 agent + 3 commands + 1 knowledge + 4 top-level). Test fixtures in `tests/fixtures/`. Requires Node.js 18+ (`node:test`).
|
||||
That one command runs the whole suite from a clean clone: **1477 tests, 370 suites** (measured 2026-08-03, all passing). Nothing runs it automatically — there is no CI in this organisation, so the command above is the verification, not a badge. Test fixtures in `tests/fixtures/`. Requires Node.js 18+ (`node:test`).
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -677,9 +653,9 @@ This plugin is cautious by design — configuration files are important, and a b
|
|||
|
||||
---
|
||||
|
||||
## What This Plugin Does Not Cover
|
||||
## Non-goals
|
||||
|
||||
- **Runtime behavior** — this plugin audits configuration files, not what Claude actually does at runtime. For runtime defense, see [claude-code-llm-security](https://git.fromaitochitta.com/open/claude-code-llm-security)
|
||||
- **Runtime behavior** — this plugin audits configuration files, not what Claude actually does at runtime. For runtime defense, see [llm-security](https://git.fromaitochitta.com/open/llm-security)
|
||||
- **Secret scanning** — config-audit checks for structural issues, not leaked credentials. Use llm-security for secret detection
|
||||
- **Custom scanner rules** — scanners check against known Claude Code configuration schemas. Custom rule definitions are not supported
|
||||
- **Remote/team configuration** — managed settings, SSO-provisioned config, and organization-level policies are detected as gaps but not managed
|
||||
|
|
@ -713,7 +689,9 @@ reproducible, all-scope, zero-quota auditing.
|
|||
|
||||
---
|
||||
|
||||
## Version History
|
||||
## Changelog
|
||||
|
||||
Full detail in [CHANGELOG.md](CHANGELOG.md). Highlights per release:
|
||||
|
||||
| Version | Date | Highlights |
|
||||
|---------|------|-----------|
|
||||
|
|
@ -753,8 +731,6 @@ reproducible, all-scope, zero-quota auditing.
|
|||
| **1.0.0** | 2026-02-11 | Cross-platform support |
|
||||
| **0.7.0** | 2026-02-07 | Initial version (version reset from inflated 1.2.0) |
|
||||
|
||||
See [CHANGELOG.md](CHANGELOG.md) for full details.
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue