feat: Add git workflow configuration to specify init

[brianluby]

Summary

Add the ability to configure git worktree mode during project initialization via specify init, allowing users to develop multiple features simultaneously in parallel directories.

New CLI Options

Option	Values	Default	Description
--git-mode	branch / worktree	branch	Git workflow mode
--worktree-strategy	sibling / nested / custom	sibling	Worktree location
--worktree-path	absolute path	-	Custom path (if strategy is custom)

Key Features

• Interactive selection for git workflow when options not provided
• Git 2.5+ version check before allowing worktree mode
• Conflict detection for --no-git + --git-mode worktree
• Worktree location preview before confirmation
• Auto-add .worktrees/ to .gitignore for nested strategy
• Prominent agent notification when worktree mode is used (via specify.md template)
• Naming convention: <repo>-<branch> for sibling/custom strategies

Usage Examples

# Interactive mode
specify init my-project --ai claude

# Explicit worktree with sibling strategy
specify init my-project --git-mode worktree --worktree-strategy sibling

# Worktree with nested strategy
specify init my-project --git-mode worktree --worktree-strategy nested

Test Plan

• Test specify init with --git-mode worktree --worktree-strategy sibling
• Test specify init with --git-mode worktree --worktree-strategy nested
• Verify .gitignore updated for nested strategy
• Test conflict detection: --no-git --git-mode worktree
• Test with Git < 2.5 (should error gracefully)
• Run /speckit.specify and verify worktree created with correct naming
• Verify agent notification appears in worktree mode

AI Disclosure

This PR was developed with assistance from Claude Code (Claude Opus 4.5). Changes were tested and reviewed by the contributor.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR adds comprehensive git worktree support to Spec Kit, enabling users to develop multiple features simultaneously in parallel directories instead of switching branches in a single working copy. The implementation allows project initialization with worktree configuration via new CLI options.

Changes:

• Added CLI options for git workflow mode selection (branch vs worktree) with three worktree strategies (sibling, nested, custom)
• Implemented git version checking to ensure Git 2.5+ for worktree support
• Created configuration persistence in .specify/config.json with merge support
• Updated shell scripts (bash and PowerShell) to support worktree creation with automatic fallback to branch mode
• Modified agent instruction templates to notify about worktree directory switching requirements

Reviewed changes

Copilot reviewed 13 out of 14 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/specify_cli/init.py	Added CLI options, git version validation, interactive selection, config writing, and user notifications for worktree workflow
templates/commands/specify.md	Added instructions for agents to handle worktree mode and display directory switching warnings
scripts/bash/create-new-feature.sh	Implemented worktree path calculation and creation logic with fallback to branch mode
scripts/powershell/create-new-feature.ps1	PowerShell equivalent of bash worktree implementation
scripts/bash/configure-worktree.sh	New script for post-init worktree configuration changes
scripts/powershell/configure-worktree.ps1	PowerShell equivalent of configure-worktree script
scripts/bash/common.sh	Added read_config_value function for config file parsing
scripts/powershell/common.ps1	Added Get-ConfigValue function for config file parsing
.specify/scripts/bash/*	Template copies of bash scripts for distribution
WORKTREE_DESIGN.md	Design documentation for worktree feature architecture
specs/001-git-worktrees/CHANGELOG.md	Comprehensive feature changelog and usage documentation
.gitignore	Added exclusions for config.json and .worktrees/ directory

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The worktree notice at line 1470 hardcodes the bash script path ".specify/scripts/bash/configure-worktree.sh", but users who selected PowerShell as their script type (via --script ps or interactive selection) would need to use ".specify/scripts/powershell/configure-worktree.ps1" instead. The notice should use the selected_script variable to show the appropriate script path for the user's chosen script type.

Suggested change

	worktree_notice = Panel(
	f"[bold]Git Worktree Mode Enabled[/bold]\n\n"
	f"When you run [cyan]/speckit.specify[/cyan], each feature will be created in its own directory {location_desc}.\n\n"
	f"[yellow]Important:[/yellow] After creating a feature, you must switch your coding agent/IDE to the new worktree directory to continue working on that feature.\n\n"
	f"To change this later, run: [cyan].specify/scripts/bash/configure-worktree.sh --show[/cyan]",
	configure_worktree_script_map = {
	"bash": ".specify/scripts/bash/configure-worktree.sh",
	"ps": ".specify/scripts/powershell/configure-worktree.ps1",
	}
	configure_worktree_script = configure_worktree_script_map.get(
	selected_script,
	configure_worktree_script_map["bash"],
	)
	worktree_notice = Panel(
	f"[bold]Git Worktree Mode Enabled[/bold]\n\n"
	f"When you run [cyan]/speckit.specify[/cyan], each feature will be created in its own directory {location_desc}.\n\n"
	f"[yellow]Important:[/yellow] After creating a feature, you must switch your coding agent/IDE to the new worktree directory to continue working on that feature.\n\n"
	f"To change this later, run: [cyan]{configure_worktree_script} --show[/cyan]",

[Copilot]

There's a duplicate file read operation inside the gitignore update block. Lines 1377-1378 open and read the file to check if content ends with a newline, but this same file was just read at lines 1366-1367. The content from the first read should be reused to avoid redundant I/O operations.

[Copilot]

The worktree strategy default value inconsistency could lead to confusion. In the Python CLI at line 1161, the default is set to "sibling", but in multiple other locations (bash/PowerShell scripts at lines with read_config_value calls, and in WORKTREE_DESIGN.md at line 22), the default is "nested". This inconsistency means the behavior will differ depending on whether a user explicitly sets the strategy during init or relies on defaults in the scripts.

Suggested change

	selected_worktree_strategy = "sibling" # Default
	selected_worktree_strategy = "nested" # Default

[Copilot]

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated 15 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The naming convention for custom strategy is inconsistent with the Python init command. The init command uses repo_name-branch_name format (e.g., "/tmp/worktrees/spec-kit-001-user-auth"), but this calculate_worktree_path function uses just branch_name. This will cause worktrees to be created in different locations than what was previewed during init.

[Copilot]

The default value for worktree_strategy in the scripts is "nested", but the init command and documentation state the default is "sibling". This creates an inconsistency where the --show command will display "nested" as default instead of "sibling".

[Copilot]

The default value for worktree_strategy should be "sibling" to match the constants and init command default, not "nested". This inconsistency could cause unexpected behavior where users select "sibling" during init but the script defaults to "nested".

[Copilot]

The default value for worktree_strategy in the scripts is "nested", but the init command and documentation state the default is "sibling". This creates an inconsistency where the --show command will display "nested" as default instead of "sibling".

[Copilot]

The naming convention for custom strategy is inconsistent with the Python init command. The init command uses repo_name-branch_name format (e.g., "/tmp/worktrees/spec-kit-001-user-auth"), but this calculate_worktree_path function uses just branch_name. This will cause worktrees to be created in different locations than what was previewed during init.

Suggested change

	strategy=$(read_config_value "worktree_strategy" "nested")
	custom_path=$(read_config_value "worktree_custom_path" "")
	case "$strategy" in
	nested)
	echo "$repo_root/.worktrees/$branch_name"
	;;
	sibling)
	# Sibling to the repository
	echo "$(dirname "$repo_root")/$branch_name"
	;;
	custom)
	if [[ -n "$custom_path" ]]; then
	echo "$custom_path/$branch_name"
	else
	# Fallback to nested if custom path not set
	echo "$repo_root/.worktrees/$branch_name"
	fi
	;;
	*)
	# Default to nested
	echo "$repo_root/.worktrees/$branch_name"
	local repo_name
	local worktree_dir_name
	strategy=$(read_config_value "worktree_strategy" "nested")
	custom_path=$(read_config_value "worktree_custom_path" "")
	# Use same naming convention as Python init: repo_name-branch_name
	repo_name="${repo_root##*/}"
	worktree_dir_name="${repo_name}-${branch_name}"
	case "$strategy" in
	nested)
	echo "$repo_root/.worktrees/$worktree_dir_name"
	;;
	sibling)
	# Sibling to the repository
	echo "$(dirname "$repo_root")/$worktree_dir_name"
	;;
	custom)
	if [[ -n "$custom_path" ]]; then
	echo "$custom_path/$worktree_dir_name"
	else
	# Fallback to nested if custom path not set
	echo "$repo_root/.worktrees/$worktree_dir_name"
	fi
	;;
	*)
	# Default to nested
	echo "$repo_root/.worktrees/$worktree_dir_name"

[Copilot]

The naming convention for sibling strategy is inconsistent with the Python init command. The init command uses repo_name-branch_name format (e.g., "spec-kit-001-user-auth"), but this calculate_worktree_path function uses just branch_name for sibling strategy. This will cause worktrees to be created in different locations than what was previewed during init.

[Copilot]

The default value for worktree_strategy in the scripts is "nested", but the init command and documentation state the default is "sibling". This creates an inconsistency where the --show command will display "nested" as default instead of "sibling".

[Copilot]

The default value for worktree_strategy in the scripts is "nested", but the init command and documentation state the default is "sibling". This creates an inconsistency where the --show command will display "nested" as default instead of "sibling".

Suggested change

	echo " worktree_strategy: nested"
	echo " worktree_custom_path: (none)"
	else
	echo "Current configuration ($CONFIG_FILE):"
	echo " git_mode: $(read_config_value "git_mode" "branch")"
	echo " worktree_strategy: $(read_config_value "worktree_strategy" "nested")"
	echo " worktree_strategy: sibling"
	echo " worktree_custom_path: (none)"
	else
	echo "Current configuration ($CONFIG_FILE):"
	echo " git_mode: $(read_config_value "git_mode" "branch")"
	echo " worktree_strategy: $(read_config_value "worktree_strategy" "sibling")"

[Copilot]

The default value for worktree_strategy in the scripts is "nested", but the init command and documentation state the default is "sibling". This creates an inconsistency where the --show command will display "nested" as default instead of "sibling".

[Copilot]

The default value for worktree_strategy in the scripts is "nested", but the init command and documentation state the default is "sibling". This creates an inconsistency where the --show command will display "nested" as default instead of "sibling".

[Copilot]

Pull request overview

Copilot reviewed 15 out of 16 changed files in this pull request and generated 5 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The worktree creation logic has a duplicated conditional check. Lines 360-383 check if [ "$GIT_MODE" = "worktree" ] to set up the parent directory, and then lines 385-414 check the same condition again for the actual worktree creation. These checks should be combined into a single conditional block to improve code clarity and avoid the redundant condition evaluation.

[Copilot]

Similar to the bash script, the worktree creation logic has a duplicated conditional check. Lines 332-369 check if ($gitMode -eq "worktree") to set up the parent directory, and then lines 371-415 check the same condition again for the actual worktree creation. These checks should be combined into a single conditional block to improve code clarity and avoid the redundant condition evaluation.

[Copilot]

The CHANGELOG states "Automatic fallback to branch mode when worktree creation fails" which is inaccurate. Looking at the code in scripts/bash/create-new-feature.sh lines 385-414 and scripts/powershell/create-new-feature.ps1 lines 371-415, when worktree creation fails, the scripts exit with error code 1 and display error messages. There is no automatic fallback to branch mode. The error handling explicitly calls exit 1 after displaying suggestions.

Suggested change

	- Automatic fallback to branch mode when worktree creation fails (e.g., unwritable paths)
	- Clear, actionable error messages and non-zero exit when worktree creation fails (no automatic fallback to branch mode)

[Copilot]

The design document describes a rollback plan that mentions "fall back to standard branch creation with a warning" if worktree creation fails. However, the actual implementation in the scripts exits with an error instead of falling back. This is inconsistent with the design document. Either the design document should be updated to reflect the actual behavior (exit on error), or the implementation should include a fallback mechanism as originally designed.

[Copilot]

The changelog dates are not in chronological order. Version 0.0.23 is dated "2025-02-04", which is earlier than version 0.0.22 dated "2025-11-07". Since 0.0.23 is the newer version, it should have a more recent date. Additionally, given that the current date is February 5, 2026, the date "2025-02-04" for version 0.0.23 appears to be a typo and should likely be "2026-02-04" or "2026-02-05".

[Copilot]

Pull request overview

Copilot reviewed 12 out of 13 changed files in this pull request and generated 7 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The validation checks if the parent of the custom path exists and is writable, but the custom path itself is meant to be a base directory where worktrees will be created. The validation should check if the custom path can be created (if it doesn't exist) or is writable (if it exists), rather than checking its parent.

Suggested change

	# Check if parent directory exists and is writable
	$parentPath = Split-Path $Path -Parent
	if (-not (Test-Path $parentPath)) {
	Write-Error "Error: Parent directory does not exist: $parentPath"
	exit 1
	}
	# Test writability by attempting to create a temp file
	$testFile = Join-Path $parentPath ".specify-write-test-$(Get-Random)"
	try {
	New-Item -ItemType File -Path $testFile -Force -ErrorAction Stop | Out-Null
	}
	catch {
	Write-Error "Error: Parent directory is not writable: $parentPath"
	exit 1
	}
	finally {
	Remove-Item $testFile -Force -ErrorAction SilentlyContinue
	}
	# Validate that the custom path itself is (or can be created as) a writable directory
	if (Test-Path $Path) {
	$pathItem = Get-Item $Path -ErrorAction Stop
	if (-not $pathItem.PSIsContainer) {
	Write-Error "Error: Custom path exists but is not a directory: $Path"
	exit 1
	}
	# Test writability by attempting to create a temp file in the custom path
	$testFile = Join-Path $Path ".specify-write-test-$(Get-Random)"
	try {
	New-Item -ItemType File -Path $testFile -Force -ErrorAction Stop | Out-Null
	}
	catch {
	Write-Error "Error: Custom path directory is not writable: $Path"
	exit 1
	}
	finally {
	Remove-Item $testFile -Force -ErrorAction SilentlyContinue
	}
	}
	else {
	# Attempt to create the custom path directory
	try {
	New-Item -ItemType Directory -Path $Path -Force -ErrorAction Stop | Out-Null
	}
	catch {
	Write-Error "Error: Cannot create directory for custom path: $Path"
	exit 1
	}
	}

[Copilot]

The JSON output uses printf with %s format specifiers without proper escaping. If SPEC_FILE or FEATURE_ROOT contain special characters (like quotes, backslashes, or newlines), this could produce invalid JSON. Consider using a JSON library or implementing proper escaping for string values (e.g., escaping quotes, backslashes, and control characters).

[Copilot]

The documentation states that the custom strategy creates worktrees in <custom_path>/<branch>, but the actual implementation (lines 36-37) uses <custom_path>/<repo_name>-<branch_name>. The documentation should be updated to match the implementation, which uses the repo name prefix for consistency with the sibling strategy.

Suggested change

	* `custom`: Creates worktrees in `<custom_path>/<branch>`.
	* `custom`: Creates worktrees in `<custom_path>/<repo_name>-<branch_name>`.

[Copilot]

The condition ".worktrees" in existing_content is too broad and could match unintended strings like "my-worktrees" in comments or other contexts. Consider checking for the exact pattern with word boundaries or line boundaries to avoid false positives.

Suggested change

	# Check if entry already exists (with or without trailing newline)
	if worktree_entry in existing_content or ".worktrees" in existing_content:
	# Check if entry already exists as a dedicated ignore rule
	existing_lines = [line.strip() for line in existing_content.splitlines()]
	if any(line == ".worktrees" or line == ".worktrees/" for line in existing_lines):

[Copilot]

When checking if the parent directory exists, consider that the worktree_path itself might need to be created (not just its parent). The current validation checks if the parent of worktree_path exists, but worktree_path is meant to be a base directory where multiple worktrees will be created (e.g., /tmp/worktrees/myrepo-feature1, /tmp/worktrees/myrepo-feature2). The validation should ensure the base path can be created, not just its parent.

Suggested change

	if not Path(worktree_path).is_absolute():
	console.print(f"[red]Error:[/red] --worktree-path must be an absolute path (got: {worktree_path})")
	raise typer.Exit(1)
	# Validate parent exists
	parent = Path(worktree_path).parent
	if not parent.exists():
	console.print(f"[red]Error:[/red] Parent directory does not exist: {parent}")
	raise typer.Exit(1)
	selected_worktree_path = worktree_path
	else:
	# Prompt for custom path
	if sys.stdin.isatty():
	console.print()
	selected_worktree_path = typer.prompt("Enter custom worktree base path (absolute path)")
	if not Path(selected_worktree_path).is_absolute():
	console.print(f"[red]Error:[/red] Path must be absolute (got: {selected_worktree_path})")
	raise typer.Exit(1)
	parent = Path(selected_worktree_path).parent
	if not parent.exists():
	console.print(f"[red]Error:[/red] Parent directory does not exist: {parent}")
	raise typer.Exit(1)
	base_path = Path(worktree_path)
	if not base_path.is_absolute():
	console.print(f"[red]Error:[/red] --worktree-path must be an absolute path (got: {worktree_path})")
	raise typer.Exit(1)
	# Validate base path is a directory or can be created
	if base_path.exists():
	if not base_path.is_dir():
	console.print(f"[red]Error:[/red] --worktree-path exists and is not a directory: {base_path}")
	raise typer.Exit(1)
	else:
	parent = base_path.parent
	if not parent.exists():
	console.print(f"[red]Error:[/red] Parent directory does not exist: {parent}")
	raise typer.Exit(1)
	if not os.access(parent, os.W_OK | os.X_OK):
	console.print(f"[red]Error:[/red] Cannot create worktree base directory under: {parent}")
	raise typer.Exit(1)
	selected_worktree_path = str(base_path)
	else:
	# Prompt for custom path
	if sys.stdin.isatty():
	console.print()
	selected_worktree_path = typer.prompt("Enter custom worktree base path (absolute path)")
	base_path = Path(selected_worktree_path)
	if not base_path.is_absolute():
	console.print(f"[red]Error:[/red] Path must be absolute (got: {selected_worktree_path})")
	raise typer.Exit(1)
	# Validate base path is a directory or can be created
	if base_path.exists():
	if not base_path.is_dir():
	console.print(f"[red]Error:[/red] Path exists and is not a directory: {base_path}")
	raise typer.Exit(1)
	else:
	parent = base_path.parent
	if not parent.exists():
	console.print(f"[red]Error:[/red] Parent directory does not exist: {parent}")
	raise typer.Exit(1)
	if not os.access(parent, os.W_OK | os.X_OK):
	console.print(f"[red]Error:[/red] Cannot create worktree base directory under: {parent}")
	raise typer.Exit(1)
	selected_worktree_path = str(base_path)

[Copilot]

The same parent directory validation issue exists here. The validation checks if the parent of the user-provided path exists, but the path itself is a base directory that should be validated for writability, not just its parent.

Suggested change

	if not Path(worktree_path).is_absolute():
	console.print(f"[red]Error:[/red] --worktree-path must be an absolute path (got: {worktree_path})")
	raise typer.Exit(1)
	# Validate parent exists
	parent = Path(worktree_path).parent
	if not parent.exists():
	console.print(f"[red]Error:[/red] Parent directory does not exist: {parent}")
	raise typer.Exit(1)
	selected_worktree_path = worktree_path
	else:
	# Prompt for custom path
	if sys.stdin.isatty():
	console.print()
	selected_worktree_path = typer.prompt("Enter custom worktree base path (absolute path)")
	if not Path(selected_worktree_path).is_absolute():
	console.print(f"[red]Error:[/red] Path must be absolute (got: {selected_worktree_path})")
	raise typer.Exit(1)
	parent = Path(selected_worktree_path).parent
	if not parent.exists():
	console.print(f"[red]Error:[/red] Parent directory does not exist: {parent}")
	raise typer.Exit(1)
	base_path = Path(worktree_path)
	if not base_path.is_absolute():
	console.print(f"[red]Error:[/red] --worktree-path must be an absolute path (got: {worktree_path})")
	raise typer.Exit(1)
	# Validate base path exists, is a directory, and is writable
	if not base_path.exists():
	console.print(f"[red]Error:[/red] Worktree base directory does not exist: {base_path}")
	raise typer.Exit(1)
	if not base_path.is_dir():
	console.print(f"[red]Error:[/red] Worktree base path is not a directory: {base_path}")
	raise typer.Exit(1)
	if not os.access(str(base_path), os.W_OK | os.X_OK):
	console.print(f"[red]Error:[/red] Worktree base directory is not writable: {base_path}")
	raise typer.Exit(1)
	selected_worktree_path = str(base_path)
	else:
	# Prompt for custom path
	if sys.stdin.isatty():
	console.print()
	selected_worktree_path = typer.prompt("Enter custom worktree base path (absolute path)")
	base_path = Path(selected_worktree_path)
	if not base_path.is_absolute():
	console.print(f"[red]Error:[/red] Path must be absolute (got: {selected_worktree_path})")
	raise typer.Exit(1)
	# Validate base path exists, is a directory, and is writable
	if not base_path.exists():
	console.print(f"[red]Error:[/red] Worktree base directory does not exist: {base_path}")
	raise typer.Exit(1)
	if not base_path.is_dir():
	console.print(f"[red]Error:[/red] Worktree base path is not a directory: {base_path}")
	raise typer.Exit(1)
	if not os.access(str(base_path), os.W_OK | os.X_OK):
	console.print(f"[red]Error:[/red] Worktree base directory is not writable: {base_path}")
	raise typer.Exit(1)
	selected_worktree_path = str(base_path)

[Copilot]

The validation checks if the parent of the custom path exists and is writable, but the custom path itself is meant to be a base directory where worktrees will be created. The validation should check if the custom path can be created (if it doesn't exist) or is writable (if it exists), rather than checking its parent.

Suggested change

	# Check if path is writable (create parent if needed)
	CUSTOM_PARENT=$(dirname "$CUSTOM_PATH")
	if [[ ! -d "$CUSTOM_PARENT" ]]; then
	echo "Error: Parent directory does not exist: $CUSTOM_PARENT" >&2
	exit 1
	fi
	if [[ ! -w "$CUSTOM_PARENT" ]]; then
	echo "Error: Parent directory is not writable: $CUSTOM_PARENT" >&2
	exit 1
	fi
	# Validate the custom path itself (if it exists) or its parent (if it does not)
	if [[ -e "$CUSTOM_PATH" ]]; then
	if [[ ! -d "$CUSTOM_PATH" ]]; then
	echo "Error: Custom path exists but is not a directory: $CUSTOM_PATH" >&2
	exit 1
	fi
	if [[ ! -w "$CUSTOM_PATH" ]]; then
	echo "Error: Custom path directory is not writable: $CUSTOM_PATH" >&2
	exit 1
	fi
	else
	CUSTOM_PARENT=$(dirname "$CUSTOM_PATH")
	if [[ ! -d "$CUSTOM_PARENT" ]]; then
	echo "Error: Parent directory does not exist: $CUSTOM_PARENT" >&2
	exit 1
	fi
	if [[ ! -w "$CUSTOM_PARENT" ]]; then
	echo "Error: Parent directory is not writable: $CUSTOM_PARENT" >&2
	exit 1
	fi
	fi