pi-worktrees/DESIGN.md

DESIGN.md — Architecture & Design Decisions

Overview

A pi extension that manages git worktrees through tool commands and an interactive /worktree command, with tight session integration.

v1 Scope

• Four tools: git_worktree_create, git_worktree_list, git_worktree_switch, git_worktree_remove
• One command: /worktree (interactive picker)
• Session hooks: branch display update + offer new session after switch
• Out of scope: auto-worktree creation, smart defaults, persistent state

Architecture

pi-worktree.ts
├── Tools
│   ├── git_worktree_create(path, branch?, create_branch?)
│   ├── git_worktree_list()
│   ├── git_worktree_switch(target)
│   └── git_worktree_remove(path)
├── Command: /worktree (interactive picker)
└── Session hooks
    ├── Update pi's git branch display on switch
    └── Offer new session creation after switch

Key Design Decisions

Stateless Tools, Ephemeral Memory

Tools are stateless; only in-memory mapping of worktree→session during a process lifetime for back-switching. Lost on restart.

Fail Fast, No Auto-Correction

Refuse dangerous operations (existing path, current branch, uncommitted changes) with clear messages and suggested fixes. Never silently auto-correct.

Session Integration Depth (v1)

Update branch display + offer new session creation. No automatic worktree creation per branch — keeps complexity down and avoids assumptions about workflow.

Tool Behaviors

Tool	Key Behavior	Fail Conditions
create	git worktree add <path> [branch], -b for new branches	Path exists, branch is current, no write permission at target path (check with fs.access() before invoking git)
list	Parses git worktree list output into structured data	No git repo present
switch	Changes cwd to target worktree path	Already there, uncommitted changes in source
remove	git worktree remove <path>	Target is main repo, uncommitted changes

Edge Cases

1. Nested worktrees: Not supported by git — surface native error
2. Detached HEAD: Use path for identification instead of branch name
3. Untracked files on removal: Suggest removing/moving them first
4. Same-branch worktrees: Let git handle it, surface the error

Testing Strategy

Unit Tests — Parsing (git_worktree_list)

• Parse valid git worktree list output into structured data with correct branch, path, and isCurrent
• Handle detached HEAD entries (no branch name → use path for identification)
• Handle bare repos (HEAD line without branch brackets)
• Reject non-git-repo directories

Unit Tests — Validation (git_worktree_create)

• Refuse when target path already exists (suggest --force or alternative path)
• Refuse when attempting to create a worktree on the current branch in the main repo
• Surface permission errors with actionable guidance (e.g., "cannot write to /root/ — try ~/worktrees/")

Integration Tests — Each Tool

Test	Procedure
create	Create worktree → verify git worktree list shows it → remove it
list	Run against repo with 0, 1, and N worktrees → assert structured output shape
switch	Switch to existing worktree → verify cwd updated → switch back → verify original state restored
remove	Remove a linked worktree → verify it's gone from list; refuse if uncommitted changes exist

Manual Verification — /worktree Command UX

• Run /worktree in a repo with multiple worktrees
• Confirm picker shows branch names (not just paths)
• Switch to a worktree → confirm branch display updates
• Return to main repo → confirm session back-switching works

Rollout Phases

1. Core tools (create, list, switch, remove) with error handling + unit tests
2. /worktree interactive command with picker + back-switching + integration tests
3. Session integration hooks (branch display, new session offer)
4. Polish: edge cases, README, manual verification pass