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 the checkout's state as JSON.
Step 1: Detect what you are in
Copy assets/workspace-record.md before the first command, to
.sdlc-skills/evidence/{{YYYY-MM-DD}}-{{topic}}/workspace-record.md. Fill each
section as its step runs.
- Run
bash scripts/worktree-state.shto inspecttoplevel,git_dir,common_dir,linked_worktree,submodule_superproject,detached,dirty, andworktrees. - Read
submodule_superprojectfirst: inside a submodule the two directories match even though there is no linked worktree. - If the checkout is detached or host-owned and its owner is unknown, do not nest, attach, switch, or clean it.
- 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.
- If the planning happened in another workspace, rerun 1 before the first product edit.
- 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
- 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 runbash scripts/worktree-state.sh --base "$BASE"and recordbase.local_shaandbase.remote_sha. Ifremote_shais set and differs, useorigin/$BASEasBASE; ask first when local is ahead. - Read
references/baseline-contract.mdbefore any install or baseline command.
Step 3: Create the workspace
Name it by project convention, or
feature/{{short-task}},fix/{{short-task}},docs/{{short-task}}. Runbash scripts/worktree-state.sh --check-branch "$BRANCH"; if it exits1(valid_formatisfalseor a local or fetched remote branch exists), pick another name. Never overwrite or reuse an existing branch.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.
Inside a submodule (
submodule_superprojectnon-empty), create an owned branch in the submodule, write an explicit plan for the parent gitlink, and go to Step 4; never run the rest of Step 3 from the superproject's paths. Otherwise setroottomain_checkout_rootandcommon_dirto Step 1'scommon_dir, and choose the directory (dir=".worktrees"unless the user gave a path) underroot. Ifmain_checkout_rootisnull(a bare repository or separate git directory), ask where the worktree goes and stop.If
worktrees_dir_ignoredisfalse(orgit -C "$root" check-ignore -q "$dir/"fails for a customdir), exclude the directory locally withprintf '%s/\n' "$dir" >> "$common_dir/info/exclude". Never add{{dir}}/to.gitignorein any checkout: authority to commit locally covers task checkpoints, not a project change nobody requested.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, cleanIf
worktree addorcdfails 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
- Claim distinct runtime identities (ports, databases, fixtures).
- Confirm
git rev-parse --show-toplevelprints the workspace path, then run project setup there by the project's own instructions. - Run the real baseline under
references/baseline-contract.mdafter setup. If the baseline has a failing check (a red cell) you cannot attribute, or left an effect you did not contain, stop work. - Hand the completed record to whatever invoked this skill.
Pressure points
| The thought | The reality |
|---|---|
| "I'll just inspect first" | For an edit request, checking the branch and status is the first inspection. |
| "It's only a small change" | Small changes still land on the wrong branch. Outside the exceptions above, create the branch first. |
| "The harness made a detached checkout, so I'll add my own worktree" | First determine whether the host already owns isolation and cleanup. |
| "I'll make the branch after the first edit" | After the edit, you may already have mixed unrelated state. |
| "It looks like a plain checkout" | Looking is not detecting. Comparing git_dir with common_dir, plus the superproject check, is the inspection. |
Step 5: Checkpoint while you work
- 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. Readreferences/checkpointing.mdbefore the first commit. - When the work on the branch is ready for integration: REQUIRED
SUB-SKILL: invoke
finishing-a-branchwith the recorded workspace, base, and ownership. Run no push, publish, integrate, discard, delete, history rewrite, or cleanup from this skill.
| The thought | The reality |
|---|---|
| "I'll commit once it all works" | One terminal commit cannot be reviewed or reverted in pieces, and every good intermediate state is gone. |
| "Nothing is finished, so there is nothing to commit" | The unit is an independently testable change, not a finished feature. If a check can accept it, it can be a checkpoint. |
| "I should ask before each commit" | Ask once per task when no policy covers local commits; the recorded answer covers every later checkpoint. Asking again re-decides what the user decided. |
| "The check is slow — I'll run it once at the end" | Then a failing check at the end leaves every change a suspect. The smallest check per checkpoint is what keeps that cheap. |
| "It passes locally, so committing can wait" | An uncommitted passing state is one crash, wrong checkout, or overwrite away from not existing. |
| "A mid-task commit looks unfinished" | It claims nothing. Nothing reads a checkpoint as done until finishing-a-branch runs. |
Gotchas
- 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 --branchprinting...origin/{{base}}on the new branch is the sign. Unset the upstream before the first checkpoint.