Review Lab Plugin

---
name: review-lab-plugin
description: Review an MCP plugin against the homelab canonical plugin spec and identify any and all misalignments. Use when the user wants a plugin audited for spec drift, wants to compare a plugin to canonical manifests and runtime patterns, wants to know whether deviations are documented and justified, or wants a detailed plugin review report.
---

# Review Lab Plugin

Review a plugin for alignment with the homelab canonical plugin spec.

## Review Goal

Find mismatches between the target plugin and the current canonical standard.

Treat the review as a spec audit, not a style pass.

Focus on:

- correctness
- structural drift
- runtime contract drift
- missing required files
- stale manifests
- undocumented or unjustified deviations

See `references/canonical-spec.md` for the authoritative correct values for every check category below.

## Read the Canonical Surfaces

Inspect the target plugin's tree first to know what exists and what is absent. Then read each canonical file when present:

- `README.md`
- project manifest (`pyproject.toml`, `Cargo.toml`, or `package.json`)
- `.claude-plugin/plugin.json`
- `.codex-plugin/plugin.json`
- `.mcp.json`
- `.app.json`
- `CLAUDE.md`
- `AGENTS.md`
- `CHANGELOG.md`
- `Dockerfile`
- `docker-compose.yaml`
- `Justfile`
- `.env.example`
- hook config
- CI workflow (`.github/workflows/ci.yaml`)
- live test script

Also inspect the repo tree so you can reason about missing or misplaced surfaces.

## Compare Against the Spec

Check for every category below. For the exact correct values in each category, consult `references/canonical-spec.md`.

- missing required files
- wrong file locations
- version drift across manifests
- incorrect userConfig shape
- transport mismatch
- missing auth on HTTP transport
- missing `/health` endpoint
- missing `*_help` tool or action/subaction pattern
- missing live test coverage
- stale README or CLAUDE guidance
- ignore file and Docker hygiene drift

## Classify Every Misalignment

For each finding, state:

- what is misaligned
- where it appears (file path and line if known)
- what the canonical expectation is
- whether the deviation is documented
- whether the deviation appears technically justified

Do not treat every difference as a bug. A deviation is acceptable if it is deliberate, documented, and technically justified.

## Open Questions

Some findings cannot be resolved by reading files alone. Flag these explicitly as **open questions** — issues that require user input or live service access to resolve before remediation can proceed.

Examples of open questions:

- "Is the second Unraid server still in use, or can its env vars be removed?"
- "What auth scheme does this service use — bearer token or API key header?"
- "The CHANGELOG shows v1.0.0 but plugin.json shows v1.1.0 — which is correct?"

Group open questions at the end of the report so the user can answer them before align-lab-plugin begins work.

## Produce a Written Report

Write the final review to:

```
docs/reports/plugin-reviews/<YYYYMMDD-HHMMSS>.md
```

Use the fill-in-the-blanks template in `references/review-report-template.md` for the report structure.

The report must include:

- target plugin path
- review date (YYYYMMDD-HHMMSS)
- files inspected
- findings ordered by severity (CRITICAL → HIGH → MEDIUM → LOW)
- documented deviations
- justified deviations
- open questions
- concrete remediation checklist ordered by priority

## Output Style

Findings first. Each finding uses this format:

```
**[HIGH] Missing /health endpoint**
File: src/server.py
Expected: GET /health returns HTTP 200 with {"status": "ok"}
Found: No /health route registered
Fix: Add health route before starting server
```

Severity levels:

- **CRITICAL** — plugin will not load or will break other plugins
- **HIGH** — runtime contract violated, integration will fail silently
- **MEDIUM** — spec drift that degrades usability or discoverability
- **LOW** — hygiene issue, documentation gap, or cosmetic drift

Keep the report detailed and complete enough that align-lab-plugin can implement all fixes without repeating the audit.

## Related Skills

- **align-lab-plugin** — consumes the review report and implements the remediation checklist
- **lab-research-specialist** — use to verify current canonical values when the spec may have changed
- **scaffold-lab-plugin** — reference for the canonical 15-surface list and correct plugin structure