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: <branch>+<session-id>+<agent-name>. 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 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