git-worktree-manager

SKILL.md

Git Worktree Manager

Tier: POWERFUL

Category: Engineering

Domain: Parallel Development & Branch Isolation

Overview

Use this skill to run parallel feature work safely with Git worktrees. It standardizes branch isolation, port allocation, environment sync, and cleanup so each worktree behaves like an independent local app without stepping on another branch.

This skill is optimized for multi-agent workflows where each agent or terminal session owns one worktree.

Core Capabilities

Create worktrees from new or existing branches with deterministic naming

Auto-allocate non-conflicting ports per worktree and persist assignments

Copy local environment files (.env*) from main repo to new worktree

Optionally install dependencies based on lockfile detection

Detect stale worktrees and uncommitted changes before cleanup

Identify merged branches and safely remove outdated worktrees

When to Use

You need 2+ concurrent branches open locally

You want isolated dev servers for feature, hotfix, and PR validation

You are working with multiple agents that must not share a branch

Your current branch is blocked but you need to ship a quick fix now

You want repeatable cleanup instead of ad-hoc rm -rf operations

Key Workflows

1. Create a Fully-Prepared Worktree

Pick a branch name and worktree name.

Run the manager script (creates branch if missing).

Review generated port map.

Start app using allocated ports.

python scripts/worktree_manager.py \
  --repo . \
  --branch feature/new-auth \
  --name wt-auth \
  --base-branch main \
  --install-deps \
  --format text

If you use JSON automation input:

cat config.json | python scripts/worktree_manager.py --format json
# or
python scripts/worktree_manager.py --input config.json --format json

2. Run Parallel Sessions

Recommended convention:

Main repo: integration branch (main/develop) on default port

Worktree A: feature branch + offset ports

Worktree B: hotfix branch + next offset

Each worktree contains .worktree-ports.json with assigned ports.

3. Cleanup with Safety Checks

Scan all worktrees and stale age.

Inspect dirty trees and branch merge status.

Remove only merged + clean worktrees, or force explicitly.

python scripts/worktree_cleanup.py --repo . --stale-days 14 --format text
python scripts/worktree_cleanup.py --repo . --remove-merged --format text

4. Docker Compose Pattern

Use per-worktree override files mapped from allocated ports. The script outputs a deterministic port map; apply it to docker-compose.worktree.yml.

See docker-compose-patterns.md for concrete templates.

5. Port Allocation Strategy

Default strategy is base + (index * stride) with collision checks:

App: 3000

Postgres: 5432

Redis: 6379

Stride: 10

See port-allocation-strategy.md for the full strategy and edge cases.

Script Interfaces

python scripts/worktree_manager.py --help

Create/list worktrees

Allocate/persist ports

Copy .env* files

Optional dependency installation

python scripts/worktree_cleanup.py --help

Stale detection by age

Dirty-state detection

Merged-branch detection

Optional safe removal

Both tools support stdin JSON and --input file mode for automation pipelines.

Common Pitfalls

Creating worktrees inside the main repo directory

Reusing localhost:3000 across all branches

Sharing one database URL across isolated feature branches

Removing a worktree with uncommitted changes

Forgetting to prune old metadata after branch deletion

Assuming merged status without checking against the target branch

Best Practices

One branch per worktree, one agent per worktree.

Keep worktrees short-lived; remove after merge.

Use a deterministic naming pattern (wt-<topic>).

Persist port mappings in file, not memory or terminal notes.

Run cleanup scan weekly in active repos.

Use --format json for machine flows and --format text for human review.

Never force-remove dirty worktrees unless changes are intentionally discarded.

Validation Checklist

Before claiming setup complete:

git worktree list shows expected path + branch.

.worktree-ports.json exists and contains unique ports.

.env files copied successfully (if present in source repo).

Dependency install command exits with code 0 (if enabled).

Cleanup scan reports no unintended stale dirty trees.

References

port-allocation-strategy.md

docker-compose-patterns.md

README.md for quick start and installation details

Decision Matrix

Use this quick selector before creating a new worktree:

Need isolated dependencies and server ports -> create a new worktree

Need only a quick local diff review -> stay on current tree

Need hotfix while feature branch is dirty -> create dedicated hotfix worktree

Need ephemeral reproduction branch for bug triage -> create temporary worktree and cleanup same day

Operational Checklist

Before Creation

Confirm main repo has clean baseline or intentional WIP commits.

Confirm target branch naming convention.

Confirm required base branch exists (main/develop).

Confirm no reserved local ports are already occupied by non-repo services.

After Creation

Verify git status branch matches expected branch.

Verify .worktree-ports.json exists.

Verify app boots on allocated app port.

Verify DB and cache endpoints target isolated ports.

Before Removal

Verify branch has upstream and is merged when intended.

Verify no uncommitted files remain.

Verify no running containers/processes depend on this worktree path.

CI and Team Integration

Use worktree path naming that maps to task ID (wt-1234-auth).

Include the worktree path in terminal title to avoid wrong-window commits.

In automated setups, persist creation metadata in CI artifacts/logs.

Trigger cleanup report in scheduled jobs and post summary to team channel.

Failure Recovery

If git worktree add fails due to existing path: inspect path, do not overwrite.

If dependency install fails: keep worktree created, mark status and continue manual recovery.

If env copy fails: continue with warning and explicit missing file list.

If port allocation collides with external service: rerun with adjusted base ports.