From a212997786a35f87891df00ca0c9289e252e219e Mon Sep 17 00:00:00 2001 From: Erik Kotsiuba Date: Fri, 17 Apr 2026 12:08:06 +0200 Subject: [PATCH] chore(ask): clean up ask tool prototype --- .vscode/settings.json | 54 +++++++++++++++++ .zed/settings.json | 137 +++++++++++++++++++++++++++--------------- AGENTS.md | 136 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 279 insertions(+), 48 deletions(-) create mode 100644 .vscode/settings.json create mode 100644 AGENTS.md diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..67949f7 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,54 @@ +{ + "editor.defaultFormatter": "esbenp.prettier-vscode", + "editor.formatOnPaste": true, + "editor.formatOnSave": true, + "emmet.showExpandedAbbreviation": "never", + "js/ts.tsdk.path": "node_modules/typescript/lib", + "js/ts.tsdk.promptToUseWorkspaceVersion": true, + "[css]": { + "editor.defaultFormatter": "biomejs.biome" + }, + "[graphql]": { + "editor.defaultFormatter": "biomejs.biome" + }, + "[html]": { + "editor.defaultFormatter": "biomejs.biome" + }, + "[javascript]": { + "editor.defaultFormatter": "biomejs.biome" + }, + "[javascriptreact]": { + "editor.defaultFormatter": "biomejs.biome" + }, + "[json]": { + "editor.defaultFormatter": "biomejs.biome" + }, + "[jsonc]": { + "editor.defaultFormatter": "biomejs.biome" + }, + "[markdown]": { + "editor.defaultFormatter": "biomejs.biome" + }, + "[mdx]": { + "editor.defaultFormatter": "biomejs.biome" + }, + "[svelte]": { + "editor.defaultFormatter": "biomejs.biome" + }, + "[typescript]": { + "editor.defaultFormatter": "biomejs.biome" + }, + "[typescriptreact]": { + "editor.defaultFormatter": "biomejs.biome" + }, + "[vue]": { + "editor.defaultFormatter": "biomejs.biome" + }, + "[yaml]": { + "editor.defaultFormatter": "biomejs.biome" + }, + "editor.codeActionsOnSave": { + "source.fixAll.biome": "explicit", + "source.organizeImports.biome": "explicit" + } +} diff --git a/.zed/settings.json b/.zed/settings.json index 502baec..0e11577 100644 --- a/.zed/settings.json +++ b/.zed/settings.json @@ -1,50 +1,91 @@ { - "format_on_save": "on", - "ensure_final_newline_on_save": true, - "remove_trailing_whitespace_on_save": true, - "languages": { - "TypeScript": { - "formatter": { - "external": { - "command": "pnpm", - "arguments": [ - "exec", - "biome", - "format", - "--stdin-file-path", - "{buffer_path}" - ] - } - }, - "hard_tabs": true - }, - "JSON": { - "formatter": { - "external": { - "command": "pnpm", - "arguments": [ - "exec", - "biome", - "format", - "--stdin-file-path", - "{buffer_path}" - ] - } - } - }, - "JSONC": { - "formatter": { - "external": { - "command": "pnpm", - "arguments": [ - "exec", - "biome", - "format", - "--stdin-file-path", - "{buffer_path}" - ] - } - } - } - } + "format_on_save": "on", + "ensure_final_newline_on_save": true, + "remove_trailing_whitespace_on_save": true, + "languages": { + "TypeScript": { + "formatter": { + "external": { + "command": "pnpm", + "arguments": [ + "exec", + "biome", + "format", + "--stdin-file-path", + "{buffer_path}" + ] + }, + "language_server": { + "name": "biome" + } + }, + "hard_tabs": true, + "code_actions_on_format": { + "source.fixAll.biome": true, + "source.organizeImports.biome": true + } + }, + "JSON": { + "formatter": { + "external": { + "command": "pnpm", + "arguments": [ + "exec", + "biome", + "format", + "--stdin-file-path", + "{buffer_path}" + ] + } + } + }, + "JSONC": { + "formatter": { + "external": { + "command": "pnpm", + "arguments": [ + "exec", + "biome", + "format", + "--stdin-file-path", + "{buffer_path}" + ] + } + } + }, + "JavaScript": { + "code_actions_on_format": { + "source.fixAll.biome": true, + "source.organizeImports.biome": true + }, + "formatter": { + "language_server": { + "name": "biome" + } + } + }, + "TSX": { + "code_actions_on_format": { + "source.fixAll.biome": true, + "source.organizeImports.biome": true + }, + "formatter": { + "language_server": { + "name": "biome" + } + } + } + }, + "formatter": "language_server", + "lsp": { + "typescript-language-server": { + "settings": { + "typescript": { + "preferences": { + "includePackageJsonAutoImports": "on" + } + } + } + } + } } diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..61e6380 --- /dev/null +++ b/AGENTS.md @@ -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