Create git worktree manager CLI tool

.github/workflows/test.yml

@@ -14,16 +14,21 @@ jobs:
         tool:
           - locust-compare
           - config-utils
+          - wt-worktree
+        # Just test for 3.12 
+        # uncomment if you want to test for all versions
+        # python-version: ["3.10", "3.11", "3.12"]
+        python-version: ["3.12"]
       fail-fast: false
     steps:
     - uses: actions/checkout@v4
 
-    - name: Set up Python 3.12
+    - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v5
       with:
-        python-version: 3.12
+        python-version: ${{ matrix.python-version }}
 
-    - name: Install and test ${{ matrix.tool }}
+    - name: Install and test ${{ matrix.tool }} (Python ${{ matrix.python-version }})
       working-directory: tools/${{ matrix.tool }}
       run: |
         python -m pip install --upgrade pip

README.md

@@ -8,6 +8,7 @@ A collection of small, independent Python utilities. Each tool is self-contained
 |------|-------------|
 | [locust-compare](tools/locust-compare/) | Compare performance metrics between two Locust runs |
 | [config-utils](tools/config-utils/) | CLI tool for capturing environment variables and Django settings |
+| [wt-worktree](tools/wt-worktree/) | Git worktree manager for parallel development workflows |
 
 ## Installation
 
@@ -22,23 +23,29 @@ uv tool install 'git+https://github.com/dev-ankit/python-tools.git#subdirectory=
 
 # Install config-utils
 uv tool install 'git+https://github.com/dev-ankit/python-tools.git#subdirectory=tools/config-utils'
+
+# Install wt-worktree
+uv tool install 'git+https://github.com/dev-ankit/python-tools.git#subdirectory=tools/wt-worktree'
 ```
 
 After installation, you can run from anywhere:
 ```bash
 locust-compare <base_dir> <current_dir>
 config-utils capture-env
+wt init
 ```
 
 To update to the latest from GitHub:
 
 ```bash
 uv tool upgrade locust-compare
 uv tool upgrade config-utils
+uv tool upgrade wt-worktree
 
 # Or force reinstall:
 uv tool install --force 'git+https://github.com/dev-ankit/python-tools.git#subdirectory=tools/locust-compare'
 uv tool install --force 'git+https://github.com/dev-ankit/python-tools.git#subdirectory=tools/config-utils'
+uv tool install --force 'git+https://github.com/dev-ankit/python-tools.git#subdirectory=tools/wt-worktree'
 
 # To see installed tools:
 uv tool list
@@ -58,6 +65,9 @@ uvx --from 'git+https://github.com/dev-ankit/python-tools.git#subdirectory=tools
 
 # Run config-utils
 uvx --from 'git+https://github.com/dev-ankit/python-tools.git#subdirectory=tools/config-utils' config-utils capture-env
+
+# Run wt
+uvx --from 'git+https://github.com/dev-ankit/python-tools.git#subdirectory=tools/wt-worktree' wt init
 ```
 
 Option 3: Clone and run locally:
@@ -72,20 +82,27 @@ uvx --from . <tool-name> [args]
 
 ```
 python-tools/
-├── README.md      
+├── README.md
 ├── LICENSE             # MIT License (shared)
 ├── .github/
 │   └── workflows/
 └── tools/
-    ├── locust-compare/ # Locust performance comparison tool
+    ├── locust-compare/  # Locust performance comparison tool
     │   ├── compare_runs.py
     │   ├── pyproject.toml
     │   ├── README.md
     │   └── tests/
-    └── config-utils/ # CLI tool for capturing environment variables and Django settings
-        ├── cli.py
+    ├── config-utils/    # CLI tool for capturing environment variables and Django settings
+    │   ├── cli.py
+    │   ├── pyproject.toml
+    │   └── README.md
+    └── wt-worktree/     # Git worktree manager for parallel development
+        ├── wt/
+        ├── tests/
         ├── pyproject.toml
-        └── README.md
+        ├── README.md
+        ├── PRD.md
+        └── notes.md
 ```
 
 ## Adding a New Tool

tools/wt-worktree/PRD.md

@@ -0,0 +1,93 @@
+# `wt` - Git Worktree Manager - Product Requirements Document
+
+## Overview
+
+`wt` is a CLI tool that simplifies git worktree management for parallel development workflows. It enables multiple agents or developers to work on separate features simultaneously with an intuitive interface and shell integration.
+
+## Stories and Tasks
+
+### Story 1: Core Infrastructure ✅
+**As a developer, I want the basic project structure and core git operations, so that I can build features on top**
+
+- [x] Task 1.1: Set up project structure with pyproject.toml
+- [x] Task 1.2: Implement git operations module (git.py)
+- [x] Task 1.3: Implement configuration management (config.py)
+- [x] Task 1.4: Implement core worktree operations (worktree.py)
+- [x] Task 1.5: Add tests for core modules
+
+### Story 2: Basic Commands ✅
+**As a user, I want to initialize and manage worktrees, so that I can work on multiple features**
+
+- [x] Task 2.1: Implement `wt init` command
+- [x] Task 2.2: Implement `wt switch` command (existing worktrees)
+- [x] Task 2.3: Implement `wt switch -c` (create new worktrees)
+- [x] Task 2.4: Implement `wt list` command
+- [x] Task 2.5: Add tests for basic commands
+
+### Story 3: Worktree Management Commands ✅
+**As a user, I want to compare, delete, and check status of worktrees**
+
+- [x] Task 3.1: Implement `wt diff` command
+- [x] Task 3.2: Implement `wt delete` command with prompts
+- [x] Task 3.3: Implement `wt status` command
+- [x] Task 3.4: Add tests for management commands
+
+### Story 4: Advanced Features ✅
+**As a user, I want to run commands in worktrees and clean up merged branches**
+
+- [x] Task 4.1: Implement `wt run` command
+- [x] Task 4.2: Implement `wt clean` command
+- [x] Task 4.3: Implement `wt config` command
+- [x] Task 4.4: Add tests for advanced features
+
+### Story 5: Shell Integration ✅
+**As a user, I want seamless shell integration, so that I can navigate worktrees easily**
+
+- [x] Task 5.1: Implement `wt shell-init` command
+- [x] Task 5.2: Generate bash/zsh shell wrapper
+- [x] Task 5.3: Generate fish shell wrapper
+- [x] Task 5.4: Add --shell-helper flag for cd support
+- [x] Task 5.5: Test shell integration
+
+### Story 6: User Experience ✅
+**As a user, I want helpful prompts and error messages**
+
+- [x] Task 6.1: Implement user prompts module (prompts.py)
+- [x] Task 6.2: Add comprehensive error messages
+- [x] Task 6.3: Add progress indicators
+- [x] Task 6.4: Handle edge cases (spaces in paths, special characters)
+
+### Story 7: Documentation and Testing ✅
+**As a developer, I want comprehensive documentation and tests**
+
+- [x] Task 7.1: Write comprehensive test suite
+- [x] Task 7.2: Create README.md with usage examples
+- [x] Task 7.3: Create notes.md documenting implementation decisions
+- [x] Task 7.4: Update root README.md
+- [x] Task 7.5: End-to-end testing
+
+## Success Criteria
+
+1. All commands work as specified in the spec
+2. Test coverage > 80%
+3. Shell integration works in bash, zsh, and fish
+4. Error messages are clear and actionable
+5. Configuration system works with both local and global configs
+6. Tool handles edge cases gracefully (uncommitted changes, conflicts, etc.)
+
+## Technical Requirements
+
+- Python 3.10+
+- Click for CLI framework
+- Subprocess-based git operations (no gitpython dependency for simplicity)
+- TOML configuration files
+- Shell wrappers for cd integration
+
+## Non-Goals (Future Considerations)
+
+- `wt clone` - Clone with pre-configuration
+- `wt sync` - Pull/rebase all worktrees
+- `wt exec` - Run command across all worktrees
+- Worktree templates
+- Agent tracking
+- Locking mechanism