---
name: borghei/git-worktree-manager
source: https://app.decimal.ai/s/borghei-git-worktree-manager@1/SKILL.md
source_sha256: 26dafdc23653
---

# Git Worktree Manager

Manage parallel development workflows using Git worktrees with deterministic naming, automatic port allocation, environment file synchronization, dependency installation, and cleanup automation. Optimized for multi-agent workflows where each agent or terminal session owns an isolated worktree with its own ports, environment, and running services.

## Core Capabilities

- **Worktree lifecycle** — create worktrees from new or existing branches with deterministic naming, copy `.env` files, install dependencies by lockfile detection, list with clean/dirty + ahead/behind status, and safely remove with uncommitted-change detection.
- **Port allocation** — deterministic per-worktree assignment (`base + index * stride`), collision detection against running processes, persistent map in `.worktree-ports.json`, and Docker Compose override generation.
- **Multi-agent isolation** — one branch per worktree, one agent per worktree, no shared state, conflict-free parallel execution, task-ID mapping for traceability.
- **Cleanup automation** — stale detection by age, merged-branch detection for safe removal, dirty-state warnings, and bulk cleanup with safety confirmations.

## When to Use

- You need 2+ concurrent branches open with running dev servers.
- You want isolated environments for feature work, hotfixes, and PR review.
- Multiple AI agents need separate workspaces that do not interfere.
- Your current branch is blocked but a hotfix is urgent.
- You want automated cleanup instead of manual `rm -rf` operations.

## Clarify First

Before managing worktrees, confirm these inputs. If any is unknown or vague, ASK — do not assume:

- [ ] **Operation** — create, list, remove, or clean up worktrees (selects the `worktree_manager.py` action vs `port_allocator.py` vs `worktree_validator.py`)
- [ ] **Branch & base** — which branch(es) the worktree(s) track and from what base (drives worktree naming and isolation)
- [ ] **Port/service needs** — whether dev servers or Docker need allocated ports (drives the deterministic port block and the Docker Compose override generated)

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

## Tools

| Tool | Purpose | Command |
|------|---------|---------|
| `worktree_manager.py` | List, create, remove, and clean up worktrees | `python scripts/worktree_manager.py list` |
| `port_allocator.py` | Assign/check/release deterministic port blocks; sync registry | `python scripts/port_allocator.py status` |
| `worktree_validator.py` | Validate worktree health (stale, missing branch, env parity, port conflicts, lockfile) | `python scripts/worktree_validator.py --stale-days 14` |

## References

Load the reference that matches the task — keep this file lean and pull detail on demand:

- **[references/setup-and-ports.md](references/setup-and-ports.md)** — quick-start `git worktree` commands, the deterministic port-allocation strategy and `.worktree-ports.json` format, collision-detection snippet, the full `setup-worktree.sh` script, and the Docker Compose per-worktree override. Read when creating a worktree or wiring up ports/services.
- **[references/cleanup-and-workflows.md](references/cleanup-and-workflows.md)** — the `cleanup-worktrees.sh` safe-cleanup script, the multi-agent assignment pattern and rules, the scenario→action decision matrix, and the post-creation validation checklist. Read when automating cleanup or coordinating agents.
- **[references/operations-playbook.md](references/operations-playbook.md)** — common pitfalls, best practices, the troubleshooting table, and the success-criteria bar. Read before shipping a workflow or when diagnosing problems.

## Scope & Limitations

**This skill covers:**
- Git worktree lifecycle: creation, listing, status inspection, and removal
- Deterministic port allocation and collision avoidance for parallel dev servers
- Environment file synchronization and Docker Compose override patterns
- Multi-agent workspace isolation strategies and cleanup automation

**This skill does NOT cover:**
- Git branching strategies or merge conflict resolution (see `pr-review-expert` and `release-manager`)
- Secret rotation, vault integration, or credential management (see `env-secrets-manager`)
- CI/CD pipeline configuration or automated test orchestration (see `ci-cd-pipeline-builder`)
- Monorepo package management, workspace linking, or cross-package dependency resolution (see `monorepo-navigator`)

## Integration Points

| Skill | Integration | Data Flow |
|-------|-------------|-----------|
| `env-secrets-manager` | Worktree setup copies `.env` files that contain secrets managed by this skill | `.env` files flow from main repo to each worktree; secret references remain consistent across all copies |
| `ci-cd-pipeline-builder` | CI pipelines can spin up worktrees for parallel test matrix execution | Pipeline config triggers `setup-worktree.sh` per matrix job; port allocation prevents service collisions |
| `release-manager` | Release branches get dedicated worktrees for stabilization while feature work continues | Release worktree is created from the release branch; merged status drives cleanup automation |
| `monorepo-navigator` | In monorepo setups, worktrees must respect package boundaries and shared dependencies | Worktree creation inherits the monorepo root lockfile; package-level dev servers use allocated port blocks |
| `pr-review-expert` | PR reviews can be performed in isolated worktrees with running code for manual validation | Reviewer creates a worktree at the PR branch, runs the dev server on allocated ports, and removes after review |
| `tech-debt-tracker` | Stale worktrees and abandoned branches surface as tech debt indicators | Cleanup script output feeds into debt tracking; worktree age and merge status inform priority scores |