Using Git Worktrees

Using Git Worktrees

Give every task its own checkout, prove the base it starts from, and write down what you found there before you change anything.

When to use

• You are about to edit files, implement a feature/fix/refactor, execute a plan, or dispatch agents.
• Runtime or review isolation matters: parallel agents, risky changes, separate ports, databases, fixtures, or long-running app state.
• Skip for read-only investigation, when the user explicitly says to stay in the current checkout, or when the current branch/workspace is already dedicated to this task with known ownership, base, and baseline.

Step 1: Detect what you are in

Open assets/workspace-record.md now. Fill each section as its step runs.

1. Run this. Do not judge the checkout from the prompt or the path name:

   git rev-parse --show-toplevel
   git status --short --branch
   git rev-parse --show-superproject-working-tree   # non-empty: you are in a submodule
   git_dir="$(cd "$(git rev-parse --git-dir)" && pwd -P)"
   common_dir="$(cd "$(git rev-parse --git-common-dir)" && pwd -P)"
   [ "$git_dir" != "$common_dir" ] && echo "already inside a linked worktree"
   git worktree list
   

2. Read the submodule line first: inside a submodule the two directories match without a linked worktree. Write down any harness-native workspace metadata.

3. Detached or host-owned checkout with unknown owner → do not nest, attach, switch, or clean it.

4. Write every resource and dirty change into the inventory: created by this task, or pre-existing/user-owned/shared/host-owned. Unknown → second column. It blocks switching and cleanup. Never stash dirty state you do not own.

5. Planning happened in another workspace → rerun 1 before the first product edit. Plan approval says nothing about code isolation.

Step 2: Prove the base

1. Take the base from direct user or project guidance. Record revision and remote freshness:

   git fetch origin "$BASE"          # only with network authority; otherwise record "not fetched"
   git rev-parse "$BASE" "origin/$BASE"
   

2. Record gate inputs outside the source tree (ignored, generated, external) in their own section.

3. Read references/baseline-contract.md before any install or baseline command.

Step 3: Create the workspace

1. Name it by project convention, or feature/{{short-task}}, fix/{{short-task}}, docs/{{short-task}}. Check collisions:

   git check-ref-format --branch "$BRANCH"
   git show-ref --verify --quiet "refs/heads/$BRANCH" && echo "local branch exists"
   git show-ref --verify --quiet "refs/remotes/origin/$BRANCH" && echo "remote branch exists"
   git worktree list | grep -F "[$BRANCH]"
   

   Anything prints → pick another name. Never overwrite or reuse.

2. Pick the mechanism, first that applies: user instruction → project guidance → harness-native worktree command or session flag (use the name above, confirm HEAD is the proven base, skip to Step 4) → a worktree you create below. Never git switch -c or git checkout -b in a shared checkout.

3. Choose the directory and prove it is ignored. User-given path wins.

   root="$(cd "$common_dir/.." && pwd -P)" && cd "$root"   # main checkout root, even from inside a linked worktree
   dir=".worktrees"
   [ -d "$root/worktrees" ] && [ ! -d "$root/.worktrees" ] && dir="worktrees"
   git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null || echo "NOT IGNORED"
   git check-ignore -q "$dir" || echo "$dir itself is not ignored"
   

4. Either line printed → do not edit .gitignore in the shared checkout. Exclude locally, then make adding {{dir}}/ to .gitignore the first commit on the task branch:

   printf '%s/\n' "$dir" >> "$(git rev-parse --git-common-dir)/info/exclude"
   

5. Create from the proven base and enter:

   path="$root/$dir/${BRANCH//\//-}"
   git worktree add "$path" -b "$BRANCH" "$BASE"
   cd "$path" && git status --short --branch   # expect: ## $BRANCH, clean
   

6. worktree add or cd fails on a permission or sandbox boundary → try a path the boundary allows and ask the user to confirm it. None works → report and stop. Never edit the shared checkout instead. Submodule → an owned branch and an explicit plan for the parent gitlink.

Step 4: Baseline it

1. Claim distinct runtime identities (ports, databases, fixtures).
2. Run project setup inside the worktree by the project's own instructions.
3. Run the real baseline under references/baseline-contract.md: pre-run inspection, pre/post capture, each red cell bound. Red cell you cannot attribute, or an effect you did not contain → stop work.
4. Hand the completed assets/workspace-record.md to whatever invoked this skill: identity, inventory, external gate inputs, baseline evidence and side effects, runtime identities, task-owned resources.

Pressure points

Step 5: Checkpoint while you work

1. After each coherent piece a reviewer could accept or reject separately: REQUIRED SUB-SKILL: invoke verifying-completion, run its smallest real gate, commit locally. Do not wait for the final candidate. Do not ask per checkpoint. Withhold only when direct user or project policy withholds.
2. Candidate ready for integration → REQUIRED SUB-SKILL: invoke finishing-a-branch with the recorded workspace, base, and ownership. Run no push, publish, integrate, discard, delete, history rewrite, or cleanup from this skill.