# 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 |
| `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

## Rollout Phases

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