Skip to content
Back to skills

Using Worktrees

BSecurity

Give a task its own filesystem checkout.

  • 3 stars
  • 0 votes
  • 0 copies
  • 0 views
  • Added November 16, 2026
ai-agentsrustgogit

Works with

  • claude code
  • terminal
  • cli

Security analysis

B85/100
  • highPerforms destructive filesystem operations

Pro shows the line behind each finding and how to fix it

Scanned November 16, 2026

npx -y skills add Acendas/shipyard --skill using-worktrees --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Using Worktrees?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Using Worktrees
[![Security: B — Skills Directory](https://www.skillsdirectory.com/api/skills/acendas-using-worktrees/badge)](https://www.skillsdirectory.com/skills/acendas-using-worktrees)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: using-worktrees
description: Give a task its own filesystem checkout.
disable-model-invocation: true
---

# Using Worktrees

Shipyard isolates parallel task execution in git worktrees so concurrent subagents don't clobber each other's edits. **Trust the platform** — pass `isolation: worktree` on the Agent call and let Claude Code handle creation, cwd, and cleanup.

**Render before asking.** Render the decision context as chat text before any AskUserQuestion (rules printed at startup under SHIPYARD_STARTUP_RULES).

## When to Use Worktrees

| Mode | Use worktrees? |
|---|---|
| Solo (1–3 tasks per wave, sequential) | No — tasks run on the working branch, one after another |
| Task / parallel (4+ tasks per wave, concurrent) | **Yes** — one worktree per task |
| Track mode (persistent feature tracks) | **Yes** — one worktree per feature track |
| `--isolation false` / `execution.isolation: none` | **No** — forced sequential in-place on the working branch (see below) |
| `/ship-review` diff inspection | Optional — read-only; worktree only if reviewing across branches |
| Hotfix | No — work on the user's current branch directly |
| `/ship-execute --task` (land-now) / `--hotfix` | No — single change, working branch |

The rule of thumb: **isolate when concurrency would otherwise race**. Sequential work doesn't need worktrees.

## Choosing No Isolation (`--isolation false`)

A project with a heavy build (large native toolchain, slow dependency install, big test image) can pay more to reconstruct a cold worktree than it saves from parallelism. For those, `/ship-execute --isolation false` — or the persistent `execution.isolation: none` in config.md (`shipyard-data config set-isolation none`) — runs the sprint **sequentially in-place on the working branch**, keeping the warm canonical checkout.

**No-isolation is sequential-only, by construction.** It is NOT "parallel without worktrees." Two parallel builders on one shared checkout would clobber each other's edits, and there would be no per-task `shipyard/wt-*` branch for the wave-integration gate (`verify-wave-integrated`) to rebase and merge — the whole branch-based integration model assumes one worktree branch per concurrent task. So when isolation is off, dispatch is the `solo` shape regardless of task count; `--isolation false` combined with `--mode task|track` coerces to sequential with a one-line note rather than racing.

The integration gate stays correct either way: with zero `shipyard/wt-*` branches it is **vacuously satisfied** — sequential commits land directly on the working branch, nothing to rebase.

The complementary lever — keep isolation *and* get speed — is `worktree_warm` (CoW-clone build-artifact dirs into each fresh worktree) plus `shared_caches` (shared package-manager download caches). Prefer those first; reach for `--isolation false` when the build genuinely can't run cheaply outside the canonical checkout.

## How to Create a Worktree (the New, Simple Way)

The orchestrator dispatches a subagent with `isolation: "worktree"` on the `Agent` call. This is the only path; there is no manual pre-creation fallback:

```
Agent(
  subagent_type: "general-purpose",
  model: <model= from `shipyard-data resolve-model <role>`, or omit if empty>,
  effort: <effort= from `shipyard-data resolve-model <role>`, or omit if empty>,
  isolation: "worktree",
  prompt: <task-loop prompt template, parameterized>
)
```

The caller resolves model and effort with `shipyard-data resolve-model <role>` (one line `model=<m> effort=<e>`; omit an empty field) — never hardcode a literal.

Claude Code:

1. Fires the `WorktreeCreate` hook (Shipyard's `worktree-branch.mjs`) which creates a branch named `shipyard/wt-<id>` from the current local HEAD.
2. Creates the worktree under `.claude/worktrees/<id>/` with that branch checked out.
3. Spawns the subagent with cwd = the worktree path.
4. Subagent edits / commits / runs tests in the worktree.
5. Subagent returns; Claude Code captures the cwd correctly (no leakage to parent).
6. After the orchestrator-side gate passes, orchestrator **accepts each returned commit** (`shipyard-data step accept-return <task> sprint=<id> wave=<n> commit=<sha> --data-dir <data_dir>`), which anchors the commit, records the terminal return event, and marks the task done, then rebases + ff-merges the worktree branch back onto the working branch. It discovers the branch from git ground truth (`git worktree list` → the `shipyard/wt-*` row), **never** from the Agent return's `worktreeBranch` field — that field is undefined/unreliable (Claude Code #51596), and trusting it skips merge-back and orphans commits.
7. Orchestrator runs `shipyard-data verify-wave-integrated` (the pre-teardown gate); only on exit 0 does it remove the worktree (`git worktree remove`) and delete the branch with `git branch -d` (never `-D`).

The orchestrator does **not** need to:
- Pre-create the worktree manually.
- Pass the worktree path in the prompt.
- Tell the subagent to `cd` into the worktree.
- Track which subagent ended up in which directory.

All of that is now Claude Code's job.

## Branch Naming

Shipyard's `WorktreeCreate` hook (`bin/hooks/worktree-branch.mjs`) names the branch `shipyard/wt-<id>` where `<id>` is derived from the worktree name Claude Code passes to the hook. Conventions:

- Per-task subagent: `<id>` = `<TASK_ID>-<short-slug>` → branch `shipyard/wt-T-042-add-user-endpoint`.
- Per-feature track (track mode): `<id>` = `<FEATURE_ID>-<short-slug>` → branch `shipyard/wt-F-007-checkout-rewrite`.
- Probe / readiness check: `<id>` = `probe-<timestamp>` → branch `shipyard/wt-probe-1715168400`.

The `shipyard/wt-` prefix is the discriminator: any branch starting with it is a Shipyard-owned worktree branch and may be safely cleaned up by the orchestrator at wave boundaries.

**Discover the branch from git, not the Agent return.** The branch name is deterministic (`shipyard/wt-<worktree-name>`) and visible in `git worktree list --porcelain`. Do NOT read it from the Agent tool's `worktreeBranch` return field: because Shipyard's hook owns branch creation, Claude Code reports `worktreeBranch: undefined` (the #51596 bug), so any logic that keys off it silently no-ops the merge-back. Integrate by the `COMMIT:` SHA from the structured return contract + the `shipyard/wt-*` row from `git worktree list` — both ground truth.

## Base Ref: `head` for In-Progress Sprints

Shipyard's worktrees must branch from **local HEAD**, not `origin/<default>`. Sprint work builds on local-only commits from earlier waves; an `origin/<default>` base would silently drop them.

Set in the project's `.claude/settings.json`:

```json
{ "worktree": { "baseRef": "head" } }
```

**Verified at execute, not just at setup.** `/ship-execute` Step 0 runs `shipyard-data ensure-worktree-baseref`, which sets this idempotently every sprint (atomic JSON merge — never a model hand-edit). Don't rely on setup having set it once: it drifts, and a missing setting is silently wrong. The setting is also the backstop for when the `WorktreeCreate` hook doesn't fire — native worktree creation then still bases on local HEAD instead of `fresh` (= `origin/<default>`), which would skip Wave N-1's commits.

## Cleanup at Wave Boundaries

After all subagents in a wave return:

1. **Accept every gate-passed return first.** `shipyard-data step accept-return <task> sprint=<id> wave=<n> commit=<sha> --data-dir <data_dir>` for each `COMPLETE` return pins a `shipyard/keep-<task>` ref to the commit and records terminal evidence. From here the commit survives rebase, teardown, and worktree-name collisions — the insurance half of the integration gate. Use bare `shipyard-data anchor-commit` only for salvage paths where a branch tip must be preserved but the task did not pass the gate and must not be marked done.
2. **Rebase each task branch sequentially onto the working branch**, in task-ID order (deterministic, replayable history even though tasks ran in parallel). Discover the branches from `git worktree list` (the `shipyard/wt-*` rows), never from `worktreeBranch`.
   ```
   for branch in shipyard/wt-T-042 shipyard/wt-T-043 ...; do
     git rebase <working-branch> $branch
     git checkout <working-branch>
     git merge --ff-only $branch
   done
   ```
   Conflicts → render the conflicting file list and the conflict hunks as chat text first (diffs read via git exist only in context and can't render inside an AskUserQuestion card), then `AskUserQuestion`. Do NOT fall back to a regular merge — that creates fork lines in the graph.
3. **Gate before teardown.** `shipyard-data verify-wave-integrated` proves every live `shipyard/wt-*` branch is merged and no return commit is dangling. Exit 3 → HARD STOP: don't remove anything; integrate the named branches and re-run. This is the structural guarantee that teardown can never precede merge-back.
4. **Remove the worktree and delete the branch — only past the gate:**
   ```
   git worktree remove .claude/worktrees/<id>
   git branch -d shipyard/wt-<id>     # -d, never -D: refuses an unmerged branch
   ```
5. **Verify clean state** — `git worktree list` should show no `shipyard/wt-*` paths after wave merge.

Anthropic's stale-worktree cleanup (`cleanupPeriodDays`) reaps leftover worktrees with no uncommitted changes and no unpushed commits at session start (ones with either are left for salvage); do not duplicate it.

## When Things Go Wrong

### Subagent's worktree branch doesn't start with `shipyard/wt-*`

This means the `WorktreeCreate` hook didn't fire correctly. Hard-stop the subagent (the prompt template instructs it to refuse to proceed). Investigate the hook before retrying — never let the subagent "fix" by checking out the working branch directly, that bypasses isolation entirely.

### The Agent return shows `worktreeBranch: undefined`

Expected, not an error. Shipyard's `WorktreeCreate` hook owns branch creation, so Claude Code has no branch of its own to report (Claude Code #51596). **Never gate merge-back on this field.** Derive the branch from `git worktree list` and integrate by the `COMMIT:` SHA from the return contract.

### Rebase conflicts at wave boundary

Two parallel subagents touched the same file (a planning lesson). Resolve by:

1. Render the conflict files and the two diffs as chat text, then AskUserQuestion — the AskUserQuestion card cannot carry diffs; packing them into option strings does not count as showing them.
2. User chooses which to keep, or merges manually.
3. Continue the wave.

### Stale `git worktree` administrative metadata

If a user manually `rm -rf`'d a worktree directory, git's internal `.git/worktrees/<name>/` lingers. Defend with:

```
git worktree prune
```

Run this at the start of `/ship-execute` (Step 0). It only removes admin metadata for already-deleted directories — never touches live worktrees, branches, or commits.

### Worktree branch failure (hook didn't run)

Anthropic fixed this for `--worktree` and `isolation: worktree` (changelog: "Fixed `WorktreeCreate` and `WorktreeRemove` plugin hooks being silently ignored"), so this should be rare. If it happens:

- Verify `plugins/shipyard/hooks/hooks.json` has the `WorktreeCreate` entry — hook installation isn't reported by any CLI; check the manifest directly.
- Check the recent `claude --version` against the changelog requirement.

## Pairing With Other Skills

- **`dispatching-task-loop`** uses this skill's contract when dispatching with `isolation: "worktree"`. The dispatch skill's prompt tells the subagent its branch should start with `shipyard/wt-` — that contract is owned here.
- **`acquiring-skill-lock`** is independent; locks live under `<SHIPYARD_DATA>` (outside any worktree), so worktree creation doesn't affect lock semantics.
- **`/ship-review`** can read the diff against either the merged working branch or specific worktree branches; this skill provides the branch-naming convention.

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.