From worktree-wizard
This skill should be used when the user asks to "set up worktree-wizard", "integrate worktree-wizard", "add worktree support", "create docker-compose for worktrees", "add wt labels", "configure hot-reload for Docker", "set up volume mounts", "isolate ports per worktree", "onboard project to worktree-wizard", or needs guidance on wt.base-port labels, WT_* env var patterns, slot-based port isolation, dev-mode Dockerfiles, or hot-reload configurations per framework.
How this skill is triggered — by the user, by Claude, or both
Slash command
/worktree-wizard:worktree-wizard-integrationThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Provide the domain knowledge needed to correctly integrate worktree-wizard into any project. This includes docker-compose conventions, env var patterns, volume mount strategies, hot-reload configurations, and justfile setup.
Provide the domain knowledge needed to correctly integrate worktree-wizard into any project. This includes docker-compose conventions, env var patterns, volume mount strategies, hot-reload configurations, and justfile setup.
Add a wt.base-port label to every service needing port isolation. worktree-wizard adds the slot number (1-9) to compute the host port per worktree.
services:
api:
labels:
wt.base-port: "8000"
ports:
- "${WT_API_PORT:-8000}:8000" # host:container
Rules:
WT_{SERVICE_NAME_UPPER}_PORT (hyphens/dots become underscores):-default fallback so slot 0 works without env varswt.base-port for the primary port only; additional ports use manual env var patternsTo opt in to data isolation for a service, add a wt.data-dir label. This creates isolated data directories per slot.
db:
labels:
wt.data-dir: "/var/lib/postgresql/data"
volumes:
- ${WT_DB_DATA:-./.docker-data/db}:/var/lib/postgresql/data
Services communicate by service name over Docker's internal network. Port offsets are irrelevant for inter-service communication:
backend:
environment:
- DATABASE_URL=postgresql://postgres:postgres@db:5432/app
Never use localhost or offset ports for service-to-service connections.
Mount source code into the container so host edits are visible immediately:
backend:
volumes:
- ./backend:/app # source code
For Node.js services, preserve container node_modules with an anonymous volume:
frontend:
volumes:
- ./frontend:/app
- /app/node_modules # prevents host node_modules from shadowing
For per-framework Dockerfile patterns, dev commands, and configuration details, consult references/stack-patterns.md.
Quick reference:
| Framework | Dev Command | Watches |
|---|---|---|
| FastAPI | uvicorn main:app --reload --host 0.0.0.0 | *.py |
| Django | python manage.py runserver 0.0.0.0:8000 | *.py |
| Flask | flask run --reload --host 0.0.0.0 | *.py |
| Express | nodemon index.js or tsx watch | *.js/*.ts |
| Vite | vite --host 0.0.0.0 --port 3000 | src/, index.html |
| Next.js | next dev --hostname 0.0.0.0 --port 3000 | pages/, app/ |
| Go (Air) | air | *.go |
| Rust (cargo-watch) | cargo watch -x run | *.rs |
| Rails | rails server -b 0.0.0.0 | app/, config/ |
| Spring Boot | ./mvnw spring-boot:run | src/ (with devtools) |
Import worktree.just from the project justfile:
import "worktree-wizard/worktree.just"
Override config vars before the import if needed:
wt-health-timeout := "90"
import "worktree-wizard/worktree.just"
List CLI tools the project needs beyond git/just/docker:
# .wt-required-tools
node
psql
For custom logic after worktree creation (migrations, seed data):
#!/bin/bash
# scripts/wt-post-setup.sh
echo "Running migrations..."
docker compose exec -T db psql -U postgres -c "CREATE DATABASE app;" 2>/dev/null || true
Must be executable: chmod +x scripts/wt-post-setup.sh
Always add:
.worktrees/
.docker-data/
.env*.local
One backend or microservice with optional database:
./:/app or ./src:/app/srcSeparate subdirectories for backend and frontend:
./backend:/app./frontend:/app + /app/node_moduleswt.base-portWT_BACKEND_PORT for browser accessreferences/stack-patterns.md — Dockerfile templates, dev commands, and compose service blocks per framework (Python, Node, Go, Rust, Ruby, Java)npx claudepluginhub asabedia/worktree-wizard --plugin worktree-wizardManages port allocations for git worktrees in local development to avoid service collisions. Books unique ports for postgres, redis, etc., and supports dynamic docker-compose via env vars.
Creates git worktree with symlinked/copied assets, independent per-project environments (venv/npm), and direnv .envrc. Uses .worktree.yml or infers config.
Creates isolated git worktrees for feature branches with dependency installs, port allocation via dev-setup scripts, and baseline test verification. Supports create or setup modes for clean workspaces.