model: claude-sonnet-4-6

create-worktree

Create a worktree and flip this session into it in one step, using Claude Code's native worktree support so you also get .worktreeinclude copying, worktree.baseRef, and native cleanup for free.

Inputs & confirmation

At any step, if a required input is missing or the safe path is ambiguous, stop and use AskUserQuestion before acting — don't assume a default that changes what gets created. Confirm when unclear:

• the worktree name / task — if none was given, ask what to build and what to name it; never invent a slug from nothing;
• the source — new branch vs. existing branch / issue / PR;
• the base ref, when it isn't the default and wasn't given;
• whether to enter the new worktree now.

1. Decide the name and source

Derive a short, meaningful kebab-case slug from what the user is building (e.g. fix-login-redirect, add-csv-export). Never use generic names like worktree-1. Resolve the source:

• Plain task / branch name → use the slug directly.
• GitHub issue (#123 / issue URL) → gh issue view <n> --json number,title, then slug = issue-<n>-<short-title-slug>. Remember the issue to reference in the PR later.
• GitHub PR (#123 / PR URL) → this is the existing-worktree path (see 2b).
• --base <ref> → only meaningful via the fallback in 2c; native creation uses the worktree.baseRef setting.

If it's ambiguous (new vs. existing branch, which base), ask with AskUserQuestion first.

2. Create and enter

2a. New branch — preferred (native, auto-flips)

Call the EnterWorktree tool with name: <slug>. Native Claude Code then, in one atomic step: creates the worktree under .claude/worktrees/<slug>/, branches per the worktree.baseRef setting (default: fresh from origin/<default>), copies .worktreeinclude files, fires any WorktreeCreate hook, and switches this session's working directory into the worktree. The branch is typically named worktree-<slug>.

EnterWorktree with name is rejected if the session is already inside a worktree. If so, either ExitWorktree (action keep) back to the main checkout first, or create the new branch with git worktree add and enter it via path (2b).

2b. From a PR, or entering an existing worktree

git fetch origin
git worktree add ".claude/worktrees/pr-<n>" -b "<headRefName>" --track "origin/<headRefName>"

Then call EnterWorktree with path: .claude/worktrees/pr-<n> to flip in. (Cross-fork PRs may need the fork added as a remote first — say so if the fetch fails.)

2c. Fallback when EnterWorktree is unavailable (e.g. -p/non-interactive)

bash "${CLAUDE_PLUGIN_ROOT}/scripts/wt-create.sh" "<slug>" [base-ref]

It prints the worktree path on its last stdout line. The session can't auto-flip here — tell the user to cd <path> or run claude --worktree <slug>.

3. Ensure the worktree tree is gitignored (deterministic)

Native creation does not touch .gitignore, so the new .claude/worktrees/ tree would otherwise surface as untracked files in the main checkout. Once the worktree exists (2a/2b), run the idempotent helper:

bash "${CLAUDE_PLUGIN_ROOT}/scripts/wt-ensure-gitignore.sh"

It targets the main checkout's .gitignore even when run from inside the worktree, creates it if the repo has none, and is a no-op if the rule is already present. (The 2c fallback already does this internally — re-running is harmless.)

4. Per-project setup (opt-in, deterministic)

Once inside the worktree, run the setup helper. It deterministically runs .claude/worktree-setup.sh if the project has one (install deps, init a local DB, etc.) and is a safe no-op otherwise — so this step always behaves the same:

bash "${CLAUDE_PLUGIN_ROOT}/scripts/wt-run-optin.sh" setup

Don't hand-run an install instead. (Setup is scoped to user-initiated creation on purpose — it deliberately does not run for every subagent-isolation worktree.)

5. Report

Confirm: you're now working in the worktree, the branch, the base it was cut from, env files copied, and whether setup ran. When done, /worktree-ops:merge-worktree ships it and cleans up.