/worktree

description: "Start a new task in an isolated Git worktree for parallel multi-task development. Creates a task branch, worktree directory with planning files, and leaves the main directory untouched. Usage: /plan-cascade:worktree [task-name] [target-branch]. Example: /plan-cascade:worktree feature-login main"

Planning with Files - Git Worktree Mode

You are now starting a task in **Git Worktree Mode**. This creates an isolated environment for your task with its own branch and directory, enabling **parallel multi-task development**.

Path Storage Modes

Plan Cascade supports two path storage modes for runtime files:

New Mode (Default)

Runtime files are stored in a user directory, keeping the project root clean:

• **Windows**: `%APPDATA%/plan-cascade/<project-id>/.worktree/`
• **Unix/macOS**: `~/.plan-cascade/<project-id>/.worktree/`

Where `<project-id>` is a unique identifier based on the project name and path hash (e.g., `my-project-a1b2c3d4`).

Legacy Mode

Files are stored in the project root for backward compatibility:

• Worktrees: `<project-root>/.worktree/`

To check which mode is active, use:

uv run python -c "from plan_cascade.state.path_resolver import PathResolver; from pathlib import Path; r=PathResolver(Path.cwd()); print('Mode:', 'legacy' if r.is_legacy_mode() else 'new'); print('Worktree dir:', r.get_worktree_dir())"

**Note**: User-visible files like `findings.md` and `progress.md` remain in the worktree directory itself, not in the user data directory.

What is Git Worktree Mode?

Git worktree allows you to have multiple working trees attached to the same repository, each on a different branch. This means:

• **Multiple tasks, no conflicts**: Each task works in its own directory
• **No branch switching**: Stay on your main branch while working on feature branches
• **Isolated environments**: Each task has its own files and planning documents
• **Easy cleanup**: When done, merge and remove the worktree

Step 1: Determine Configuration

First, check for existing worktrees:

git worktree list

If there are existing worktrees, show them to the user and ask if they want to create another one.

Step 2: Parse Parameters

Parse the user's command arguments:

• **Task name**: `{{args}}` - First argument (or use `task-YYYY-MM-DD-HHMM` format for uniqueness)
• **Target branch**: Second argument (or auto-detect `main`/`master`)

Step 3: Verify Git Repository

Check this is a valid git repository:

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

Step 4: Detect Default Branch

DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@refs/remotes/origin/@@')
if [ -z "$DEFAULT_BRANCH" ]; then
    # Fallback detection
    if git show-ref --verify --quiet refs/heads/main; then
        DEFAULT_BRANCH="main"
    elif git show-ref --verify --quiet refs/heads/master; then
        DEFAULT_BRANCH="master"
    else
        DEFAULT_BRANCH="main"
    fi
fi
echo "Default branch detected: $DEFAULT_BRANCH"

Step 5: Determine Task Names and Paths

Set these variables using PathResolver for proper path resolution:

TASK_NAME="{{args|first arg or 'task-' + date + '-' + time}}"
TASK_BRANCH="$TASK_NAME"
TARGET_BRANCH="{{args|second arg or $DEFAULT_BRANCH}}"
ORIGINAL_BRANCH=$(git branch --show-current)
ROOT_DIR=$(pwd)

# Resolve worktree directory using PathResolver
# New mode: ~/.plan-cascade/<project-id>/.worktree/<task-name>
# Legacy mode: <project-root>/.worktree/<task-name>
WORKTREE_BASE=$(uv run python -c "from plan_cascade.state.path_resolver import PathResolver; from pathlib import Path; print(PathResolver(Path.cwd()).get_worktree_dir())" 2>/dev/null || echo ".worktree")
WORKTREE_DIR="$WORKTREE_BASE/$(basename $TASK_NAME)"

Example with command `/plan-cascade:worktree feature-login main`:

• `TASK_NAME = "feature-login"`
• `TASK_BRANCH = "feature-login"`
• `TARGET_BRANCH = "main"`
• `WORKTREE_DIR`:
• **New mode**: `~/.plan-cascade/my-project-a1b2c3d4/.worktree/feature-login`
• **Legacy mode**: `.worktree/feature-login`

Example with no args `/plan-cascade:worktree`:

• `TASK_NAME = "task-2026-01-23-1430"` (includes time for uniqueness)
• `TASK_BRANCH = "task-2026-01-23-1430"`
• `TARGET_BRANCH = "main"` (detected)
• `WORKTREE_DIR`:
• **New mode**: `~/.plan-cascade/my-project-a1b2c3d4/.worktree/task-2026-01-23-1430`
• **Legacy mode**: `.worktree/task-2026-01-23-1430"`

Step 6: Check for Existing Worktree

if [ -d "$WORKTREE_DIR" ]; then
    echo "Worktree already exists: $WORKTREE_DIR"
    echo "This task is already in progress."
    echo "Navigate to: cd $WORKTREE_DIR"
    exit 0
fi

Step 7: Create Git Worktree

Create the actual Git worktree:

# Check if branch already exists in another worktree
if git show-ref --verify --quiet refs/heads/"$TASK_BRANCH"; then
    echo "ERROR: Branch $TASK_BRANCH already exists in another worktree"
    exit 1
fi

# Create the worktree
git worktree add -b "$TASK_BRANCH" "$WORKTREE_DIR" "$TARGET_BRANCH"
echo "Created worktree: $WORKTREE_DIR"

**Important**: This uses `git worktree add` which creates a real separate working directory. The main directory remains unchanged and on its original branch.

Step 8: Create Planning Configuration in Worktree

Save the worktree configuration **inside the worktree directory**:

cat > "$WORKTREE_DIR/.planning-config.json" << EOF
{
  "mode": "worktree",
  "task_name": "$TASK_NAME",
  "task_branch": "$TASK_BRANCH",
  "target_branch": "$TARGET_BRANCH",
  "worktree_dir": "$WORKTREE_DIR",
  "original_branch": "$ORIGINAL_BRANCH",
  "root_dir": "$ROOT_DIR",
  "created_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "planning_files": [
    "task_plan.md",
    "findings.md",
    "progress.md"
  ]
}
EOF

Step 9: Create Planning Files in Worktree

Create the three planning files **inside the worktree directory**:

# Create ta