speckit.spex-worktrees.worktree

Git Worktree Management for spex

Overview

This command manages git worktrees to isolate feature development. It supports four actions:

• create: Called by the after_specify hook after speckit-specify completes. Creates a worktree, restores main, and prints switch instructions.
• ensure: Called by the before_implement hook. Verifies worktree isolation exists. If already in a worktree, proceeds silently. If not, creates one (same as create).
• list: Shows all active feature worktrees with path, branch, and feature name.
• finish: Merges the current worktree's branch into the default branch and removes the worktree. Use when implementation is complete.
• cleanup: Detects worktrees whose branches are merged and offers removal.

Action Routing

Determine the action from the argument:

• If invoked with argument create (from the after_specify hook): the action is create. Execute immediately, no confirmation needed.
• If invoked with argument ensure (from the before_implement hook): the action is ensure. See Action: Ensure below.
• If invoked with argument finish: the action is finish.
• If invoked with argument cleanup: the action is cleanup.
• Otherwise (no args, list, or invoked directly): the action is list.

Prerequisites

The project must be a git repository.

git rev-parse --git-dir >/dev/null 2>&1 || { echo "ERROR: Not a git repository"; exit 1; }

Action: Create

This action runs after speckit-specify has created a feature branch and spec files.

Step 1: Read Configuration

Read base_path from the worktrees extension config (or default to .claude/worktrees):

WORKTREE_CONFIG=".specify/extensions/spex-worktrees/worktree-config.yml"
BASE_PATH=$(yq -r '.worktrees.base_path // ".claude/worktrees"' "$WORKTREE_CONFIG" 2>/dev/null || echo ".claude/worktrees")

Default: .claude/worktrees (inside the project directory, keeps CWD stable in Claude Code).

Step 2: Get Current Branch