---
name: opusmith-setup
description: Check the local uv/audio runtime and explain how to start an Opusmith music project after plugin installation.
---

# Opusmith setup

Locate the plugin root two directories above this file. Use a local writable music workspace.
Check `uv --version`, then `uv sync --project "<plugin-root>" --locked`.
If plugin files are read-only, put `UV_PROJECT_ENVIRONMENT` in a writable local cache.
Run `uv run --project "<plugin-root>" python "<plugin-root>/scripts/doctor.py"`.
The doctor produces and validates real synthesized audio in a temporary directory; it does
not call an external model, upload files or install a sample library.

Read `../opusmith/SKILL.md` for creation/revision guidance. Offer concrete first-use examples
such as a 90-second Progressive House piece or a Trance × Dubstep theme with contrasting drums.
Let the user choose an ordinary local output folder; do not save songs into plugin caches.
Native specialists are optional: Claude loads plugin agents; Codex uses the provided
`scripts/install_codex_roles.py` for project-scoped TOML roles. Setup does not modify global
agent settings or invoke every specialist automatically.

For singing, load `../opusmith/references/vocals.md` only when needed. The optional
OpenUtau bridge requires .NET SDK 10 and a separate official voicebank download.
Use `scripts/setup_vocals.py`; never bundle or upload models by default. Traditional
波音リツ is the reviewed commercial default; 綺萱 DiffSinger is explicitly evaluation-only
pending the separate vocoder commercial review. Instrumental setup needs neither.