From fec4c82a5d1dc4cb3b4dadb882125a300b679ad7 Mon Sep 17 00:00:00 2001 From: pleb Date: Wed, 1 Jul 2026 10:42:09 -0700 Subject: [PATCH] docs: update plugin helper agent workflow --- .../skills/beatsaber-plugin-manager/SKILL.md | 13 +------ AGENTS.md | 34 ++++++++++++++++--- 2 files changed, 30 insertions(+), 17 deletions(-) diff --git a/.agents/skills/beatsaber-plugin-manager/SKILL.md b/.agents/skills/beatsaber-plugin-manager/SKILL.md index e0e9d77..51ed61c 100644 --- a/.agents/skills/beatsaber-plugin-manager/SKILL.md +++ b/.agents/skills/beatsaber-plugin-manager/SKILL.md @@ -5,10 +5,7 @@ description: Install or update a Beat Saber plugin in the plugin-helper repo by # Install Beat Saber Plugin -Use the repository's own `plugin-helper` commands to manage plugins for BSManager instances whenever the helper supports the operation. Do not manually copy release files into the game instance except: - -- to bootstrap BSIPA/core packages before the helper has a first-class bootstrap command -- to undo your own mistaken install before rerunning the helper +Use the repository's own `plugin-helper` commands to manage plugins for BSManager instances whenever the helper supports the operation. ## Hard Guardrail @@ -37,14 +34,6 @@ such as .NET assemblies. Record the artifact source plus BeatMods `modVersion`, version id, `zipHash`, dependencies, and supported game version in the repo notes/lock data. -Accepted URL shapes include: - -```text -https://github.com///releases -https://github.com///releases/tag/ -https://github.com///releases/download// -``` - ## Workflow 1. Confirm the workspace is the `plugin-helper` repo. diff --git a/AGENTS.md b/AGENTS.md index 148499d..66fd2dd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,13 +6,18 @@ Guidance for coding agents working in this repo. - This repo manages Beat Saber plugins for BSManager instances. - Default instance roots are: - - `/home/pleb/Windows/Users/pleb/BSManager/BSInstances` - - `/home/pleb/.local/share/BSManager/BSInstances` + - `~/Windows/Users/pleb/BSManager/BSInstances` + - `~/.local/share/BSManager/BSInstances` - A local BSManager source checkout may be available at - `/home/pleb/src/Zagrios/bs-manager`. Use it as a read-only reference when + `~/src/Zagrios/bs-manager`. Use it as a read-only reference when investigating launch behavior, inherited Steam arguments, instance layout, or Proton environment details unless the user explicitly asks for BSManager code changes. +- Keep plugin source checkouts under `~/src//` when a + locked or registry plugin has a GitHub source repo. Prefer checking out the + upstream author/repo first, with `origin` pointing at upstream. If the user has + an existing personal fork checkout, preserve it as a remote named `github` + and set/add `origin` to the upstream repo instead of replacing local work. - Prefer repo-local state for planned installs unless the task explicitly targets the user's live default state. Use `--state-dir .state` for the local Linux install and `--state-dir .state-windows` for the mounted Windows install @@ -24,13 +29,17 @@ Guidance for coding agents working in this repo. - For human-style inspection, prefer the menu with repo-local state: `PYTHONPATH=src python -m plugin_helper --state-dir .state menu`. - When targeting the local Linux BSManager install, pass - `--instances-root /home/pleb/.local/share/BSManager/BSInstances` and normally + `--instances-root ~/.local/share/BSManager/BSInstances` and normally `--state-dir .state`. - When targeting the mounted Windows BSManager install, pass - `--instances-root /home/pleb/Windows/Users/pleb/BSManager/BSInstances` and + `--instances-root ~/Windows/Users/pleb/BSManager/BSInstances` and normally `--state-dir .state-windows`. - Use the helper commands instead of manually copying plugin files into an instance. +- When adding, updating, building, or investigating a GitHub-hosted plugin, + check for `~/src//` and clone the upstream repo there if + it is missing. Do not substitute forks or similar repos without explicit user + direction. - Treat BSIPA as a bootstrap phase: - `bootstrap` installs the locked BSIPA archive and records generated files. - ordinary plugin plans should depend on healthy bootstrap state. @@ -46,6 +55,21 @@ Guidance for coding agents working in this repo. - For live game validation, follow `docs/SMOKETEST.md` and tear down Beat Saber processes afterward. +## Pull Requests + +- When the user asks for a PR against an upstream plugin, compose and submit a + polite pull request using the user's existing `gh` session. +- Keep upstream PRs small, focused, and easy for the maintainer to verify. Favor + narrow compatibility fixes, clear commit messages, and minimal formatting or + project-file churn. +- Work from the upstream checkout under `~/src//` when available. + If the upstream remote is not writable, create or reuse the user's fork with + `gh repo fork`, push a topic branch there, and open the PR against upstream. +- Include concise verification notes in the PR body, especially the exact build + or smoke-test command and any generated artifact name. Mention local-only + build configuration separately if it was needed, and do not commit machine + paths or helper state unless the user explicitly asks for it. + ## Launch Notes - BSManager may inherit Beat Saber launch arguments configured in Steam.