SDLC Agent-Skill Wiki

Pattern: Worktree isolation (each unit of work in its own git worktree)

5 min read

Run each unit of work in a dedicated git worktree — a separate working directory on its own branch, sharing one repository — so parallel, experimental, and autonomous work never corrupts the mainline or collides with other in-flight units. When a unit is abandoned, its worktree is discarded with no trace on the trunk; when it succeeds, it merges cleanly.

Two frameworks make this a first-class, explicit skill. Compound Engineering (ce-worktree) runs ce-work and the autonomous lfg loop inside it; Superpowers (sp-using-git-worktrees) prefers the harness’s native worktree tool, falls back to git worktree, and verifies a clean test baseline before any implementation begins. Other frameworks use worktrees ad hoc; these two foreground isolation as a reusable step.

Why it’s distinctive

This is the filesystem counterpart to pattern-fresh-context-subagents (which isolates an agent’s context): worktree isolation isolates the files. It is the safety substrate that makes pattern-autonomous-loop non-destructive — an unattended agent can build, break, and retry without risking the developer’s working tree — and it enables running multiple units concurrently (one product, five worktrees). Other frameworks use git worktrees ad hoc; Compound Engineering foregrounds isolation as an explicit, reusable step.

Compound Engineering:

  • ce-worktree — ensures an isolated worktree exists (native detection + fallback).
  • ce-work — executes the plan inside the isolated worktree.
  • lfg — runs the whole autonomous loop in isolation.

Superpowers:

  • sp-using-git-worktrees — detect existing isolation → prefer the harness’s native worktree tool → fall back to git worktree (verified git-ignored) → verify a clean test baseline.
  • sp-finishing-a-development-branch — the counterpart teardown: removes only the worktrees it created, per the merge/PR/keep/discard choice.

Seeds — the pattern seen from the shared-state side rather than the workspace side:

  • seeds-init — installs the merge=union gitattributes that let branches from parallel worktrees each append work items and merge without conflict; dedup-on-read (last occurrence wins) resolves the duplicates union leaves.
  • seeds-sync — commits the store, which is the unit those merges reconcile. Together with advisory file locks and atomic temp-file-and-rename writes, this is what makes one tracker safe for several isolated agents at once — the concern every prompt-based framework leaves to the runtime.

Beads — the state-side half of the pattern: isolation is only useful if the isolated agents still share one queue.

  • beads-worktree — create, inspect, and safely remove git worktrees with the store wired correctly, rather than sharing or stranding the database.
  • beads-init — content-hash IDs so two branches cannot mint the same id (“merges never renumber work”), and Dolt cell-level three-way merge for the rest; bd recompute-blocked repairs derived flags after a merge lands.
  • beads-merge-slot — the merge slot serializes the one step isolation cannot parallelize.

pstack — stated as a principle and cited by name at every fan-out:

Tessl:

  • tessl-launch — cloud launches run a capability against a repository in an isolated sandbox, with secrets supplied by tessl-environment rather than baked into the bundle.

builder-skills:

Matt Pocock — Skills for Real Engineers:

  • mp-implement-spec — each implementer subagent works one ticket in its own worktree on its own branch, rebased on the integration branch and fast-forward merged back by a merger subagent (v1.3.0).

Enabled by (infrastructure)

The execution layer provides this pattern as substrate — the isolation exists whether or not any skill asks for it:

  • sandcastle (library) — createWorktree() plus the branch / merge-to-head strategies give every run its own worktree/branch; the worktree is preserved on a dirty exit and removed when clean.
  • warren (platform) — the same “never corrupt the trunk” intent realized at the OS level: a fresh bwrap-isolated workspace per run (local) or a dedicated pod per run (k8s), rather than a git worktree.
  • bernstein (platform) — a git worktree per spawned agent is the default sandbox, “so multiple agents running against the same repository cannot stomp on each other’s files, processes, or secrets”; the choice is pluggable behind a SandboxBackend protocol with seven heavier first-party backends (docker, e2b microVMs, modal, daytona, blaxel, runloop, vercel) and an entry-point group for third parties.
  • gh-aw (platform) — the isolation is the CI substrate itself: every run gets an ephemeral GitHub Actions runner, optionally hardened by the Agent Workflow Firewall (the engine in a Docker container behind a Squid proxy enforcing a domain allowlist — “All traffic routed through proxy enforcing the domain allowlist”), with gVisor or KVM-microVM runtimes as stronger substrates. The distinctive addition is egress isolation: the other runtimes here bound what the agent may write; the firewall bounds what it may reach.

Persisted by (store)

Isolation is only useful if the isolated agents can still see one queue — that is this layer’s contribution.

  • beads — content-hash IDs so parallel branches never renumber work, Dolt cell-level three-way merge for concurrent field edits, beads-worktree to wire a new worktree to the store correctly, and beads-merge-slot to serialize the one step that cannot be parallel.
  • seeds — merge=union gitattributes plus dedup-on-read, advisory locks, and atomic writes, so several worktree agents share one file store and git reconciles it (seeds-init, seeds-sync).

See Also

Graph View

Backlinks