Create extension file structure with tool scaffolding

- Add .pi/extensions/pi-worktree.ts with correct imports and default export
- Define WorktreeEntry, WorktreeListResult, WorktreeError types
- Register 4 tools: create, list, switch, remove (stubs)
- Register /worktree command (stub)
- Add helper function stubs: parseWorktreeList, pathExists, resolveWorktreeTarget
- Uses defineTool() and Type from pi SDK for type-safe registration

.pi/extensions/pi-worktree.ts

@@ -0,0 +1,162 @@
+/**
+ * pi-worktree Extension
+ *
+ * Manages git worktrees through tool commands and an interactive `/worktree` command.
+ *
+ * Tools:
+ * - git_worktree_create — Create a linked worktree for a branch
+ * - git_worktree_list — List all linked worktrees
+ * - git_worktree_switch — Switch working directory to a worktree
+ * - git_worktree_remove — Remove a linked worktree
+ *
+ * Command:
+ * - /worktree — Interactive picker to switch between worktrees
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "@earendil-works/pi-ai";
+
+// ─── Type Definitions ──────────────────────────────────────────────
+
+/** A single worktree entry parsed from `git worktree list`. */
+interface WorktreeEntry {
+	/** Full path to the worktree directory. */
+	path: string;
+	/** Short commit hash checked out in this worktree. */
+	commit: string;
+	/** Branch name, or "(detached)" for detached HEAD. */
+	branch: string;
+	/** Whether this worktree is the current working directory. */
+	isCurrent: boolean;
+}
+
+/** Result of listing all worktrees. */
+interface WorktreeListResult {
+	/** All worktrees in the repository. */
+	worktrees: WorktreeEntry[];
+	/** Total number of worktrees. */
+	count: number;
+}
+
+/** Error returned when a worktree operation fails. */
+interface WorktreeError {
+	/** Human-readable error message from git or validation. */
+	message: string;
+	/** Suggested fix for the user. */
+	suggestion?: string;
+}
+
+// ─── Tool Parameter Schemas ────────────────────────────────────────
+
+const createWorktreeParams = Type.Object({
+	path: Type.String({ description: "Path for the new worktree (relative or absolute)" }),
+	branch: Type.Optional(Type.String({ description: "Branch name to check out. Defaults to 'main'." })),
+	create_branch: Type.Optional(
+		Type.Boolean({
+			description: "If true and branch doesn't exist, create it. Defaults to false.",
+		}),
+	),
+});
+
+const listWorktreeParams = Type.Object({});
+
+const switchWorktreeParams = Type.Object({
+	target: Type.String({ description: "Path or branch name of the target worktree to switch to." }),
+});
+
+const removeWorktreeParams = Type.Object({
+	path: Type.String({ description: "Path of the worktree to remove." }),
+});
+
+// ─── Helper Functions (stubs) ──────────────────────────────────────
+
+/**
+ * Parse raw `git worktree list` output into structured entries.
+ * @param rawOutput - Raw stdout from `git worktree list`
+ * @param currentDir - Current working directory for comparison
+ * @returns Array of parsed worktree entries
+ */
+function parseWorktreeList(rawOutput: string, currentDir: string): WorktreeEntry[] {
+	throw new Error("not implemented");
+}
+
+/**
+ * Check if the target path exists.
+ * @param path - Path to check
+ * @param ctx - Extension context for file system access
+ * @returns True if the path exists
+ */
+async function pathExists(path: string, ctx: ExtensionContext): Promise<boolean> {
+	throw new Error("not implemented");
+}
+
+/**
+ * Resolve a worktree target (path or branch name) to its full path.
+ * @param target - Path or branch name to resolve
+ * @param worktrees - List of all worktrees
+ * @returns The resolved path, or undefined if not found
+ */
+function resolveWorktreeTarget(target: string, worktrees: WorktreeEntry[]): string | undefined {
+	throw new Error("not implemented");
+}
+
+// ─── Tool Definitions ──────────────────────────────────────────────
+
+const gitWorktreeCreateTool = defineTool({
+	name: "git_worktree_create",
+	label: "Git Worktree Create",
+	description: "Create a linked worktree for a branch in the current repo.",
+	parameters: createWorktreeParams,
+	async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+		throw new Error("not implemented");
+	},
+});
+
+const gitWorktreeListTool = defineTool({
+	name: "git_worktree_list",
+	label: "Git Worktree List",
+	description: "List all linked worktrees in the current repo.",
+	parameters: listWorktreeParams,
+	async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+		throw new Error("not implemented");
+	},
+});
+
+const gitWorktreeSwitchTool = defineTool({
+	name: "git_worktree_switch",
+	label: "Git Worktree Switch",
+	description: "Switch pi's working directory to a linked worktree.",
+	parameters: switchWorktreeParams,
+	async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+		throw new Error("not implemented");
+	},
+});
+
+const gitWorktreeRemoveTool = defineTool({
+	name: "git_worktree_remove",
+	label: "Git Worktree Remove",
+	description: "Remove a linked worktree.",
+	parameters: removeWorktreeParams,
+	async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+		throw new Error("not implemented");
+	},
+});
+
+// ─── Extension Entry Point ────────────────────────────────────────
+
+export default function (pi: ExtensionAPI) {
+	// Register tools
+	pi.registerTool(gitWorktreeCreateTool);
+	pi.registerTool(gitWorktreeListTool);
+	pi.registerTool(gitWorktreeSwitchTool);
+	pi.registerTool(gitWorktreeRemoveTool);
+
+	// Register /worktree command
+	pi.registerCommand("worktree", {
+		description: "Interactive picker to switch between linked worktrees.",
+		handler: async (_args, _ctx) => {
+			throw new Error("not implemented");
+		},
+	});
+}

findings.md

@@ -0,0 +1,40 @@
+# Findings — Issue #1: Create Extension File Structure
+
+## Git Workflow
+- Branch: `issue-1` (based on origin/main)
+- Remote: `https://git.excelera.net/david/pi-worktrees.git`
+- Tool: `fj` CLI for Forgejo issues (auto-detected from git remote)
+- PR: Will use `fj pr create` when complete
+
+## Project Context
+- **Extension location**: `.pi/extensions/pi-worktree.ts`
+- **Pattern**: Single-file extension with default export function
+- **API imports**: `@earendil-works/pi-coding-agent` (ExtensionAPI, ExtensionContext)
+- **Schema library**: TypeBox (`typebox`) for tool parameter schemas
+- **No npm dependencies** beyond what pi provides
+
+## Validation Approach
+This project has no traditional test suite. Validation is:
+1. File exists at `.pi/extensions/pi-worktree.ts`
+2. Correct imports from `@earendil-works/pi-coding-agent` and `typebox`
+3. Follows single-file extension pattern (default export function)
+4. pi loads without errors via `/reload` or restart
+
+## Issue #1 Acceptance Criteria
+- [ ] `.pi/extensions/pi-worktree.ts` exists
+- [ ] Correct imports from `@earendil-works/pi-coding-agent` and `typebox`
+- [ ] Extension loads without errors when pi starts
+- [ ] Follows the single-file extension pattern with default export function
+
+## Related Files (from main branch)
+| File | Purpose |
+|------|---------|
+| `README.md` | User-facing docs — describes 4 tools + `/worktree` command |
+| `DESIGN.md` | Architecture decisions for the extension |
+| `DOMAIN.md` | Git worktree domain concepts and terminology |
+| `AGENTS.md` | Agent conventions, repo details, fj CLI usage |
+
+## Session Discoveries
+- **TypeBox import**: Use `{ Type } from "@earendil-works/pi-ai"` (re-exported) rather than direct `typebox` import — matches pi's extension examples.
+- **Tool definition helper**: Use `defineTool()` from `@earendil-works/pi-coding-agent` for type-safe tool registration.
+- **Validation command**: `bun build <file> --no-bundle --emit=metadata` compiles and validates TypeScript without bundling.

progress.md

@@ -0,0 +1,26 @@
+# Progress Log — Issue #1: Create Extension File Structure
+
+## Session 1 — [2025-07-24]
+
+### Task 001: Scaffold `.pi/extensions/pi-worktree.ts`
+
+| Phase | Status | Notes |
+|-------|--------|-------|
+| Phase 0 (Context) | ✅ Done | Branch issue-1 from origin/main, docs found, TypeScript + TypeBox confirmed |
+| Step 1 (Read Task) | ✅ Done | Issue #1: Create Extension File Structure. Acceptance: file exists, correct imports, loads without errors |
+| Step 2 (Scaffold) | ✅ Done | Created full scaffold with types, tool schemas, helper stubs, and entry point |
+| Step 3 (RED) | ✅ Done | Scaffold compiles — stub functions throw "not implemented" as expected |
+| Step 4 (GREEN) | ✅ Done | `bun build` succeeds with no errors. All imports resolve from pi's global bun install.
+
+### Scaffold Contents
+- **Types**: `WorktreeEntry`, `WorktreeListResult`, `WorktreeError`
+- **Tool schemas**: `createWorktreeParams`, `listWorktreeParams`, `switchWorktreeParams`, `removeWorktreeParams`
+- **Helper stubs**: `parseWorktreeList()`, `pathExists()`, `resolveWorktreeTarget()`
+- **Tools registered**: `git_worktree_create`, `git_worktree_list`, `git_worktree_switch`, `git_worktree_remove`
+- **Command registered**: `/worktree` (stub)
+
+---
+
+### Test Results
+
+_N/A — validation is pi loading + TypeScript syntax. `bun build` passes with zero errors._

task_plan.md

@@ -0,0 +1,18 @@
+# Task Plan — Issue #1: Create Extension File Structure
+
+| Task | Description | TDD Status | Done |
+|------|-------------|------------|------|
+| 001 | Scaffold `.pi/extensions/pi-worktree.ts` with correct imports, tools, command, and helper stubs | ☑ RED ✅ GREEN ✅ REFACTOR | ☑ |
+
+## Milestone Context (from implementation plan)
+
+- **Milestone 1: Foundation** — Set up extension structure and register basic tools
+- **Task 1.1**: Create Extension File — empty file with correct imports, loads without errors
+- **Task 1.2**: Register Tool Scaffolding — four tool registrations with placeholder execute functions
+- **Task 1.3**: Implement `git_worktree_list`
+
+## Notes
+
+- No traditional test framework — validation is: file exists at `.pi/extensions/pi-worktree.ts`, correct imports, pi loads without errors via `/reload` or restart.
+- Single-file extension pattern: default export function receiving `ExtensionAPI`.
+- Uses fj CLI for issue operations (auto-detected from git remote).