Axiomantic Spellbook Using Git Worktrees

Using Git Worktrees

Announce: "Using git-worktrees skill for isolated workspace."

Invariant Principles

1. Directory precedence: existing > CLAUDE.md > ask user (never assume)
2. Safety gate: Project-local worktrees MUST be gitignored before creation
3. Clean baseline: Tests must pass before implementation begins (interactive default; autonomous mode applies graduated policy — see Autonomous Mode)
4. Auto-detect over hardcode: Infer setup from manifest files

Inputs

Outputs

Directory Selection Process

Follow this priority order:

1. Check Existing Directories

ls -d .worktrees 2>/dev/null     # Preferred (hidden)
ls -d worktrees 2>/dev/null      # Alternative

If found: Use that directory. If both exist, .worktrees wins.

2. Check CLAUDE.md

grep -i "worktree.*director" CLAUDE.md 2>/dev/null

If preference specified: Use it without asking.

3. Ask User

If no directory exists and no CLAUDE.md preference:

No worktree directory found. Where should I create worktrees?

1. .worktrees/ (project-local, hidden)
2. ~/.local/spellbook/worktrees/<project-name>/ (global location)

Which would you prefer?

Safety Verification

For Project-Local Directories (.worktrees or worktrees)

MUST verify directory is ignored before creating worktree:

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

If NOT ignored:

1. Add appropriate line to .gitignore
2. Commit the change
3. Proceed with worktree creation

For Global Directory (~/.local/spellbook/worktrees)

No .gitignore verification needed — outside project entirely.

Creation Steps

1. Detect Project Name

project=$(basename "$(git rev-parse --show-toplevel)")

2. Create Worktree

# Determine full path
case $LOCATION in
  .worktrees|worktrees)
    path="$LOCATION/$BRANCH_NAME"
    ;;
  ~/.local/spellbook/worktrees/*)
    path="~/.local/spellbook/worktrees/$project/$BRANCH_NAME"
    ;;
esac

# Check if branch/worktree already exists
git worktree list | grep -q "$BRANCH_NAME" && echo "ERROR: Worktree exists"

# Create worktree with new branch
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

3. Run Project Setup

Auto-detect and run appropriate setup:

if [ -f package.json ]; then npm install; fi
if [ -f Cargo.toml ]; then cargo build; fi
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install || uv sync; fi
if [ -f go.mod ]; then go mod download; fi

If setup fails: Report specific failure. Ask whether to proceed or troubleshoot.

4. Verify Clean Baseline

Run tests to ensure worktree starts clean:

# Use project-appropriate command: npm test / cargo test / pytest / go test ./...

If tests fail: Report failures, ask whether to proceed or investigate.

If tests pass: Report ready.

5. Report Location

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

Autonomous Mode Behavior

Check context for autonomous mode indicators:

• "Mode: AUTONOMOUS" or "autonomous mode"
• worktree preference specified (e.g., "single", "per_parallel_track", "none")

When autonomous mode is active:

Skip These Interactions

• "Where should I create worktrees?" — use default (.worktrees/) or CLAUDE.md preference
• "Tests fail during baseline — ask whether to proceed" — proceed if minor, pause if critical

Make These Decisions Autonomously

• Directory location: Use .worktrees/ as default if no existing directory or CLAUDE.md preference
• Gitignore fix: Always fix automatically (add to .gitignore + commit)
• Minor test failures: Log and proceed; major failures pause

Circuit Breakers (Always Pause For)

• All tests failing (baseline completely broken)
• Git worktree command fails (structural git issue)
• .gitignore cannot be modified (permissions or other issue)

Quick Reference

Common Mistakes

Example Workflow

[Check .worktrees/ - exists]
[Verify ignored - git check-ignore confirms .worktrees/ is ignored]
[Create worktree: git worktree add .worktrees/auth -b feature/auth]
[Run npm install]
[Run npm test - 47 passing]

Worktree ready at /Users/jesse/myproject/.worktrees/auth
Tests passing (47 tests, 0 failures)
Ready to implement auth feature

Before reporting worktree ready — if ANY unchecked, STOP and resolve:

• Directory location follows precedence (existing > CLAUDE.md > asked)
• Project-local path verified gitignored (or global path used)
• git worktree add completed successfully
• Dependencies installed for project type
• Baseline tests pass in new worktree

Integration

Called by:

• design-exploration (Phase 4) — REQUIRED when design is approved and implementation follows
• Any skill needing isolated workspace

Pairs with:

• finishing-a-development-branch — REQUIRED for cleanup after work complete
• executing-plans — Work happens in this worktree (supports both batch and subagent modes)

Converted and distributed by TomeVault — claim your Tome and manage your conversions.