/spec-worktree

name: spec-worktree
description: Internal helper for caller-owned git worktree isolation. Governed callers are spec-dogfood and spec-work; every caller must provide the forward invocation and intake contract.
user-invocable: false
allowed-tools: Bash(bash *worktree-manager.sh*)

Worktree Isolation

Detect whether the current checkout is already isolated, then create or attach a worktree under `.worktrees/<slug>` only when isolation is still needed. The bundled script adds branch-specific setup that `git worktree add` alone does not handle:

• Does not copy `.env*` files by default; `--copy-env` is an explicit opt-in for workflows that need local env files
• Detects `mise`/`direnv` configs and prints review commands without changing user trust state
• Adds `.worktrees` to `.gitignore` if not already ignored
• Does not modify the main repo checkout — `from-branch` and PR heads are fetched, not checked out

Step 0: Detect existing isolation

Before creating anything, invoke the bundled script with `detect --json` through the same `bash -c` wrapper whose command text includes `exec bash ...worktree-manager.sh`:

bash -c 'if [ -n "${CLAUDE_SKILL_DIR:-}" ]; then exec bash "$CLAUDE_SKILL_DIR/scripts/worktree-manager.sh" "$@"; fi; exec bash "$(git rev-parse --show-toplevel)"/"skills/spec-worktree/scripts/worktree-manager.sh" "$@"' _ detect --json

The output is the deterministic facts contract `spec-worktree-detect.v1`:

{
  "schema_version": "spec-worktree-detect.v1",
  "state": "ordinary-checkout | linked-worktree | submodule | unknown",
  "reason_code": "same-git-dir | linked-worktree | submodule-superproject | not-git-repo | git-query-failed | output-contract-failed",
  "worktree_root": "<absolute path or null>",
  "main_worktree_root": "<absolute path or null>",
  "git_dir": "<resolved absolute path or null>",
  "common_dir": "<resolved absolute path or null>",
  "branch": "<current branch or null>"
}

`state=ordinary-checkout` and `state=submodule` mean creation may proceed if the workflow still needs isolation. For `state=submodule`, the new worktree is created under the submodule's own working tree (`<submodule-root>/.worktrees/<branch>`), not the superproject. `state=linked-worktree` means the current checkout is already isolated; report `worktree_root` and `branch`, then work in place instead of creating another worktree. `state=unknown` or any non-zero detect exit means stop and report `reason_code`; do not fall back to raw `git worktree add`.

The script computes this by comparing resolved absolute `--absolute-git-dir` and resolved absolute `--git-common-dir`. Equal paths are an ordinary checkout. Different paths plus non-empty `--show-superproject-working-tree` are a submodule. Different paths plus empty superproject output are an existing linked worktree.

`detect --json` requires `node` on `PATH` to serialize the facts. When `node` is missing the command still prints a parseable `state=unknown`/`reason_code=output-contract-failed` object and exits non-zero, so a consumer always gets a structured reason_code rather than empty output.

Choose the mode

There are two modes. The caller must choose one before invoking the script:

• **New work:** create a fresh branch from a base branch. Use this when the task has no existing ref to test or modify.
• **Isolate an existing ref:** attach a worktree to a PR head, existing branch, tag, or commit. Use this for PR review, dogfood, or any workflow that needs to test a target ref without switching the primary checkout.

A branch can be checked out in only one worktree at a time. In existing-ref mode, if the target branch is already checked out anywhere, the script reports `already_checked_out branch=<name> path=<path>` and exits 0 without creating a second checkout. The caller must act on that verdict: work at the reported path, ask the user, or stop. Never force a duplicate branch checkout.

Creating a new-work worktree

Invoke the bundled script through a `bash -c` wrapper whose command text includes `exec bash ...worktree-manager.sh`. On Claude Code, `${CLAUDE_SKILL_DIR}` resolves to the skill's own runtime directory across marketplace-cached installs and local plugin development. In source or non-Claude runtime contexts, use the repo-root fallback path so generated Codex assets can rewrite it to the installed skill directory. This shape intentionally matches the narrow `allowed-tools` pattern.

bash -c 'if [ -n "${CLAUDE_SKILL_DIR:-}" ]; then exec bash "$CLAUDE_SKILL_DIR/scripts/worktree-manager.sh" "$@"; fi; exec bash "$(git rev-parse --show-toplevel)"/"skills/spec-worktree/scripts/worktree-manager.sh" "$@"' _ create [--copy-env] <branch-name> [from-branch]

Defaults:

• `from-branch` defaults to origin's default branch (or `main` if that cannot be resolved)
• The new branch is created at `origin/<from-branch>` (or the local ref if the remote is unavailable)
• `.env*` files are not copied unless `--copy-env` is passed

Examples:

bash -c 'if [ -n "${CLAUDE_SKILL_DIR:-}" ]; then exec bash "$CLAUDE_SKILL_DIR/scripts/worktree-manager.sh" "$@"; fi; exec bash "$(git rev-parse --show-toplevel)"/"skills/spec-worktree/scripts/worktree-manager.sh" "$@"' _ create feat/login
bash -c 'if [ -n "${CLAUDE_SKILL_DIR:-}" ]; then exec bash "$CLAUDE_SKILL_DIR/scripts/worktree-manager.sh" "$@"; fi; exec bash "$(git rev-parse --show-toplevel)"/"skills/spec-worktree/scripts/worktree-manager.sh" "$@"' _ create fix/email-validation develop
bash -c 'if [ -n "${CLAUDE_SKILL_DIR:-}" ]; then exec bash "$CLAUDE_SKILL_DIR/scripts/worktree-manager.sh" "$@"; fi; exec bash "$(git rev-parse --show-toplevel)"/"skills/spec-worktree/scripts/worktree-manager.sh" "$@"' _ create --copy-env feat/local-env

After creation, switch to the worktree with `cd .worktrees/<branch-name>`.

The `create` command consumes the same detection function before creating `.worktrees/<branch>` or running `git worktree add`. It refuse