make-worktree

Per Claude Code convention, worktrees live inside the repo at .claude/worktrees/<task_id>/ and use a branch named task/<task_id>.

When to invoke

Before any operation in repos/<repo_name>/ that mutates state:

• git commit
• git checkout
• file edits (Write, Edit)

Read-only operations (Read, Grep, Glob) do not need a worktree.

Setup

# 1. Create the worktree from the primary checkout
REPO_NAME="<repo_name>"
cd repos/$REPO_NAME
mkdir -p .claude/worktrees
git worktree add .claude/worktrees/<task_id> -b task/<task_id>

# 2. Compute canonical absolute roots
cd .claude/worktrees/<task_id>
WORKTREE_ROOT=$(pwd -P)                   # canonical absolute worktree root
PRIMARY_ROOT=$(cd ../../.. && pwd -P)      # canonical absolute primary checkout root
echo "WORKTREE_ROOT=$WORKTREE_ROOT"
echo "PRIMARY_ROOT=$PRIMARY_ROOT"

# 3. Locate the guard script — delivered alongside this skill file.
#    The skill is linked under BOTH .claude/skills/make-worktree/
#    and .agents/skills/make-worktree/ for every executor.
#    The workspace root is 5 parents above the task worktree
#    (<workspace>/repos/<repo>/.claude/worktrees/<task_id>):
WORKSPACE_ROOT=$(cd "$WORKTREE_ROOT/../../../../.." && pwd -P)
#    The primary checkout root is 3 parents above the task worktree
#    (<primary>/.claude/worktrees/<task_id> → cd ../../.. → <primary>):
GUARD="$WORKSPACE_ROOT/.claude/skills/make-worktree/worktree_guard.py"
if [ ! -f "$GUARD" ]; then
    GUARD="$WORKSPACE_ROOT/.agents/skills/make-worktree/worktree_guard.py"
fi
if [ ! -f "$GUARD" ]; then
    echo "ERROR: Cannot locate worktree_guard.py in .claude/skills/ or .agents/skills/" >&2
    echo "  Workspace root: $WORKSPACE_ROOT" >&2
    echo "  Expected at: .claude/skills/make-worktree/worktree_guard.py" >&2
    echo "  or:          .agents/skills/make-worktree/worktree_guard.py" >&2
    exit 2
fi

# 4. Activate the worktree-root guard — this snapshots the primary checkout
#    state so later steps can detect accidental primary-checkout edits.
python "$GUARD" setup \
    --worktree-root "$WORKTREE_ROOT" \
    --primary-root "$PRIMARY_ROOT" \
    --task-id "<task_id>"

# 5. All subsequent repo commands MUST use $WORKTREE_ROOT:
#    cd "$WORKTREE_ROOT"
#    scripts/local_ci.sh all  # lint/static only; daily E2E is separate (THR-291 seq69)
#    git -C "$WORKTREE_ROOT" diff --stat

After setup, absolute repos/<repo>/... paths are FORBIDDEN.
Every Read, Write, Edit, grep, glob, git, and test command that touches
repo files MUST use $WORKTREE_ROOT (the worktree path) or a relative
path rooted at the worktree. The canonical primary checkout root
$PRIMARY_ROOT contains the repos/<repo>/ path — that surface is the
source of every known false-green verification incident. Use of the
primary-checkout path that results in a guard failure on verify will be
treated as a task defect.

Verify (before test, commit, and report)

Before running tests, committing, or reporting completion, verify that
no accidental primary-checkout edits have occurred:

python "$GUARD" verify --worktree-root "$WORKTREE_ROOT"

A successful verification prints GUARD PASS. A failure prints a loud
diagnostic naming the primary root, the task worktree root, every
changed primary-checkout path (categorized as tracked, staged, or
untracked), and preservation-first recovery instructions that use
safe git diff inspection and patch application — no destructive
git checkout, git reset, or rm commands are ever suggested.

The guard does NOT inspect the task worktree diff — a zero-diff task
passes when the primary checkout is unchanged. Edits in the task
worktree are expected and never falsely accused.

Repository Git process

Guard setup and verification do not configure Git hooks. setup also
self-heals the known stale mandatory pre-push-hook configuration in worktrees
created before the 2026-08-07 PR #607 change, printing a notice when it clears
that worktree's own injected configuration. Follow each repository's documented
Git-hook and publication-process requirements.
git push --no-verify remains prohibited by engineering policy, and GitHub CI
remains the authoritative clean-environment / matrix gate.

Concurrency

Two sessions on the same agent role may try to create different worktrees simultaneously. If git worktree add fails because of a stale lock, retry once after 1 second.

Temporary review, QA, and scratch worktrees

When a review, QA run, or diagnostic needs an additional disposable worktree,
never create temporary review or QA worktrees under /tmp. Put them beneath
the owning agent workspace so the existing registered-workspace cleanup
authority covers their bytes and concurrent agents cannot share a path:

SCRATCH_WORKTREES="$WORKSPACE_ROOT/.happyranch/scratch/worktrees"
mkdir -p "$SCRATCH_WORKTREES"
git -C "$PRIMARY_ROOT" worktree add "$SCRATCH_WORKTREES/<task-id>-<exact-sha>" <exact-sha>

Use the immutable commit SHA in both the directory suffix and git worktree add. If the workspace-owned directory cannot be created, stop with the error;
never fall back to /tmp. At the end of the review or QA run, remove only the
exact registered worktree with git worktree remove <exact-path> after
checking its status. Do not infer cleanup eligibility from a task-like name or
Unix ownership.

Cleanup

Before the final completion callback — including blocker/error paths — assess
the exact task-owned worktree. Preserve it when it is dirty, staged, untracked,
committed but not present in a durable remote ref, associated with an open or
closed-unmerged PR,
still referenced by a live session/control/process/fd, explicitly deferred, or
when any identity, ownership, probe, or deadline fact is unavailable or
uncertain. Do not infer eligibility from a task-like directory name.

Only after every preservation check succeeds, change to the primary checkout
and remove that exact registered path without force:

cd repos/<repo_name>
git worktree remove .claude/worktrees/<task_id>

Never delete the task branch. If a preservation check fails or removal returns
nonzero, leave the worktree and branch intact and add
worktree-deferred: <specific reason> to the completion report's
risks_flagged. Make one bounded attempt only; do not schedule or perform a
retry, force removal, historical scan, prune, or cache sweep.

Later root-terminal reconsideration

A maker deferral preserves this task-owned worktree and must remain in the
completion risks. After a future structural root reaches completed, failed,
cancelled or superseded, its runtime owner can reconsider canonical registered
worktrees in that parent tree. At that separate pass the old deferral is
advisory; fresh exact-HEAD preservation, clean/ownership/recursive safety,
current task/successor/job/host and unchanged same-user scanner evidence still
govern. Dirty, local-only, open, active, held, protected or unknown paths retain.
This grants the maker no extra deletion authority or historical sweep. The root
owner records stable committed audit identity, bounded frontier/remainder and
possible post-action anomalies; replay/missing finish never retries. Branches
remain. Manual/daily age/ordinal/peer/history/cache gates stay separate.