worktree

name	worktree
description	Create a Git worktree for a new task. This skill should be used when the user asks to "start working on", "implement", "fix", "add", "refactor", "migrate", or otherwise begin a code task that requires a new branch. Do not use for trivial tasks like reading files, answering questions, or changes to the current dotfiles repo.
allowed-tools	Bash(git *), Bash(git -C *), Read, Glob

Worktree

Create a Git worktree for a new task, following the project's worktree protocol.

Why this skill exists

The worktree protocol (AGENTS.md lines 120–143) is multi-step and easy to get wrong: forgetting to fetch, branching from a stale default, creating in the wrong directory. This skill automates the full procedure.

Arguments

$ARGUMENTS — description of the task (used to derive the branch/worktree slug).

Workflow

1. Resolve the main checkout

Determine the main repo checkout path:

• First resolve Git's common dir with git -C <cwd-or-main> rev-parse --path-format=absolute --git-common-dir.
• If the common dir ends in /.git, the main checkout is its parent directory.
• This works for both legacy repo-local worktrees and preferred worktrees under ~/Developer/git-worktrees/<repo>/<branch>.
• Legacy example: /Users/gio/Developer/my-repo/.git-worktrees/feature-x → /Users/gio/Developer/my-repo.
• Preferred example: /Users/gio/Developer/git-worktrees/my-repo/feature-x → /Users/gio/Developer/my-repo.

Verify the resolved path is a git repo with git -C <main> rev-parse --git-dir.

2. Discover the default branch

git -C <main> remote show origin | grep 'HEAD branch'

Parse the branch name (e.g., main, trunk, master).

3. Fetch

git -C <main> fetch origin

4. Derive the worktree slug

From $ARGUMENTS or the task description, create a short slug:

• Lowercase, hyphen-separated, no special characters.
• Keep it under ~30 characters.
• Example: "Add user authentication" → add-user-auth.

5. Create the worktree

Resolve the preferred and legacy worktree roots in this order:

• Preferred root: ~/Developer/git-worktrees/<repo-name>/
• Legacy root: <main>/.git-worktrees/

Search the preferred root first when checking for existing migrated worktrees. Only fall back to the legacy root when the preferred root is absent or the repo has not been migrated yet.

New worktrees always go in the preferred root. If the repo still has legacy worktrees under <main>/.git-worktrees/, suggest running git-worktree-migrate <main> to migrate them.

Create the preferred root if needed, then add the new worktree there.

git -C <main> worktree add ~/Developer/git-worktrees/<repo-name>/<slug> -b <slug> origin/<default>

6. Bootstrap

Discover and run any repo-defined bootstrap procedure so the new worktree is ready to build and test.

• Read the new worktree's agent instructions file (AGENTS.md, CLAUDE.md, etc.) and look for a section titled "Bootstrap" — or an equivalent label.
• Run the command(s) that section names, in the new worktree, as a background task so the rest of the session can continue in parallel.
• If no such section exists, surface that to the user as a finding — do not guess.

7. Report

Print the worktree path, the branch's upstream, and the bootstrap status. Example:

Worktree created at /Users/gio/Developer/git-worktrees/my-repo/add-user-auth. Branch add-user-auth tracking origin/main. Bootstrap running in background (per AGENTS.md § Bootstrap).

Constraints

• Never use git --git-dir or cd path && — use git -C for all operations.
• Whether a task warrants a worktree at all is decided by the branching rules in agents/rules/git.md, not here.
• If already inside a worktree for a different task, resolve back to the main checkout before creating.
• New worktrees go in ~/Developer/git-worktrees/<repo-name>/.
• .git-worktrees/ is legacy fallback only.