working-in-isolation

Working in isolation

Before changing anything in a repository — code, docs, config, or other files — make sure your work lands somewhere it won't collide with existing or in-progress work. Decide the workspace based on the git state. When in doubt, pause and ask the user.

Decision: where does this work go?

Check the current state, then take the first matching rule:

git branch --show-current      # current branch
git status --porcelain         # empty = clean tree
git worktree list              # >1 entry = worktrees already exist

1. The user named a workspace (explicit command, or a configured preference) → follow it.
2. Dirty tree (staged or unstaged changes) OR worktrees already exist → a human or another agent is mid-work here. Use a new worktree so your changes can't collide with theirs.
3. On dev / main / master → sync with origin and create a new branch using the rule 3 command below. Keeps the base clean and makes the work easy to review.
4. On any other branch → work in place. The user already isolated this workspace; adding a worktree is needless ceremony.

Hard rule: never make changes while on dev / main / master. If you find yourself on a base branch, branch (rule 3) or worktree (rule 2) first.

Create a worktree (rule 2)

Prefer your harness's native Git worktree capability if it exists. The capability may be deferred or lazily loaded. Otherwise, fall back to a Git worktree:

git worktree add .worktrees/<branch-name> -b <branch-name>
cd .worktrees/<branch-name>

Keep the worktree out of version control: if .worktrees/ isn't already ignored by Git, add it to .gitignore and commit that first. If worktree creation fails (sandbox or permission limits), say so and fall back to checking out a branch in place (rule 3).

Create a branch (rule 3)

After syncing the base branch with origin, create the new branch from the current HEAD with no upstream tracking: