Kjell Tore Guttormsen
001090261e
Dogfooding `/config-audit plugin-health` against a fasit registered before the
run: 11 of 12 predictions confirmed, 1 refuted with evidence, 0 deviations.
The command's default path could not produce the report it documents.
M-BUG-21 (third arm): the argument loop ended in
`else if (!args[i].startsWith('-')) targetPath = args[i]` with no unknown-flag
branch, so `--output-file /tmp/x.json` was dropped and its value became the scan
target. Worse than in drift-cli: a non-existent path discovers no plugins, so the
scanner answered "No plugins found" (info) with exit 0 — a reassuring answer, not
an error. Unknown options and a value-less `--output-file` now exit 3.
M-BUG-33: the scanner had no `--output-file` and its default-mode report goes to
stderr, which `commands/plugin-health.md` discards with `2>/dev/null` before
telling the agent to read stdout. Zero bytes captured.
M-BUG-34: per-plugin rows and the grade formula never left `scan()` — the only
grade code, `formatPluginHealthReport`, had no caller — and cross-plugin findings
were flattened behind a `category` they share with per-plugin findings. The
mandated table and Cross-Plugin section were unbuildable, so the command had to
fabricate them. `scanDetailed()` now returns them; `scan()`'s frozen v5.0.0
envelope is unchanged by construction.
M-BUG-35: `.claude-plugin/marketplace.json` was flagged as an unknown file. It is
the documented catalog location, and `"source": "./"` makes the repo root its own
plugin, so one `.claude-plugin/` legitimately holds both.
Also: `commands/posture.md` ran both optional scanners in default mode under
`2>/dev/null` and read stdout — the same class as feature-gap.md:133 in the fix
chunk. A CLI-side flag fix does not close its callers.
Tests 1420 -> 1432, red first. Frozen v5.0.0 snapshots untouched.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XhhZ8zg1amR7YCAPqiZWdt
86 lines
3.3 KiB
Markdown
86 lines
3.3 KiB
Markdown
---
|
|
name: config-audit:plugin-health
|
|
description: Audit plugin configuration quality — validates structure, frontmatter, and cross-plugin coherence
|
|
argument-hint: "[plugin-path]"
|
|
allowed-tools: Read, Glob, Grep, Bash
|
|
model: sonnet
|
|
---
|
|
|
|
# Config-Audit: Plugin Health
|
|
|
|
Audit Claude Code plugin structure and quality — validates plugin.json, CLAUDE.md, command/agent frontmatter, and detects cross-plugin conflicts.
|
|
|
|
## Arguments
|
|
|
|
- `$ARGUMENTS` may contain a path to a specific plugin directory
|
|
- If omitted: scans all plugins in the marketplace root
|
|
- `--raw`: pass-through to the scanner; produces v5.0.0 verbatim envelope (bypasses the humanizer) for byte-stable diff tooling
|
|
|
|
## Implementation
|
|
|
|
### Step 1: Discover plugins and greet
|
|
|
|
If a specific path is given, scan only that plugin. Otherwise, find all plugins using Glob for `**/.claude-plugin/plugin.json`.
|
|
|
|
Tell the user:
|
|
|
|
```
|
|
## Plugin Health Check
|
|
|
|
Auditing {N} plugin(s) for structure, frontmatter quality, and cross-plugin conflicts...
|
|
```
|
|
|
|
### Step 2: Run scanner
|
|
|
|
Run silently for each plugin. Default mode writes a humanized JSON payload to `--output-file` where each PLH finding carries `userImpactCategory`, `userActionLanguage`, and `relevanceContext` alongside the v5.0.0 fields. `--raw` is passed through verbatim when present, and prints the byte-stable v5.0.0 envelope on stdout instead.
|
|
|
|
```bash
|
|
TMPFILE="/tmp/config-audit-plugin-health-$$.json"
|
|
RAW_FLAG=""
|
|
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
|
|
node ${CLAUDE_PLUGIN_ROOT}/scanners/plugin-health-scanner.mjs <path> --output-file "$TMPFILE" $RAW_FLAG 2>/dev/null; echo $?
|
|
```
|
|
|
|
Read `$TMPFILE` with the Read tool. Exit codes 0, 1 and 2 are normal; only 3 is a real error.
|
|
|
|
The payload carries three things the report needs:
|
|
|
|
- `plugins[]` — one row per plugin: `name`, `declaredName`, `commandCount`, `agentCount`, `findingCount`, `score`, `grade`. Use these for the table; never estimate a grade yourself.
|
|
- `cross_plugin_findings[]` — the namespace-collision and shared-command-name findings, already separated from the per-plugin ones (they also carry `crossPlugin: true` in `findings`).
|
|
- `findings[]` — every finding, humanized.
|
|
|
|
### Step 3: Present results
|
|
|
|
```markdown
|
|
### Plugin Health Report
|
|
|
|
| Plugin | Grade | Commands | Agents | Status |
|
|
|--------|-------|----------|--------|--------|
|
|
| {plugins[].name} | {plugins[].grade} ({plugins[].score}) | {plugins[].commandCount} | {plugins[].agentCount} | {Good/Issues found} |
|
|
| ... | ... | ... | ... | ... |
|
|
|
|
{If cross-plugin issues:}
|
|
#### Cross-Plugin Issues ({count})
|
|
| Issue | Plugins | Recommendation |
|
|
|-------|---------|----------------|
|
|
| ... | ... | ... |
|
|
|
|
{If findings:}
|
|
#### Findings by Plugin
|
|
|
|
**{plugin-name}** ({finding_count} findings):
|
|
1. [{userActionLanguage}] {humanized title} ({id}) — {humanized recommendation}
|
|
2. ...
|
|
```
|
|
|
|
Group findings within each plugin by `userImpactCategory` (e.g., "Configuration mistake", "Conflict") and lead each line with `userActionLanguage` ("Fix this now", "Fix soon", "Optional cleanup"). The humanizer already produced the plain-language `title`/`recommendation` strings — render them verbatim, do not paraphrase.
|
|
|
|
### Step 4: Suggest next steps
|
|
|
|
```
|
|
### What's next
|
|
|
|
- Fix structural issues based on recommendations above
|
|
- `/config-audit posture` — Full configuration posture assessment
|
|
- `/config-audit fix` — Auto-fix deterministic issues
|
|
```
|