pi-ask/docs/README.md

Docs

This folder keeps only the documentation needed to understand and maintain the extension without turning docs into a second copy of the code.

Files

• configuration.md — source of truth for configuring pi-ask keymaps, behaviour, and /answer extraction
• contract.md — external behavior, full tool payload/result details, and UX guarantees
• architecture.md — module boundaries and invariants
• ../skills/ask-user/SKILL.md — auto-bundled agent-side decision-gate guidance; enabled by default, but can be disabled via pi config; inspired by https://github.com/edlsh/pi-ask-user

Reading order

• start with configuration.md for config-editing rules
• read contract.md for behavior
• read architecture.md for code layout

Local test run

From repo root, run:

pnpm dev
pnpm dev ../some-target-folder

This starts pi in isolated mode, loads only this extension and bundled ask-user skill, and uses the optional folder as --cd target.

Rule of thumb

If a detail is about implementation mechanics, it should usually live in src/ or tests/, not here.