pi-ask: Instructions file for Codex

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.