# 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