plugin-helper/.agents/skills/beatsaber-plugin-update-auditor/SKILL.md

name, description

name

description

beatsaber-plugin-update-auditor

Audit Beat Saber plugin-helper locks for available plugin updates and follow-up work. Use when the user asks to check all Beat Saber plugins for updates, compare locked mods against GitHub or BeatMods, review plugin/version compatibility tracking notes, identify PR/local/manual builds that need follow-up, or skip paid/private Patreon and Discord plugin sources during update checks. Read docs/notes/update-checks/<version>/ before the audit and add a new markdown file there when the audit finishes.

Beat Saber Plugin Update Auditor

Use this skill from the plugin-helper repo to produce an update audit, not to blindly update plugins. Keep public, private, and experimental sources distinct.

Before auditing, read the shared policy references:

• repo-workflow.md for repo root, .venv, PYTHONPATH=src, dirty worktree handling, and validation commands.
• state-and-profiles.md for .state, profiles, install identity, instance selection, and checkout locations.
• artifact-policy.md for GitHub/BeatMods/private-source/checksum policy.
• live-validation.md only when reviewing smoke-test notes or launch failures.

Workflow

1. Confirm repo context:

   test -f pyproject.toml && test -d src/plugin_helper && test -d locks && test -d registry/plugins
   git status --short
   

2. Choose the instance from the user request. If omitted, use the latest available BSInstance unless the current task context clearly points at another instance:

   PYTHONPATH=src .venv/bin/python -m plugin_helper instances
   

3. Read the update journal for that Beat Saber version before drawing conclusions. Journals live under docs/notes/update-checks/<version>/, one directory per game version, with as many markdown files as needed (usually one dated file per check). List the directory and read the recent files. Treat them as prior findings, not as a substitute for a fresh audit. If the directory does not exist yet, create it when recording this check.

4. Run the update audit with repo-local state unless the user explicitly targets another configured profile:

   PYTHONPATH=src .venv/bin/python -m plugin_helper --state-dir .state updates --instance <instance>
   PYTHONPATH=src .venv/bin/python -m plugin_helper --state-dir .state updates --instance <instance> --json
   

   The command checks ordinary GitHub locks, beatmods-* locks via BeatMods verified metadata, skips patreon/ and discord/ sources, and marks local, PR, manual, failed-trial, or pending-smoke entries as review items.

5. Read the active compatibility tracker before proposing updates for review items. For the current migration notes, inspect:

   sed -n '1,380p' docs/notes/install-and-verify-plugins-1.44.1.md
   sed -n '1,220p' docs/notes/naluluna-mod-assistant.md
   

   Follow up on rows marked failed, omitted, currently failed, smoke blocked, manual resmoke pending, local build, PR build, or local/private. The lock reason and docs/notes/update-checks/<version>/ are the current record. When an older note says a plugin was removed and the lock still has a local or pull-request build, the lock wins. Correct that note in the same change. Do not reinstall failed or omitted plugins unless the lock or journal identifies a newer compatible source.

   To see what BeatMods has for one mod, query status=all for that game version and filter by mod name in the client. BeatMods ignores search and name. An empty verified list is not the whole catalog.

6. For each public update candidate, inspect source notes before changing the lock. Follow the shared artifact policy for GitHub-first sourcing and BeatMods fallback cases.

7. Do not attempt automated public update checks for:

   • patreon/NalulunaModAssistant or Naluluna bundles
   • discord/BeatSaberPlus or BeatSaberPlus/ChatPlexSDK bundles
   • other paid or closed-source plugin zips

   Report them as skipped/manual follow-up only.

8. If the user asks to apply an update, switch to the beatsaber-plugin-manager workflow for download, lock update, planning, apply, and smoketest.

Output

Summarize in four groups:

• Public updates found: plugin, current version, candidate version, source.
• Current public locks: count only unless the user asks for every row.
• Review follow-ups: local builds, PR builds, failed trials, blocked smokes, or notes saying compatibility work is pending.
• Skipped private sources: Patreon/Discord paid or closed-source packages.

Mention BeatMods/GitHub API errors separately from "no update found"; those are unknowns, not proof that the plugin is current.

Journal

After the audit, add a new markdown file. Do not rewrite earlier journal files.

docs/notes/update-checks/<beat-saber-version>/<YYYY-MM-DD>.md

Use <YYYY-MM-DD>-<short-slug>.md when that date already has an entry. Keep the note short: date, instance, the four summary groups, and any comparison that changed a recommendation. A version directory may hold many files.