61 lines
2.5 KiB
Markdown
61 lines
2.5 KiB
Markdown
# 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
|