worktree-first

name	worktree-first
description	Isolate every feature branch in its own worktree; never share the root workspace.

Worktree-First Protocol

When This Applies

Any time you're about to start a new feature or fix that needs its own branch. If your next step is git checkout -b <newbranch> in a shared workspace, this protocol is mandatory.

The Rule

Create a worktree; never share the root workspace. The root worktree (the top-level repository directory) is a shared physical checkout — multiple concurrent sessions read from it and write to it. If you check out a feature branch in the root, every commit any other session makes in the root goes onto your branch, not the trunk.

Steps

1. Use the git_worktree tool. Not raw git checkout -b, not git worktree add from the shell — the tool wraps both and adds the safety checks (clean baseline, target dir git-ignored, trunk resolution). Pass:

   • path: ../<repo-name>-<feature-slug> — a sibling directory to the repo root, not a subdirectory of it. Sibling paths avoid gitlink-submodule confusion (git treats a linked-worktree directory inside the tracked tree as a submodule pointer, which creates persistent M entries in git status on the root as the worktree's HEAD advances). Example: for a repo at /git_repos/foo/Cercano, a good worktree path is /git_repos/foo/Cercano-runtime-dashboard.
   • branch: feat/<feature-slug> or fix/<feature-slug>.
   • trunk: the target trunk (usually main).

2. Do all work inside the worktree. Every cd, test run, edit, and commit lives in the isolated directory. The root stays on trunk, untouched.

3. Do not git checkout <branch> in the root worktree while your feature is active. If you need to look at trunk state, do it in the root (which is already on trunk). If you need to look at your branch, do it in the worktree.

Why This Exists

The root worktree is the default directory other sessions operate in when they touch the repo. If your feature branch is checked out there:

• Other agents committing "quick fixes" for unrelated tracks land on your branch instead of trunk.
• Any nested worktree left inside the tracked tree gets recorded as a submodule pointer whose HEAD keeps drifting — showing up as a persistent conflict every time you rebase. The sibling convention above sidesteps this entirely.
• Rebasing back onto trunk multiplies conflicts by every stowaway commit — each one carries its own worktree-pointer noise that has to be reconciled per commit.
• Rolling back is dangerous — other sessions may still be reading the checked-out working tree.

A worktree is one tool call to create with git_worktree. It isolates all of this at zero ongoing cost. Skipping the worktree to save one step now trades minutes for hours of rebase conflict resolution later.

What This Prevents

• Concurrent-modification hazards between agent sessions sharing the root
• Submodule-pointer conflicts on nested-worktree paths you never touched (avoided entirely by the sibling-directory convention above)
• Unrelated commits from other sessions accumulating on your feature branch
• "How did I end up with 14 commits I don't recognize?" investigations mid-rebase

Fast Path for Trivial Changes

For genuinely trivial changes — a typo, a label rename, a comment fix, a one-line copy tweak — the worktree ceremony is disproportionate. The fast path is:

• Applies to changes ≤ 5 lines across ≤ 2 files with no logic changes.
• Create a feature branch in the root with git checkout -b fix/<slug>. The worktree-first watchdog check is expected to fire here; overriding it is the fast-path escape valve, and the user is asked to authorize.
• Stage only your intended files with an explicit path list. Root may have other sessions' in-progress edits — never git add -A.
• Commit via the checkpoint tool.
• Land via git_land. The test gate and safety refs still run — the fast path saves worktree ceremony, not the safety guarantees.
• Delete the branch after landing.

The fast path is deliberately narrow. Anything with a logic change, a new file, or touching more than a couple of files goes through the full worktree flow. When in doubt: use the worktree.