Worktree + PR by design — orchestrator patterns

Worktree + PR by design — orchestrator patterns

One-liner

Contract: Task → git worktree + branch → worker → push → PR. Coordinator never edits the main tree. Steal hardest from pi-pr-agents, Claude Code worktrees, and Conductor workspaces.

Related: Cloud agent orchestrator · 2026-09-28 Pi SDK sessions worktrees and TS coordinator · 2026-09-28 Persistent project coordinator model · 2026-09-26 Cloud agent orchestrators in the wild

Herdr skipped (Coordy request).

---

Pattern taxonomy

Layer	Isolates	PR handoff	DIY fit
A. Worktree-only	Files + branch (shared .git)	Push → gh pr create / Graphite	Best local default
B. Worktree + runtime	A + ports / DB / env copies	Same	Needed for parallel dev/tests
C. Branch-in-VM/container	Full machine	Platform opens PR	Cloud/security; heavier
D. Branch-only (shared WD)	Nothing on disk	Fragile	Anti-pattern
E. Coordinator / worker	Coordinator never edits; workers own worktrees	1 worker ≈ 1 PR (or stack)	Core DIY shape

Hard rules: one branch ↔ one worktree; worktrees ≠ security boundary; worktrees ≠ semantic merge safety.

---

Products worth stealing

pi-pr-agents (highest for Pi-SDK)

Every PR subagent gets a worktree + branch; main agent cannot edit/write. Modes: independent | stack | graphite. Depth-capped tools; shared registry.json; /cleanup.

Steal: Main never codes; 1 PR = 1 worktree; Graphite stacks; registry across worktrees.

npm · anonx3247/pi-pr-agents · pi.dev package

Claude Code — native worktree isolation

Worktrees under .claude/worktrees/; --worktree / subagent isolation: worktree; blocks redirects into main checkout; .worktreeinclude.

Steal: First-class isolation flag; refuse main-checkout escape.

docs/worktrees · sub-agents

Conductor (Melty Labs)

Workspace = worktree + branch + chat + PR under ~/conductor/workspaces/…. Issue/Linear → review → Create PR; archive after merge; setup scripts / include-patterns for gitignored files.

Steal: Workspace as atomic product unit (files + branch + chat + PR).

git-worktrees · issue-to-pr

Cursor Cloud Agents

VM isolation (not local worktree); cursor/… branch; API autoCreatePR; start-from-prUrl.

Steal: PR-on-complete contract + env snapshot — pair with local worktrees in DIY.

cloud-agent · API

Factory Droid

CLI -w/--worktree → ~/.factory/worktrees/…; Mission Mode = orchestrator + worker/validator; autonomy tiers.

Steal: Worktree on interactive and headless; mission coordinator not sharing WD with workers.

CLI ref

Composio Agent Orchestrator (ao)

Per-session worktree; agent-agnostic adapters; observer routes CI/review/conflicts back to owning session.

Steal: Closed-loop PR feedback; multi-harness behind one coordinator API.

ComposioHQ/agent-orchestrator

Contrast: Tembo / OpenHands

Tembo & OpenHands emphasize sandbox/VM security, not worktree-first. Steal: PR as only merge surface; optional Docker when untrusted — still keep PR as the gate.

---

Anti-patterns

1. Shared checkout for parallel writers
2. Worktree without unique branch
3. Worktree without runtime isolation (ports/DB/cache) when running servers
4. Auto-merge to main skipping PR/CI
5. Orchestrator that also edits the main tree
6. Treating worktree as a security boundary
7. No include-list / setup script → broken deps in the worktree
8. Assuming file-disjoint ⇒ merge-safe (semantic conflicts)

---

Recommendation for Noa’s keypoint 3

Shape the TypeScript coordinator like pi-pr-agents + Conductor semantics (cloud later):

1. Contract: Task → worktree+branch → Pi worker → push → PR (Graphite optional). Never land on default branch.
2. Coordinator: git worktree add, queue, registry, peek/steer/stop, gh/gt, cleanup — no product file edits.
3. Worker: implement + atomic commits + tests with cwd = worktree only.
4. Repro: pin baseSha; include-list + setup script; persist {baseSha, branch, worktreePath, prUrl}.
5. Parallel: unique branches; optional port/env maps; overlap check before integrate.
6. Escape hatch: Docker/VM only for OS isolation; PR remains the integration gate.

Maps cleanly onto 2026-09-28 Persistent project coordinator model (durable PM) + 2026-09-28 Pi SDK sessions worktrees and TS coordinator (cwd = worktree).

---

Sources

Primary steals: pi-pr-agents, Claude Code worktrees, Conductor, Factory Droid, Composio ao, Cursor Cloud Agents (PR contract). Landscape map: Nimbalyst worktree tools 2026.