From local-dev-setup
Manage git worktrees with automatic HTTPS domain routing for Weslink Laravel projects. Use when a developer says 'worktree erstellen', 'neuen worktree', 'wt create', 'feature branch mit eigener domain', or asks about parallel development on multiple branches.
How this skill is triggered — by the user, by Claude, or both
Slash command
/local-dev-setup:wtThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Worktrees allow parallel development on multiple branches, each with its own HTTPS domain. The `wt` CLI tool in `~/dev/infrastructure/bin/wt` handles everything automatically.
Worktrees allow parallel development on multiple branches, each with its own HTTPS domain. The wt CLI tool in ~/dev/infrastructure/bin/wt handles everything automatically.
There are two creation modes: fast (default) and full.
wt create calendar-fix
1. git worktree add .worktrees/calendar-fix -b feature/calendar-fix
2. Symlinks vendor/, node_modules/, .env to main project
3. Symlinks gitignored SSL certs needed by Vite
4. Generates nginx server config (new port)
5. Generates Traefik routing config
6. Regenerates TLS certificate with new SAN
7. Writes .wt-meta (mode=fast, db=shared)
Result: https://demo.kibi--calendar-fix.test is immediately accessible. Shares database with main project. No install step needed.
Best for: frontend fixes, small bugfixes, CSS changes.
wt create:full new-migration
1. git worktree add .worktrees/new-migration -b feature/new-migration
2. Runs composer install + npm install (own copies)
3. Runs npm run build (Vite assets)
4. Copies .env, adjusts APP_URL, DB_DATABASE, CENTRAL_DOMAIN, and SERVER_NAME
5. Symlinks gitignored SSL certs needed by Vite
6. Creates separate PostgreSQL database (pattern: {project}_wt_{name_underscored})
7. Runs php artisan migrate --seed
8. For multi-tenant projects (kibi): auto-creates demo tenant
9. Generates nginx server config (new port)
10. Generates Traefik routing config
11. Regenerates TLS certificate with new SAN
12. Writes .wt-meta (mode=full, db={project}_wt_{name_underscored})
Result: https://demo.kibi--new-migration.test with its own database, vendor/, and node_modules/.
Best for: new packages, migrations, breaking changes.
Each worktree contains a .wt-meta file that stores its configuration:
mode=fast|full
db=<database-name-or-shared>
This file is used by wt remove to determine cleanup steps and by wt list to display mode info.
| Project Type | Main Domain | Worktree Domain |
|---|---|---|
| With tenant subdomains (kibi) | *.kibi.test | *.kibi--<name>.test |
| Simple (bessler, contradoo, scada) | project.test | project--<name>.test |
The -- separator is used because it cannot be a valid tenant name.
All commands auto-detect the project based on the current working directory.
cd ~/dev/projects/kibi-connect/kibi
# Create worktree (fast mode - symlinks vendor/node_modules/.env, shares DB)
wt create <name> [branch] [base]
# Create worktree (full mode - own vendor/node_modules/.env, separate DB)
wt create:full <name> [branch] [base]
# Default branch: feature/<name>
# Default base: origin/develop
# List worktrees (shows mode, vendor status, database)
wt list
# Run command in worktree
wt run <name> artisan migrate
wt run <name> artisan test --filter=MyTest
# Remove worktree (cleans up routing + cert, drops DB for full mode)
wt remove <name>
wt create (fast mode):git fetch origingit worktree add .worktrees/<name> -b feature/<name> origin/developvendor/ and node_modules/ to main project (relative symlinks).env to main projectcerts/ directory) to main projectproject-name (range 8100-8999)/opt/homebrew/etc/nginx/servers/<project>-wt-<name>.conf~/dev/infrastructure/traefik/dynamic/<project>-wt-<name>.yml.wt-meta with mode=fastwt create:full (full mode):git fetch origingit worktree add .worktrees/<name> -b feature/<name> origin/developcomposer install (own vendor/)npm install (own node_modules/)npm run build to compile Vite assets (ensures the worktree serves properly without a running Vite dev server).env from main projectAPP_URL, DB_DATABASE, CENTRAL_DOMAIN, and SERVER_NAME in the copied .env (sets correct worktree domain)certs/ directory) to main project{project}_wt_{name_underscored})php artisan migrate --seedphp artisan kibi:create-demo-tenant)project-name (range 8100-8999)/opt/homebrew/etc/nginx/servers/<project>-wt-<name>.conf~/dev/infrastructure/traefik/dynamic/<project>-wt-<name>.yml.wt-meta with mode=full and db={project}_wt_{name_underscored}wt remove:.wt-meta to determine modegit worktree remove --forcewt list:Shows all worktrees with mode (fast/full), vendor status (symlinked/independent), and database (shared/own name).
Read ../setup-infra/references/projects.json for the full project list with paths, ports, and domain patterns.
.worktrees/ directory is gitignored.wt-meta file in each worktree tracks its mode and database name"Not in a known project directory": cd into one of the known project directories first.
502 Bad Gateway on worktree domain: nginx config may not have reloaded. Run nginx -s reload.
SSL error on worktree domain: Certificate needs to be regenerated. Run infra cert-regen "*.kibi--<name>.test" or re-create the worktree.
Port conflict: The port is deterministic based on the project+name hash. If there's a collision, remove and recreate with a different name.
npx claudepluginhub weslinkde/weslink-claude-marketplace --plugin local-dev-setupSets up git worktrees for Laravel projects served by Laravel Herd, creating isolated feature branches with dedicated site URLs and Vite configuration.
Automates Git worktree creation for isolated feature branches, listing, removal, and status checks. Copies env files like .env/.nvmrc and runs npm/yarn/pnpm/bun install.
Manages git worktrees via unified bash script for parallel development: creates isolated feature environments, lists/switches status, copies .env files, cleans up merged/stale worktrees.