using-git-worktrees

name	using-git-worktrees
description	Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via git worktree

Using Git Worktrees

Overview

Ensure work happens in an isolated workspace using git worktrees.

Core principle: Detect existing isolation first. Ensure a remote exists. Then use git worktree. Never fight the harness.

Announce at start: "I'm using the using-git-worktrees skill to set up an isolated workspace."

Step 0: Detect Existing Isolation

Before creating anything, check if you are already in an isolated workspace.

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
BRANCH=$(git branch --show-current)

Submodule guard: GIT_DIR != GIT_COMMON is also true inside git submodules. Before concluding "already in a worktree," verify you are not in a submodule:

# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
git rev-parse --show-superproject-working-tree 2>/dev/null

If GIT_DIR != GIT_COMMON (and not a submodule): You are already in a linked worktree. Skip to Step 3 (Project Setup). Do NOT create another worktree.

Report with branch state:

• On a branch: "Already in isolated workspace at <path> on branch <name>."
• Detached HEAD: "Already in isolated workspace at <path> (detached HEAD, externally managed). Branch creation needed at finish time."

If GIT_DIR == GIT_COMMON (or in a submodule): You are in a normal repo checkout.

Has your human partner already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree:

"Would you like me to set up an isolated worktree? It protects your current branch from changes."

Honor any existing declared preference without asking. If your human partner declines consent, work in place and skip to Step 0.5.

Step 0.5: Ensure Remote Repository Exists

Check that the project has a remote configured. This check is idempotent — it runs each time this skill is invoked but only does meaningful work once (when no remote exists yet).

git remote get-url origin 2>/dev/null

If a remote already exists: Continue to Step 1.

If no remote exists (new project):

REPO_NAME=$(basename "$(git rev-parse --show-toplevel)")
gh repo create --private "$REPO_NAME" --source=. --remote=origin
git push -u origin main

Report: "Created private GitHub repo <name> and set as origin."

If gh is not available or the command fails: Note the failure — the project has no remote backup until this is resolved. Flag it for your human partner and continue anyway.

Step 1: Create Isolated Workspace

Use git worktree directly to create an isolated workspace.

Directory Selection

Follow this priority order. Explicit preference always beats observed filesystem state.

1. Check your instructions for a declared worktree directory preference. If one is specified, use it without asking.

2. Check for an existing project-local worktree directory:

   ls -d .worktrees 2>/dev/null     # Preferred (hidden)
   ls -d worktrees 2>/dev/null      # Alternative
   

   If found, use it. If both exist, .worktrees wins.

3. If there is no other guidance available, default to .worktrees/ at the project root.

Safety Verification

MUST verify directory is ignored before creating worktree:

git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

If NOT ignored: Add to .gitignore, commit the change, then proceed.

Why critical: Prevents accidentally committing worktree contents to repository.

Create the Worktree

# Determine path based on chosen location
# path="$LOCATION/$BRANCH_NAME"

git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

Sandbox fallback: If git worktree add fails with a permission error (sandbox denial), tell your human partner the sandbox blocked worktree creation and you're working in the current directory instead. Then run setup and baseline tests in place.

Step 3: Project Setup

Auto-detect and run appropriate setup:

# Node.js
if [ -f package.json ]; then npm install; fi

# Rust
if [ -f Cargo.toml ]; then cargo build; fi

# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi

# Go
if [ -f go.mod ]; then go mod download; fi

Step 4: Verify Clean Baseline

Run tests to ensure workspace starts clean:

# Use project-appropriate command
npm test / cargo test / pytest / go test ./...

If tests fail: Report failures, ask whether to proceed or investigate.

If tests pass: Report ready.

Report

Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>

Quick Reference

Situation	Action
Already in linked worktree	Skip creation (Step 0)
In a submodule	Treat as normal repo (Step 0 guard)
Remote already exists	Skip Step 0.5
No remote, gh available	Create private repo + push (Step 0.5)
No remote, gh unavailable	Flag for human partner, continue
.worktrees/ exists	Use it (verify ignored)
worktrees/ exists	Use it (verify ignored)
Both exist	Use .worktrees/
Neither exists	Check instruction, then default .worktrees/
Directory not ignored	Add to .gitignore + commit
Permission error on create	Sandbox fallback, work in place
Tests fail during baseline	Report failures + ask
No package.json/Cargo.toml	Skip dependency install

Common Mistakes

Skipping detection

• Problem: Creating a nested worktree inside an existing one
• Fix: Always run Step 0 before creating anything

Skipping ignore verification

• Problem: Worktree contents get tracked, pollute git status
• Fix: Always use git check-ignore before creating project-local worktree

Assuming directory location

• Problem: Creates inconsistency, violates project conventions
• Fix: Follow priority: existing > instruction file > default

Proceeding with failing tests

• Problem: Can't distinguish new bugs from pre-existing issues
• Fix: Report failures, get explicit permission to proceed

Red Flags

Never:

• Create a worktree when Step 0 detects existing isolation
• Create worktree without verifying it's ignored (project-local)
• Skip baseline test verification
• Proceed with failing tests without asking
• Skip Step 0.5 on a new project (remote backup matters)

Always:

• Run Step 0 detection first
• Run Step 0.5 to verify remote exists
• Follow directory priority: existing > instruction file > default
• Verify directory is ignored for project-local
• Auto-detect and run project setup
• Verify clean test baseline