AGENTS.md

@@ -1,5 +1,35 @@
 # AGENTS.md — pi-worktree Extension
 
+## Repo Details
+
+| Property | Value |
+|----------|-------|
+| **Host** | `git.excelera.net` |
+| **Remote** | `https://git.excelera.net/david/pi-worktrees.git` |
+| **Owner** | david |
+| **Repo** | pi-worktrees |
+
+## Using `fj` CLI to Pull Issues
+
+This repo uses the [`fj`](https://git.excelera.net/david/fj) CLI tool (Forgejo CLI) for issue operations. It's auto-detected from the git remote, so `-H` is optional inside this repo:
+
+```bash
+# Search open issues in this repo
+fj issue search --repo pi-worktrees
+
+# View a specific issue
+fj issue view <ISSUE_NUM>
+
+# List all open issues
+fj issue search --state open
+```
+
+### Prerequisites
+
+- `fj` must be installed and authenticated (`fj whoami`)
+- Credentials stored at `~/.local/share/forgejo-cli/keys.json`
+- Auth via OAuth login or application token on `git.excelera.net`
+
 ## Project Structure
 
 ```

DESIGN.md

@@ -41,7 +41,7 @@ Update branch display + offer new session creation. No automatic worktree creati
 
 | Tool | Key Behavior | Fail Conditions |
 |------|-------------|-----------------|
-| `create` | `git worktree add <path> [branch]`, `-b` for new branches | Path exists, branch is current |
+| `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 |
@@ -53,9 +53,36 @@ Update branch display + offer new session creation. No automatic worktree creati
 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
+1. Core tools (create, list, switch, remove) with error handling + unit tests
-2. `/worktree` interactive command with picker + back-switching
+2. `/worktree` interactive command with picker + back-switching + integration tests
 3. Session integration hooks (branch display, new session offer)
-4. Polish: edge cases, README, user testing
+4. Polish: edge cases, README, manual verification pass

DOMAIN.md

@@ -21,6 +21,28 @@ A git worktree is a linked working directory that shares the same repository but
 | **Bare repo** | A `.git/` without a working tree — used as the central store when all worktrees are linked |
 | **Detached HEAD** | When a worktree checks out a commit directly instead of a branch |
 
+### Raw Output Format — `git worktree list`
+
+The parser should expect this exact pipe-separated format from `git worktree list`:
+
+```
+/home/user/project          abc1234 [main]           # main repo (current)
+/tmp/feature-x              def5678 [feature-x]      # linked worktree on a branch
+/tmp/detached               fedcba HEAD               # detached HEAD (no branch name)
+```
+
+| Field | Position | Description |
+|-------|----------|-------------|
+| **Path** | Column 1 | Absolute path to the working tree directory |
+| **Hash** | Column 2 | Short commit hash (HEAD) for this worktree |
+| **Branch** | Column 3+ | Branch name in `[brackets]`, or `HEAD` if detached |
+
+**Parsing rules:**
+- Lines with `[branch-name]` → the branch is identified by what's inside the brackets.
+- Lines with `HEAD` (no brackets) → detached HEAD; identify this worktree by path only.
+- The first entry in the output is always the main repo — mark it as `isCurrent: true`.
+- Worktrees listed after the first entry are linked worktrees (`isCurrent: false`).
+
 ### Constraints (from git itself)
 
 - You cannot create a nested worktree (worktree inside a worktree).

README.md

@@ -28,10 +28,10 @@ List all linked worktrees in the current repo.
 
 Returns structured data with `branch`, `path`, and `isCurrent` for each worktree.
 
-**Example output**:
+**Example output** (raw `git worktree list` format, parsed into structured data):
 ```
-main — /home/user/repo (current)
+/home/user/repo          abc1234 [main]
-feature-x — /home/user/repo/feature-x
+/home/user/repo/feature-x def5678 [feature-x]
 ```
 
 ### `git_worktree_switch`
@@ -77,5 +77,6 @@ Lists all worktrees with a branch-first display and lets you select one to switc
 
 ## Requirements
 
+- **pi >= 0.5.0** (with `ExtensionAPI` and `registerCommand` support)
 - Git 2.x with worktree support (all modern versions)
 - No external npm dependencies — uses only pi's extension API and TypeBox schemas.