Plan, create, synchronize, recover, and clean up Git worktrees without losing uncommitted work or confusing branch, path, and service state.
A worktree gives you another checkout. It does not automatically isolate ports, databases, caches, credentials, background processes, or ownership. That gap is where parallel work gets messy.
This skill starts with a complete worktree inventory, then turns the requested change into an explicit isolation plan. It records each tree's path, branch or detached commit, dirty and untracked state, lock state, upstream, purpose, and owner. Before any mutation, it shows the exact command, working directory, preconditions, approval, verification, and recovery path.
Use it to split parallel agent or developer work, coordinate branches in a monorepo, repair a moved or stale linked tree, synchronize changes without hiding local work, or remove old trees safely. The package includes a decision rubric, human and JSON report formats, a canonical operation-record schema, and a read-only checker for references, approvals, force flags, and blocker consistency. It does not run Git, recover deleted uncommitted files, or prove repository state by itself.
Input
We need separate worktrees for an API migration, an admin UI change, and a hotfix. Main has one untracked investigation file. The API and admin apps both default to port 3001 and the migration tree must not touch the shared development database. Plan only. Do not create branches, install packages, or start services.
Output
A complete inventory that preserves the untracked file; distinct branch, path, owner, and base decisions for each tree; a collision register for port 3001, the shared database, migration order, and generated output; exact proposed commands with pending approval; baseline and integration checks; and a blocked or limited verdict tied to unresolved ownership and environment decisions.
Provide the repository path, the parallel changes or recovery goal, base and target refs, worktree-path preference, repository setup and test commands, service or data constraints, and the mutations the agent may perform. The skill returns an inventory and ordered command plan first. Live creation, synchronization, recovery, force overrides, and cleanup stay behind explicit authority.
A local Git repository whose main and linked worktrees can be inspected.
A current Git installation with `git worktree list`, `add`, `lock`, `move`, `remove`, `prune`, and `repair` as required by the job.
Project-owned setup, verification, branch, environment, and cleanup rules when they exist.
Optional. Required only to run the bundled read-only JSON operation-record checker.
SKILL.md; worktree decision rubric; human-readable and JSON report formats; canonical worktree-operation schema; read-only operation-record checker; Agent Skills interface metadata
No reviews yet.
Input
The main repository moved from /srv/old/app to /srv/app. Two linked worktrees were also moved. `git worktree list` shows one locked tree at a missing path and another prunable entry. I do not know whether either directory had uncommitted files. Diagnose and return the safest recovery plan. Do not prune, unlock, remove, or force anything.
Output
A state-by-state diagnosis that separates administrative repair from file recovery; read-only inventory and prune dry-run commands; a `git worktree repair` plan using verified new paths; lock-reason and owner checks; explicit warning that Git metadata cannot restore deleted uncommitted files; and no prune or unlock command presented as safe until ownership is resolved.
Input
Return one JSON worktree-operation record. Feature A is merged and clean. Feature B has two modified files and an untracked SQL scratch file. Feature C is detached at a commit that is not on a named branch. A stale missing entry is marked prunable. Prepare cleanup, but no discard, branch deletion, force, or real prune is approved.
Output
One checker-ready JSON object with stable references; separate inventory entries for all trees; an owned disposition decision for Feature B; a branch-retention decision for Feature C; prune dry-run before any cleanup; exact removal preconditions for Feature A; pending approval on mutations; blockers for undispositioned work and detached-commit retention; and a verdict whose blocker IDs match the open decisions.
Creator
Rrevano4
