Worktree

Git Worktree Skill

Create an isolated worktree under .worktrees/, install dependencies, and verify a test baseline. The point is to give the user a fresh, fully-configured workspace without polluting the main checkout — which matters when running multiple parallel feature branches or when the main checkout has in-progress changes you don't want to disturb.

Input

$ARGUMENTS is the branch name (e.g. feat/my-feature, fix/bug-123). If missing, prompt the user — guessing a branch name is worse than asking.

Workflow

Validate the environment

# Check git version supports worktrees (2.5+)
git --version

# Verify we're in a git repository
git rev-parse --git-dir

If not in a git repo, stop with error: "Not a git repository. Run this from a project root."

Ensure .worktrees/ is gitignored

Check if .worktrees/ is in .gitignore:

# Check if .worktrees is already ignored
grep -q "^\.worktrees" .gitignore 2>/dev/null && echo "already-ignored" || echo "needs-adding"

If not ignored:

1. Append .worktrees/ to .gitignore
2. Stage and commit the change:

echo ".worktrees/" >> .gitignore
git add .gitignore
git commit -m "chore: add .worktrees to gitignore"

Report: ".worktrees/" added to .gitignore and committed

Check for an existing worktree

# List existing worktrees
git worktree list

# Check if target worktree already exists
ls -d .worktrees/$BRANCH_NAME 2>/dev/null && echo "exists" || echo "new"

If worktree exists:

• Report: "Worktree already exists at .worktrees/$BRANCH_NAME"
• Skip creation, proceed to verification steps (Step 6)

Create the worktree

# Create the worktree with a new branch
git worktree add .worktrees/$BRANCH_NAME -b $BRANCH_NAME

# Or if branch already exists:
git worktree add .worktrees/$BRANCH_NAME $BRANCH_NAME

Handle errors:

• If branch exists but not as worktree: use existing branch
• If path exists but not registered: git worktree prune then retry

Report: "Created worktree at .worktrees/$BRANCH_NAME"

Run the setup files

Change into the worktree and run whatever project-level setup the repo defines. The order matters — install deps first so subsequent steps have a working environment.

cd .worktrees/$BRANCH_NAME

INSTALL.md (required)

Check for INSTALL.md:

ls INSTALL.md 2>/dev/null && echo "found" || echo "missing"

If found:

• Read INSTALL.md
• Follow installation instructions (typically bun install, npm install, etc.)
• Report each step executed

If missing:

• Warning: "No INSTALL.md found. Attempting common install commands..."
• Try in order:
  1. bun install (if bun.lockb exists)
  2. npm install (if package-lock.json exists)
  3. yarn install (if yarn.lock exists)
• If none work, report: "Could not auto-detect package manager. Manual setup may be required."

RUN.md (optional)

Check for RUN.md:

ls RUN.md 2>/dev/null && echo "found" || echo "missing"

If found:

• Read RUN.md
• Note startup instructions (don't auto-run services unless explicitly requested)
• Report: "RUN.md found. See instructions for starting dev environment."

If missing:

• No action needed
• Report: "No RUN.md found (optional)"

FEEDBACK_LOOPS.md (optional, recommended)

Check for FEEDBACK_LOOPS.md:

ls FEEDBACK_LOOPS.md 2>/dev/null && echo "found" || echo "missing"

If found:

• Read FEEDBACK_LOOPS.md
• Note available feedback tools (test commands, linters, etc.)
• Report: "FEEDBACK_LOOPS.md found. Feedback tools available for verification."

If missing:

• Report: "No FEEDBACK_LOOPS.md found. Consider creating one for consistent verification."
• Suggest creating FEEDBACK_LOOPS.md with common checks:

  Suggested FEEDBACK_LOOPS.md structure:
  - Test command (e.g., bun test)
  - Type checking (e.g., tsc --noEmit)
  - Linting (e.g., eslint .)
  - Build verification (e.g., bun run build)
  

Verify the test baseline

Run the test suite once before handing the workspace to the user. The reason this matters is diagnostic: if a test fails later, they need to know whether they introduced the failure or inherited it.

# Detect and run tests
if [ -f "package.json" ]; then
  # Try common test commands
  bun test 2>/dev/null || npm test 2>/dev/null || yarn test 2>/dev/null || echo "no-tests"
fi

If tests pass:

• Report: "Test baseline verified. All tests passing."

If tests fail:

• Warning: "Test baseline has failures. Review before starting development."
• List failing tests
• Ask: "Proceed anyway? (Tests may have been failing before your changes)"

If no tests:

• Note: "No test suite detected."

Final report

Worktree Setup Complete

Location: .worktrees/$BRANCH_NAME
Branch: $BRANCH_NAME

Setup Status:
  .gitignore: [Updated/Already configured]
  Dependencies: [Installed/Failed/Manual required]
  RUN.md: [Found/Not present]
  FEEDBACK_LOOPS.md: [Found/Not present (recommended)]
  Test Baseline: [Passing/Failing/No tests]

Next Steps:
  1. cd .worktrees/$BRANCH_NAME
  2. Start development (see RUN.md if present)
  3. Run tests frequently to catch regressions

To remove worktree when done:
  git worktree remove .worktrees/$BRANCH_NAME

Idempotency

This skill is safe to run multiple times:

• Detects existing worktrees and skips creation
• .gitignore check is additive
• Setup files can be re-executed
• Test baseline always runs for verification

Error handling

Integration with SDLC

When invoked from /sdlc:implement or similar workflows:

• Return the worktree path for subsequent operations
• Report setup status for workflow awareness
• Any warnings should be propagated to parent workflow

Example Usage

Manual invocation:

/worktree feat/new-feature

Skill invocation:

Skill(primitives:worktree, args: "feat/new-feature")

Expected output:

Creating worktree for feat/new-feature...

[1/6] Checking .gitignore... already configured
[2/6] Creating worktree... done
[3/6] Installing dependencies... bun install complete (1.2s)
[4/6] Checking RUN.md... found
[5/6] Checking FEEDBACK_LOOPS.md... found
[6/6] Running test baseline... 42 tests passed

Worktree ready at .worktrees/feat/new-feature