# AGENTS.md

Guidance for agents working in this repository.

## Project scope

This repo builds a **pi.dev extension** that adds an `ask` / interview-style user question flow.

Primary deliverables in this repo:

- research and comparison docs:
  - `RESEARCH.md`
  - `FINDINGS.md`
  - `SPEC.md`
- TypeScript extension implementation in `src/`
- tests for core logic in `tests/`

## Key project goals

When making changes, optimize for:

1. **pi-native extension design**
   - prefer `pi.registerTool()`
   - prefer `ctx.ui.custom()` for complex interactive flows
   - keep result shapes compatible with normal pi tool results

2. **testable architecture**
   - keep state and decision logic in plain TypeScript modules
   - keep pi/TUI wiring thin
   - prefer testing state transitions and serialization over testing terminal rendering details

3. **research alignment**
   - keep implementation consistent with `SPEC.md`
   - if behavior changes materially, update `README.md` and `SPEC.md`
   - if new harness findings are added, update `RESEARCH.md` and/or `FINDINGS.md`

## Tech stack

- TypeScript
- pnpm
- Biome
- pi extension APIs from `@mariozechner/pi-coding-agent`
- TUI components from `@mariozechner/pi-tui`
- TypeBox for tool schemas

## Commands

Use these project commands:

```bash
pnpm install
pnpm test
pnpm typecheck
pnpm format
pnpm lint
pnpm check
```

Notes:

- `pnpm check` runs Biome write/check flow for this repo.
- `pnpm test` runs the Node test runner against `tests/*.test.ts`.
- the extension is intended to be loaded dynamically with:

```bash
pi -e ./src/index.ts
```

## File-specific guidance

### `src/`

- keep implementation in TypeScript only
- preserve the separation between:
  - schema/types
  - state logic
  - UI component logic
  - tool registration
- avoid introducing unnecessary framework abstractions
- prefer small pure helper functions where possible

### `tests/`

- add or update tests when changing state behavior
- prefer focused tests for:
  - question normalization
  - selection behavior
  - tab movement
  - custom answer submission
  - result summarization
  - cancellation behavior

### docs

Keep docs practical and synced with the implementation.

- `README.md`: how to install, run, test, and use the tool
- `SPEC.md`: intended design and UX contract
- `RESEARCH.md`: harness comparison notes
- `FINDINGS.md`: synthesized conclusions from source research

## Coding expectations

- follow Biome/Ultracite formatting and lint expectations
- prefer explicit, readable code over clever code
- use descriptive names
- use early returns to keep control flow simple
- avoid dead code and generic boilerplate comments
- do not add React/JSX-specific patterns unless the repo actually starts using them

## What to avoid

- do not add unrelated framework guidance or dependencies
- do not add browser/web UI unless the task explicitly requires it
- do not hardcode machine-specific paths
- do not weaken type safety just to silence errors
- do not commit editor-specific files unless they are clearly project-useful

## When changing behavior

If you change the ask flow in a meaningful way, update the relevant docs in the same change:

- user-facing usage changes -> `README.md`
- architecture/contract changes -> `SPEC.md`
- comparative harness findings -> `RESEARCH.md` / `FINDINGS.md`

## Preferred workflow for agents

1. read the relevant docs first
2. inspect the existing implementation before refactoring
3. make the smallest coherent change
4. run:
   - `pnpm format`
   - `pnpm typecheck`
   - `pnpm test`
5. update docs if behavior or expectations changed