plugin-review

---
name: "plugin-review"
description: "Review plugin quality with tiered checks and dependency scoping. Use for PR and pre-release audits."
license: "MIT"
---

# Plugin Review

## Overview

Tiered quality review of plugins with dependency-aware scoping.

## When NOT To Use

- Reviewing one skill rather than a plugin (use `abstract:skills-eval`)
- Reviewing hooks (use `abstract:hooks-eval`)
- Tracing `Skill()` references across plugins (use
  `abstract:skill-graph-audit`)

## Table of Contents

- [Tiers](#tiers)
- [Orchestration](#orchestration)
- [Scope Detection](#scope-detection)
- [Module Loading](#module-loading)
- [Verdict](#verdict)
- [Output Format](#output-format)
- [Quality Gate Mode](#quality-gate-mode)
- [Configuration](#configuration)

## Tiers

| Tier | Trigger | Scope | Depth | Duration |
|------|---------|-------|-------|----------|
| branch | Default | Affected and related | Quick gates | ~2 min |
| pr | Before merge | Affected and related | Standard | ~5 min |
| release | Before version bump | All 17 plugins | Full | ~15 min |

## Orchestration

1. **Detect scope**: parse `--tier` flag, find affected
   plugins from git diff, resolve related plugins from
   `docs/plugin-dependencies.json`
2. **Plan**: build check matrix (tier x plugin x role)
3. **Execute**: run checks per tier definition
4. **Report**: per-plugin table, aggregate verdict

## Scope Detection

Affected plugins: `git diff main --name-only` filtered to
`plugins/*/`.

Related plugins: load `docs/plugin-dependencies.json`,
look up each affected plugin's reverse index to find
dependents. Mark as "related" (lighter checks).

If `--tier release` or no git diff available, scope to
all plugins.

## Module Loading

- **Always**: this SKILL.md (orchestration logic)
- **branch tier**: load `modules/tier-branch.md`
- **pr tier**: load `modules/tier-branch.md` then
  `modules/tier-pr.md`
- **release tier**: load all tier modules plus
  `modules/tier-release.md`
- **When resolving deps**: load
  `modules/dependency-detection.md`

## Verdict

| Result | Meaning |
|--------|---------|
| PASS | All checks green |
| PASS-WITH-WARNINGS | Non-blocking issues |
| FAIL | Blocking issues found |

## Output Format

```
Plugin Review (<tier> tier)
Affected: <list>
Related:  <list> (<reason>)

Plugin          test  lint  type  reg   verdict
<name>          PASS  PASS  PASS  PASS  PASS
...

Verdict: <PASS|PASS-WITH-WARNINGS|FAIL> (N/N plugins healthy)
```

PR and release tiers add scorecard sections.

## Quality Gate Mode

The `--quality-gate` flag enables CI/CD integration with
exit codes that distinguish warnings from failures:

- `0`: all quality gates passed
- `1`: warnings present but gates passed (non-blocking)
- `2`: quality gate failures (blocking)
- `3`: critical issues found (blocking)

Use `--fail-on warning` to treat warnings as blocking.

## Configuration

Place a `.plugin-review.yaml` file in the plugin root
to customize thresholds and focus areas:

```yaml
plugin_review:
  quality_gates:
    structure_min: 80
    skills_min: 75
    hooks_min: 70
    tokens_max_total: 50000
    bloat_max_percentage: 15
  focus_areas:
    - skills
    - hooks
    - tokens
  exclude_patterns:
    - "*/legacy/*"
    - "*/deprecated/*"
  severity_overrides:
    missing_description: warning
    large_file: info
```

See the `/plugin-review` command reference for full
usage examples.

## Exit Criteria

- [ ] The output includes a per-plugin table with columns: test, lint, type, reg, verdict, and
  an aggregate PASS / PASS-WITH-WARNINGS / FAIL verdict.
- [ ] Scope detection identifies affected plugins via `git diff main --name-only` filtered to
  `plugins/*/`; if git diff is unavailable, the skill falls back to all-plugin scope and
  states this explicitly.
- [ ] Any plugin scoring below the `structure_min` (default 80) or `skills_min` (default 75)
  threshold is listed as a FAIL, not a warning.
- [ ] `--quality-gate` mode returns exit code 2 for blocking failures and exit code 1 for
  non-blocking warnings, distinguishable by the calling CI step.