multi-agent-worktree-discipline

Multi-Agent Worktree Discipline

Why this skill exists

When several agents share one repository through git worktrees, the expensive failures are not merge conflicts — they are silent ones: an agent redoes work that exists uncommitted in another worktree, a lockfile reinstall wipes an uncommitted dependency, a branch switch strands edits, a resumed session pushes with the wrong GitHub account, or a "fixed" build was actually run against the wrong Node version. Each of these costs an hour or more and looks like a mystery until you know the pattern. This skill is the checklist and the recovery protocols.

1. Session bootstrap (run before doing anything else)

1. Identify where you are. Run git worktree list and git rev-parse --show-toplevel. Confirm which worktree you are in and which branch it has checked out. Never infer location from the path string — on case-insensitive filesystems (macOS default) ~/repos/x and ~/Repos/x are the same directory, and per-agent worktrees often live under hidden dirs (.codex/, .cursor/, .claude/worktrees/, ~/.agents/worktrees/).
2. Pin the toolchain per command, not per session. Agent shells frequently resolve a different runtime than the repo expects (.nvmrc, rust-toolchain, etc.) because the sandbox PATH is built before version managers run. If the repo pins a version, export the pinned toolchain's bin dir onto PATH inside every shell invocation (shell state may not persist between calls). Symptom of getting this wrong: test runners dying with module-format errors (ERR_REQUIRE_ESM), not a clear version message.
3. Install dependencies from the lockfile. Fresh worktrees lack gitignored artifacts: node_modules, .env.local, build caches. If the repo has a worktree-setup script, run it. Otherwise install with the lockfile-respecting command (npm ci, pnpm install --frozen-lockfile) — plain npm install can rebuild optional native bindings incorrectly and mutate the lockfile.
4. Beware symlinked/shared node_modules. Some worktrees symlink node_modules to the primary checkout to save disk. That means: (a) installing in one place affects all of them, and (b) a build failure like Cannot find module 'x' usually means broken worktree resolution or a stale build cache (.next, dist) — fix the link and clear the cache; do not add duplicate dependencies or edit app code to route around it.
5. Verify your push identity. Run gh auth status (and git config user.email). Session resume and multi-account setups can silently switch the active account to one that cannot create PRs (e.g. an enterprise-managed account). Switch back explicitly (gh auth switch --user <name>) before any push or PR.