chore(ask): clean up ask tool prototype

2026-04-17 12:08:06 +02:00
parent 133a0548ba
commit a212997786
3 changed files with 279 additions and 48 deletions
@@ -0,0 +1,136 @@
+# 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