isolation:\"worktree\", or while another subagent is in flight, to avoid three dispatch hazards — file-scope overlap with an in-flight subagent, a stale dispatch base, and collisions with another live agent/session editing the same checkout or git-submodule path. Invoke when about to call the Agent tool with isolation:\"worktree\"; when another subagent is running; right after a merge or branch switch; or when another Claude session is editing a shared repo/submodule path. Does NOT cover PR / merge mechanics (github-contribution-workflow) or post-commit diff sanity (pr-diff-verification).'\nallowed-tools: Bash(git worktree *) Bash(git status *) Bash(git log *) Bash(git rev-parse *) Bash(git merge-base *)Claude Code's own isolation primitives are the Subagents feature (\"each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions\") and isolation:\"worktree\"'s base-branch selection. Neither one checks whether a NEW dispatch's file scope overlaps an in-flight one, or whether the worktree base is stale — that pre-flight discipline is what this skill adds on top.
references/official-docs.md.Before dispatching a new subagent via the Agent tool — especially with isolation: \"worktree\" — if ANY other subagent is currently running or has an active worktree.
Trigger phrases / situations:
\nAgent tool when git worktree list shows non-main worktrees[in_progress] tasks in TaskList that involve subagent workSkip when: dispatching the first subagent in a session, or all prior subagents have completed AND their worktrees are cleaned/merged.
\ngit worktree list --porcelain | grep '^worktree ' | cut -d' ' -f2- | tail -n +2\nPlain git worktree list is fine for a human to eyeball, but don't parse it: filtering\non [main] breaks when the default branch isn't named main, and splitting on\nwhitespace breaks on a path containing a space — cut -d' ' -f2- keeps everything after\nthe first space instead of splitting on every space, so it doesn't have that problem.\n--porcelain sidesteps the [main]-name issue — tail -n +2 drops the first\n(main-checkout) worktree line. For each remaining worktree path,\ncapture:
(cd <path> && git status --short)(cd <path> && git log -1 --format=%s)Expect one permission prompt per worktree for these two checks, whichever form you write\nthem in. Per the permissions docs, a Bash\nrule \"must match each subcommand independently\"; git -C <path> status is a different\ninvocation form that Bash(git status *) doesn't match; and cd combined with git\n\"prompts when the cd changes into a different directory, since running git in a new\ndirectory can execute that directory's hooks\". So this skill's allowed-tools covers the\nStep-1 listing (Bash(git worktree *)) but not the per-worktree checks — the prompt is\nexpected; approve it.
Read the planned subagent's task prompt. Extract:
\n## Task scope and ## Inputs sections — see leader-developer-handoff-contract)Sources/.../Settings/)For each in-flight subagent's dirty-file set vs the new dispatch's likely scope:
\nisolation: \"worktree\". Note in dispatch prompt: \"in-flight subagent X is editing target Y; do not touch files Z.\"The intersection check above only reasons about file paths, but a booted Simulator is\njust as exclusive a resource as a file: pre-assign a UDID per subagent in the dispatch prompt\nrather than letting each agent boot/pick one implicitly. Some simctl settings are device-global,\nnot per-app — xcrun simctl ui <udid> appearance|content_size changes the whole device's state,\nso agent A switching to dark mode or Dynamic Type contaminates agent B's screenshots if they\nshare a simulator (see apple-dev-skills:interactive-simulator-ux-audit for the driving pattern this protects).
isolation: \"worktree\" does not always branch from your current local HEAD — the base\ndepends on worktree.baseRef (\"fresh\" vs \"head\"), and a resumed agent can drift off its\nstarting branch. Before dispatching, confirm the base:
git rev-parse --abbrev-ref HEAD # on the branch you think you are?\ngit log --oneline -3 # does it include the commit/PR this work depends on?\ngit merge-base --is-ancestor <dep-sha> HEAD && echo \"base OK\" || echo \"STALE BASE\"\nFor the baseRef decision table, the sync-before-dispatch recovery recipe, the real incident\nthat motivated this check, and the two resumed-agent traps (stale pwd/branch, ghost index\nentries), see references/worktree-base-and-recovery.md.
When ANOTHER Claude session (or human) is actively editing the same working checkout — or a git submodule vendored into your repo (e.g. a shared .claude/skills/<plugin> submodule) — do NOT edit that shared checkout in place. Two writers on one working tree clobber each other's uncommitted edits, fight over branch HEAD, and produce confusing diffs.
Instead, collaborate through isolation + PR:
\norigin/main (not the shared checkout's possibly-dirty local state):\ngit -C <shared-repo-or-submodule-path> fetch origin && git -C <…> worktree add /tmp/<name> -b <branch> origin/mainThis is the cross-session mirror of the within-session conflict check: same goal (no two writers on one tree), different scope (independent sessions / submodules rather than your own in-flight subagents). When unsure whether another agent is on a path, treat it as occupied and use the worktree+PR path — it's cheap insurance.
\nWhen overlap detected, present to user:
\n⚠️ Conflict detected between new dispatch and in-flight subagent:\n\nIn-flight: <subagent-id> editing:\n - <file 1>\n - <file 2>\n\nNew dispatch would touch:\n - <file 1> ← OVERLAP\n - <file 3>\n\nOptions:\n1. Serialize — wait for in-flight to merge, then dispatch\n2. Carve — rewrite new dispatch prompt to exclude overlapping files\n3. Proceed anyway — risk: subagent commits compete on push\n--force-with-lease does NOT silently overwrite — it rejects the push when the remote ref has moved since the client last fetched. The real footgun is a different one: worktree B rebases onto a stale base (e.g. the main SHA from before worktree A pushed), producing a divergent history; resolving it then requires a force-push that can drop worktree A's commits. Prevent this by serializing or carving scopes before dispatch.If your Leader runs a pre-dispatch pre-flight (process cleanup, rebase onto main, tool trust), insert this conflict-detection step before it. For why mise trust is required before mise install/mise exec take effect in a fresh worktree or CI checkout, see apple-dev-skills:mise-tool-management.
If git worktree list shows stale entries (worktree dir gone but git registration alive), they are NOT a conflict source — they just need git worktree prune. Don't block dispatch on stale registrations; check ls <worktree-path> to confirm the directory actually exists before computing dirty-file intersection.
Leader is about to dispatch: \"Developer for error funnel refactor — files: Sources/App/Composition/Live.swift, Sources/App/Root/RootViewModel.swift, Tests/RootViewModelTests.swift\"\n\n`git worktree list` shows in-flight subagent `agent-abc123` editing:\n M Sources/App/Components/BannerController.swift\n\nIntersection: Module overlap (same `Sources/App/`, different files) → WARN.\n\nVerdict: dispatch with `isolation: \"worktree\"`. Note in prompt: \"in-flight subagent on BannerController.swift — do not touch that file; module Sources/App/ is shared.\"\ngithub-contribution-workflow — routes worktree/submodule collision questions here; that skill owns PR/branch mechanics, this one owns pre-dispatch and cross-session conflict checks.