@smicolon/ai-kit 0.2.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smicolon/ai-kit",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "AI coding tool pack manager for Smicolon standards",
   "license": "MIT",
   "repository": {

package/packs/worktree/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "worktree",
-  "version": "0.1.0",
-  "description": "Git worktree manager for parallel development with automatic env copying and dependency installation",
+  "version": "0.2.0",
+  "description": "Git worktree manager for parallel development with env isolation, Docker port offsets, and database auto-creation",
   "author": {
     "name": "Smicolon",
     "email": "dev@smicolon.com",

package/packs/worktree/CHANGELOG.md

@@ -1,12 +1,33 @@
 # Changelog
 
-All notable changes to smi-worktree will be documented in this file.
+All notable changes to worktree will be documented in this file.
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-02-15
+
+### Added
+
+- `.worktreeinclude` config file — gitignore-style patterns for files to copy
+- Auto-generates `.worktreeinclude` with sensible defaults on first `wt create`
+- `[rewrite]` section — auto-suffixes DB_NAME, DATABASE_URL, COMPOSE_PROJECT_NAME per branch
+- `{{BRANCH}}` template support for custom env var rewriting
+- `[docker]` section — generates `docker-compose.worktree.yml` with port offsets
+- Deterministic port offset via branch name hash (1-100 range)
+- Custom compose file path via `file=` directive (supports monorepo nested paths)
+- Auto-creates Postgres databases (Docker containers or local)
+- `docker compose down` on `wt remove` before removing worktree
+- Port mapping summary in create output
+
 ### Changed
-- Renamed from `smi-worktree` to `worktree` as part of ai-kit migration
-- Moved from `plugins/smi-worktree/` to `packs/worktree/`
+
+- `wt create` now uses `.worktreeinclude` patterns instead of hardcoded `.env*` copying
+- `wt remove` stops Docker containers and notes that databases are preserved
+- `wt help` documents `.worktreeinclude` sections
+
+### Removed
+
+- Hardcoded `copy_env_files()` function (replaced by `.worktreeinclude` pattern matching)
 
 ## [0.1.0] - 2026-01-17
 

package/packs/worktree/README.md

@@ -1,11 +1,14 @@
 # worktree
 
-Git worktree manager for parallel development with automatic environment setup.
+Git worktree manager for parallel development with automatic environment isolation.
 
 ## Features
 
 - **Sibling naming**: `project--branch-name/` convention
-- **Auto env copy**: Copies `.env*` from root and nested directories
+- **`.worktreeinclude`**: Configurable file copying (replaces hardcoded `.env*`)
+- **Env rewriting**: Auto-suffixes DB names, URLs, and compose project names per branch
+- **Docker isolation**: Port-offset overrides so worktrees don't conflict
+- **Database auto-creation**: Creates Postgres databases for rewritten DB names
 - **Package manager detection**: bun → pnpm → yarn → npm
 - **Monorepo aware**: Detects workspaces, turbo, nx, lerna
 - **Editor integration**: Open in Cursor, Antigravity, or VS Code
@@ -16,6 +19,98 @@ Git worktree manager for parallel development with automatic environment setup.
 /plugin install worktree
 ```
 
+## Quick Start
+
+```bash
+/wt create feature/auth
+# → Creates worktree at ~/code/project--feature-auth/
+# → Copies files per .worktreeinclude
+# → Rewrites DB_NAME, DATABASE_URL with branch suffix
+# → Generates docker-compose.worktree.yml with offset ports
+# → Creates database in running Postgres
+# → Installs dependencies
+```
+
+## `.worktreeinclude`
+
+Auto-generated on first `wt create` if missing. Commit this file so your team shares the same config.
+
+```ini
+# .worktreeinclude — Files to copy to new worktrees
+.env*
+
+# Monorepo (uncomment as needed)
+# apps/*/.env*
+# packages/*/.env*
+# services/*/.env*
+
+[rewrite]
+auto
+
+[docker]
+auto
+# file=apps/backend/docker-compose.local.yml
+# port_offset=10
+```
+
+### File Patterns (top section)
+
+Gitignore-style glob patterns for untracked files to copy from main worktree:
+
+```
+.env*
+apps/*/.env*
+config/local.yml
+```
+
+### `[rewrite]` — Env Var Isolation
+
+**`auto` mode** detects and suffixes known keys with a branch slug:
+
+| Key | Example | Result |
+|-----|---------|--------|
+| `DB_NAME` | `myapp` | `myapp_feature_auth` |
+| `POSTGRES_DB` | `myapp` | `myapp_feature_auth` |
+| `DATABASE_URL` | `postgres://...host/myapp` | `postgres://...host/myapp_feature_auth` |
+| `COMPOSE_PROJECT_NAME` | `myapp` | `myapp_feature_auth` |
+
+**Template mode** uses `{{BRANCH}}` for custom vars:
+
+```bash
+MY_CUSTOM_DB=app_{{BRANCH}}
+REDIS_PREFIX={{BRANCH}}_
+```
+
+Both modes work together — template takes precedence over auto.
+
+Branch slug: `feature/auth-v2` → `feature_auth_v2` (lowercase, special chars → `_`, max 30 chars).
+
+### `[docker]` — Docker Compose Isolation
+
+Generates a `docker-compose.worktree.yml` override with port offsets:
+
+- **`auto`**: Auto-detects compose file (`local.yml` → `docker-compose.local.yml` → `docker-compose.yml` → etc.)
+- **`file=path`**: Specify compose file path (supports nested monorepo paths)
+- **`port_offset=N`**: Override the auto-calculated offset
+
+```ini
+[docker]
+auto
+file=apps/backend/docker-compose.local.yml
+```
+
+**How it works:**
+
+1. Parses ports from your compose file
+2. Calculates a deterministic offset from branch name (1-100 via `cksum`)
+3. Generates `docker-compose.worktree.yml` next to the original
+4. Sets `COMPOSE_FILE=original.yml:docker-compose.worktree.yml` in `.env`
+5. Sets `COMPOSE_PROJECT_NAME` for container/volume/network isolation
+
+After setup, `docker compose up -d` in the worktree automatically picks up both files.
+
+**Auto-creates databases** in running Postgres containers (Docker or local). Idempotent — safe to run multiple times.
+
 ## Usage
 
 ### Create Worktree
@@ -26,7 +121,10 @@ Git worktree manager for parallel development with automatic environment setup.
 ```
 
 Creates worktree at `~/code/project--feature-authentication/` with:
-- All `.env*` files copied
+- Files copied per `.worktreeinclude`
+- Env vars rewritten with branch suffix
+- Docker port offsets applied
+- Database created
 - Dependencies installed
 
 ### List Worktrees
@@ -43,6 +141,8 @@ Creates worktree at `~/code/project--feature-authentication/` with:
 /wt rm feat-payments -d  # also delete branch
 ```
 
+Stops Docker containers before removing. Databases are preserved (drop manually if no longer needed).
+
 ### Open in Editor
 
 ```bash
@@ -73,12 +173,6 @@ Priority: flag > `WT_EDITOR` > auto-detect (Cursor → Antigravity → VS Code)
 
 ## Auto-Setup Details
 
-### Environment Files
-
-Copies from:
-- Root: `.env`, `.env.local`, `.env.development`, etc.
-- Nested: `apps/*/.env*`, `packages/*/.env*`, `services/*/.env*`
-
 ### Package Manager Detection
 
 Checks in order:
@@ -96,6 +190,19 @@ Detects via:
 - `lerna.json`
 - `"workspaces"` in `package.json`
 
+### Compose File Detection Order
+
+When `[docker] auto` is set and no `file=` specified:
+
+1. `local.yml`
+2. `docker-compose.local.yml`
+3. `docker-compose.yml`
+4. `docker-compose.yaml`
+5. `compose.yml`
+6. `compose.yaml`
+
+Also searches `apps/*/` and `services/*/` subdirectories.
+
 ## Skill Triggers
 
 The worktree-manager skill auto-activates when you mention:
@@ -104,6 +211,8 @@ The worktree-manager skill auto-activates when you mention:
 - "feature branch setup"
 - "work on multiple branches"
 - "separate workspace for branch"
+- "docker port conflict" or "database isolation"
+- "worktreeinclude" or "env isolation"
 
 ## License
 

package/packs/worktree/commands/wt.md

@@ -1,13 +1,13 @@
 ---
 name: wt
-description: Git worktree manager - create, list, remove, and open worktrees with automatic env copying and dependency installation
+description: Git worktree manager - create, list, remove, and open worktrees with env isolation, Docker port offsets, and database auto-creation
 argument-hint: '<command> [branch] [options]'
 allowed-tools: ["Bash(${CLAUDE_PLUGIN_ROOT}/scripts/wt.sh:*)"]
 ---
 
 # Git Worktree Manager
 
-Manage git worktrees with automatic setup for parallel development.
+Manage git worktrees with automatic isolation for parallel development.
 
 ## Usage
 
@@ -19,9 +19,9 @@ Manage git worktrees with automatic setup for parallel development.
 
 | Command | Alias | Description |
 |---------|-------|-------------|
-| `create <branch>` | `c` | Create worktree, copy .env files, install deps |
+| `create <branch>` | `c` | Create worktree with isolation (env, docker, db) |
 | `list` | `ls` | List all worktrees for current repo |
-| `remove <branch>` | `rm` | Remove worktree (add `-d` to delete branch) |
+| `remove <branch>` | `rm` | Remove worktree (stops Docker, add `-d` to delete branch) |
 | `open <branch> [--editor]` | `o` | Open worktree (--cursor\|-c, --agy\|-a, --code\|-v) |
 
 ## Instructions
@@ -35,7 +35,7 @@ Run the worktree manager script:
 ## Examples
 
 ```bash
-# Create worktree for new feature
+# Create worktree for new feature (with full isolation)
 /wt create feature/authentication
 
 # Short form
@@ -44,7 +44,7 @@ Run the worktree manager script:
 # List all worktrees
 /wt ls
 
-# Remove worktree
+# Remove worktree (stops Docker containers first)
 /wt rm feature/authentication
 
 # Remove worktree AND delete branch
@@ -67,7 +67,27 @@ Run the worktree manager script:
 
 ## Auto-Setup on Create
 
-1. Copies all `.env*` files from root
-2. Copies nested `.env*` from `apps/*/`, `packages/*/`, `services/*/`
-3. Detects package manager (bun → pnpm → yarn → npm)
-4. Runs install at root (monorepo-aware)
+1. Loads `.worktreeinclude` (generates default if missing)
+2. Copies files matching glob patterns
+3. Rewrites env vars (DB_NAME, DATABASE_URL, etc.) with branch suffix
+4. Generates `docker-compose.worktree.yml` with port offsets
+5. Auto-creates database in running Postgres
+6. Detects package manager (bun → pnpm → yarn → npm)
+7. Runs install at root (monorepo-aware)
+
+## `.worktreeinclude` Format
+
+```ini
+# File patterns to copy
+.env*
+apps/*/.env*
+
+[rewrite]
+auto                    # suffix DB_NAME, DATABASE_URL, etc.
+# MY_DB=app_{{BRANCH}} # template mode
+
+[docker]
+auto                    # auto-detect compose file
+# file=apps/backend/docker-compose.local.yml
+# port_offset=10
+```

package/packs/worktree/scripts/wt.sh

@@ -11,6 +11,7 @@ RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
 BLUE='\033[0;34m'
+CYAN='\033[0;36m'
 NC='\033[0m' # No Color
 
 # Helpers
@@ -58,66 +59,574 @@ detect_pkg_manager() {
 # Detect if monorepo
 is_monorepo() {
     local dir="${1:-$REPO_ROOT}"
-    # Check for monorepo indicators
     [[ -f "$dir/pnpm-workspace.yaml" ]] && return 0
     [[ -f "$dir/turbo.json" ]] && return 0
     [[ -f "$dir/nx.json" ]] && return 0
     [[ -f "$dir/lerna.json" ]] && return 0
-    # Check for workspaces in package.json
     if [[ -f "$dir/package.json" ]]; then
         grep -q '"workspaces"' "$dir/package.json" 2>/dev/null && return 0
     fi
     return 1
 }
 
-# Copy .env files from source to destination
-copy_env_files() {
+# Get worktree path from branch name
+get_worktree_path() {
+    local branch="$1"
+    local safe_branch="${branch//\//-}"
+    echo "${REPO_PARENT}/${REPO_NAME}--${safe_branch}"
+}
+
+# Strip main repo name prefix from worktree basename
+get_branch_from_worktree() {
+    local wt_path="$1"
+    local wt_name=$(basename "$wt_path")
+    echo "${wt_name#${REPO_NAME}--}"
+}
+
+# =============================================================================
+# Phase 1: .worktreeinclude Parsing & File Copying
+# =============================================================================
+
+# Generate default .worktreeinclude if it doesn't exist
+generate_default_worktreeinclude() {
+    local target="$REPO_ROOT/.worktreeinclude"
+    [[ -f "$target" ]] && return 0
+
+    cat > "$target" << 'TEMPLATE'
+# .worktreeinclude — Files to copy to new worktrees
+# Commit this file so your team shares the same config
+.env*
+
+# Monorepo (uncomment as needed)
+# apps/*/.env*
+# packages/*/.env*
+# services/*/.env*
+
+[rewrite]
+auto
+
+[docker]
+auto
+# file=apps/backend/docker-compose.local.yml
+# port_offset=10
+TEMPLATE
+    info "Generated .worktreeinclude (commit this file)"
+}
+
+# Parse .worktreeinclude into 3 arrays: file patterns, rewrite lines, docker lines
+parse_worktreeinclude() {
+    local include_file="$REPO_ROOT/.worktreeinclude"
+    WT_FILE_PATTERNS=()
+    WT_REWRITE_LINES=()
+    WT_DOCKER_LINES=()
+
+    [[ -f "$include_file" ]] || return 0
+
+    local current_section="files"
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        # Strip trailing whitespace
+        line="${line%"${line##*[![:space:]]}"}"
+        # Skip empty lines and comments
+        [[ -z "$line" ]] && continue
+        [[ "$line" == \#* ]] && continue
+
+        # Detect section headers
+        if [[ "$line" == "[rewrite]" ]]; then
+            current_section="rewrite"
+            continue
+        elif [[ "$line" == "[docker]" ]]; then
+            current_section="docker"
+            continue
+        fi
+
+        case "$current_section" in
+            files)   WT_FILE_PATTERNS+=("$line") ;;
+            rewrite) WT_REWRITE_LINES+=("$line") ;;
+            docker)  WT_DOCKER_LINES+=("$line") ;;
+        esac
+    done < "$include_file"
+}
+
+# Expand glob patterns against main worktree, return matched files (relative paths)
+match_files_by_patterns() {
+    local src="$1"
+    MATCHED_FILES=()
+
+    for pattern in "${WT_FILE_PATTERNS[@]}"; do
+        # Use subshell with nullglob to safely expand globs
+        while IFS= read -r -d '' file; do
+            local rel="${file#"$src"/}"
+            MATCHED_FILES+=("$rel")
+        done < <(
+            cd "$src"
+            shopt -s nullglob
+            shopt -s globstar 2>/dev/null || true  # bash 4+ only, needed for **
+            for f in $pattern; do
+                [[ -f "$f" ]] && printf '%s\0' "$src/$f"
+            done
+        )
+    done
+}
+
+# Copy matched files preserving directory structure
+copy_matched_files() {
     local src="$1"
     local dst="$2"
     local count=0
 
-    # Copy root .env* files
-    for envfile in "$src"/.env*; do
-        [[ -f "$envfile" ]] || continue
-        local filename=$(basename "$envfile")
-        cp "$envfile" "$dst/$filename"
+    for rel in "${MATCHED_FILES[@]+"${MATCHED_FILES[@]}"}"; do
+        local dir=$(dirname "$rel")
+        [[ "$dir" != "." ]] && mkdir -p "$dst/$dir"
+        cp "$src/$rel" "$dst/$rel"
         ((count++))
     done
 
-    # Copy nested .env* files from common monorepo directories
-    for subdir in apps packages services libs modules; do
-        [[ -d "$src/$subdir" ]] || continue
-        for app_dir in "$src/$subdir"/*/; do
+    echo "$count"
+}
+
+# =============================================================================
+# Phase 2: Env Var Rewriting
+# =============================================================================
+
+# Branch name → safe slug for suffixing (lowercase, special chars → _, max 30)
+sanitize_branch_for_suffix() {
+    local branch="$1"
+    local slug
+    slug=$(printf '%s' "$branch" | tr '[:upper:]' '[:lower:]' | tr -c '[:alnum:]' '_')
+    # Trim leading/trailing underscores
+    slug="${slug#_}"
+    slug="${slug%_}"
+    # Truncate to 30 chars
+    printf '%s' "${slug:0:30}"
+}
+
+# Rewrite a single .env file — auto-detect known keys + template {{BRANCH}}
+rewrite_env_file() {
+    local env_file="$1"
+    local branch_slug="$2"
+    local has_auto=false
+
+    # Check if auto mode is enabled
+    for line in "${WT_REWRITE_LINES[@]}"; do
+        [[ "$line" == "auto" ]] && has_auto=true
+    done
+
+    local tmpfile
+    tmpfile=$(mktemp)
+    local changed=false
+
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        local newline="$line"
+
+        # Template: replace {{BRANCH}} placeholders
+        if [[ "$line" == *'{{BRANCH}}'* ]]; then
+            newline="${line//\{\{BRANCH\}\}/$branch_slug}"
+            changed=true
+        elif [[ "$has_auto" == true ]]; then
+            # Auto-detect known keys (only lines with = that aren't comments)
+            if [[ "$line" =~ ^[[:space:]]*([A-Za-z_][A-Za-z0-9_]*)=(.*) ]]; then
+                local key="${BASH_REMATCH[1]}"
+                local val="${BASH_REMATCH[2]}"
+                # Strip surrounding quotes from val for processing
+                local raw_val="$val"
+                raw_val="${raw_val#\"}"
+                raw_val="${raw_val%\"}"
+                raw_val="${raw_val#\'}"
+                raw_val="${raw_val%\'}"
+
+                case "$key" in
+                    DB_NAME|POSTGRES_DB|MYSQL_DATABASE|DATABASE_NAME)
+                        # Suffix the value
+                        newline="${key}=${raw_val}_${branch_slug}"
+                        changed=true
+                        ;;
+                    DATABASE_URL|POSTGRES_URL)
+                        # Parse URL: scheme://user:pass@host:port/dbname?params
+                        # Suffix the database name portion
+                        if [[ "$raw_val" =~ ^(.*://[^/]*/?)([^?]+)(.*) ]]; then
+                            local prefix="${BASH_REMATCH[1]}"
+                            local dbname="${BASH_REMATCH[2]}"
+                            local suffix="${BASH_REMATCH[3]}"
+                            newline="${key}=${prefix}${dbname}_${branch_slug}${suffix}"
+                            changed=true
+                        fi
+                        ;;
+                    COMPOSE_PROJECT_NAME)
+                        newline="${key}=${raw_val}_${branch_slug}"
+                        changed=true
+                        ;;
+                esac
+            fi
+        fi
+
+        printf '%s\n' "$newline"
+    done < "$env_file" > "$tmpfile"
+
+    if [[ "$changed" == true ]]; then
+        mv "$tmpfile" "$env_file"
+    else
+        rm -f "$tmpfile"
+    fi
+
+    echo "$changed"
+}
+
+# Find and rewrite all .env* files in the worktree
+rewrite_all_env_files() {
+    local wt_path="$1"
+    local branch_slug="$2"
+    local count=0
+
+    # Only proceed if there are rewrite lines configured
+    [[ ${#WT_REWRITE_LINES[@]} -gt 0 ]] || return 0
+
+    while IFS= read -r -d '' env_file; do
+        local basename_f
+        basename_f=$(basename "$env_file")
+        # Only process .env* files (not .envrc or similar non-env files)
+        [[ "$basename_f" == .env* ]] || continue
+        local result
+        result=$(rewrite_env_file "$env_file" "$branch_slug")
+        [[ "$result" == "true" ]] && ((count++))
+    done < <(find "$wt_path" -name '.env*' -not -path '*/node_modules/*' -not -path '*/.git/*' -print0 2>/dev/null)
+
+    echo "$count"
+}
+
+# =============================================================================
+# Phase 3: Docker Compose Isolation
+# =============================================================================
+
+# Deterministic port offset from branch name (1-100 range via cksum)
+branch_to_port_offset() {
+    local branch="$1"
+    local hash
+    hash=$(printf '%s' "$branch" | cksum | awk '{print $1}')
+    echo $(( (hash % 100) + 1 ))
+}
+
+# Minimal YAML parser: extract host ports from docker-compose services
+# Output format: service_name:host_port:container_port (one per line)
+parse_docker_compose_ports() {
+    local compose_file="$1"
+    awk '
+    /^[[:space:]]*[a-zA-Z_][a-zA-Z0-9_-]*:/ && !/^\s*-/ && !/ports:/ && !/image:/ && !/container_name:/ {
+        # Top-level or nested service name
+        indent = 0
+        for (i = 1; i <= length($0); i++) {
+            if (substr($0, i, 1) == " ") indent++
+            else break
+        }
+        line = $0
+        gsub(/^[[:space:]]+/, "", line)
+        gsub(/:.*/, "", line)
+        if (indent <= 4) current_service = line
+    }
+    /ports:/ {
+        in_ports = 1
+        next
+    }
+    in_ports && /^[[:space:]]*-[[:space:]]*"?[0-9]/ {
+        line = $0
+        gsub(/^[[:space:]]*-[[:space:]]*/, "", line)
+        gsub(/"/, "", line)
+        gsub(/[[:space:]].*/, "", line)
+        # line is now like "5432:5432" or "8025:8025"
+        split(line, parts, ":")
+        if (length(parts) >= 2) {
+            print current_service ":" parts[1] ":" parts[2]
+        }
+        next
+    }
+    in_ports && /^[[:space:]]*[^-[:space:]]/ {
+        in_ports = 0
+    }
+    ' "$compose_file"
+}
+
+# Detect compose file path — checks [docker] file= directive, then auto-detects
+detect_compose_file() {
+    local wt_path="$1"
+    local compose_file=""
+
+    # Check for file= directive in [docker] config
+    for line in "${WT_DOCKER_LINES[@]}"; do
+        if [[ "$line" =~ ^file=(.+) ]]; then
+            local specified="${BASH_REMATCH[1]}"
+            specified="${specified#"${specified%%[![:space:]]*}"}"  # trim leading
+            specified="${specified%"${specified##*[![:space:]]}"}"  # trim trailing
+            if [[ -f "$wt_path/$specified" ]]; then
+                echo "$specified"
+                return 0
+            else
+                warn "Specified compose file not found: $specified"
+            fi
+        fi
+    done
+
+    # Auto-detect in standard locations
+    local candidates=(
+        "local.yml"
+        "docker-compose.local.yml"
+        "docker-compose.yml"
+        "docker-compose.yaml"
+        "compose.yml"
+        "compose.yaml"
+    )
+
+    # Check root first
+    for candidate in "${candidates[@]}"; do
+        if [[ -f "$wt_path/$candidate" ]]; then
+            echo "$candidate"
+            return 0
+        fi
+    done
+
+    # Check nested app directories
+    for subdir in apps services; do
+        [[ -d "$wt_path/$subdir" ]] || continue
+        for app_dir in "$wt_path/$subdir"/*/; do
             [[ -d "$app_dir" ]] || continue
-            local app_name=$(basename "$app_dir")
-            for envfile in "$app_dir".env*; do
-                [[ -f "$envfile" ]] || continue
-                local filename=$(basename "$envfile")
-                # Ensure target directory exists
-                mkdir -p "$dst/$subdir/$app_name"
-                cp "$envfile" "$dst/$subdir/$app_name/$filename"
-                ((count++))
+            for candidate in "${candidates[@]}"; do
+                if [[ -f "$app_dir$candidate" ]]; then
+                    local rel="${app_dir#"$wt_path"/}$candidate"
+                    echo "$rel"
+                    return 0
+                fi
             done
         done
     done
 
-    echo "$count"
+    return 1
 }
 
-# Get worktree path from branch name
-get_worktree_path() {
-    local branch="$1"
-    # Replace slashes with dashes for branch names like feature/auth
-    local safe_branch="${branch//\//-}"
-    echo "${REPO_PARENT}/${REPO_NAME}--${safe_branch}"
+# Generate docker-compose.worktree.yml override with port offsets
+generate_docker_compose_override() {
+    local compose_file="$1"  # full path to original compose file
+    local offset="$2"
+    local override_dir
+    override_dir=$(dirname "$compose_file")
+    local override_file="$override_dir/docker-compose.worktree.yml"
+
+    local ports_data
+    ports_data=$(parse_docker_compose_ports "$compose_file")
+
+    [[ -z "$ports_data" ]] && return 1
+
+    local tmpfile
+    tmpfile=$(mktemp)
+
+    cat > "$tmpfile" << 'HEADER'
+# Auto-generated by wt — DO NOT EDIT
+# Port offsets for worktree isolation
+services:
+HEADER
+
+    local current_service=""
+    while IFS=: read -r service host_port container_port; do
+        [[ -z "$service" ]] && continue
+        local new_port=$((host_port + offset))
+
+        if [[ "$service" != "$current_service" ]]; then
+            printf '  %s:\n' "$service" >> "$tmpfile"
+            printf '    ports:\n' >> "$tmpfile"
+            current_service="$service"
+        fi
+        printf '      - "%d:%s"\n' "$new_port" "$container_port" >> "$tmpfile"
+    done <<< "$ports_data"
+
+    mv "$tmpfile" "$override_file"
+    echo "$override_file"
 }
 
-# Strip main repo name prefix from worktree basename
-get_branch_from_worktree() {
+# Orchestrate Docker isolation: detect, offset, generate override, update .env
+setup_docker_isolation() {
     local wt_path="$1"
-    local wt_name=$(basename "$wt_path")
-    # Remove the repo name prefix and --
-    echo "${wt_name#${REPO_NAME}--}"
+    local branch="$2"
+    local branch_slug="$3"
+
+    # Check if docker section has 'auto' or any config
+    local has_docker=false
+    for line in "${WT_DOCKER_LINES[@]}"; do
+        [[ "$line" == "auto" || "$line" =~ ^file= ]] && has_docker=true
+    done
+    [[ "$has_docker" == true ]] || return 0
+
+    local compose_rel
+    compose_rel=$(detect_compose_file "$wt_path") || {
+        warn "No docker-compose file found, skipping Docker isolation"
+        return 0
+    }
+
+    local compose_full="$wt_path/$compose_rel"
+    local offset
+    offset=$(branch_to_port_offset "$branch")
+
+    # Check for custom port_offset
+    for line in "${WT_DOCKER_LINES[@]}"; do
+        if [[ "$line" =~ ^port_offset=([0-9]+) ]]; then
+            offset="${BASH_REMATCH[1]}"
+        fi
+    done
+
+    info "Docker isolation: $compose_rel (port offset +$offset)"
+
+    local override_file
+    override_file=$(generate_docker_compose_override "$compose_full" "$offset") || {
+        warn "No ports found in compose file, skipping port override"
+        return 0
+    }
+
+    local override_rel="${override_file#"$wt_path"/}"
+    success "Generated $override_rel"
+
+    # Set COMPOSE_FILE and COMPOSE_PROJECT_NAME in root .env
+    local root_env="$wt_path/.env"
+    local compose_file_val="${compose_rel}:${override_rel}"
+    local project_name="${REPO_NAME}_${branch_slug}"
+
+    # Append or update COMPOSE_FILE in .env
+    if [[ -f "$root_env" ]]; then
+        local tmpfile
+        tmpfile=$(mktemp)
+        local found_cf=false
+        local found_cpn=false
+        while IFS= read -r line || [[ -n "$line" ]]; do
+            if [[ "$line" =~ ^COMPOSE_FILE= ]]; then
+                printf 'COMPOSE_FILE=%s\n' "$compose_file_val"
+                found_cf=true
+            elif [[ "$line" =~ ^COMPOSE_PROJECT_NAME= ]]; then
+                printf 'COMPOSE_PROJECT_NAME=%s\n' "$project_name"
+                found_cpn=true
+            else
+                printf '%s\n' "$line"
+            fi
+        done < "$root_env" > "$tmpfile"
+        [[ "$found_cf" == false ]] && printf 'COMPOSE_FILE=%s\n' "$compose_file_val" >> "$tmpfile"
+        [[ "$found_cpn" == false ]] && printf 'COMPOSE_PROJECT_NAME=%s\n' "$project_name" >> "$tmpfile"
+        mv "$tmpfile" "$root_env"
+    else
+        printf 'COMPOSE_FILE=%s\n' "$compose_file_val" > "$root_env"
+        printf 'COMPOSE_PROJECT_NAME=%s\n' "$project_name" >> "$root_env"
+    fi
+
+    # Print port mapping summary
+    local ports_data
+    ports_data=$(parse_docker_compose_ports "$compose_full")
+    if [[ -n "$ports_data" ]]; then
+        echo ""
+        echo -e "  ${CYAN}Port mappings:${NC}"
+        while IFS=: read -r service host_port container_port; do
+            [[ -z "$service" ]] && continue
+            local new_port=$((host_port + offset))
+            echo -e "    ${service}: ${host_port} → ${GREEN}${new_port}${NC}"
+        done <<< "$ports_data"
+    fi
+}
+
+# =============================================================================
+# Phase 4: Database Auto-Creation
+# =============================================================================
+
+# Detect Postgres — checks Docker containers first, then local
+detect_postgres() {
+    # Check Docker containers for postgres
+    if command -v docker &>/dev/null; then
+        local pg_container
+        pg_container=$(docker ps --filter "ancestor=postgres" --filter "status=running" --format '{{.Names}}' 2>/dev/null | head -1)
+        if [[ -n "$pg_container" ]]; then
+            echo "docker:$pg_container"
+            return 0
+        fi
+        # Also check by port binding (for custom images)
+        pg_container=$(docker ps --filter "publish=5432" --filter "status=running" --format '{{.Names}}' 2>/dev/null | head -1)
+        if [[ -n "$pg_container" ]]; then
+            echo "docker:$pg_container"
+            return 0
+        fi
+    fi
+
+    # Check local postgres
+    if command -v pg_isready &>/dev/null && pg_isready -q 2>/dev/null; then
+        echo "local"
+        return 0
+    fi
+
+    return 1
+}
+
+# Create database if it doesn't exist (idempotent)
+create_database_if_not_exists() {
+    local db_name="$1"
+    local pg_source="$2"  # "docker:container_name" or "local"
+
+    local exists_query="SELECT 1 FROM pg_database WHERE datname='$db_name'"
+    local create_query="CREATE DATABASE \"$db_name\""
+    local result=""
+
+    if [[ "$pg_source" == local ]]; then
+        result=$(psql -tAc "$exists_query" postgres 2>/dev/null || true)
+        if [[ "$result" != "1" ]]; then
+            psql -c "$create_query" postgres 2>/dev/null && return 0 || return 1
+        fi
+    elif [[ "$pg_source" == docker:* ]]; then
+        local container="${pg_source#docker:}"
+        result=$(docker exec "$container" psql -U postgres -tAc "$exists_query" postgres 2>/dev/null || true)
+        if [[ "$result" != "1" ]]; then
+            docker exec "$container" psql -U postgres -c "$create_query" postgres 2>/dev/null && return 0 || return 1
+        fi
+    fi
+
+    return 0  # Already exists
+}
+
+# Read rewritten DB name from .env files and auto-create databases
+auto_create_databases() {
+    local wt_path="$1"
+    local pg_source
+
+    pg_source=$(detect_postgres) || {
+        warn "Postgres not running, skipping database auto-creation"
+        return 0
+    }
+
+    # Collect unique database names from all .env files
+    local db_names=()
+    while IFS= read -r -d '' env_file; do
+        while IFS= read -r line; do
+            if [[ "$line" =~ ^(DB_NAME|POSTGRES_DB|MYSQL_DATABASE|DATABASE_NAME)=(.+) ]]; then
+                local val="${BASH_REMATCH[2]}"
+                val="${val#\"}" ; val="${val%\"}"
+                val="${val#\'}" ; val="${val%\'}"
+                # Only add if not already in array
+                local found=false
+                for existing in "${db_names[@]+"${db_names[@]}"}"; do
+                    [[ "$existing" == "$val" ]] && found=true
+                done
+                [[ "$found" == false ]] && db_names+=("$val")
+            elif [[ "$line" =~ ^(DATABASE_URL|POSTGRES_URL)=(.+) ]]; then
+                local url="${BASH_REMATCH[2]}"
+                url="${url#\"}" ; url="${url%\"}"
+                # Extract db name from URL: scheme://user:pass@host:port/dbname
+                if [[ "$url" =~ ://[^/]*/([^?]+) ]]; then
+                    local val="${BASH_REMATCH[1]}"
+                    local found=false
+                    for existing in "${db_names[@]+"${db_names[@]}"}"; do
+                        [[ "$existing" == "$val" ]] && found=true
+                    done
+                    [[ "$found" == false ]] && db_names+=("$val")
+                fi
+            fi
+        done < "$env_file"
+    done < <(find "$wt_path" -maxdepth 3 -name '.env*' -not -path '*/node_modules/*' -not -path '*/.git/*' -print0 2>/dev/null)
+
+    for db_name in "${db_names[@]+"${db_names[@]}"}"; do
+        if create_database_if_not_exists "$db_name" "$pg_source"; then
+            success "Database ready: $db_name"
+        else
+            warn "Could not create database: $db_name"
+        fi
+    done
 }
 
 # =============================================================================
@@ -141,9 +650,9 @@ cmd_create() {
         exit 1
     fi
 
+    # --- Step 1: Create git worktree ---
     info "Creating worktree for branch: $branch"
 
-    # Check if branch exists (local or remote)
     if git show-ref --verify --quiet "refs/heads/$branch" 2>/dev/null; then
         info "Checking out existing local branch: $branch"
         git worktree add "$wt_path" "$branch"
@@ -156,16 +665,47 @@ cmd_create() {
     fi
     success "Worktree created at: $wt_path"
 
-    # Copy .env files
-    info "Copying .env files..."
-    local env_count=$(copy_env_files "$REPO_ROOT" "$wt_path")
-    if [[ "$env_count" -gt 0 ]]; then
-        success "Copied $env_count .env file(s)"
-    else
-        warn "No .env files found to copy"
+    # --- Step 2: Load .worktreeinclude ---
+    generate_default_worktreeinclude
+    parse_worktreeinclude
+
+    # --- Step 3: Copy files matching patterns ---
+    if [[ ${#WT_FILE_PATTERNS[@]} -gt 0 ]]; then
+        info "Copying files from .worktreeinclude..."
+        match_files_by_patterns "$REPO_ROOT"
+        local file_count
+        file_count=$(copy_matched_files "$REPO_ROOT" "$wt_path")
+        if [[ "$file_count" -gt 0 ]]; then
+            success "Copied $file_count file(s)"
+        else
+            warn "No matching files found to copy"
+        fi
     fi
 
-    # Detect and run package manager install
+    # --- Step 4: Rewrite env vars ---
+    local branch_slug
+    branch_slug=$(sanitize_branch_for_suffix "$branch")
+
+    if [[ ${#WT_REWRITE_LINES[@]} -gt 0 ]]; then
+        info "Rewriting env vars (suffix: _$branch_slug)..."
+        local rewrite_count
+        rewrite_count=$(rewrite_all_env_files "$wt_path" "$branch_slug")
+        if [[ "$rewrite_count" -gt 0 ]]; then
+            success "Rewrote $rewrite_count .env file(s)"
+        fi
+    fi
+
+    # --- Step 5: Docker Compose isolation ---
+    if [[ ${#WT_DOCKER_LINES[@]} -gt 0 ]]; then
+        setup_docker_isolation "$wt_path" "$branch" "$branch_slug"
+    fi
+
+    # --- Step 6: Auto-create database ---
+    if [[ ${#WT_REWRITE_LINES[@]} -gt 0 ]]; then
+        auto_create_databases "$wt_path"
+    fi
+
+    # --- Step 7: Install dependencies ---
     local pkg_mgr=$(detect_pkg_manager "$wt_path")
     if [[ -n "$pkg_mgr" ]]; then
         info "Detected package manager: $pkg_mgr"
@@ -185,6 +725,7 @@ cmd_create() {
         success "Dependencies installed"
     fi
 
+    # --- Step 8: Summary ---
     echo ""
     success "Worktree ready!"
     echo ""
@@ -197,10 +738,8 @@ cmd_list() {
     info "Worktrees for: $REPO_NAME"
     echo ""
 
-    # Get all worktrees
     local found=0
     while IFS= read -r line; do
-        # Parse worktree output (format: "path HEAD branch")
         local wt_path=$(echo "$line" | awk '{print $1}')
         local wt_branch=$(echo "$line" | awk '{print $3}' | sed 's/\[//;s/\]//')
 
@@ -223,7 +762,6 @@ cmd_remove() {
     local branch="${1:-}"
     local delete_branch=false
 
-    # Check for --delete-branch flag
     if [[ "${2:-}" == "--delete-branch" ]] || [[ "${2:-}" == "-d" ]]; then
         delete_branch=true
     fi
@@ -243,9 +781,23 @@ cmd_remove() {
         exit 1
     fi
 
+    # Stop Docker containers if compose setup exists
+    if [[ -f "$wt_path/.env" ]]; then
+        local compose_file_val=""
+        while IFS= read -r line; do
+            [[ "$line" =~ ^COMPOSE_FILE=(.+) ]] && compose_file_val="${BASH_REMATCH[1]}"
+        done < "$wt_path/.env"
+
+        if [[ -n "$compose_file_val" ]] && command -v docker &>/dev/null; then
+            info "Stopping Docker containers..."
+            (cd "$wt_path" && docker compose down 2>/dev/null) || warn "Could not stop containers (may not be running)"
+        fi
+    fi
+
     info "Removing worktree: $wt_path"
     git worktree remove "$wt_path" --force
     success "Worktree removed"
+    info "Note: databases are preserved — drop manually if no longer needed"
 
     if [[ "$delete_branch" == true ]]; then
         info "Deleting branch: $branch"
@@ -258,7 +810,6 @@ cmd_open() {
     local branch=""
     local editor=""
 
-    # Parse arguments
     while [[ $# -gt 0 ]]; do
         case "$1" in
             --cursor|-c)
@@ -299,7 +850,6 @@ cmd_open() {
         exit 1
     fi
 
-    # Priority: flag > WT_EDITOR env > auto-detect
     if [[ -z "$editor" && -n "${WT_EDITOR:-}" ]]; then
         editor="$WT_EDITOR"
     fi
@@ -312,7 +862,6 @@ cmd_open() {
         info "Opening in $editor: $wt_path"
         "$editor" "$wt_path"
     else
-        # Auto-detect: Cursor → Antigravity → VS Code
         if command -v cursor &>/dev/null; then
             info "Opening in Cursor: $wt_path"
             cursor "$wt_path"
@@ -336,7 +885,7 @@ cmd_help() {
     echo "Usage: wt <command> [args]"
     echo ""
     echo "Commands:"
-    echo "  create, c <branch>     Create worktree, copy .env files, install deps"
+    echo "  create, c <branch>     Create worktree with isolation (env, docker, db)"
     echo "  list, ls               List all worktrees for current repo"
     echo "  remove, rm <branch>    Remove worktree (add -d to delete branch too)"
     echo "  open, o <branch>       Open worktree (flag > WT_EDITOR > auto-detect)"
@@ -346,6 +895,17 @@ cmd_help() {
     echo "Environment:"
     echo "  WT_EDITOR              Default editor (cursor, agy, code)"
     echo ""
+    echo "Isolation (.worktreeinclude):"
+    echo "  Auto-generated on first 'wt create' if missing."
+    echo "  Controls which files to copy and how to isolate services."
+    echo ""
+    echo "  Sections:"
+    echo "    (top)       Glob patterns for files to copy (e.g., .env*)"
+    echo "    [rewrite]   'auto' to suffix DB_NAME, DATABASE_URL, etc."
+    echo "                Use {{BRANCH}} for custom templates"
+    echo "    [docker]    'auto' to generate port-offset override"
+    echo "                'file=path' for custom compose file"
+    echo ""
     echo "Naming convention:"
     echo "  ~/code/project/              → main repo"
     echo "  ~/code/project--feat-auth/   → worktree for feat-auth branch"

package/packs/worktree/skills/worktree-manager/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: worktree-manager
-description: This skill should be used when the user mentions "worktree", "wt", "new branch workspace", "parallel development", "feature branch setup", "work on multiple branches", "separate workspace for branch", or wants to manage git worktrees for parallel feature development.
-version: 1.0.0
+description: This skill should be used when the user mentions "worktree", "wt", "new branch workspace", "parallel development", "feature branch setup", "work on multiple branches", "separate workspace for branch", "docker port conflict", "database isolation", "worktreeinclude", "env isolation", or wants to manage git worktrees for parallel feature development.
+version: 2.0.0
 ---
 
 # Git Worktree Manager Skill
 
-Manages git worktrees for parallel development with automatic environment setup.
+Manages git worktrees for parallel development with automatic environment isolation.
 
 ## Activation Triggers
 
@@ -17,14 +17,17 @@ This skill activates when the user:
 - Needs a "separate workspace for a feature"
 - Asks about "parallel development" setup
 - Wants to "set up a new branch workspace"
+- Has "docker port conflicts" between branches
+- Needs "database isolation" for parallel work
+- Asks about ".worktreeinclude" or "env isolation"
 
 ## Commands Reference
 
 | Command | Alias | Description |
 |---------|-------|-------------|
-| `/wt create <branch>` | `/wt c` | Create worktree with auto-setup |
+| `/wt create <branch>` | `/wt c` | Create worktree with full isolation |
 | `/wt list` | `/wt ls` | Show all worktrees |
-| `/wt remove <branch>` | `/wt rm` | Remove worktree |
+| `/wt remove <branch>` | `/wt rm` | Remove worktree (stops Docker first) |
 | `/wt open <branch> [--editor]` | `/wt o` | Open (--cursor\|-c, --agy\|-a, --code\|-v) |
 
 ## Naming Convention
@@ -36,23 +39,55 @@ Worktrees are created as siblings with `--` separator:
 ~/[PARENT_DIRECTORY]/[REPO_NAME]--[BRANCH_NAME]/   # worktree for [BRANCH_NAME]
 ```
 
+## Three-Layer Isolation
+
+### Layer 1: `.worktreeinclude` — File Selection
+
+Gitignore-style file at repo root controlling which untracked files to copy. Auto-generated with sensible defaults on first `wt create`.
+
+```ini
+.env*
+# apps/*/.env*
+
+[rewrite]
+auto
+
+[docker]
+auto
+```
+
+### Layer 2: `[rewrite]` — Env Var Isolation
+
+- **`auto`**: Suffixes DB_NAME, POSTGRES_DB, DATABASE_URL, COMPOSE_PROJECT_NAME with branch slug
+- **`{{BRANCH}}`**: Template placeholder for custom vars
+
+### Layer 3: `[docker]` — Docker Compose Override
+
+- Generates `docker-compose.worktree.yml` with port offsets
+- Sets `COMPOSE_FILE` and `COMPOSE_PROJECT_NAME` in `.env`
+- Auto-creates databases in running Postgres
+
 ## Auto-Setup Features
 
 When creating a worktree, the following happens automatically:
 
 1. **Branch handling**: Creates new branch or checks out existing (local/remote)
-2. **Env files**: Copies all `.env*` from root and nested directories
-3. **Package manager**: Detects bun/pnpm/yarn/npm from lockfiles
-4. **Dependencies**: Runs install at root (monorepo-aware)
+2. **File copying**: Copies files matching `.worktreeinclude` patterns
+3. **Env rewriting**: Suffixes database names and URLs with branch slug
+4. **Docker isolation**: Generates port-offset override, sets compose config
+5. **Database creation**: Creates database in running Postgres (idempotent)
+6. **Package manager**: Detects bun/pnpm/yarn/npm from lockfiles
+7. **Dependencies**: Runs install at root (monorepo-aware)
 
 ## Behavioral Expectations
 
 When user asks about worktrees or parallel development:
 
 1. Suggest using `/wt create <branch>` for new worktrees
-2. Explain the naming convention if they seem unfamiliar
-3. Mention the auto-setup features (env copying, dep install)
+2. Explain the three-layer isolation if they have Docker/database conflicts
+3. Mention `.worktreeinclude` for customizing which files are copied
 4. Show the `cd` command output for easy navigation
+5. Explain that `wt remove` stops Docker containers but preserves databases
 
 ## Example Interactions
 
@@ -60,9 +95,19 @@ When user asks about worktrees or parallel development:
 
 **Response**: Use `/wt create feature/auth` to create a parallel workspace. This will:
 - Create `project--feature-auth/` as sibling directory
-- Copy your `.env` files
+- Copy your `.env` files and rewrite DB names with `_feature_auth` suffix
+- Generate Docker port offsets so both worktrees can run simultaneously
 - Install dependencies
 
-**User**: "Show me my worktrees"
+**User**: "My worktrees are conflicting on port 5432"
+
+**Response**: The `.worktreeinclude` file's `[docker]` section handles this. With `auto` enabled, `wt create` generates a `docker-compose.worktree.yml` override that offsets all ports. Each worktree gets a deterministic offset based on the branch name. Run `docker compose config` to verify the merged ports.
 
-**Response**: Use `/wt ls` to list all worktrees for the current repo.
+**User**: "How do I customize which files are copied to worktrees?"
+
+**Response**: Edit `.worktreeinclude` in your repo root. It uses gitignore-style patterns:
+```
+.env*
+config/local.yml
+apps/*/.env*
+```