4.4 KiB
| name | description |
|---|---|
| using-git-worktrees | Ensure feature work happens in an isolated workspace before it starts - detects existing isolation, creates a git worktree or native isolated workspace, sets up the project, and verifies a clean baseline. Use before executing an implementation plan or starting anything that should not disturb the current working tree. Triggers: start a new feature, work on this separately, set up a branch for this, isolate this work, spin up a worktree. |
Ensure work happens in an isolated workspace. Prefer this environment's native worktree/branch tools if any exist. Fall back to manual git worktrees only when no native tool is available.
Core principle: detect existing isolation first, then use native tools, then fall back to git. 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 whether you're 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," check git rev-parse --show-superproject-working-tree — if it returns a path, you're in a submodule, treat as a normal repo.
If GIT_DIR != GIT_COMMON (and not a submodule): you're already in a linked worktree — skip to Step 2. Report: "Already in isolated workspace at <path> on branch <name>" (or note detached HEAD, externally managed, if applicable).
If GIT_DIR == GIT_COMMON (or in a submodule): normal repo checkout. If the user hasn't already stated a worktree preference, ask for consent:
"Would you like me to set up an isolated worktree? It protects your current branch from changes." If declined, work in place and skip to Step 2.
Step 1: Create Isolated Workspace
1a. Native tools (preferred): if this environment already provides a way to create an isolated workspace/worktree (a tool, command, or flag), use it and skip to Step 2. Native tools handle directory placement, branch creation, and cleanup automatically — using raw git worktree add when a native tool exists creates phantom state the harness can't see or manage.
1b. Git worktree fallback (only if no native tool exists):
Directory selection priority: 1) any directory preference the user has already stated, 2) an existing project-local worktree directory (.worktrees preferred over worktrees if both exist), 3) default to .worktrees/ at the project root.
Safety check: git check-ignore -q .worktrees (or worktrees) — if NOT ignored, add to .gitignore and commit that change first.
Create it:
path="$LOCATION/$BRANCH_NAME"
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"
Sandbox fallback: if git worktree add fails with a permission error, tell the user the sandbox blocked worktree creation and that you're working in the current directory instead; run setup/baseline tests in place.
Step 2: Project Setup
Auto-detect and run appropriate install: npm install (package.json), cargo build (Cargo.toml), pip install -r requirements.txt / poetry install (Python), go mod download (go.mod).
Step 3: Verify Clean Baseline
Run the project's tests. If they fail, report failures and ask whether to proceed or investigate first. If they pass, report ready:
Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>
Common Mistakes
Fighting the harness (using raw git worktree when native isolation exists). Skipping detection (creating a nested worktree inside an existing one). Skipping ignore verification (worktree contents get tracked). Assuming directory location instead of following the priority order. Proceeding with failing tests without asking.
Red Flags
Never: create a worktree when Step 0 already detects isolation, use raw git worktree commands when a native tool is available, skip straight to 1b without checking 1a, create a project-local worktree without verifying it's gitignored, skip baseline test verification, proceed with failing tests without asking. Always: run Step 0 detection first, prefer native tools, follow the directory priority order, verify gitignore for project-local worktrees, auto-detect and run project setup, verify a clean test baseline.