auditing

Auditing Bundle-Plugins

Overview

Systematically evaluate a bundle-plugin project or a single skill across applicable quality categories — including security scanning — score each, and produce a diagnostic report. This skill is a pure diagnostic tool: it identifies and reports issues but does not orchestrate fixes.

Core principle: Measure and report. A scored audit gives orchestrating skills (blueprinting, optimizing, releasing) the information they need to decide what to fix. When sources contradict, apply the authority hierarchy in references/source-of-truth-policy.md.

This skill includes security scanning. No need to invoke a separate security skill — see Category 10 under Full Project Audit.

Announce at start: "I'm using the auditing skill to audit [this project / this skill]."

Plugin context: When installed as a plugin, operate on the user's project ($CLAUDE_PROJECT_DIR / <target-dir>), not the plugin's own cache. Read files from and detect scope in the target; write all outputs (reports, JSON baselines) to the workspace's .bundles-forge/audits/. See references/input-normalization.md for edge-case input types, naming conventions, and security rules. <plugin-root> in commands below resolves to $CLAUDE_PLUGIN_ROOT (Claude Code), $CURSOR_PLUGIN_ROOT (Cursor), or . (local development).

Resolve Input & Detect Scope

The target can be a local path, a GitHub URL, or a zip file. Normalize to a local directory, then detect scope. This applies to all three audit modes.

Input Normalization

This is a mandatory step — do not skip it or improvise paths. Resolve the target to a local directory before proceeding to Scope Detection or any audit Step 1.

1. Resolve the workspace. The workspace is $CLAUDE_PROJECT_DIR or $CURSOR_PROJECT_DIR (plugin mode), falling back to the current working directory.
2. Normalize the target by type:
3. Local path — use directly; no transformation needed.
4. GitHub URL — parse <owner> and <repo> from the URL. Shallow-clone to <workspace>/.bundles-forge/repos/<owner>__<repo>/ using --depth 1 --no-checkout, then run git checkout. If the directory already exists, append a __<YYYYMMDD> timestamp to avoid collisions. Do not clone to /tmp/, ~/, or any path outside .bundles-forge/repos/.
5. Zip/tar.gz — extract to <workspace>/.bundles-forge/repos/<archive-name>/.
6. Create the target subdirectory if it does not exist.
7. On failure (network error, 404, auth required, rate limit): tell the user what failed and suggest providing a local path or zip file instead. Do not silently skip or proceed with partial data.

See references/input-normalization.md for the full naming convention (version/timestamp suffixes), GitHub subdirectory URLs, and security rules.

Scope Detection

After normalization, determine the audit scope from the resolved local path:

| Target | How to Detect | Mode | |--------|--------------|------| | Project root | Has skills/ directory | Full audit — all 10 categories | | Project root + workflow request | User explicitly requests workflow audit, or specifies --focus-skills | Workflow audit — 3-layer workflow checks (W1-W11) | | Single skill directory | Contains SKILL.md but no skills/ subdirectory | Skill audit — 4 applicable categories | | Single SKILL.md file | Path ends in SKILL.md | Skill audit — 4 applicable categories |

If the target is a single skill, skip to the Skill Audit section below. If a workflow audit is requested, skip to the Workflow Audit section below.

Full Project Audit

audit-plugin orchestrates audit-security (security), audit-skill (skill quality), audit-workflow (workflow integration), and audit-docs (documentation consistency D1-D9), then adds structure, manifest, version-sync, hook, and testing checks.

Categories at a glance (see references/plugin-checklist.md for 60+ individual checks):

| Category | Weight | |----------|--------| | Structure | High | | Platform Manifests | Medium | | Version Sync | High | | Skill Quality | Medium | | Cross-References | Medium | | Workflow | High | | Hooks | Medium | | Testing | Medium | | Documentation | Low | | Security | High |

Security Scan (Category 10): Scans 7 attack surfaces. See references/security-checklist.md for the full pattern list. security-checklist.md is the canonical source; the table below is a quick-reference summary.

| Target | Risk Level | |--------|-----------| | SKILL.md content | High | | Hook scripts | High | | Hook configs (HTTP hooks) | High | | OpenCode plugins | High | | Agent prompts | Medium | | Bundled scripts | Medium | | MCP configs | Medium |

Step 1 — Run Script Baseline

Prerequisites: Target directory resolved to a local path (via Input Normalization above) with a skills/ directory (Full audit scope confirmed).

Action:

bundles-forge audit-plugin --json --output-dir .bundles-forge/audits <target-dir>

This collects the deterministic baseline — structure, manifests, version sync, skill quality, cross-references, hooks, documentation, and security patterns are verified with reproducible results regardless of agent behavior.

Expected Output: A JSON baseline file at .bundles-forge/audits/audit_plugin-<YYYYMMDD-HHmmss>.json. Verify the file exists and is valid JSON before proceeding to Step 2.

Failure Handling:

• Exit code 0/1/2 with valid JSON file: Proceed to Step 2. Exit 1 = warnings, exit 2 = critical findings — both are valid baselines.
• Exit code non-0/1/2 or stdout empty: Retry with python "<plugin-root>/bin/bundles-forge" audit-plugin --json --output-dir .bundles-forge/audits <target-dir>. If both fail, check Python version (requires 3.9+), report the traceback and stop.

Step 2 — Dispatch Auditor

Prerequisites: JSON baseline file from Step 1 exists at .bundles-forge/audits/.

Action: Pass the JSON baseline file contents to the auditor agent (agents/auditor.md) as input context. The auditor is the single source of truth for scoring formula, report format, and qualitative assessment criteria. It adds ±2 qualitative score adjustments, narrative evaluation, and compiles a layered report using references/plugin-report-template.md.

Full execution details — category weights, scoring formula, report format, Go/No-Go logic — are defined in agents/auditor.md and supported by checklists in references/.

When auditing a project created by bundles-forge:blueprinting, the auditor may reference the design document's "Success Criteria" section (if present in .bundles-forge/blueprints/ or project root) to evaluate whether the implementation aligns with the original project goals.

Expected Output: The auditor produces:

1. A scored audit report saved to .bundles-forge/audits/<project-name>-v<version>-audit.<date>.md — must follow the template structure in references/plugin-report-template.md
2. Per-skill breakdowns with Verdict, Strengths, and Key Issues
3. A Go/No-Go recommendation with qualitative adjustment rationale

Failure Handling:

• Subagent dispatch unavailable: Ask the user — "Subagents are not available. I can run the audit checks inline. Proceed inline?" If confirmed, read agents/auditor.md and follow its execution instructions within this conversation context, using the JSON baseline file as input. The agent file contains the complete audit protocol. The inline execution must still produce all three expected outputs listed above.
• Auditor returns without saving report: The report file in .bundles-forge/audits/ is a mandatory output. If the auditor did not save it, save the report yourself following the naming convention in agents/auditor.md.

Step 3 — Behavioral Verification (W10-W11)

Prerequisites: Step 2 complete. The audit report exists in .bundles-forge/audits/.

Action: Decide whether to run behavioral ver