Skip to content

PRD.md

Latest commit

 

History

History
101 lines (76 loc) · 3.81 KB

PRD.md

File metadata and controls

101 lines (76 loc) · 3.81 KB
Raw

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

  • Task 1.1: Set up project structure with pyproject.toml
  • Task 1.2: Implement git operations module (git.py)
  • Task 1.3: Implement configuration management (config.py)
  • Task 1.4: Implement core worktree operations (worktree.py)
  • 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

  • Task 2.1: Implement wt init command
  • Task 2.2: Implement wt switch command (existing worktrees)
  • Task 2.3: Implement wt switch -c (create new worktrees)
  • Task 2.4: Implement wt list command
  • 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

  • Task 3.1: Implement wt diff command
  • Task 3.2: Implement wt delete command with prompts
  • Task 3.3: Implement wt status command
  • 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

  • Task 4.1: Implement wt run command
  • Task 4.2: Implement wt clean command
  • Task 4.3: Implement wt config command
  • 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

  • Task 5.1: Implement wt shell-init command
  • Task 5.2: Generate bash/zsh shell wrapper
  • Task 5.3: Generate fish shell wrapper
  • Task 5.4: Add --shell-helper flag for cd support
  • Task 5.5: Test shell integration

Story 6: User Experience ✅

As a user, I want helpful prompts and error messages

  • Task 6.1: Implement user prompts module (prompts.py)
  • Task 6.2: Add comprehensive error messages
  • Task 6.3: Add progress indicators
  • 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

  • Task 7.1: Write comprehensive test suite
  • Task 7.2: Create README.md with usage examples
  • Task 7.3: Create notes.md documenting implementation decisions
  • Task 7.4: Update root README.md
  • 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

Story 8: Worktree Sync ✅

As a user, I want to sync worktrees with their upstream branches

  • Task 8.1: Add git operations for stash, pull, and rebase
  • Task 8.2: Implement sync_worktree method in worktree.py
  • Task 8.3: Implement wt sync command in cli.py
  • Task 8.4: Add comprehensive tests for wt sync
  • Task 8.5: Update documentation

Non-Goals (Future Considerations)

  • wt clone - Clone with pre-configuration
  • wt exec - Run command across all worktrees
  • Worktree templates
  • Agent tracking
  • Locking mechanism