# AGENTS.md — pi-worktree Extension

## Project Structure

```
.pi/extensions/pi-worktree.ts    # Single-file extension (all tool + command logic)
README.md                        # User-facing documentation
DESIGN.md                        # Architecture and design decisions
DOMAIN.md                        # Domain concepts and terminology
```

## Tech Stack

- **Language**: TypeScript
- **Schema**: TypeBox (`@sinclair/typebox`) for tool parameter schemas
- **Runtime**: pi coding agent extension API (`ExtensionAPI`, `ExtensionContext`)
- **Git**: native via `pi.exec("git", [...])` — no external git packages
- **No npm dependencies** in v1 beyond what pi provides

## Extension Entry Point

The extension is a single default-exported function:

```typescript
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";

export default function (pi: ExtensionAPI) {
  // register tools and commands here
}
```

## Tool Conventions

- Each tool is a `Type.Object` schema + async execute function.
- Execute signature: `(toolCallId, params, signal, onUpdate, ctx)` 
- Always check `result.exitCode !== 0` for git failures — surface the message with suggested fixes.
- **Fail fast**: refuse dangerous operations (existing paths, current branch, uncommitted changes) with clear messages and suggestions. No silent auto-correction.

## Command Conventions

- Register via `pi.registerCommand("name", { description, handler })`.
- Use `ctx.ui.select()` for interactive pickers.
- Parse structured data from tool results (not raw text).

## State Management

- Tools are **stateless** — each call works independently based on current git state.
- Session memory is ephemeral (per pi process lifetime) for back-switching behavior only.

## Error Handling Pattern

```typescript
if (result.exitCode !== 0) {
  return {
    content: [{ type: "text", text: `Error: ${result.stderr}. Suggestion: <fix>` }],
    isError: true
  };
}
```

Always include a suggested fix in error messages.

## Validation Checklist

- [ ] Extension loads without errors when pi starts
- [ ] All four tools registered with correct signatures
- [ ] Error paths return `isError: true` with helpful messages
- [ ] `/worktree` command shows interactive picker
- [ ] Branch display updates after switching worktrees
- [ ] No external dependencies beyond TypeBox + pi SDK