worktrees

Orchestrates Git worktrees as isolated coding lanes for parallel and risky development work.

1|Updated Mar 15, 2025
One-click install
npx skills add https://github.com/adikpb/dotfiles --skill worktrees-adikpb
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: worktrees
Source: https://github.com/adikpb/dotfiles/tree/main/.config/opencode/skills/worktrees
Command: npx skills add https://github.com/adikpb/dotfiles --skill worktrees-adikpb

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Managing parallel branches, risky refactors, or background agent work in a single Git checkout leads to context switching, half-committed states, and broken working environments. This Skill provides a safe, structured protocol for creating, tracking, integrating, and cleaning up Git worktrees as isolated coding lanes. ## Core Features & Use Cases - Isolated Lane Management: Creates worktrees under .slim/worktrees/<slug>/ with consistent branch naming and a .slim/worktrees.json manifest for structural state tracking. - Safety Guardrails: Enforces pre-flight checks, mandatory user confirmation before any Git mutation, and managed .gitignore/.ignore blocks to keep lane artifacts local. - Full Lifecycle Workflow: Covers planning, delegation to sub-agents, diff validation, integration, and cleanup across four defined phases. - Use Case: You need to refactor an authentication flow while keeping your main checkout stable. The Orchestrator creates a worktree lane, assigns a specialist agent to work inside it, validates the diff against the base branch, and merges only after your approval. ## Quick Start Ask the Orchestrator to create a worktree lane for your task, for example: set up an isolated worktree to refactor the authentication module on a new branch.

Frequently Asked Questions about worktrees

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a Git worktree for parallel development?▼

Run git worktree add -b <branch> .slim/worktrees/<slug> <base> after confirming the repository state and branch name availability. This Skill automates the pre-flight checks, ignore-file setup, and manifest registration around that command.

When should I use Git worktrees instead of branches?▼

Use worktrees for risky refactoring, parallel tasks, background agents, or exploratory spikes that would disrupt your active checkout. Avoid them for simple single-file changes, documentation updates, or minor bug fixes.

Can multiple agents work in separate Git worktrees safely?▼

Yes, each sub-agent runs with its working directory set to its own worktree path, keeping builds and edits isolated. Track file or folder ownership per lane to prevent merge conflicts between parallel agents.

Why does git worktree remove fail on my lane?▼

Removal fails when the worktree has uncommitted changes or untracked files. Commit or archive all changes first, verify a clean state, then run git worktree remove with explicit user approval.

Does this workflow work with nested worktrees inside the repository?▼

Yes, lanes live under .slim/worktrees/ inside the repository rather than as sibling directories. The managed .gitignore and .ignore blocks keep these nested worktrees hidden from Git while remaining readable to tooling.