Refactor agent skills
This commit is contained in:
pleb
@@ -0,0 +1,85 @@
|
||||
# Beat Saber Artifact Policy
|
||||
|
||||
Use this policy for plugin install/update/bootstrap tasks and for audit reports
|
||||
that discuss candidate artifacts.
|
||||
|
||||
## Source Priority
|
||||
|
||||
- Prefer upstream GitHub release artifacts for ordinary repository-backed
|
||||
plugins.
|
||||
- Use BeatMods primarily as compatibility, dependency, and verification
|
||||
metadata.
|
||||
- Use BeatMods CDN artifacts only for inaccessible upstream assets,
|
||||
BeatMods-only packages, framework/library dependencies, or cases where no
|
||||
matching upstream release asset exists.
|
||||
- Skip paid/private Patreon, Discord, and closed-source sources during automated
|
||||
public update checks. Report them as manual follow-up unless the user provides
|
||||
the artifact and asks to manage it.
|
||||
|
||||
## Repository Guardrail
|
||||
|
||||
- For ordinary GitHub-hosted plugins, require an explicit GitHub repository,
|
||||
release URL, or user-provided local planning note before selecting a release.
|
||||
- If the user provided a repo URL but no release URL, query that exact repo's
|
||||
releases and choose the most appropriate non-draft, non-prerelease release for
|
||||
the target instance.
|
||||
- If the user provided no repo or release URL for a plugin install/update, stop
|
||||
and ask for one.
|
||||
- Do not discover a different repository from web search, substitute a fork, or
|
||||
infer the "correct" project from a similar package name.
|
||||
- If the URL is a releases page, use that repo's release API and choose the
|
||||
latest non-draft, non-prerelease release unless the user asks for a tag.
|
||||
- If the URL is a tag URL, use that exact tag.
|
||||
|
||||
## BeatMods Exceptions
|
||||
|
||||
When the user explicitly asks to bootstrap a Beat Saber instance or install
|
||||
verified mods without GitHub URLs, use BeatMods verified metadata to identify
|
||||
compatible versions and dependency closure. Still prefer upstream GitHub assets
|
||||
when BeatMods exposes a `gitUrl` and a matching release asset can be found.
|
||||
|
||||
Record the artifact source plus BeatMods `modVersion`, version id, `zipHash`,
|
||||
dependencies, and supported game version in repo notes or lock data when
|
||||
BeatMods metadata drives the selection.
|
||||
|
||||
BeatMods dependency entries are mod-version ids. Resolve the selected mod's
|
||||
dependency closure before downloading.
|
||||
|
||||
## Checksums And Inspection
|
||||
|
||||
- Download artifacts into the selected helper state directory, normally:
|
||||
|
||||
```bash
|
||||
<state_dir>/instances/<instance>/downloads/<plugin-id>/
|
||||
```
|
||||
|
||||
- Record SHA-256 checksums for downloaded or built artifacts.
|
||||
- Match the checksum against GitHub's `digest` when available.
|
||||
- For BeatMods CDN artifacts, preserve BeatMods `zipHash` metadata and verify
|
||||
the downloaded archive against the expected hash when the helper supports it.
|
||||
- Inspect archive contents before selecting install strategy:
|
||||
|
||||
```bash
|
||||
unzip -l <artifact>
|
||||
```
|
||||
|
||||
## Install Strategy Guide
|
||||
|
||||
- `dll-to-plugins`: asset is a single `.dll` that belongs in `Plugins/`.
|
||||
- `bsipa-zip`: zip top-level paths are only `IPA/`, `Libs/`, or `Plugins/`.
|
||||
- `root-zip`: zip contains valid game-root paths outside the BSIPA top-level
|
||||
set. Use this for BSIPA/bootstrap archives because `IPA.exe`,
|
||||
`IPA.runtimeconfig*.json`, and root `winhttp.dll` are game-root files.
|
||||
- `zip-to-pending`: only when the release is intended for `IPA/Pending/`.
|
||||
- `manual`: do not use for installable releases.
|
||||
|
||||
## BSIPA Bootstrap
|
||||
|
||||
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.
|
||||
|
||||
For BSIPA bootstrap archives, expect root-relative `IPA/` and `IPA.exe` files
|
||||
whether sourced from GitHub or BeatMods. Extract into the instance root and run
|
||||
`IPA.exe -n` under the same Proton environment used by the smoke test. This
|
||||
creates or copies root `winhttp.dll` and root `Libs/` substrate files.
|
||||
@@ -0,0 +1,43 @@
|
||||
# Beat Saber Live Validation
|
||||
|
||||
Use this policy when a task changes or verifies a live BSManager instance.
|
||||
|
||||
## Smoke Test
|
||||
|
||||
- Follow `docs/SMOKETEST.md` for live game validation.
|
||||
- Before starting Beat Saber, announce how long the smoke window will run, using
|
||||
the current duration in `docs/SMOKETEST.md` unless the user requested a
|
||||
different duration.
|
||||
- Do not rely on `timeout` to kill the full game process tree.
|
||||
- Prefer the documented foreground Proton launch with a background watchdog that
|
||||
sleeps for the smoke window, then terminates Beat Saber by process name.
|
||||
- After the run, confirm no Beat Saber process remains. If cleanup fails, say so
|
||||
and ask the user to close it manually.
|
||||
|
||||
## Required After Live Apply
|
||||
|
||||
After any successful helper `apply` that changes a live BSManager instance, run
|
||||
the documented live smoke test before the final response unless the user
|
||||
explicitly says not to. Helper `check`, unit tests, compile checks, and file-hash
|
||||
verification are useful but do not replace live validation.
|
||||
|
||||
## Logs
|
||||
|
||||
Inspect `Logs/_latest.log`, Unity `Player.log` when relevant, and the live
|
||||
process command line before calling a black screen or launch failure a plugin
|
||||
failure. Duplicate launch args such as repeated `--no-yeet fpfc` can trigger
|
||||
fatal command-line parsing after BSIPA/plugin loading succeeds.
|
||||
|
||||
Expected successful BSIPA/SongCore lines include:
|
||||
|
||||
```text
|
||||
Game version <version>
|
||||
Loading plugins from Plugins and found <n>
|
||||
Beat Saber IPA (BSIPA): <version>
|
||||
SongCore (SongCore): <version>
|
||||
```
|
||||
|
||||
Warnings about older mod target game-version metadata can be acceptable when
|
||||
BeatMods verified that exact package for the target Beat Saber version. Record
|
||||
them in the tracker or roadmap rather than treating them as automatic install
|
||||
failure.
|
||||
@@ -0,0 +1,52 @@
|
||||
# plugin-helper Repo Workflow
|
||||
|
||||
Use these rules for all Beat Saber `plugin-helper` skills.
|
||||
|
||||
## Repo Context
|
||||
|
||||
- Work from the `plugin-helper` repo root.
|
||||
- Confirm context before acting:
|
||||
|
||||
```bash
|
||||
test -f pyproject.toml && test -d src/plugin_helper && test -d registry && test -d locks
|
||||
git status --short
|
||||
```
|
||||
|
||||
- The worktree may already be dirty. Treat existing changes as user work:
|
||||
preserve them, do not revert them, and avoid unrelated formatting or metadata
|
||||
churn.
|
||||
- Use `rg`/`rg --files` for search.
|
||||
|
||||
## Python Commands
|
||||
|
||||
- Run helper commands with `PYTHONPATH=src`.
|
||||
- Prefer `.venv/bin/python` when `.venv` exists; otherwise use `python`.
|
||||
- For human-style inspection, prefer repo-local state:
|
||||
|
||||
```bash
|
||||
PYTHONPATH=src .venv/bin/python -m plugin_helper --state-dir .state menu
|
||||
```
|
||||
|
||||
## Validation
|
||||
|
||||
- After code changes in this repo, run:
|
||||
|
||||
```bash
|
||||
PYTHONPATH=src .venv/bin/python -m compileall -q src tests
|
||||
PYTHONPATH=src .venv/bin/python -m unittest discover -s tests
|
||||
```
|
||||
|
||||
- For skill-only edits, also run `quick_validate.py` for each edited skill:
|
||||
|
||||
```bash
|
||||
python /home/pleb/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/<skill-name>
|
||||
```
|
||||
|
||||
- Plain `python -m unittest` can fail in this source-layout repo without
|
||||
`PYTHONPATH=src`.
|
||||
|
||||
## Final Reporting
|
||||
|
||||
Report the commands actually run and their results. When a task changes repo
|
||||
files, include a concise commit message suggestion unless the user already asked
|
||||
for a commit.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user