Isolate

---
name: isolate
description: "Start work in a fresh git worktree branched from the remote default branch, so parallel agents never share a tree. Use before the first edit of any feature, fix or task, and whenever a repo has more than one session working in it."
when_to_use: "Invoked when the user says \"isolate\", and automatically as step 1 of the spine, before any edit."
allowed-tools: Bash, Read, Grep, Glob
model: opus
user-invocable: true
argument-hint: "[slug]"
---

# Isolate

One tree per task. The failure this prevents has no error message: two agents in
one working copy overwrite each other's edits, and git reports nothing, because
from git's side the second write is just the current state of the file.

## Resolve the remote default first

Read `git ls-remote --symref origin HEAD`, fetch the corresponding branch and
set `AUTODEV_BASE_REF` to its verified remote-tracking ref. Do not assume it is
`origin/main`. If the remote is unavailable, use a verified local base appropriate
to this task and name the freshness limit.

## Before creating anything, check nobody is already on it

```bash
git ls-remote --heads origin
gh pr list --state all --limit 30
```

Two commands, seconds each. A branch that already exists under the name you were
about to create is the cheapest possible warning that someone is on the same
problem. Read that branch before renaming around it, and if the work is
duplicated keep the better implementation rather than yours.

**But a branch name is not evidence about its content.** Test whether its commit
is an ancestor of the default branch, and run a control so a uniform answer
cannot pass as a finding:

```bash
git merge-base --is-ancestor origin/<branch> "$AUTODEV_BASE_REF"   # exit 0 = already landed
git merge-base --is-ancestor "$AUTODEV_BASE_REF" "$AUTODEV_BASE_REF"       # positive control, expect 0
```

`[measured 2026-09-02]` a branch named `fix/always-on-without-a-trigger` was the
only match for a search about skill triggers. It had already landed, and its tip
commit was a telemetry path fix. The name matched the search and nothing else
did.

### Neither command above can see unpushed work

Both read the REMOTE. Where commits stay local until someone says push, which is
the default in this estate, the normal state of work in progress is invisible to
both. So the scope check as written is blind to precisely the case it exists for.

Add the local probe, and run it against the repo's MAIN CLONE rather than your
own tree, because that is where another session's finished-but-unpushed work
sits:

```bash
git -C <main-clone> rev-list --left-right --count "$AUTODEV_BASE_REF...HEAD"
git -C <main-clone> log --oneline "$AUTODEV_BASE_REF..HEAD"
git -C <main-clone> status --porcelain
```

The first prints `behind<TAB>ahead`. A non-zero right-hand number means finished
work exists that no worktree cut from `origin/main` can see, including yours.
The third says whether someone is still typing in it.

`[measured 2026-09-03]` two sessions wrote the same layout gate for one repo
within an hour. The remote showed nothing, because the first session's gate AND
its fix for the underlying defect were committed locally and never pushed: six
commits ahead, zero behind. From any worktree the defect still looked open, and
the second session's evidence that "it does not exist" was correct about
`origin/main` and wrong about the repo.

Nothing surfaced it. The two sessions found out because one sent the other an
unsolicited message about a patch, and the reconciliation took four exchanges
because the first quoted line numbers without naming a ref. A tracked file has
as many current values as there are checkouts.

**Two habits follow, and the second is the one that generalises.** Name the ref
in any claim about a file, so "line 1867" becomes "line 1867 of local main at
87f1ce7f". And re-fetch before you ACT, not before you send: that same
measurement was two commits stale by the time it was read, because the clone was
being actively worked while the message sat in a queue.

## Create the tree

```bash
git fetch origin
git worktree add .claude/worktrees/<slug> -b <slug> "$AUTODEV_BASE_REF"
```

Branch from the **remote** default branch, not from local `main`, which may be
behind or may carry another session's uncommitted work.

**Unless your work sits on unpushed local commits.** Then branch from `HEAD` and
say so, because `origin/main` does not contain them and the tree would silently
start without what you are building on. One command decides it:

```bash
git log --oneline "$AUTODEV_BASE_REF..HEAD"
```

These are candidate local dependencies, not automatic authority to include them.
Read their scope and start from the exact needed commit only when this task
builds on it. Otherwise use the fetched remote default and reconcile overlap.
No local commits are lost merely by creating a different worktree.

`.claude/worktrees/` is the convention because it is gitignored, so the trees
never appear as untracked files in the parent clone.

## A fresh worktree is not a working checkout

`git worktree add` copies the tracked tree and nothing else. Two things are
missing and both fail in ways that look like a bug in your change:

- **Required local configuration.** Identify the variables/files this task's
  development target needs. Reuse the project's approved secret/config mechanism
  or copy only the necessary same-project local files into the isolated tree.
  Keep them ignored and do not print values. Do not import production targets
  merely because a sibling env file exists. Missing configuration is a setup
  gap, not evidence the implementation is broken.
- **`node_modules`, but only if the repo has dependencies.** A worktree cut from
  an older base, or reusing the parent's install, surfaces import errors for
  dependencies added since. Count them before installing: a repo with zero deps
  needs no install, and running one anyway is a minute spent per worktree.

Verify required local configuration through the application’s safe startup/check
without printing values. An env-file count does not prove configuration is
present or missing: the project may inject it through a secret manager.

## Never touch a tree you did not create

Do not `git checkout` in a clone another session is using. Run `git status`
first: a dirty tree you did not dirty means someone is in there, and a checkout
carries their uncommitted work onto your branch without warning them.

The same applies to another agent's worktree, its branch, and its uncommitted
work. If you need what is on it, read it; do not switch into it.

## When to skip this

One checkout, one session, one-line change. The threshold is whether anyone else
could be in the tree while you work, not how large the change is.

If you skip it, say so. A step skipped and named is a decision; a step skipped
silently is indistinguishable from one forgotten.

## Finish by removing it

```bash
git worktree remove .claude/worktrees/<slug>
git worktree list
```

Only after the branch is merged or the work is deliberately abandoned, and
required ignored evidence, reports and resume state have a surviving recovery
path. Check untracked files as well as git status for tracked edits. A clean
index does not mean the directory is disposable. A stale worktree holds
a branch checked out, so the next session that tries to use that branch gets a
refusal it has no context for.