WonderPanda/worktrunk-setup
.claude/skills/worktrunk-setup/SKILL.md
Set up worktrunk (git worktree manager) with dynamic port allocation for Better-T-Stack monorepos using Doppler, Alchemy, and Vite. Use when bootstrapping a new project's worktree workflow, or when asked to "set up worktrunk", "configure worktrees", "add worktree support", or "set up dynamic ports for worktrees". Covers: post-create hooks (Doppler setup, dependency install, .env.worktree generation), env-based port overrides in Vite and Alchemy configs, and dev script modification to source worktree-specific env vars after Doppler injection.
development
Updated Apr 16, 2026
$ install --global
skillsauthnpx skillsauth add WonderPanda/mana-vault worktrunk-setupInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 16, 2026, 4:49 PM7.2s1 file scanned
SKILL.md
- name:
- worktrunk-setup
- description:
- >
- for worktrees". Covers:
- post-create hooks (Doppler setup, dependency install, .env.worktree generation),
Worktrunk Setup for Better-T-Stack
Configure worktrunk so each worktree gets isolated dev server ports via hash_port, preventing port conflicts when running multiple worktrees simultaneously.
Prerequisites
- Worktrunk CLI installed (
wt) - Doppler CLI configured for the project
- Better-T-Stack monorepo with Alchemy (infra), Vite (web), and Hono (server)
Setup Steps
1. Make ports configurable via env vars
apps/web/vite.config.ts — read web port from env:
server: {
port: Number(process.env.DEV_WEB_PORT) || 3001,
},
packages/infra/alchemy.run.ts — read server port from env:
dev: {
port: Number(process.env.DEV_SERVER_PORT) || 3007,
},
2. Source .env.worktree after Doppler in dev script
package.json — modify the dev script to source .env.worktree (if present) after Doppler injects base env vars, overriding port-dependent values in worktrees:
"dev": "doppler run -c dev -- sh -c '[ -f .env.worktree ] && set -a && . ./.env.worktree && set +a; exec turbo dev'"
In the main checkout, .env.worktree doesn't exist so Doppler defaults pass through unchanged.
3. Create .config/wt.toml project hooks
[post-create]
doppler = "doppler setup -p <PROJECT_NAME> -c dev --no-interactive"
install = "bun install"
env = """
cat > .env.worktree << 'EOF'
DEV_WEB_PORT={{ branch | hash_port }}
DEV_SERVER_PORT={{ ('server-' ~ branch) | hash_port }}
CORS_ORIGIN=http://localhost:{{ branch | hash_port }}
VITE_SERVER_URL=http://localhost:{{ ('server-' ~ branch) | hash_port }}
BETTER_AUTH_URL=http://localhost:{{ ('server-' ~ branch) | hash_port }}
EOF
"""
[post-start]
copy = "wt step copy-ignored"
[pre-merge]
lint = "bun run check"
typecheck = "bun run check-types"
[list]
url = "http://localhost:{{ branch | hash_port }}"
Replace <PROJECT_NAME> with the Doppler project name.
The ('server-' ~ branch) | hash_port concatenation ensures web and server ports never collide — they hash different strings.
Add any additional port-dependent env vars to the env hook (e.g., POLAR_SUCCESS_URL, webhook URLs).
4. Gitignore .env.worktree
Add .env.worktree to .gitignore. Do NOT add it to .worktreeinclude — each worktree generates its own.
5. Create .worktreeinclude
If not already present, create .worktreeinclude to copy gitignored files to new worktrees:
.claude/**
node_modules/
.env
.turbo/
How It Works
wt switch --create <branch>runspost-createhooks: configures Doppler, installs deps, writes.env.worktreewith deterministic portsbun run devruns Doppler, then sources.env.worktreeoverrides, then starts Turbo- Alchemy reads
DEV_SERVER_PORT, Vite readsDEV_WEB_PORT— both fall back to defaults if unset wt listshows each worktree's dev server URL
Port Allocation
hash_port maps strings to ports in the 10000–19999 range. Ports are deterministic — the same branch always gets the same port on any machine.
Related Skills
WonderPanda/tanstack-db-client
tools
VerifiedTrustedCommunity
TanStack DB client-side reactive data patterns for Mana Vault. Use when working with useLiveQuery hooks, client-side collections, RxDB/Dexie sync, or any reactive data queries in the web app. Covers hook locations, DB setup, and query builder best practices.
SKILL.mdUpdated Apr 16, 2026
WonderPanda/react-native-expo
development
VerifiedTrustedCommunity
React Native and Expo patterns for Mana Vault mobile app. Use when working on the native app in apps/native/, modifying Expo Router routes, HeroUI Native components, or Uniwind styling. Covers project structure and key conventions.
SKILL.mdUpdated Apr 16, 2026
WonderPanda/react-components
development
VerifiedTrustedCommunity
React component patterns, styling conventions, and UI guidelines for Mana Vault web app. Use when creating or modifying React components, working with TailwindCSS, shadcn/ui, class-variance-authority, or route components in TanStack Router.
SKILL.mdUpdated Apr 16, 2026
WonderPanda/local-first-replication
tools
VerifiedTrustedCommunity
Bootstraps local-first replication architecture using RxDB + oRPC + TanStack DB in TanStack Router applications. Covers server-side EventPublisher pattern, checkpoint-based pull endpoints, push replication with conflict resolution, multiplexed SSE streaming (single connection for all entities), client-side RxDB setup with IndexedDB, replication configuration, and React integration with TanStack DB collections and useLiveQuery. Use when: (1) Setting up offline-first architecture from scratch, (2) Adding real-time replication to a TanStack Router + oRPC app, (3) Bootstrapping a local-first data layer, (4) Implementing multiplexed sync to avoid browser connection limits, (5) Adding push replication with conflict resolution, (6) Creating reactive queries with RxDB + TanStack DB. Triggers: "set up local-first", "bootstrap offline-first", "add replication architecture", "set up RxDB with oRPC", "create local-first architecture", "implement pull replication", "implement push replication", "add multiplexed sync", "set up tanstack db with rxdb", "add real-time replication", "offline-first setup".
SKILL.mdUpdated Apr 16, 2026