Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees following GitLens conventions
This project uses a custom worktree convention. The WorktreeCreate and WorktreeRemove hooks in .claude/settings.json handle automatic worktree creation. This skill documents the conventions for manual worktree operations.
Worktrees live in a sibling directory to the main repo, named <repo-name>.worktrees/:
vscode-gitlens/ # Main repo
vscode-gitlens.worktrees/ # Worktrees root
├── debt/
│ ├── library/ # Branch: debt/library
│ ├── library+<session-id>+agent-x/ # Agent worktree from debt/library
│ └── refactor-home/ # Branch: debt/refactor-home
├── feature/
│ ├── ai-chat/ # Branch: feature/ai-chat
│ └── graph-actions/ # Branch: feature/graph-actions
└── bug/
└── graph-performance/ # Branch: bug/graph-performance
Agent worktrees use delimiters: . This keeps them as siblings to the parent worktree (not nested inside it), groups them by conversation session, and makes it easy to trace back to the originating session.
+<branch>+<session-id>+<agent-name>Branch path segments map directly to directory nesting (e.g., debt/library -> debt/library/).
Follow the conventions in AGENTS.md:
| Type | Prefix | Example |
|---|---|---|
| Feature | feature/ | feature/search-natural-language |
| Bug fix | bug/ | bug/graph-performance |
| Tech debt | debt/ | debt/library |
| With issue | include #N | feature/#1234-search-natural-language |
When creating a worktree manually (not via the hook):
# 1. Find the worktrees root
REPO_ROOT=$(git rev-parse --path-format=absolute --git-common-dir | sed 's|/.git$||')
REPO_NAME=$(basename "$REPO_ROOT")
WORKTREES_ROOT="$REPO_ROOT/../$REPO_NAME.worktrees"
# 2. Create the worktree
git worktree add "$WORKTREES_ROOT/<type>/<name>" -b "<type>/<name>"
# 3. Install dependencies (automatic when using the hook)
cd "$WORKTREES_ROOT/<type>/<name>"
pnpm install
The WorktreeCreate hook automatically runs pnpm install in the new worktree. No manual setup is needed. Skip test baseline verification — builds are expensive in this project; verify after implementation instead.
.worktrees/ directory), not inside.gitignore verification needed — the directory is outside the repo