Stage a SUB/WAVE git worktree so the dev stack can run from it, then start it. A git worktree only checks out tracked files — the dev stack also needs gitignored files (controller/.env, web/.env.local, docker/.env, web/node_modules, and a state/ directory) that this skill copies or scaffolds from the main working tree. Use this skill whenever the user wants to test branch changes in a worktree, run subwave from a worktree, "prep"/"set up" a worktree for dev mode, or asks to copy env files / node_modules / state into a worktree — phrases like "test this worktree in dev mode", "start subwave from the worktree", "prep the worktree", "run my branch locally", "copy the required files into the worktree". Do NOT use it for the main checkout (that's subwave-control) or for production.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Instruções da origem · Visualização somente leitura
name
subwave-worktree-dev
description
Stage a SUB/WAVE git worktree so the dev stack can run from it, then start it. A git worktree only checks out tracked files — the dev stack also needs gitignored files (controller/.env, web/.env.local, docker/.env, web/node_modules, and a state/ directory) that this skill copies or scaffolds from the main working tree. Use this skill whenever the user wants to test branch changes in a worktree, run subwave from a worktree, "prep"/"set up" a worktree for dev mode, or asks to copy env files / node_modules / state into a worktree — phrases like "test this worktree in dev mode", "start subwave from the worktree", "prep the worktree", "run my branch locally", "copy the required files into the worktree". Do NOT use it for the main checkout (that's subwave-control) or for production.
SUB/WAVE worktree dev setup
Get the SUB/WAVE dev stack running from inside a git worktree so branch
changes can be tested without touching the main checkout.
Why a worktree needs prep
A worktree checks out every tracked file, so all source is already there.
But the dev stack also depends on gitignored files that do not travel with
a worktree checkout:
File
Why the stack needs it
.env
Root .env — ADMIN_USER / ADMIN_PASS / SITE_URL. Dev compose references it as ./.env; compose refuses to start without it.
controller/.env
Dev compose declares env_file: ./controller/.env — controller container won't start without it. Navidrome + Ollama config.
web/.env.local
Dev API/stream URL overrides ( etc.). Without it the web UI defaults to same-origin and cannot reach the controller.
NEXT_PUBLIC_API_URL
/api
docker/.env
Compose variable substitution (legacy — harmless to copy).
state/setup-config.json
Navidrome creds the wizard saved on main. Without this the controller reports needsSetup: true and the player redirects to /onboarding on every load.
state/secrets.env
Cloud LLM / TTS API keys (if main has any). Sourced into the controller's process.env on boot.
state/settings.json
Operator's full config — LLM provider/model, personas, shows, TTS. Without it the controller boots with default settings (llm.model = ''), every LLM call returns "fetch failed", and the new skills cannot run.
state/moods.json
Library mood tagging produced by npm run tag (LLM walk over the whole library — expensive to redo per branch).
state/sfx.json + sfx/
Sound-effects catalogue metadata + rendered WAVs the admin UI lists and liquidsoap mixes in.
state/jingles.json + jingles.m3u + jingles/
Pre-rendered station idents. Liquidsoap reads the M3U with reload_mode="watch".
state/recent-plays.json
24h play log — the picker and the library-deep-cut skill key off it for dedup.
state/sessions/
Archived DJ sessions (the live one is regenerated on boot).
state/voice/
Persona TTS reference voices (Chatterbox cloning refs, if any).
web/node_modules
Needed by npm run dev.
state/
Bind-mounted into the containers. A worktree's state/ is empty.
state/ is mirrored from main so the worktree boots into the same configured
station — same LLM provider, same personas, same library moods, same jingles —
ready to test branch changes against real data. Runtime state (queue.json,
session.json, archive/, logs/, listeners.jsonl, now-playing.json) is
not copied, since those would clash with what the worktree's own containers
produce fresh on first boot. The broadcast container generates its own
state/icecast-secrets.env on first boot, so worktrees never need to copy
icecast config either.
Two load-bearing facts
One stack at a time. Both compose files use fixed container names
(sub-wave-broadcast, …) and host ports (Web 7700, Controller 7701,
Icecast 7702). A worktree stack and the main-checkout stack collide — stop
whatever is running before starting another.
Controller changes need --build, web changes do not. The controller
image COPYs its source at build time, so testing worktree controller code
requires docker compose up -d --build. The web dev server (npm run dev)
hot-reloads from the worktree filesystem, so UI changes appear with no build.
Workflow
Step 0 — Identify the worktree
The target worktree is usually the session's current directory. Confirm it is a
linked worktree and not the main checkout:
git rev-parse --absolute-git-dir # a worktree's is <main>/.git/worktrees/<name>
git worktree list # shows the main tree + every linked worktree
If the user named a specific worktree path, use that.
Step 1 — Stop any running stack
Only one stack can run. Stop whatever is up (it may be the main checkout's):
# Kill the web dev server if it holds :7700 — but only if it is `node`,# never macOS ControlCenter/AirPlay.
WEB_PID=$(lsof -nP -iTCP:7700 -sTCP:LISTEN -t 2>/dev/null | head -1)
[ -n "$WEB_PID" ] && ps -p "$WEB_PID" -o comm= | grep -qi node && kill"$WEB_PID"# Bring down whichever dev stack is up. The compose file lives at the# checkout root (not under docker/); container names are global, so any# checkout's docker-compose.dev.yml targets the running containers.
docker compose -f <some-checkout>/docker-compose.dev.yml down
Step 2 — Prep the worktree
Run the bundled script. It copies the env files, mirrors the operator's
declarative state/ from main (settings, moods, sfx, jingles, sessions, voice),
and runs npm install for the web app. <skill base directory> is the
absolute path shown as "Base directory for this skill" when the skill loads.
bash "<skill base directory>/scripts/prep-worktree.sh" <worktree-path>
Flags: --reset-state wipes and re-scaffolds state/ (use when the user wants
a clean slate); --skip-npm skips the dependency install (use when
node_modules is already good). The script is idempotent — re-running it only
fills in what is missing, never overwrites a file the worktree already has.
Step 3 — Start the stack from the worktree
Compose files now live at the worktree root (not under docker/):
cd <worktree-path> && docker compose -f docker-compose.dev.yml up -d --build
--build is required so the worktree's controller source is baked into the
image. The first build is slow (all services); later builds only rebuild
changed layers. Then start the web dev server in the background (it is a
long-running foreground process):
cd <worktree-path>/web && npm run dev
Step 4 — Verify on-air
Give Liquidsoap ~5s to connect to Icecast, then probe the controller:
If /health fails, peek at docker compose logs --tail=30 controller broadcast
and surface the error. A fresh state/ is normal — an empty queue and default
settings on first boot are expected, not faults.
Iterating
Web/UI change — nothing to do; npm run dev hot-reloads it.
Controller source change — rebuild just that service:
cd <worktree-path> && docker compose -f docker-compose.dev.yml up -d --build controller.
liquidsoap/radio.liq change — it is bind-mounted in dev; just
docker compose restart broadcast.
