# 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.