isolate

SKILL.md

Isolate

Create a worktree branched from the latest origin/main so task work never starts on stale code.

Announce: "Setting up an isolated worktree for this task."

Inputs

Branch name: from /orient Step 1 (e.g., feat/auth, fix/login-crash). Ask if not provided.

Base ref: the current branch's parent (detected via reflog, default main). Override only when explicitly stacking on a different branch.

Detect parent branch

The parent branch (what this branch will eventually merge into) is determined from the reflog:
PARENT_BRANCH=$(
  git reflog show HEAD --pretty=format:'%gs' \
    | grep "^branch: Created from" \
    | head -1 \
    | sed 's/branch: Created from //' \
    | sed 's|^origin/||'
)
PARENT_BRANCH=${PARENT_BRANCH:-main}

Returns empty when the branch was created from a detached HEAD or in a web session with no reflog — falls back to main. Correct 99% of the time for normal local development.

Already in a Worktree?

If the session CWD is already inside a linked worktree (not the primary), freshen the branch instead of creating a new one:

WORKTREE="<absolute-path-to-current-worktree>"
git -C "$WORKTREE" fetch origin "$PARENT_BRANCH"
git -C "$WORKTREE" merge "origin/$PARENT_BRANCH"

If conflicts arise, stop and present them to the user. Do not auto-resolve.

After freshening, skip ahead to Baseline test.

Step 1: Select directory

Priority
Check
Action

1
.worktrees/ exists
Use it

2
worktrees/ exists
Use it

3
Both exist
.worktrees/ wins

4
CLAUDE.md specifies
Follow preference

5
None found
Ask user (.worktrees/ recommended)

Step 2: Verify gitignored

git check-ignore -q .worktrees

If NOT ignored, fix before proceeding:

echo ".worktrees" >> .gitignore
git add .gitignore
git commit -m "chore: gitignore worktree directory"

Step 3: Fetch and create

A worktree branched from a stale local parent means baked-in merge conflicts. Always fetch first, always branch from origin/$PARENT_BRANCH (not the local copy).

REPO_ROOT="$(git rev-parse --show-toplevel)"
WORKTREE_DIR="$REPO_ROOT/.worktrees/<name>"

git fetch origin "$PARENT_BRANCH"
git worktree add "$WORKTREE_DIR" -b <prefix>/<name> "origin/$PARENT_BRANCH"

Lock the worktree immediately so git worktree prune doesn't sweep it during long-running agent sessions. Run from the main repo context (not the worktree):

git -C "$REPO_ROOT" worktree lock --reason "Agent session in progress" "$WORKTREE_DIR"

/ship will unlock before removing the worktree at the end of the task.

Claude Code: optionally call EnterWorktree({path}) to move session CWD into the new worktree.

Step 4: Install dependencies

Auto-detect from manifest files:

File
Command

pnpm-lock.yaml
pnpm install

yarn.lock
yarn install

package-lock.json
npm install

package.json (no lockfile)
Ask before installing

Cargo.toml
cargo build

requirements.txt
pip install -r requirements.txt

pyproject.toml
poetry install

go.mod
go mod download

Run from the worktree path: pnpm --dir "$WORKTREE_DIR" install

Step 5: Baseline test

Run the project's test suite. If tests fail, report failures and ask whether to proceed. Do not silently continue.

Report

Worktree ready at <absolute-path>
Branch: <prefix>/<name> (from origin/main @ <short-sha>)
Tests: <N> passing

Path Discipline

cd does not persist between Claude Code Bash calls. Use absolute paths for all file operations and git -C <abs-path> for git commands.

Integration

Called by: /task (Step 2), /brainstorming, /build
Pairs with: /ship (cleans up worktree after work is done)
1d