# Git Worktree Swarm

> Automates the complex setup of parallel git worktrees for agentic swarms with dependency-aware wave execution.

- Skill: `winstonkoh87/git-worktree-swarm` (Agent Skill)
- Install (CLI): `npx skillmds@latest add winstonkoh87/git-worktree-swarm`
- Raw SKILL.md: https://api.skillmd.com/api/skills/winstonkoh87/git-worktree-swarm/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: winstonkoh87 (https://skillmd.com/u/winstonkoh87)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/winstonkoh87/git-worktree-swarm

---


# Git Worktree Swarm Orchestrator

Sets up parallel, isolated git environments so multiple sub-agents can work on the same repository simultaneously without merge conflicts. Uses **wave-based execution** to respect task dependencies.

## Triggers

"swarm", "parallel agents", "setup worktrees", "multi-agent", "wave execution"

## Core Mechanics

### Phase 1: Setup

1. Detect current branch.
2. Spawn `n` temporary worktrees (`.agent-workspace-1`, etc.).
3. Assign tasks to isolated clones.

### Phase 2: Wave Execution (Dependency DAG)

Plans are grouped into **waves** based on dependency analysis:

```
WAVE 1 (parallel — no dependencies)
├── Worktree A: Task 1 (User model)     → Fresh context (P513)
├── Worktree B: Task 2 (Product model)  → Fresh context (P513)
│
[State merge: A.state + B.state → combined handoff]
│
WAVE 2 (parallel — depends on Wave 1)
├── Worktree C: Task 3 (Orders API, needs User model)
├── Worktree D: Task 4 (Cart API, needs Product model)
│
[State merge: C.state + D.state → combined handoff]
│
WAVE 3 (sequential — depends on Wave 2)
└── Worktree E: Task 5 (Checkout UI, needs Orders + Cart)
```

**Wave Assignment Rules**:

| Condition | Assignment |
|---|---|
| Task has no dependencies | Wave 1 |
| Task depends on Wave N output | Wave N+1 |
| Tasks touch the same files | Same wave, sequential (not parallel) |
| Task has cross-cutting concerns | Latest wave of any dependency |

### Phase 3: Context Isolation (P513)

Each worktree agent receives only:

- The specific plan/task
- Relevant source files (from dependency analysis)
- STATE.md (accumulated decisions from prior waves)
- Project context (design.md / REQUIREMENTS.md)

Never: full conversation history, debug logs, unrelated research.

### Phase 4: Merge

1. Each task commits atomically (P43 micro-commit).
2. Merge worktrees back to main branch in wave order.
3. Conflict resolution: if merge conflicts arise, spawn resolution agent.
4. Cleanup: remove temporary worktrees.

## Reference Paths

- [Protocol 513: Context Isolation](../../../protocols/engineering/ENG-513-context-isolation.md)
- [Protocol 43: Micro-Commit](../../../protocols/engineering/ENG-43-micro-commit-protocol.md)
- `.context/memories/protocols/engineering/100-git-worktree-parallelism.md`
- `.context/memories/protocols/architecture/409-parallel-worktree-orchestration.md`