git-worktree-isolation

Isolate code-editing subagents in separate git worktrees to prevent build and commit races.

2|Updated Aug 2, 2026
One-click install
npx skills add https://github.com/Arasz/ai-raccoon --skill git-worktree-isolation-arasz
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: git-worktree-isolation
Source: https://github.com/Arasz/ai-raccoon/tree/main/.ai-badger/skills/learned/uncategorized/git-worktree-isolation
Command: npx skills add https://github.com/Arasz/ai-raccoon --skill git-worktree-isolation-arasz

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Running multiple AI coding agents in the same directory causes dotnet build failures from shared obj/ folders, file modification races, staged-file collisions in shared commits, and detached-HEAD push failures. This Skill provides verified operational rules for isolating each subagent in its own git worktree and recovering from the failure modes that appear when worktrees are shared. ## Core Features & Use Cases - Worktree isolation workflow: Create per-subagent worktrees with git worktree add, merge results back with fetch/merge, and clean up with git worktree remove. - Race and pitfall recovery: Diagnose and repair staged-file leaks across parallel lanes, detached HEAD states, vanished worktrees, patch-tool writes landing in the main checkout, and red origin/main merges. - Verification gates: Confirm commits with git show --stat HEAD, verify pushes with git rev-parse, and prove pre-existing test failures using throwaway base-commit worktrees. - Use Case: An orchestrator dispatches three parallel implementation subagents into one task worktree with disjoint file sets; each lane commits only its own paths using the pathspec commit form, and the orchestrator reviews at the seams before merging. ## Quick Start Dispatch each code-editing subagent into its own git worktree created with git worktree add, and verify every commit with git show --stat HEAD before merging it back.

Frequently Asked Questions about git-worktree-isolation

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run parallel AI coding agents without conflicts?

Give each subagent its own git worktree created with git worktree add, never the orchestrator's directory. Parallel subagents can share one task worktree only when the plan assigns each a disjoint file set, with commits made per package using the pathspec commit form.

How do I create a git worktree for a subagent?

Run git worktree add -b <branch> <path> <base> so the worktree starts on a real branch. Using a remote ref like origin/<branch> without -b creates a detached HEAD where commits land on no branch and git push fails.

Why does dotnet build fail when two agents share a directory?

Shared obj/ directories across concurrent builds cause MSB3492 errors and stale build states. Isolate each agent in its own worktree, and if a build fails with MSB3492, remove obj/ folders and rebuild only when no other build is running.

Why did my git commit include another agent's files?

git commit captures the whole index, so another lane's staged files ride into your commit. Check git diff --cached --name-only before committing, commit only your paths with git commit -m "msg" -- <paths>, and verify with git show --stat HEAD afterward.

Can git worktrees disappear while I am using them?

Yes, another session's git worktree remove or prune can delete a worktree you created, including its directory. Re-check git worktree list before relying on a path and re-create the worktree as needed rather than assuming it survives across turns.

How do I prove a test failure existed before my changes?

Create a throwaway worktree at the base commit with git worktree add /tmp/base-check <base-sha>, run only the failing tests there, then remove it. An identical failure at base proves the issue is pre-existing fixture drift rather than your diff.