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:**
   - **Local path** — use directly; no transformation needed.
   - **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/`.**
   - **Zip/tar.gz** — extract to `<workspace>/.bundles-forge/repos/<archive-name>/`.
3. **Create the target subdirectory** if it does not exist.
4. **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:**

```bash
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 ba