feat: register all four worktree tools with placeholder implementations

Register git_worktree_list, git_worktree_create, git_worktree_switch,
and git_worktree_remove with correct TypeBox schemas. Each tool returns
'Not implemented yet.' as a placeholder response.

.pi/extensions/pi-worktree.ts

@@ -0,0 +1,70 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "git_worktree_list",
+    label: "Git Worktree List",
+    description: "List all linked worktrees in the current repo with branch, path, and status.",
+    parameters: Type.Object({}),
+    async execute() {
+      return {
+        content: [{ type: "text", text: "Not implemented yet." }],
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "git_worktree_create",
+    label: "Git Worktree Create",
+    description: "Create a linked worktree for a branch in the current repo.",
+    parameters: Type.Object({
+      path: Type.String({ description: "Path for the new worktree" }),
+      branch: Type.Optional(
+        Type.String({
+          description: "Branch name (new or existing). Defaults to 'main'.",
+        })
+      ),
+      create_branch: Type.Optional(
+        Type.Boolean({
+          description: "Create a new branch? Defaults to true if branch doesn't exist.",
+        })
+      ),
+    }),
+    async execute() {
+      return {
+        content: [{ type: "text", text: "Not implemented yet." }],
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "git_worktree_switch",
+    label: "Git Worktree Switch",
+    description: "Switch pi's working directory to a linked worktree.",
+    parameters: Type.Object({
+      target: Type.String({
+        description: "Path or branch name of the target worktree",
+      }),
+    }),
+    async execute() {
+      return {
+        content: [{ type: "text", text: "Not implemented yet." }],
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "git_worktree_remove",
+    label: "Git Worktree Remove",
+    description: "Remove a linked worktree.",
+    parameters: Type.Object({
+      path: Type.String({ description: "Path of the worktree to remove" }),
+    }),
+    async execute() {
+      return {
+        content: [{ type: "text", text: "Not implemented yet." }],
+      };
+    },
+  });
+}

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.