Refactor agent skills

2026-07-10 08:42:55 -07:00
parent f4fedaeb34
commit 26def9609d
8 changed files with 291 additions and 102 deletions
@@ -0,0 +1,53 @@
+# plugin-helper State And Profiles
+
+Use these rules when selecting BSManager instances, state directories, and source
+checkout locations.
+
+## Instance Selection
+
+- Prefer the Beat Saber instance the user names.
+- If the user omits an instance, use the latest available BSInstance unless the
+  current task context or user notes clearly point at another instance.
+- Discover available instances with the helper rather than assuming a hard-coded
+  game version:
+
+  ```bash
+  PYTHONPATH=src .venv/bin/python -m plugin_helper instances
+  ```
+
+## State Directories
+
+- Prefer repo-local `.state` for planned installs, update audits, downloaded
+  artifacts, and generated plans unless the user explicitly targets live default
+  state or another configured profile.
+- For mounted Windows installs, prefer the shared Windows-partition state
+  directory configured in `plugin-helper.local.toml` when both roots contain the
+  same instance name.
+- Keep target-specific managed state with the selected target root. Do not mix a
+  Linux install's `installed.json` with a Windows install's state unless the user
+  intentionally selected that shared state.
+
+## Profiles
+
+- Read `plugin-helper.local.toml` before choosing a configured profile:
+
+  ```bash
+  sed -n '1,220p' plugin-helper.local.toml
+  PYTHONPATH=src .venv/bin/python -m plugin_helper --profile <profile-id> instances
+  ```
+
+- Treat the selected profile's `instances_root` and `state_dir` as a pair.
+- When using `--profile`, prefer it over manually passing default BSManager paths.
+
+## Source Checkouts
+
+- Keep plugin source checkouts under `~/src/<owner>/<repo>` when a locked or
+  registry plugin has a GitHub source repo.
+- Prefer checking out upstream `owner/repo` first, with `origin` pointing at
+  upstream.
+- If a personal fork checkout already exists, preserve it as a remote named
+  `github` and set or add `origin` to the upstream repo instead of replacing
+  local work.
+- For temporary PR/build work tied to a selected profile, use that profile's
+  `<state_dir>/build/<name>` when the skill explicitly calls for disposable
+  build checkouts.