71 lines
2.3 KiB
Markdown
71 lines
2.3 KiB
Markdown
# 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
|