# 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

```
.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