Isolating

Announce at start: "I'm applying the isolating skill to set up a separate workspace."

Directory Resolution

Resolve the worktree root in this order — stop at first match:

1. Existing directory — check for .worktrees/ then worktrees/ in repo root
2. CLAUDE.md directive — grep -i "worktree.*director" CLAUDE.md
3. Prompt — offer .worktrees/ (project-local, hidden) or ~/.config/arsyn/worktrees/<project>/ (global)

Gitignore Gate

For project-local directories only:

git check-ignore -q .worktrees 2>/dev/null

If NOT ignored: add to .gitignore, commit, then proceed. Worktree contents tracked in git cause nested-repo confusion that is painful to untangle.

Global directories (~/.config/arsyn/worktrees/) skip this check entirely.

Worktree Lifecycle

# 1. Detect project
project=$(basename "$(git rev-parse --show-toplevel)")

# 2. Create worktree + branch
git worktree add "$WORKTREE_ROOT/$BRANCH_NAME" -b "$BRANCH_NAME"
cd "$WORKTREE_ROOT/$BRANCH_NAME"

# 3. Install dependencies (auto-detect)
# 4. Run test suite for clean baseline

See references/setup-commands.md for dependency installation and test commands by ecosystem.

If baseline tests fail: report failures and ask whether to proceed or investigate. Do not silently continue.

Report when ready:

Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>

Quick Reference

Gotchas

• Shared database state — Worktrees share git objects but not app state. A migration in one worktree affects every worktree hitting the same database. Coordinate or use separate databases.
• Stale worktrees accumulate — Merged branches leave orphaned worktrees. git worktree list to audit; git worktree remove to clean.
• Wrong base branch — Creating from a stale local ref instead of latest main/develop. Always git fetch and branch from the updated remote tip.
• Forgetting ignore verification — The single most common mistake. Project-local worktree directories that aren't gitignored pollute git status and risk accidental commits.

Integration

Called by:

• ideating (Phase 4) — when design is approved and implementation follows
• orchestrating — before dispatching subagent tasks
• executing — before running plan batches

Pairs with:

• finalizing — cleans up the worktree after work completes