Using Git Worktrees

When to use

• Skip creating a workspace when the user explicitly says to stay, when the project's written policy says to stay (Step 1.6), or when Step 1 confirms a linked worktree owned by this task or the harness. Reuse the workspace you are in and its baseline record, and keep making Step 5 checkpoints.
• Skip read-only work.

Available scripts

• scripts/worktree-state.sh — reports checkout isolation, submodule status, dirty state, base resolution, branch collisions, and .worktrees/ ignore status as JSON.

Step 1: Detect what you are in

Open assets/workspace-record.md before the first command. Fill each section as its step runs.

1. Run bash scripts/worktree-state.sh to inspect toplevel, git_dir, common_dir, linked_worktree, submodule_superproject, detached, dirty, and worktrees.
2. Read submodule_superproject first: inside a submodule the two directories match even though there is no linked worktree.
3. If the checkout is detached or host-owned and its owner is unknown, do not nest, attach, switch, or clean it.
4. Write every resource and every dirty change into the record's Inventory section, under whoever created it. Never stash dirty state you do not own.
5. If the planning happened in another workspace, rerun 1 before the first product edit.
6. If the project's agent instructions file or contribution rules say in writing to work in the current checkout, record the file and the quoted line as Isolation kind, keep the inventory from 4, and skip creation as you would for a user's okay: work on the branch that is checked out, and never cut or switch a branch in it. The line must name the current checkout or rule out a worktree; a line about bases, branch names, or commits is not one, and nothing in the checkout's state is. With no such line, no user okay, and no owned linked worktree, continue to Step 2.

Step 2: Prove the base

1. Take the base from direct user or project guidance. With none, the base is the current branch this task started from. On a detached HEAD, or when the guidance conflicts, ask and stop. With network authority, run git fetch origin "$BASE" (otherwise record "not fetched"), then run bash scripts/worktree-state.sh --base "$BASE" and record base.local_sha and base.remote_sha.
2. 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}}. Run bash scripts/worktree-state.sh --check-branch "$BRANCH"; if it exits 1 (valid_format is false or a local or remote branch exists), pick another name. Never overwrite or reuse an existing branch.
2. Pick the mechanism, taking the first that applies: a user instruction; then project guidance; then a harness-native worktree command, run with the name above and HEAD at the proven base, after which skip to Step 4; then the steps below. A harness-native command acts on the session's own repository: if the work is in another repository, skip it, run the steps below from that repository, and say why the native command was not used.
3. Inside a submodule (submodule_superproject non-empty), stop here: create an owned branch in the submodule and write an explicit plan for the parent gitlink, and never run the rest of Step 3 from the superproject's paths. Otherwise set root to main_checkout_root and common_dir to Step 1's common_dir, and choose the directory (dir=".worktrees" unless the user gave a path) under root. If main_checkout_root is null (a bare repository or separate git directory), ask where the worktree goes and stop.
4. If worktrees_dir_ignored is false (or git -C "$root" check-ignore -q "$dir/" fails for a custom dir), exclude the directory locally with printf '%s/\n' "$dir" >> "$common_dir/info/exclude"; that is the whole change. Never add {{dir}}/ to .gitignore in any checkout: authority to commit locally covers task checkpoints, not a project change nobody requested.

5. Create from the proven base and enter:

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

6. If worktree add or cd fails on a sandbox or permission boundary, try a path the boundary allows, confirmed with the user. If none works, report and stop; never edit the shared checkout instead.

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 after setup. If the baseline has a failing check (a red cell) you cannot attribute, or left an effect you did not contain, stop work.
4. Hand the completed record to whatever invoked this skill.

Pressure points

Step 5: Checkpoint while you work

1. After each coherent piece a reviewer could accept or reject separately: REQUIRED SUB-SKILL: invoke verification-before-completion, run its smallest real check, and commit locally under the recorded authority, staging only the paths this task changed.
2. When the work on the branch is 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.

Gotchas

• Read references/checkpointing.md before the first commit: it defines the unit of a checkpoint, how to stage one by path, and what git commit does not grant.
• A check written during planning lands on whatever branch the shared checkout is on.
• A policy line that okays the current checkout grants only that; local commits still need their own line or the user's answer under Step 5.
• A branch a harness-native command cuts from a remote ref can still track it; git status --short --branch printing ...origin/{{base}} on the new branch is the sign. Unset the upstream before the first checkpoint.