melodic-software/audit-plugins

Audit Plugins Command

Validate plugin manifests, component organization, namespace compliance, and marketplace readiness.

Initialization

Before auditing, initialize the environment:

1. Get the current UTC date for audit timestamps.
2. Capture the project root path for subagent communication.
3. Ensure the temp directory (.claude/temp/) exists.
4. Clean up any stale audit files if the user confirms.

The plugin-development skill provides authoritative validation guidance (auto-loaded when this command runs).

What Gets Audited

• plugin.json manifest structure and validity
• Required fields (name, description, version)
• Component organization (commands, skills, agents, hooks)
• Namespace compliance and consistency
• Documentation completeness
• Distribution and marketplace readiness

Command Arguments

| Argument | Description | | --- | --- | | (none) | Smart mode: audit only modified, never-audited, or stale (>90 days) plugins | | --force | Audit ALL plugins regardless of status | | --skip-validation | Skip finding validation (faster, but may include false positives) | | --local-only | Only audit local/dev repo plugins | | --global-only | Only audit globally installed plugins | | plugin-name | Audit specific plugin(s) by name | | local:name | Explicitly target local plugin | | global:name | Explicitly target global plugin |

Step 1: Discover Plugin Sources

Detect all plugin sources in local repo and globally installed locations.

For local discovery, check marketplace repos (plugins/*/plugin.json), single plugin repos (.claude-plugin/plugin.json), and track plugin names for deduplication.

For global discovery, check ~/.claude/plugins/ (Unix) or %USERPROFILE%\.claude\plugins\ (Windows). Skip globals that have local dev versions.

Step 2: Parse Arguments

Parse flags and plugin names from the command arguments. Read audit logs for each discovered source to determine audit status (modified, never audited, stale >90 days).

Step 3: Present Audit Plan

Display mode (SMART or FORCE), sources discovered, deduplication status, and audit queue with batching strategy.

Step 4: Execute Audits

For each plugin, spawn the plugin-component-auditor subagent with the following context:

• Source (local or global)
• Full path to plugin directory
• Manifest location (path to plugin.json)
• Last audit date or "Never audited"
• Current audit date
• Project root path

Run subagents in parallel batches of 3-5.

Role boundaries:

• Subagents write individual audit findings to .claude/temp/ as JSON and markdown files
• Main command collects subagent results, aggregates scores, and updates the central audit log

Step 4.5: Validate Findings

Unless --skip-validation flag is present:

1. Spawn the audit-finding-validator agent with:
   • project_root: The captured project root path
   • audit_type: "plugin"
   • audit_files: List of .claude/temp/audit-*-plugin-*.json file paths
2. Wait for validation to complete
3. Read updated JSON files with validation results
4. Filter out FALSE_POSITIVE findings completely before aggregation
5. Note: Filtered findings are logged to .claude/temp/audit-filtered-findings.json

If --skip-validation flag is present:

• Skip validation phase entirely (current speed preserved)
• Present all findings without filtering
• Note in summary: "Validation: Skipped"

Step 5: Final Summary

Report total audited by source, results, and details table. Note that global plugin fixes must be applied manually.

Include validation statistics (if validation was performed):

• Validation performed: Yes/No
• Findings validated: X
• False positives filtered: Y
• Verified findings: Z
• Unverified findings: W

Important Notes

Deduplication

Local dev repo plugins take precedence over globally installed versions. Global plugins are read-only - report findings but recommend manual fixes.

Cross-Platform Paths

| Platform | Global Plugins | | --- | --- | | Unix | ~/.claude/plugins/ | | Windows | %USERPROFILE%\.claude\plugins\ |

Manifest Locations

Plugins may store their manifest in either plugin.json (root) or .claude-plugin/plugin.json (nested). Check both locations during discovery.

Audit Log Location

All audit results are written to .claude/audit/plugins.md.

Use /audit-log plugins to view current audit status.

Example Usage

Example 1: Audit All Plugins

User: /audit-plugins

Claude: Discovering plugin sources...

## Audit Plan
**Mode**: SMART
- Local: claude-ecosystem, code-quality, git (3 plugins)
- Global: soft-skills (1 plugin)
- Deduplicated: claude-ecosystem (global skipped)

**Will audit**: 4 plugins in 1 batch

[Spawns plugin-component-auditor subagents]

## Audit Complete
| Source | Plugin | Result | Score |
| --- | --- | --- | --- |
| local | claude-ecosystem | PASS | 100/100 |
| local | code-quality | PASS | 95/100 |

Example 2: Audit Specific Plugin

User: /audit-plugins claude-ecosystem
Claude: PASS (Score: 100/100)