validate-plugins

name	validate-plugins
description	Validate plugin structure and health. --scope=plugin (deep single-plugin check), --scope=all (fast repo-wide sweep), --scope=health (full health dashboard).
disable-model-invocation	false

/validate-plugins

Usage: /validate-plugins [<plugin-name>] [--scope=plugin|all|health]

Route by --scope:

• --scope=plugin — deep validation of one plugin before publishing (default when a name is given)
• --scope=all — fast structural sweep across every plugin in the repo (default when no name is given)
• --scope=health — full health dashboard for one plugin (structure + components + catalog + themes)

---

--scope=plugin — Deep single-plugin validation

Usage: /validate-plugins acss-kit or /validate-plugins acss-kit --scope=plugin

Run each check in order. Report all failures at the end, not one at a time.

1. Manifest

• plugins/<plugin>/.claude-plugin/plugin.json exists and is valid JSON
• Required fields present: name, description, version, author, license
• version is a valid semver string
• claudeCodeMinVersion is present (warn if missing, don't fail)

2. Marketplace entry

• .claude-plugin/marketplace.json has an entry matching the plugin name
• The entry does not have a "version" field (this causes silent conflicts)
• description is non-empty

3. Required files

• README.md exists
• commands/ directory exists and contains at least one .md file
• skills/ directory exists and contains at least one SKILL.md

4. Command files

For each commands/*.md:

• Has valid YAML front-matter with description and allowed-tools fields
• Body references SKILL.md (not re-implements logic inline)
• Does not contain repo-relative paths to fpkit source (e.g., ../../acss/)

5. SKILL.md references

• No repo-relative fpkit source links — all fpkit references must be full GitHub URLs (https://github.com/shawn-sandy/acss/...)
• Each command mentioned in the SKILL.md has a corresponding commands/*.md file

6. Python scripts (if present)

• Run python3 -m py_compile <script> on each .py file in plugins/<plugin>/scripts/
• Report any syntax errors

7. Assets

• If assets/ exists, verify no .tmpl files contain un-substituted {{PLACEHOLDER}} tokens that don't follow the {{ALL_CAPS}} convention

Output

PASS  Manifest fields
PASS  Marketplace entry
FAIL  Command files — app-init.md missing allowed-tools front-matter
PASS  SKILL.md references
...

Exit with a count of failures. If zero failures: "Plugin is ready to publish."

---

--scope=all — Fast repo-wide structural sweep

Usage: /validate-plugins --scope=all

Scans every directory under plugins/ and reports pass/fail for each. No plugin name needed.

Run these checks for each plugins/*/ directory:

1. Manifest exists and has required fields

jq -e '(.name | type == "string" and length > 0) and (.version | type == "string" and length > 0) and (.description | type == "string" and length > 0)' plugins/<plugin>/.claude-plugin/plugin.json

• PASS if file exists and all three fields are non-null/non-empty strings.
• FAIL if file is missing or any field is absent or empty.

2. Marketplace entry has no version key

Read .claude-plugin/marketplace.json. Run two checks in sequence.

First verify the entry exists:

jq -e --arg p "<plugin>" '.plugins | map(.name) | index($p) != null' .claude-plugin/marketplace.json

• FAIL if absent: "marketplace.json has no entry for — add one."

Then verify no version key:

jq -e '.plugins[] | select(.name == "<plugin>") | has("version") | not' .claude-plugin/marketplace.json

• FAIL: "marketplace.json entry for carries a version key — remove it."

3. Required files present

• plugins/<plugin>/README.md
• plugins/<plugin>/skills/ containing at least one SKILL.md
• plugins/<plugin>/commands/ containing at least one .md file

Output

plugins/acss-kit
  PASS  Manifest fields (name, version, description)
  PASS  Marketplace entry has no version key
  PASS  README.md present
  PASS  skills/ contains SKILL.md files
  PASS  commands/ has .md files

Summary: 2 plugins checked, 0 failures total.

After the sweep, offer: "Run /validate-plugins <name> for a full pre-publish check on any plugin above."

---

--scope=health — Full health dashboard

Usage: /validate-plugins acss-kit --scope=health

Produces a single dashboard summarizing structural and content health. Read-only — does NOT modify any files.

Step 1 — Resolve target

If no argument is provided, default to acss-kit. Confirm plugins/<plugin-name>/.claude-plugin/plugin.json exists. If not, list available plugins and halt.

Step 2 — Structural validation

Run the --scope=plugin checks above on <plugin-name>. Capture output as the "Structure" section.

Step 3 — Component reference scan

Glob plugins/<plugin-name>/skills/component-*/reference.md. If none are found, skip Steps 3 and 4 and record "N/A" for Component checks in the dashboard.

For each matched reference.md:

1. Check whether the file contains all nine canonical sections (verification banner, Overview, Generation Contract, Props Interface, TSX Template, CSS Variables, SCSS Template, Accessibility, Usage Examples).
2. Verify that a sibling SKILL.md exists in the same directory.
3. Mark OK if all present, FIX if any are missing or out of order.

Roll up to: N components OK / M components FIX.

Step 4 — Skill directory completeness

Glob plugins/<plugin-name>/skills/component-*/. For each directory, confirm both SKILL.md and reference.md exist. Report any directory with a missing file.

Step 5 — Theme reference parity

Invoke the theme-reference-reviewer agent. Capture its check verdicts. Each FAIL becomes a row in the "Themes" section.

Step 6 — Bundled theme validation

validate_theme.py only validates files matching ^(light|dark|brand-[\w-]+)\.css$.

1. Build the candidate file list from assets/ and assets/brand-presets/ (if present).
2. Run python3 plugins/<plugin-name>/scripts/validate_theme.py <file> for each candidate (timeout 30s).
3. Classify: exit 0 + validate_theme: OK → PASS; exit 1 → FAIL; no palette files found in stdout → INFO (not PASS).

Step 7 — Render the dashboard

== plugin-health: <plugin-name> @ v<version> ==

Structure              [OK | FIX] <one-line summary>
Components             [OK | FIX] N OK / M FIX
Catalog parity         [OK | FIX] <orphans/stale counts>
Theme references       [OK | FIX] <fail count>
Bundled themes         [OK | FIX] <preset pass/fail counts>

-- Detail --

Components needing attention:
  - <name>.md — missing: Accessibility

Catalog issues:
  - Orphan: <name>.md (file present, no catalog row)

Bundled theme failures:
  - <file> — <failing pair name>

-- Suggested fixes --

  Run /validate-plugins <name>           (for each Structure FIX)
  Run /acss-kit-component-update <name>  (for each Component FIX)
  Run /acss-kit-style-update <path>      (for each Theme FIX)
  Run /acss-kit-component-author <name>  (for each missing component skill)

If everything is OK: "All systems green. Plugin is release-ready."

Step 8 — Pre-release reminder

Before opening a PR:
  1. Run /release-plugin <plugin-name> <new-version>
  2. Confirm plugins/<plugin-name>/CHANGELOG.md mentions user-visible changes