pi-ask/AGENTS.md

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:

• src/ — implementation
• tests/ — behavior coverage
• docs/ — contract and architecture

Project goals

Optimize for:

1. pi-native design

   • prefer pi.registerTool()
   • prefer ctx.ui.custom() for complex flows
   • keep results compatible with normal pi tool results

2. testable architecture

   • keep state logic in plain TypeScript modules
   • keep pi/TUI wiring thin
   • prefer testing transitions and serialization over terminal rendering details

3. small docs, clear code

   • keep implementation consistent with docs/contract.md
   • update docs when behavior changes materially
   • keep docs focused on contracts and boundaries, not line-by-line explanations

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:

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:

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 short and synced with the implementation.

• README.md: install, run, and use
• docs/README.md: docs index
• docs/contract.md: external behavior and UX guarantees
• docs/architecture.md: module boundaries and invariants
• when the README last commit badge uses a ?v=<commit-sha> cache-busting param, update that SHA when the badge is stale and you are already touching README.md for a related docs/release refresh

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

Update the relevant docs in the same change:

• usage changes -> README.md
• contract or UX changes -> docs/contract.md
• module boundary changes -> docs/architecture.md

Preferred workflow

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