spec-worktree

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
• Trusts mise/direnv configs, with branch-aware safety rules so review branches do not auto-grant trust to untrusted .envrc content
• 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)"/".claude/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.