@geoqiao/pi-ask 1.3.1 → 1.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/README.md +97 -247
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,3 +1,9 @@
1
+ ## 1.3.2
2
+
3
+ ### Patch Changes
4
+
5
+ - 058a2d4: Streamline the package READMEs with quick starts, common commands, and capability tables. Link pi-ask configuration to its existing source-of-truth guide, fold detailed screenshots, and preserve context-first clarification and TUI/RPC boundaries. Clarify paseo-btw prerequisites, native-versus-Skill invocation, context inheritance, and safety limitations without changing runtime behavior.
6
+
1
7
  ## 1.3.1
2
8
 
3
9
  ### Patch Changes
package/README.md CHANGED
@@ -1,316 +1,166 @@
1
- ![pi-ask main image](docs/media/pi-ask-main.png)
2
-
3
- # @geoqiao/pi-ask
1
+ # Pi Ask
4
2
 
3
+ [![npm version](https://img.shields.io/npm/v/@geoqiao/pi-ask)](https://www.npmjs.com/package/@geoqiao/pi-ask)
5
4
  [![npm downloads](https://badgen.net/npm/dm/@geoqiao/pi-ask)](https://www.npmjs.com/package/@geoqiao/pi-ask)
6
5
  [![CI](https://github.com/geoqiao/pi-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/geoqiao/pi-tools/actions/workflows/ci.yml)
7
- [![last commit](https://badgen.net/github/last-commit/geoqiao/pi-tools)](https://github.com/geoqiao/pi-tools/commits/main)
8
- [![stars](https://badgen.net/github/stars/geoqiao/pi-tools)](https://github.com/geoqiao/pi-tools/stargazers)
9
-
10
- > [!IMPORTANT]
11
- > This is an independently maintained continuation of [`eko24ive/pi-ask`](https://github.com/eko24ive/pi-ask), with portable Pi RPC mode support while preserving the rich TUI experience.
12
-
13
- `@geoqiao/pi-ask` is an ask tool that cares about your answers.
14
6
 
15
- It lets an agent pause, ask structured questions in a terminal UI or portable Pi RPC dialogs, and continue with normalized answers instead of guessing.
7
+ **Answer your agent's questions without losing the thread.**
16
8
 
17
- ![pi-ask demo](docs/media/pi-ask-demo.gif)
9
+ `@geoqiao/pi-ask` adds structured clarification to [Pi](https://pi.dev): choose options, type your own answer, or ask for an explanation before deciding. Get a rich terminal form in TUI mode and portable sequential dialogs in RPC mode, with normalized answers returned to the agent.
18
10
 
19
- High-quality video: [demo.mp4](https://github.com/user-attachments/assets/a8503ca9-afcb-4c31-9edc-353b985a0209)
11
+ ![Pi Ask: structured questions, custom answers, and review](docs/media/pi-ask-demo.gif)
20
12
 
21
- ## Upstream and contributions
13
+ [Watch the high-quality demo](https://github.com/user-attachments/assets/a8503ca9-afcb-4c31-9edc-353b985a0209)
22
14
 
23
- This project preserves the upstream Git history, MIT license, and author attribution. New
24
- development and releases are maintained independently in the
25
- [`geoqiao/pi-tools`](https://github.com/geoqiao/pi-tools/tree/main/packages/pi-ask) monorepo. Issues
26
- and contributions are welcome there.
15
+ [Quick start](#quick-start) · [Everyday use](#everyday-use) · [TUI and RPC](#tui-and-rpc) · [Settings](#settings) · [Documentation](#documentation)
27
16
 
28
- ## Install
17
+ ## Quick start
29
18
 
30
19
  ```bash
31
20
  pi install npm:@geoqiao/pi-ask
32
21
  ```
33
22
 
34
- Or try it without installing (load once for the current run):
23
+ Run `/reload` in an already-open Pi session. The agent can then call `ask_user` when clarification is needed; you can also explicitly ask it to interview you.
24
+
25
+ To try the package for one run without adding it to your saved package configuration:
35
26
 
36
27
  ```bash
37
28
  pi -e npm:@geoqiao/pi-ask
38
29
  ```
39
30
 
40
- ## Features
41
-
42
- Once installed, this package gives the agent a native way to ask for clarification instead of guessing. The rich interface is used in TUI mode.
43
-
44
- - 🧭 Familiar ask-style interface: tabbed questions, single/multi select, and preview mode
45
- - ⭐ Optional warning-colored `(recommended)` markers that do not preselect answers
46
- - ✍️ Inline free-form `Type your own` answers
47
- - 📎 Native pi-style `@` file references inside answer and note editors
48
- - 📝 Question-level and option-level notes
49
- - 👀 Review tab with `Submit`, `Elaborate`, and `Cancel`
50
- - 💬 Elaboration flow to capture note-based clarification before final submission
51
- - 🔌 Pi RPC fallback using portable sequential dialogs with normalized results
52
- - ⌨️ Context-aware customizable keymaps with aliases for main flow, editors, and settings
53
- - ⚙️ Ask settings with persisted behaviour, notifications, keymaps, and `/answer` extraction config
54
- - 🔔 Optional external notifications when an ask flow is waiting for input
55
- - 🔁 Slash commands for fallback/replay:
56
- - `/answer` extracts questions from the latest assistant message into an ask flow
57
- - `/answer:again` reopens the latest `/answer` form on the current branch
58
- - `/ask:replay` replays the latest real `ask_user` form on the current branch
59
- - 🛟 Automatic recovery of an unanswered `ask_user` form after startup, resume, or fork
60
- - 🗣️ You can talk to your agent to configure pi-ask; it will read the bundled configuration guide and tailor the config for you
31
+ If the agent has already asked questions in plain text, run `/answer` in TUI mode to turn its latest completed message into a form.
61
32
 
62
- ## Feature walkthrough
33
+ > Independently maintained continuation of [eko24ive/pi-ask](https://github.com/eko24ive/pi-ask), preserving the upstream history, MIT license, and attribution while adding portable Pi RPC support.
63
34
 
64
- ### Native `@` file references
65
- Use pi-style `@` file path autocomplete inside free-form answers and note editors.
35
+ ## Everyday use
66
36
 
67
- ![Native pi-style @ file references inside the ask flow](docs/media/feature-at-file-mentions.png)
68
-
69
- ### Option and question notes
70
- Attach clarification notes to a specific option (`n`) or add broader question-level context (`Shift+N`).
71
-
72
- | Option notes | Question notes |
73
- |---|---|
74
- | ![Option note editor with note text for selected option](docs/media/feature-option-note.png) | ![Question-level note editor with saved note](docs/media/feature-question-note.png) |
75
-
76
- ### Review tab — Elaborate and Submit
77
- Ask the agent to elaborate on notes before finalizing choices, or review all answers before returning them to the agent.
78
-
79
- | Elaborate | Submit |
37
+ | Need | Feature |
80
38
  |---|---|
81
- | ![Review tab with Elaborate action and expanded note preview](docs/media/feature-review-elaborate.png) | ![Review tab with Submit action highlighted](docs/media/feature-review-submit.png) |
39
+ | Choose one answer or several | Single-select, multi-select, and preview questions |
40
+ | Give an answer outside the options | Inline `Type your own`, with native Pi-style `@` file references |
41
+ | Understand a choice before deciding | Notes on a question or option, followed by `Elaborate` |
42
+ | Review before continuing | `Submit`, `Elaborate`, and `Cancel` review actions in TUI |
43
+ | See the agent's recommendation | Optional `(recommended)` markers with reasons; never preselected |
44
+ | Recover a previous form | Replay commands and automatic recovery of interrupted TUI asks |
82
45
 
83
- ### Single-select and multi-select questions
84
- Pick one option when answers are mutually exclusive, or choose multiple options when several answers apply.
46
+ ### Commands
85
47
 
86
- | Single-select | Multi-select |
48
+ | Command | What it does |
87
49
  |---|---|
88
- | ![Single-select question with one selected option](docs/media/feature-single-select.png) | ![Multi-select question with multiple selected options](docs/media/feature-multi-select.png) |
89
-
90
- ### Preview mode
91
- Use a dedicated preview pane when options need richer detail.
50
+ | `/answer` | Extracts questions from the latest completed assistant message and opens an ask form |
51
+ | `/answer:again` | Reopens the latest `/answer` form on the current branch |
52
+ | `/ask:replay` | Reopens the latest real `ask_user` form on the current branch |
53
+ | `/ask-settings` | Opens the settings overlay; `?` inside a form opens the same overlay |
92
54
 
93
- ![Preview question showing a dedicated preview pane](docs/media/feature-preview-pane.png)
55
+ These commands are TUI-only. Replay is branch-aware and works with `/resume` and `/tree`. Closing a command-opened form does not start an agent turn; submitting or elaborating sends a normal user follow-up.
94
56
 
95
- ### Custom answer (`Type your own`)
96
- Capture free-form input inline without leaving the flow.
57
+ `/answer` uses a configured extraction model and the preceding user message as context. It validates the extracted form and retries missing or invalid output. Normal `ask_user` calls do not use this extraction model. See [extraction settings](docs/configuration.md#answer-extraction).
97
58
 
98
- ![Inline custom answer input for Type your own option](docs/media/feature-custom-answer-input.png)
59
+ ### When the agent asks
99
60
 
100
- ## Default key bindings
61
+ The agent should read available code, docs, conversation, and prior answers first. It asks only for unresolved critical requirements, outcome-changing preferences, or consequential/hard-to-reverse actions beyond existing authorization. Explicitly requested interviews, requirements gathering, and interactive questions also use `ask_user`.
101
62
 
102
- Open ask settings with `?` during the ask flow, or with the `/ask-settings` command from pi.
63
+ Clear small changes, settled choices, authorized reversible steps, and routine implementation details proceed without reconfirmation. Multiple options or architecture/naming/research labels alone do not trigger questions; clear comparison/research requests get analysis first. Follow-ups address only current blockers, and settled decisions reopen only for materially new information.
103
64
 
104
- Keymaps are context-aware and configurable in `~/.pi/agent/extensions/eko24ive-pi-ask.json`. The established filename is retained so users can switch from the upstream package without losing settings.
105
- Each action accepts a key string or an array of aliases.
65
+ Delegated autonomy does not waive safety boundaries. Cancellation, skipped questions, and unclear answers are not high-risk approval. This is prompt guidance, **not a runtime permission check or a guarantee of model behavior**. See the [policy and verification limits](docs/contract.md#skill-alignment-advisory) and [skill examples](skills/ask-user/SKILL.md#examples-and-behavioral-evaluation-cases).
106
66
 
107
- Default contexts:
67
+ ## TUI and RPC
108
68
 
109
- - `global`: `dismiss` (`Ctrl+C`) and `settings` (`?`)
110
- - `main`: confirm/cancel/toggle, tab navigation, option navigation, and note shortcuts
111
- - `editor`: custom answer submit/close and empty-editor navigation
112
- - `noteEditor`: note save/close and empty-editor navigation
113
- - `settingsModal`: close, next/previous setting, and toggle
69
+ Both modes return normalized answers, but their interfaces differ:
114
70
 
115
- Fixed bindings:
116
-
117
- | Key | Context | Effect |
71
+ | Capability | TUI | RPC with portable UI support |
118
72
  |---|---|---|
119
- | `1..9` | Options list | Select or toggle matching option |
120
- | `1` `2` `3` | Review tab | Trigger `Submit` / `Elaborate` / `Cancel` |
121
- | `@` | Editors | File-reference affordance |
122
- | Arrow keys / `Tab` | Non-empty editor | Stay in editor for cursor movement |
123
-
124
- Review-tab shortcuts can optionally require the same number key twice via `behaviour.doublePressReviewShortcuts`. `behaviour.presentSingleAsMulti` can render future single-select questions as multi-select while preserving the requested type in results; use `main.changeQuestionType` (`t` by default) to change the active question type live.
125
-
126
- You can edit the config file yourself, ask pi to edit it for you, or use `/ask-settings` to find the exact config path, toggle behaviour/notification settings, or reset config to defaults with a guarded double press. pi-ask treats the config file as user-owned: load-time migrations and invalid files are handled in memory without rewriting or backing up the file, and read-only/externally managed configs fail gracefully with a manual-edit message.
127
-
128
- ```json
129
- {
130
- "schemaVersion": 5,
131
- "answer": {
132
- "extractionModels": [
133
- { "provider": "openai-codex", "id": "gpt-5.4-mini" },
134
- { "provider": "github-copilot", "id": "gpt-5.4-mini" },
135
- { "provider": "anthropic", "id": "claude-haiku-4-5" }
136
- ],
137
- "extractionTimeoutMs": 30000,
138
- "extractionRetries": 1
139
- },
140
- "behaviour": {
141
- "autoSubmitWhenAnsweredWithoutNotes": false,
142
- "confirmDismissWhenDirty": true,
143
- "doublePressReviewShortcuts": true,
144
- "presentSingleAsMulti": false,
145
- "showFooterHints": true
146
- },
147
- "keymaps": {
148
- "global": { "dismiss": ["ctrl+c"], "settings": ["?"] },
149
- "main": {
150
- "confirm": ["enter"],
151
- "cancel": ["esc"],
152
- "toggle": ["space"],
153
- "changeQuestionType": ["t"],
154
- "nextTab": ["tab", "right"],
155
- "previousTab": ["shift+tab", "left"],
156
- "nextOption": ["down"],
157
- "previousOption": ["up"],
158
- "optionNote": ["n"],
159
- "questionNote": ["shift+n"]
160
- },
161
- "editor": {
162
- "submit": ["enter"],
163
- "close": ["esc"],
164
- "nextTabWhenEmpty": ["tab", "right"],
165
- "previousTabWhenEmpty": ["shift+tab", "left"],
166
- "nextOptionWhenEmpty": ["down"],
167
- "previousOptionWhenEmpty": ["up"]
168
- },
169
- "noteEditor": {
170
- "save": ["enter"],
171
- "close": ["esc"],
172
- "nextTabWhenEmpty": ["tab", "right"],
173
- "previousTabWhenEmpty": ["shift+tab", "left"],
174
- "nextOptionWhenEmpty": ["down"],
175
- "previousOptionWhenEmpty": ["up"]
176
- },
177
- "settingsModal": {
178
- "close": ["esc", "ctrl+c", "?"],
179
- "nextOption": ["down"],
180
- "previousOption": ["up"],
181
- "toggle": ["enter", "space"]
182
- }
183
- },
184
- "notifications": {
185
- "enabled": true,
186
- "channels": ["bell"]
187
- }
188
- }
189
- ```
190
-
191
- Accepted notation follows pi-tui key ids. Common aliases are normalized, for example `escape` → `esc`, `return` → `enter`, `control+c` → `ctrl+c`, and `Shift+N` → `shift+n`.
192
-
193
- ## Use
194
-
195
- After installation, the extension registers the `ask_user` tool plus `/ask-settings`, `/answer`, `/answer:again`, and `/ask:replay` commands.
196
-
197
- Agents first read available context and call `ask_user` only for unresolved critical requirements, outcome-changing preferences, or consequential/hard-to-reverse actions beyond existing authorization. Explicitly requested interviews and requirements gathering also use the tool.
198
-
199
- Clear small changes, settled choices, authorized reversible steps, and routine implementation details proceed without reconfirmation. Multiple options or an architecture/naming/research label alone do not trigger questions; clear comparison/research requests get analysis first. Questions stay on current blockers, and settled decisions reopen only for materially new information. Delegated autonomy does not waive safety boundaries, and cancellation or missing/unclear answers never supplies high-risk approval. This is prompt guidance, not a runtime permission check; see the [policy and verification limits](docs/contract.md#skill-alignment-advisory) and [skill examples](skills/ask-user/SKILL.md#examples-and-behavioral-evaluation-cases).
200
-
201
- Agents can mark any number of grounded preferences with `recommended: true` and use option descriptions for reasons. In interactive sessions, it opens a terminal UI flow for structured answers, supports native pi-style `@` file references while typing answers or notes, and returns normalized answers back to the agent. Ask settings are available both from `?` in the ask flow and from the `/ask-settings` command. Behaviour and notification settings are binary `on`/`off` toggles that save immediately when the config file is writable; save failures revert the toggle and show a manual-edit message. The settings overlay includes a guarded double-press reset-to-defaults action; keymaps, notification channels, and extraction settings are changed by editing the shown config file path.
202
-
203
- ### Pi RPC fallback
204
-
205
- When Pi runs in RPC mode with portable extension UI support, `ask_user` keeps the same normalized result contract but uses sequential dialogs:
206
-
207
- - each question card contains only its real options plus `Type something…`
208
- - selecting a real option and submitting advances directly to the next question or completes the flow
209
- - `Type something…` opens one `input` dialog; on multi questions it is the fallback for entering multiple choices
210
- - dismissing a question or its input skips that question instead of cancelling the flow
211
- - recommendation markers, descriptions, and preview content are flattened into readable option strings without changing canonical values or labels
212
- - multiple questions include `[current/total]` progress in each dialog title
213
- - tool abort signals close portable `select`/`input` dialogs and return `cancelled: true`
214
-
215
- RPC intentionally does not reproduce the tabbed same-screen form, native checkbox cards, repeated multi-select cards, notes, Skip/Cancel option rows, custom preview pane, question-type hotkeys, settings overlay, or final Submit/Elaborate review tab. The fallback completes in `submit` mode after the sequential questions. `/answer`, `/answer:again`, `/ask:replay`, and `/ask-settings` remain TUI-only.
73
+ | Layout | Tabbed, same-screen form | Sequential dialogs with `[current/total]` progress |
74
+ | Answers | Native single/multi selection and custom text | One real option or `Type something…`; type multiple choices as free-form text |
75
+ | Previews and recommendations | Preview pane and recommendation subtitles | Details flattened into option text; canonical labels and values stay unchanged |
76
+ | Notes and review | Question/option notes and final review tab | No notes or final review; submitting an option advances directly |
77
+ | Settings and replay commands | Supported | TUI-only |
78
+ | Dismissal | Flow-level cancel/dismiss, with optional dirty-state confirmation | Dismissing a card or input skips that question; tool abort cancels the flow |
216
79
 
217
- ### Answer and replay commands
80
+ RPC does not emulate checkbox cards, repeated multi-select dialogs, or custom preview panes. Unanswered questions remain unanswered, including those marked `required`: that field is advisory, not submission enforcement.
218
81
 
219
- `/answer` is useful when the agent asked questions in plain text instead of using `ask_user`. It supplies the preceding user message as context, asks the configured extraction model for one synthetic `ask_user` tool call, validates the result, and opens the same ask UI. Missing or invalid tool calls are retried; raw and fenced JSON text remain supported as fallbacks.
82
+ Print, JSON, and RPC without portable UI cannot open a form. They return a needs-user-input message with pending questions rather than pretending to collect answers.
220
83
 
221
- Replay commands are branch-aware. They read persisted entries from the current pi session branch, so they work naturally with `/resume`, `/tree`, and conversation branching:
84
+ ### Interrupted forms
222
85
 
223
- - `/answer:again` reopens the latest form created by `/answer` on this branch
224
- - `/ask:replay` reopens the latest real `ask_user` form on this branch
86
+ Starting, resuming, or forking a TUI session recovers its newest unresolved `ask_user` form once. Submission is delivered as a user message because the original tool execution no longer exists. Submit or cancel prevents another automatic reopen; `/ask:replay` remains available.
225
87
 
226
- Cancellation is local to the UI: closing a replayed form does not start a new agent turn. Submitted answers are sent back as a normal user follow-up message.
88
+ New sessions, extension reloads, non-TUI modes, and RPC do not trigger recovery.
227
89
 
228
- ### Interrupted ask forms
90
+ ## Settings
229
91
 
230
- If Pi stops while an `ask_user` form is open, the tool call remains without a result. Starting, resuming, or forking that session reopens the newest unanswered form once. Submitting sends the result as a user message because the original tool execution no longer exists. Cancelling dismisses the automatic recovery. Either outcome prevents another automatic reopen, while `/ask:replay` remains available.
92
+ Open `/ask-settings`, or press `?` inside the TUI form. You can adjust auto-submit, dirty-dismiss confirmation, review shortcut confirmation, single-as-multi presentation, footer hints, and notifications. Resetting defaults requires a guarded double press.
231
93
 
232
- New sessions, extension reloads, non-TUI modes, and RPC sessions do not trigger recovery.
94
+ Settings save when the file is writable; failed saves revert the change and show a manual-edit message. Invalid files and load-time migrations do not rewrite user-owned configuration. The established upstream-compatible path remains:
233
95
 
234
- Kudos to [@k0valik](https://github.com/k0valik) for the `/answer` idea.
235
-
236
- You can also talk to pi to configure this extension. When asked to customize pi-ask settings, keymaps, notifications, or extraction behavior, the agent is instructed to read the bundled `docs/configuration.md` guide first and then edit the config file accordingly.
237
-
238
- This package also bundles the `ask-user` skill profile from `skills/ask-user/SKILL.md`. It reinforces when to use the tool, is enabled by default when installed, and can be disabled via `pi config`. The skill was inspired by https://github.com/edlsh/pi-ask-user.
239
-
240
- You can still add your own agent instruction if you want to further reinforce usage.
241
-
242
- For exact input/output and UX guarantees, see [`docs/contract.md`](docs/contract.md).
243
-
244
- ## Local development
245
-
246
- ### Run locally in pi
247
-
248
- ```bash
249
- pi -e ./src/index.ts
96
+ ```text
97
+ ~/.pi/agent/extensions/eko24ive-pi-ask.json
250
98
  ```
251
99
 
252
- ### Run in isolated test mode (extension + bundled skill only)
253
-
254
- ```bash
255
- pnpm dev
256
- pnpm dev ../test
257
- ```
100
+ For the complete config shape, defaults, keymap rules, notification channels, and extraction settings, use **[docs/configuration.md](docs/configuration.md)** rather than copying a second config example from this README. You can also ask your agent to configure pi-ask; it is instructed to read that guide first.
258
101
 
259
- `pnpm dev [path]` runs pi with `--no-extensions --no-skills --no-prompt-templates --no-themes --no-context-files`, loads this repo’s extension and `skills/ask-user`, and starts pi from `[path]` by changing directories before launch (defaults to `.`).
102
+ ### Handy default keys
260
103
 
261
- ### Install dependencies
104
+ | Key | Context | Action |
105
+ |---|---|---|
106
+ | `Tab` / `Shift+Tab` | Main flow | Next / previous question tab |
107
+ | `↑` / `↓` | Main flow | Move between options |
108
+ | `Enter` / `Space` | Main flow | Confirm / toggle |
109
+ | `1..9` | Options | Select or toggle by number |
110
+ | `n` / `Shift+N` | Main flow | Add an option / question note |
111
+ | `t` | Main flow | Change the current question type |
112
+ | `?` | Form | Open settings |
113
+ | `@` | Answer and note editors | Complete a file reference |
262
114
 
263
- ```bash
264
- pnpm install
265
- ```
115
+ In non-empty editors, arrows and `Tab` stay with the text. On the review tab, `1`, `2`, and `3` mean Submit, Elaborate, and Cancel; by default, each needs a second press. Destructive multi-to-single changes also require confirmation. The single-as-multi setting applies to new/replayed forms; `t` changes the active question. See [keymaps](docs/configuration.md#keymaps) for customization and the [contract](docs/contract.md#keyboard-behavior) for exact editing and cancellation behavior.
266
116
 
267
- ### Install git hooks (contributors)
117
+ <details>
118
+ <summary>Feature screenshots</summary>
268
119
 
269
- `lefthook` is not installed automatically. If you want the local commit hooks used by this repo, run:
120
+ | Feature | Preview |
121
+ |---|---|
122
+ | File references in answers and notes | ![Native @ file autocomplete](docs/media/feature-at-file-mentions.png) |
123
+ | Option and question notes | ![Option note](docs/media/feature-option-note.png) ![Question note](docs/media/feature-question-note.png) |
124
+ | Elaborate and Submit review | ![Elaborate review](docs/media/feature-review-elaborate.png) ![Submit review](docs/media/feature-review-submit.png) |
125
+ | Single and multi selection | ![Single selection](docs/media/feature-single-select.png) ![Multi selection](docs/media/feature-multi-select.png) |
126
+ | Rich option previews | ![Preview pane](docs/media/feature-preview-pane.png) |
127
+ | A custom answer | ![Type your own answer](docs/media/feature-custom-answer-input.png) |
270
128
 
271
- ```bash
272
- pnpm exec lefthook install
273
- ```
129
+ </details>
274
130
 
275
- ### Development commands
131
+ ## Documentation
276
132
 
277
- ```bash
278
- pnpm format
279
- pnpm lint
280
- pnpm check
281
- pnpm typecheck
282
- pnpm test
283
- ```
133
+ | Guide | Contents |
134
+ |---|---|
135
+ | [Configuration](docs/configuration.md) | Settings, keymaps, notifications, and `/answer` extraction |
136
+ | [Contract](docs/contract.md) | Input/output, TUI/RPC behavior, replay, and recovery guarantees |
137
+ | [Architecture](docs/architecture.md) | Module responsibilities and invariants |
138
+ | [Remote events](docs/remote-events.md) | Trusted local inter-extension integration |
139
+ | [Ask User skill](skills/ask-user/SKILL.md) | Context-first clarification policy and behavioral evaluation cases |
284
140
 
285
- ### Commit workflow
141
+ The bundled skill is enabled by default when installed and can be disabled through `pi config`. Tool guidance remains available without it.
286
142
 
287
- This monorepo uses `lefthook`, Commitizen, conventional commitlint, and Changesets.
143
+ ## Development
288
144
 
289
- If you want local hooks, install them once after `pnpm install`:
145
+ From the monorepo root:
290
146
 
291
147
  ```bash
292
- pnpm exec lefthook install
148
+ pnpm --filter @geoqiao/pi-ask dev
149
+ pnpm --filter @geoqiao/pi-ask dev /absolute/path/to/project
293
150
  ```
294
151
 
295
- From the repository root, the recommended flow is:
152
+ The dev script isolates this extension and its bundled skill using `--no-extensions --no-skills --no-prompt-templates --no-themes --no-context-files`, then changes to the target directory before launching Pi. To load just the extension manually, run `pi -e ./src/index.ts` from this package directory.
296
153
 
297
154
  ```bash
298
- pnpm commit
155
+ pnpm --filter @geoqiao/pi-ask typecheck
156
+ pnpm --filter @geoqiao/pi-ask test
157
+ pnpm --filter @geoqiao/pi-ask pack:check
299
158
  ```
300
159
 
301
- User-facing changes should also include a Changeset created with `pnpm changeset`.
160
+ See [CONTRIBUTING.md](../../CONTRIBUTING.md) for workspace setup, formatting, conventional commits, and Changesets. Local hooks are optional and are not installed automatically; run `pnpm exec lefthook install` at the workspace root if wanted. Keep README media in `docs/media/`; these assets are repository-only.
302
161
 
303
- ## Project layout
304
-
305
- - `src/` — TypeScript extension implementation
306
- - `tests/` — behavior-focused tests
307
- - `docs/` — small docs set for contract and architecture
308
- - `docs/media/` — repository-only README media assets
309
-
310
- ## Documentation
162
+ ## Attribution and contributions
311
163
 
312
- Docs stay intentionally small:
164
+ [MIT](LICENSE). This independently maintained continuation preserves [eko24ive/pi-ask](https://github.com/eko24ive/pi-ask)'s history and attribution. Development and issues live in [geoqiao/pi-tools](https://github.com/geoqiao/pi-tools).
313
165
 
314
- - `docs/README.md` index
315
- - `docs/contract.md` — external behavior
316
- - `docs/architecture.md` — module boundaries and invariants
166
+ Thanks to [@k0valik](https://github.com/k0valik) for the `/answer` idea. The bundled skill was inspired by [edlsh/pi-ask-user](https://github.com/edlsh/pi-ask-user).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@geoqiao/pi-ask",
3
- "version": "1.3.1",
3
+ "version": "1.3.2",
4
4
  "description": "Pi package that adds an interactive ask_user clarification tool.",
5
5
  "license": "MIT",
6
6
  "type": "module",