using-git-worktrees

Using Git Worktrees

Ensure work happens in an isolated workspace. Prefer native harness tools. Fall back to git worktrees only when no native tool is available.

Core principle: Detect isolation first. Use native tools. Then fall back to git. Never fight the harness.

Announce: "Using using-git-worktrees to set up an isolated workspace."

---

Pre-Check: Harness Capability

Read docs/superskills/.skill-init before creating anything:

cat docs/superskills/.skill-init 2>/dev/null || echo "skill-init not run — run it first"

Check TASK_TOOL field. If TASK_TOOL: NO → subagent dispatch won't work in this harness. Check HARNESS field — affects which native worktree tool to try in Step 1a.

---

Step 0: Detect Existing Isolation

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
BRANCH=$(git branch --show-current)

Submodule guard:

git rev-parse --show-superproject-working-tree 2>/dev/null
# If this returns a path → you're in a submodule, treat as normal repo

If GIT_DIR != GIT_COMMON (and not submodule): Already in linked worktree → skip to Step 3.

Report:

• On branch: "Already in isolated workspace at <path> on branch <name>."
• Detached HEAD: "Already in isolated workspace (detached HEAD, externally managed)."

If GIT_DIR == GIT_COMMON: Normal repo. Ask consent before creating worktree:

"Would you like me to set up an isolated worktree? It protects your current branch."

Honor any existing preference without asking again. If user declines → skip to Step 3.

---

Step 1: Create Isolated Workspace

1a. Native Worktree Tool (preferred)

Check for: EnterWorktree, WorktreeCreate, /worktree, --worktree. If available → use it. Skip to Step 3.

Using git worktree add when a native tool exists creates phantom state. Don't.

1b. Git Worktree Fallback (only if no native tool)

Directory selection (priority order):

1. User-declared preference in instructions → use it
2. .worktrees/ exists at project root → use it (verify ignored)
3. worktrees/ exists → use it (verify ignored)
4. ~/.config/superskills/worktrees/<project>/ exists → use it
5. No guidance → default to .worktrees/