--- name: claude-worktree description: Enters a Claude Code worktree at `.claude/worktrees//` with a name derived from the active plan or branch. Use when asked to "enter a worktree", "start a worktree", "work in a worktree", or at the plan-to-execute boundary after `/claude-feature`. Do NOT use to list, clean up, or rotate worktrees (use `git-worktree`). --- # Claude worktree Wrap the `EnterWorktree` entry path with name derivation so the user does not pick a name by hand. ## Guards - If `git rev-parse --git-dir` and `git rev-parse --git-common-dir` differ, the session is already inside a linked worktree. Stop: `❌ Already in a worktree. Run ExitWorktree first.` - If neither command resolves, the session is not in a git repo and no `WorktreeCreate` hook is configured. Stop: `❌ Not a git repository. EnterWorktree needs git or a WorktreeCreate hook.` - If the two match and `git rev-parse --show-superproject-working-tree` prints a path, the session is inside a submodule checkout. Stop: `❌ Inside a submodule of . Run this from there instead.` The submodule guard sits on the matching branch rather than ahead of the first one, and a measurement decided that. Inside a submodule at git 2.43.0 both reads return the same absorbed path under the superproject's `.git/modules/`, so the first guard does not fire and the session proceeds. Every derivation below then reads the submodule as the project: Step 1 resolves the main root to the submodule, the plan lookup reads a `.claude/plans/` the project never wrote, and entry builds `.claude/worktrees/` inside a tree the superproject tracks as a commit. The superproject read is empty in a linked worktree of a submodule and in one of the superproject alike, which is why it separates the two states rather than qualifying the first guard. ## Step 1: resolve the main worktree root Run in parallel: - `git worktree list --porcelain | awk '/^worktree /{print $2; exit}' 2>/dev/null || pwd` - `git branch --show-current 2>/dev/null || echo ""` - `git config --get core.bare 2>/dev/null || echo false` Plans always live at the main root, never inside a linked worktree. See Worktrees in `CLAUDE.md`. `EnterWorktree` writes `core.bare = true` into the shared config, and nothing restores it, so the repository can already be broken before this session arrives. Repair it before entering when the value is `true` and `/.git` is a directory: ```bash git config core.bare false ``` The directory test separates the defect from a genuinely bare repository, which keeps its objects at the root and has no `.git` directory. Announce the repair in one line naming the flag. Leave the file alone when the value is already `false`. ## Step 2: derive the worktree name Try each source in order. Stop at the first match. 0. **Caller-supplied.** The invocation carried an argument. Take it as the name and infer nothing further. Accept `` or `/`, where a leading segment matching a type in `${CLAUDE_SKILL_DIR}/../../standards/branch.md` sets `` and the rest is ``. A bare `` falls to the default type below. 1. **Plan matched to current branch.** Derive `` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. An empty result falls through to the next source here rather than becoming `latest`, since the slug is one candidate among several. If `/.claude/plans/feature-.md` exists, use ``. 2. **Single plan file.** List `/.claude/plans/feature-*.md`. If exactly one match, derive `` from the filename. 3. **Multiple plan files, no branch match.** Ask the user which plan. Show the candidate slugs as a numbered list. Do not pick. 4. **Current branch.** When no plan exists, use the `` from step 1 if it is not `main` or `master`. 4b. **Session context.** When on `main` or `master` with no matching plan, read the current conversation to infer a kebab slug from the topic being discussed. Propose it: `Infer: . Confirm or rename?` Do not enter the worktree until the user confirms or provides a corrected name. 5. **Ask.** None of the above applies. Ask the user for a name. Do not invent one. Tier 0 sits ahead of the inference because every tier below it answers from state the caller cannot set, and a caller that already knows the name has no way to say so. That gap is what a dispatched worker meets. It starts on `main`, so tier 1 cannot match, and a board carrying more than one plan puts tier 2 out of reach too, which lands the run on tier 3 and its instruction to ask somebody who is not there. A prompt naming the branch does not reach any of them, since no tier reads the prompt. Validate the result: letters, digits, dots, underscores, dashes only, max 64 chars (`/` separators are also allowed). If the derived name violates the rule, sanitize by replacing invalid chars with `-` and truncating. Show the sanitized name in the preview before invoking. Resolve `` here as well, since Step 3 previews it and Step 5 renames onto it, drawing the value from the type vocabulary in `${CLAUDE_SKILL_DIR}/../../standards/branch.md`. A type the caller spelled in tier 0 wins outright and no reading overrides it. A name from a plan takes the type that plan's own work carries, read off its `## Summary` and `**Files to touch:**` lines. Every other case takes `feat`, which covers a name from a branch, a bare name from the user, and a plan whose lines settle nothing. The caller's type wins because reading it off a plan is the half that has already disagreed in production. One dispatch checked `fix/path-form-hook` and the worker took `feat/path-form-hook`, both sides reading the same plan and grading it differently. A wrong type is cheap. `git-branch` renames to conventional format later in the same chain and runs ahead of `git-pr`, so a `feat/` written over a fix is corrected before any pull request opens. Then test both names the entry is about to claim. Neither read needs a worktree, and a stop after Step 4 leaves one built with the session sitting inside it, so both belong here rather than beside the rename: - Branch. `git for-each-ref --format='%(refname)' refs/heads// refs/remotes/origin//` printing any ref means the name is taken. Stop: `❌ Branch / already exists. Resolve manually before continuing.` A non-zero exit is a read that failed rather than a free name, so stop on that too and say the read failed. - Directory. `/.claude/worktrees//` existing means an earlier entry claimed the name. Stop: `❌ Worktree .claude/worktrees// already exists. Resolve manually before continuing.` Leave both in place. Resolving either automatically risks the wrong one. The two tests catch different collisions. The branch test misses the one `${CLAUDE_SKILL_DIR}/../../standards/slug.md` records, where two branches differing only in type collapse onto one name: `feat/foo` and `fix/foo` are distinct refs and reach one directory. The directory test is the only read that sees it. The branch test fires on the tier 1 and tier 4 sources whenever the branch the session started on is already conventional, since a name derived from that branch resolves back onto it. Stopping is the answer there. The concern already has a branch, git refuses a second under the same name, and the bare-name rename this replaces only carried the collision forward to the `git-branch` step. It fires on tier 0 as well, where a caller handed a name something already holds. It reads both ref spaces rather than the local head alone, and it reads them the way `checkClaim` does, so a name this skill clears and a branch a dispatcher cleared are one answer. `git show-ref --verify` is what that replaces. It sees no remote-tracking ref, so a branch pushed from elsewhere passed the test and collided at the first push, and its exit code cannot separate an absent ref from a tree it could not read, which reports a failed read as a free name. ## Step 3: preview Output exactly: ```plaintext Worktree: .claude/worktrees// Branch: / Source: ``` Step 2 resolved ``. Show it, since it is the one part of the entry the user cannot read off the name they supplied. ## Step 4: enter Call `EnterWorktree` with `name: ""`. Claude Code's tool permission dialog is the confirmation gate. Do not pause for additional confirmation. ## Step 5: align the branch name and repair the shared config `EnterWorktree` creates a branch named `worktree-`, which diverges from `` and breaks downstream slug derivation in `claude-autoship` and any skill that reads `git branch --show-current`. A bare `` fixes that and fails the branch-format guard in `git-pr`, which requires `/`. Rename to the conventional form, which satisfies both: ```bash git branch -m worktree- / ``` The slug transform drops a leading type segment, so `` is what every downstream derivation reads back out of the typed branch. See `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. Step 2 already cleared the target name, so the rename runs unguarded here. Do not repeat the test. A ref created between the two points is a second session racing this one, which a re-read narrows rather than closes. Skip the rename if the worktree was entered via `path` rather than `name`, since the branch already exists under its own identity. Entry also sets `core.bare = true` in the shared config, which strands the main worktree. Every later command run there fails with `fatal: this operation must be run in a work tree` while the files sit untouched on disk. The linked worktree keeps working, so nothing surfaces until the operator returns to the main checkout. Repeat the Step 1 repair, which writes the parent's config even from inside the linked worktree: ```bash git config core.bare false ``` The flag is not set on every entry, so read before writing and announce only when the write happened. Tracked upstream as `anthropics/claude-code#58345`, closed as not planned, so the repair stays until the tool changes. ## Step 6: report whether the tree can run A linked worktree is a second working directory over one repository, and every ecosystem installs its dependencies into a folder git ignores. Nothing copies that folder across, so a fresh worktree arrives without it and the session learns as much from whichever command needs it first, which reports a missing module rather than an empty working directory. Report the state on one line. Do not install. Entering a worktree to read is as common as entering one to run, and an install is slow, needs a network, and picks an ecosystem on the session's behalf. Read the worktree root and emit the first line that matches: - `package.json` present, `node_modules/` missing: `Dependencies are not installed. Run before any build, test, or server command.` Take `` from the lockfile beside the manifest, and use `bun install` when no lockfile names one. - A `pyproject.toml` or `requirements.txt` present, `.venv/` missing: `No virtual environment. Create and populate one before running anything.` - A manifest present with its folder alongside it: `Dependencies are installed.` - No package manifest of either kind: `No package manifest, so there is nothing to install.` The last line is what keeps the step honest on a stack this skill cannot read. Entry is not stack-aware, and silence is indistinguishable from a check that passed. Then report the port this worktree derives, on a second line: - `scripts/worktree-port.sh` present and exiting zero: run `bash scripts/worktree-port.sh` and emit `Port offset . Every served port adds it to the stack default.` - Present and exiting non-zero: emit `The port helper refuses this directory, so no server here has a port. ` - Absent: `No port derivation installed, so every served port is the stack default.` Branch on the exit rather than on the output, since the helper prints nothing to stdout when it refuses and reading that as a number reports an offset of zero, which is the main checkout's. The helper refuses a folder left behind after its worktree was removed, which Step 4 cannot land on, since it registers whatever it creates. The branch is here so a refusal is never read back as an offset of zero, which is the main checkout's port and the collision the helper exists to prevent. The offset is what `claude-orchestrate` sends a reader here to read rather than assign, and what an operator overrides through `WORKTREE_PORT_OFFSET` when two worktrees derive the same value. Deriving it correctly and printing it nowhere leaves both instructions naming a number no surface emits. Do not invoke `ExitWorktree` from this skill. Exit is the user's call.