chore: add script to spawn agent worktree with environment setup

.claude/skills/fix-issue/SKILL.md

@@ -4,7 +4,23 @@ description: Implement a GitHub issue with reproduction and verification
 allowed-tools: Bash, Edit, Write, Read, Glob, Grep, mcp__playwright__*, mcp__dokploy__*
 ---
 
-The issue number is passed as $1. An isolated instance is running at $DOKPLOY_BASE_URL.
+The issue number is passed as $1.
+
+## Instance
+
+No instance is running yet — start your own, isolated to this worktree:
+
+1. Check `apps/dokploy/.env` for `PORT` (assigned per-worktree already).
+2. If nothing is listening on that port, start it: `pnpm dokploy:dev` in the
+   background, then poll `curl -s -o /dev/null -w '%{http_code}' http://localhost:$PORT`
+   until it answers (usually ~10-15s).
+3. Use `http://localhost:$PORT` as the base URL for Playwright navigation.
+
+Note: `mcp__dokploy__*` (this repo's `.mcp.json`) resolves its URL from
+`$DOKPLOY_BASE_URL` once, at session startup — it cannot pick up a port
+discovered mid-session. If those tools are unavailable or point at the wrong
+instance, fall back to `curl`/`gh api` for API-level checks, or ask the user
+to relaunch with `DOKPLOY_BASE_URL` exported first.
 
 ## Tools
 

scripts/spawn-agent-worktree.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+NAME="${1:?usage: spawn-agent-worktree.sh <name>}"
+# --show-toplevel would return the CURRENT worktree's own root if this is
+# run from inside one (e.g. another agent's worktree) instead of the main
+# checkout. --git-common-dir always points at the shared .git regardless of
+# which worktree you're standing in.
+REPO_ROOT="$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")"
+WORKTREE_PATH="$REPO_ROOT/.claude/worktrees/$NAME"
+BRANCH="worktree-$NAME"
+
+if [ -e "$WORKTREE_PATH" ]; then
+	echo "Worktree already exists: $WORKTREE_PATH" >&2
+	exit 1
+fi
+
+git -C "$REPO_ROOT" fetch origin canary --quiet
+git -C "$REPO_ROOT" worktree add -b "$BRANCH" "$WORKTREE_PATH" origin/canary >&2
+
+# .worktreeinclude lists gitignored files (.env, .env.local) that a plain
+# `git worktree add` won't check out on its own - copy them in.
+while IFS= read -r pattern; do
+	[ -z "$pattern" ] && continue
+	find "$REPO_ROOT" \( -path "$REPO_ROOT/.claude/worktrees" -o -path "$REPO_ROOT/node_modules" \) -prune -o -name "$pattern" -print 2>/dev/null
+done < "$REPO_ROOT/.worktreeinclude" | while read -r src; do
+	rel="${src#"$REPO_ROOT"/}"
+	dest="$WORKTREE_PATH/$rel"
+	mkdir -p "$(dirname "$dest")"
+	cp "$src" "$dest"
+done
+
+cd "$WORKTREE_PATH"
+pnpm install --prefer-offline >&2
+
+FREE_PORT=$(node "$REPO_ROOT/scripts/find-free-port.mjs")
+sed -i.bak "s/^PORT=.*/PORT=$FREE_PORT/" apps/dokploy/.env
+sed -i.bak -E "s#^(BETTER_AUTH_URL=https?://[^:/]+):[0-9]+#\1:$FREE_PORT#" apps/dokploy/.env
+rm -f apps/dokploy/.env.bak
+
+pnpm --filter=dokploy run dev > "$WORKTREE_PATH/dev-server.log" 2>&1 &
+echo $! > "$WORKTREE_PATH/dev-server.pid"
+
+BASE_URL="http://localhost:$FREE_PORT"
+for _ in $(seq 1 30); do
+	CODE=$(curl -s -o /dev/null -w '%{http_code}' --max-time 1 "$BASE_URL/" || true)
+	if [ "$CODE" != "000" ]; then
+		break
+	fi
+	sleep 1
+done
+
+echo "export WORKTREE_PATH=$WORKTREE_PATH"
+echo "export DOKPLOY_BASE_URL=$BASE_URL"
+echo "export PORT=$FREE_PORT"