/ia-git-worktree

name: ia-git-worktree
class: tool
description: >-
  Manage Git worktrees for isolated parallel development. Use when creating,
  listing, switching, or cleaning up git worktrees, or when needing isolated
  branches for concurrent reviews or feature work.

Git worktree manager

**GATE: If the task runs inside an existing worktree (a worktree path is given and no create/remove/switch is requested), none of the creation flow applies: work in place and skip this skill.** To check: `git rev-parse --show-toplevel` appears as a linked entry in `git worktree list`.

Working rules

• Preserve other sessions' branches, files, and staged work (see Ownership).
• Verify dependencies resolve first-party code from the intended worktree.
• Keep merge, push, and cleanup within user authorization; report the exact exercised checkout and resulting commit.

Always use the manager script

Never call `git worktree add` directly; always use the `worktree-manager.sh` script.

The manager handles setup: 1. Copies `.env`, `.env.local`, `.env.test`, etc. from the main checkout, only when the base is the default branch or a local branch that already contains the fetched commit (a branch that exists only on `origin` gets none); it never overwrites or follows an existing file or symlink in the new tree 2. Ensures `.worktrees` is in the main checkout's `.gitignore` 3. Creates consistent directory structure 4. After creation, install dependencies if detected: `package.json` → `npm install`, `composer.json` → `composer install`, `pyproject.toml` → `pip install -e .`, `go.mod` → `go mod download`

**Untrusted bases (PR heads, fork or origin-only branches, third-party code):** create with `--no-env`, never `copy-env` into the tree, and keep credentials out of its commands. Skip installs; if needed, disable lifecycle scripts and plugins (`npm ci --ignore-scripts`, `composer install --no-scripts --no-plugins`) and never `pip install -e .`, which runs the build backend.

All commands use: `bash ${CLAUDE_PLUGIN_ROOT}/skills/ia-git-worktree/scripts/worktree-manager.sh <command>`. If `CLAUDE_PLUGIN_ROOT` is unset (non-Claude-Code harness), resolve the script relative to this skill's own directory.

Before creating worktrees, export a unique `WORKTREE_SESSION_ID` and retain that same value for this session's later manager calls. Example: `export WORKTREE_SESSION_ID="$(python3 -I -c 'import uuid; print(uuid.uuid4())')"`. The manager records ownership in each new worktree's Git metadata. Creation without a session ID works, but manager cleanup then refuses that tree; never adopt a previous session's ID to bypass ownership.

The manager script fetches `<base>` from `origin` into an invocation-private ref, resolves that commit, and creates the branch from its SHA, even when `origin/<base>` is absent or stale or another checkout fetches concurrently. It removes only its private ref and never checks out `<base>` in the caller's working tree. If the fetch fails (offline, no remote), it resolves the local `<base>` instead. PR review: pass the fetched PR head as `<base>`, then verify its SHA ([workflow-examples.md](./references/workflow-examples.md)). Details: [troubleshooting.md](./references/troubleshooting.md).

Commands

| Command | Description | Example | |---------|-------------|---------| | `create [--no-env] <branch> [from]` | Create worktree + branch (default: from main) | `...worktree-manager.sh create feature-login` | | `list` / `ls` | List all worktrees with status | `...worktree-manager.sh list` | | `switch <name>` / `go` | Print the registered worktree's absolute path; the caller applies it as workdir | `target=$(...worktree-manager.sh switch feature-login)` | | `copy-env <name>` | Copy .env files to existing worktree | `...worktree-manager.sh copy-env feature-login` | | `cleanup <name> [...]` / `clean` | Confirm removal of named, session-owned, clean worktrees | `...worktree-manager.sh cleanup feature-login` |

Run commands with `env -C "$target" <command>` or the harness workdir argument. A child script cannot change the caller's working directory. Listing and name resolution work from any main or linked checkout, including subdirectories.

Cleanup refuses the current checkout, another session's tree, and tracked, untracked, or ignored files. Auto-copied `.env` files and installed dependencies therefore require explicit user-managed disposition before cleanup. Confirm no process uses the named trees; the manager cannot detect every external reader. Git's normal removal safeguards remain enabled, including locked-tree refusal. Do not force deletion or suppress failures to finish cleanup.

Safety Verification

With a main checkout, verify `.worktrees` is ignored before creation:

# Verify .worktrees is ignored (should output ".worktrees")
git check-ignore .worktrees || echo "WARNING: .worktrees not in .gitignore"

If not ignored, add it to `.gitignore` before proceeding.

Before any baseline suite or migration, apply `ia-verification-before-completion`'s effective-target preflight. Resolve worktree environment/configuration overlays; verify disposable database and service targets, never the dev database. Copied `.env` files do not prove isolation. Without verified disposable targets, stop before tests. Then run the suite or its fastest relevant subset to establish a clean baseline before implementation.

Ownership

• One writer per worktree. Treat every `git worktree list` entry not created **in the current session** as read-only; a tree left from a previous round is not the current session's either. Reuse is most tempting exactly where it is most dangerous: an existing tree already has dependencies and env wired up, and another session may be running a suite in it.
• Do not mutate a tree while the current session's suite runs there. Test runners load source files as they reach them, so a mid-run edit produces a mass-failure result that looks exactly like a real regression.
• A failur