using-git-worktrees skill
OPTIONAL per-task isolation for autonomous parallel work. Routed to only on explicit opt-in by subagent-driven-development or dispatching-parallel-agents, so parallel units mutate files without colliding.
The orchestrator routes to this skill from an owning command. It is not a direct user entry point.
At a glance
Section titled “At a glance”- Runs inside
- Parallel agent work, and only when
subagent-driven-developmentordispatching-parallel-agentsexplicitly opts in to per-task isolation. - What it produces
- One consolidated working branch with every accepted unit folded back in, after all the temporary worktrees are removed.
What it does
Section titled “What it does”This is optional, per-task filesystem isolation for parallel agent work — it only runs when the implementation engine or the parallel-dispatch primitive explicitly opts into it, never by default. It gives concurrent units their own working tree each so they can edit files without colliding, then folds every accepted unit’s work back onto the caller’s single working branch, which still takes exactly one pass through the commit gate and the branch-finishing step.
Phases
Section titled “Phases”- Stand up one worktree and one branch per parallel unit, all rooted at the same clean base, and record each in a manifest.
- Let each unit do its work entirely inside its own worktree, still routed through the test-first gate — isolation changes nothing about that requirement.
- Integrate every accepted unit’s branch back onto the caller’s single working branch, resolving any conflict in the open rather than force-merging.
- Remove every worktree this skill created and clear the manifest.
The consolidated working branch goes through the caller’s usual single exit path — a single pass through the commit gate followed by a single branch-finishing decision, never one of either per unit. This skill never opens a pull request or finishes a branch on its own; it only provisions, folds back, and tears down.
| Gate | When | Effect |
|---|---|---|
| provisioning | setting up isolated units | every parallel unit must land on its own distinct worktree and branch off the same clean base, recorded in a manifest, before any isolated work begins |
| teardown | after fold-back | every worktree this skill created must be removed and the manifest cleared before the skill returns — an orphaned worktree counts as a failure |
Related
Section titled “Related”Source
Section titled “Source”Source — plugins/ca/skills/using-git-worktrees/SKILL.md (v3.8.9)
---name: using-git-worktreesdescription: OPTIONAL per-task isolation for autonomous parallel work. Routed to only on explicit opt-in by subagent-driven-development or dispatching-parallel-agents, so parallel units mutate files without colliding. Stands up one worktree per unit, works it in isolation, then integrates each unit back onto the caller's working branch for the caller's single commit-gate + finishing-a-development-branch exit. Never on the default path; it does not bypass a gate or finish per unit.disable-model-invocation: true---
# using-git-worktrees
OPTIONAL. Per-task filesystem isolation for parallel agent work — opt-in only, never the default path.Routed to by `subagent-driven-development` and `dispatching-parallel-agents` when, and only when, thecaller requests isolation. If no isolation is requested, this skill does not run; parallel units sharethe working tree under their own discipline.
Isolation lets concurrent units edit files without collision. It changesnothing about the gates — the consolidated work still clears `commit-gate` and the single`finishing-a-development-branch` terminal step, run by the caller. What it MUST NOT do is multiplythat terminal step into one PR per unit.
## Pre-flight
Read these, or STOP and surface the gap — never guess:
- `${CLAUDE_PROJECT_DIR}/.codearbiter/CONTEXT.md` — confirm the repo is a git repo and the base/working branch.- The discovered authoritative spec/plan pair for the caller's pipeline. Use its exact selected plan for the parallel unit list. Re-run the private bridge resolver `_resolve_workflow_pair` with the trusted project root and pipeline slug rather than reconstructing either path. For an HTML pair, load `${CLAUDE_PLUGIN_ROOT}/includes/artifacts.md` and obtain HTML task and path records only through the installed engine `identity`, `index`, and symbol-scoped `read` operations. For a Markdown pair, use its existing Markdown task table. Worktree planning must not create, convert, or consult a counterpart.
Confirm the caller selected isolation within its current authorized scope AND supplied the parallel unit listfrom the exact selected plan. Absent either, do not stand up worktrees. A selected isolation method isnot new authority to discard a branch or worktree.
## Phase 1 — Provision · gate: BLOCK
Stand up one worktree per parallel unit. For each unit, create a worktree on a fresh branch off thecurrent base, under a dedicated parent directory outside the main working tree(e.g. `../.codearbiter-worktrees/<slug>`):
- One worktree, one branch, one unit. Never share a worktree across units.- Branch name MUST be unique and traceable to its unit's task ID.- Retain the integration owner, base, branch, path ownership and each worktree path in the existing handoff record; update `.codearbiter/.worktrees.json` where that scratch manifest is already supported. Do not introduce a mandatory new schema to make ordinary isolation possible.
Before provisioning, inventory dirty inputs relevant to each unit and record each path's SHA-256 orabsence. A fresh worktree does not contain uncommitted caller bytes. If a dirty input overlaps aunit-owned path, stop: the unit cannot safely distinguish caller work from its own delta. Otherwise,reproduce it only as a read-only baseline, verify its hash before and after unit work, and exclude itfrom the unit index and commits. Recheck the caller copy is still byte-identical before fold-back.Preserve unrelated dirty paths by leaving them untouched.
Gate: every unit has a distinct worktree on a distinct branch, all rooted at the same verified base and recorded for resumption. Every relevant dirty input is either a content-addressed read-only baseline outside unit ownership or a named stop; unit commits exclude those baselines, and no cleaning, resetting, stashing or overwriting occurred.
## Phase 2 — Isolated work · gate: BLOCK
Each parallel unit works entirely inside its own worktree. Dispatch is unchanged — the caller stilldispatches its author and reviewer agents; they simply operate on the isolated path.
- A unit MUST NOT read or write outside its assigned worktree.- A unit MUST NOT touch `main` or any other unit's branch.- All implementation inside a worktree still flows through `tdd` — isolation is not a TDD bypass.
Gate: each unit's work is contained to its own worktree, with no cross-worktree or base-branch writes.
## Phase 3 — Fold back · gate: BLOCK
Integrate each isolated unit's work back onto the caller's single working branch — do NOT finish eachunit on its own. Per unit, in order:
1. Confirm the unit was accepted by the caller under its applicable completion and check contract. Inspect accessible command, cwd, source/input identity, output and exit status; reuse valid evidence and rerun only missing or affected checks. An explicit review batch retains its triaged verdict. An unaccepted unit does not fold back.2. Integrate its branch onto the caller's working branch (merge or rebase), resolving any conflict here, in the open. If a rebase rewrites the unit branch, immediately refresh its recorded tip in the handoff before fold-back and use that refreshed tip for later ancestry proof. Never integrate onto `main` or the default branch.
The consolidated working branch then takes the caller's normal single exit — ONE `commit-gate` passand ONE `finishing-a-development-branch` decision, run by the caller, not per unit. This skillintegrates; it never opens N PRs or finishes N branches. A unit that cannot integrate cleanly issurfaced as a conflict for resolution — never force-merged, never dropped silently.
Gate: every accepted unit integrated onto the caller's working branch with conflicts resolved; noper-unit PR or finish was opened.
## Phase 4 — Cleanup handoff · gate: BLOCK
Record which worktrees and branches remain after fold-back. Integrated unit worktrees and branchesremain retained by default: they have no per-unit merged PR, so `post-merge-cleanup` cannot provethem merged. This phase is their removal path only when all of the following hold: for a rebased unit,the recorded tip was refreshed after rebase; the current recorded tip is an ancestor of the caller'sconsolidated working branch after fold-back; the unit worktree isclean with no unique untracked or stashed residue; and the existing explicit cleanup confirmationnames both its path and branch. Then remove that exact worktree with `git worktree remove` and deletethat exact branch with `git branch -d`; never use `-D`. If any proof or confirmation is absent, retainthe unit and its handoff entry. Continue to route cleanup of the consolidated PR branch itself through`post-merge-cleanup`. Do not auto-delete an integrated, unaccepted or abandoned unit merely to closethis skill.
Gate: every remaining worktree is accounted for; no unreviewed work or user data is discarded.
## Hard rules
- MUST NOT run on the default path — isolation requires an explicit caller opt-in.- MUST NOT share a worktree or a branch across parallel units.- MUST NOT let a unit read or write outside its assigned worktree, or touch `main`.- MUST NOT open a per-unit PR or run `finishing-a-development-branch` per unit — integrate accepted units onto the caller's working branch, which takes the single `commit-gate` + finishing exit.- MUST NOT delete a branch or worktree without the separately required per-item confirmation and cleanup proof (ADR-0036). Retain and report worktrees awaiting that action.