pi-ask-user 0.1.1 → 0.2.0

package/README.md

@@ -9,6 +9,30 @@ A Pi package that adds an interactive `ask_user` tool for collecting user decisi
 - Optional freeform responses
 - Context display support
 - Graceful fallback when interactive UI is unavailable
+- Bundled `ask-user` skill for mandatory decision-gating in high-stakes or ambiguous tasks
+
+## Bundled skill: `ask-user`
+
+This package now ships a skill at `skills/ask-user/SKILL.md` that nudges/mandates the agent to use `ask_user` when:
+
+- architectural trade-offs are high impact
+- requirements are ambiguous or conflicting
+- assumptions would materially change implementation
+
+The skill follows a "decision handshake" flow:
+
+1. Gather evidence and summarize context
+2. Ask one focused question via `ask_user`
+3. Wait for explicit user choice
+4. Confirm the decision, then proceed
+
+See: `skills/ask-user/references/ask-user-skill-extension-spec.md`.
+
+## Demo
+
+![ask_user demo](./media/ask-user-demo.gif)
+
+High-quality video: [ask-user-demo.mp4](./media/ask-user-demo.mp4)
 
 ## Install
 
@@ -37,27 +61,3 @@ The registered tool name is:
 }
 ```
 
-## Local development
-
-```bash
-pi -e ./index.ts
-```
-
-## Release workflow
-
-### One-time setup
-
-1. Add `NPM_TOKEN` in GitHub repo secrets.
-2. Keep `package.json` version in sync with release tag.
-
-### Publish with provenance (recommended)
-
-- Create tag: `vX.Y.Z`
-- Create a GitHub Release for that tag
-- The `publish.yml` workflow publishes to npm with `--provenance`
-
-You can also trigger the publish workflow manually from GitHub Actions.
-
-## License
-
-MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ask-user",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Interactive ask_user tool for pi-coding-agent with multi-select and freeform input UI",
   "type": "module",
   "keywords": [
@@ -28,10 +28,14 @@
   "pi": {
     "extensions": [
       "./index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "files": [
     "index.ts",
+    "skills",
     "README.md",
     "LICENSE"
   ],

package/skills/ask-user/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: ask-user
+description: "You MUST use this before high-stakes architectural decisions, irreversible changes, or when requirements are ambiguous. Runs a decision handshake with the ask_user tool: summarize context, present structured options, collect explicit user choice, then proceed."
+metadata:
+  short-description: Decision gate for ambiguity and high-stakes choices
+---
+
+# Ask User Decision Gate
+
+Use this skill to force explicit user alignment before consequential decisions.
+
+This skill is about **decision control**, not general chit-chat.
+
+## Non-negotiable rule
+
+Invoke `ask_user` before proceeding when **any** of the following is true:
+
+1. The next step changes architecture, schema, API contracts, deployment strategy, or security posture.
+2. The work is costly to undo (large refactor, migration, destructive edit, production-facing behavior change).
+3. Requirements, constraints, or success criteria are unclear, conflicting, or missing.
+4. Multiple valid options exist and the trade-off is preference-dependent.
+5. You are about to assume something that can materially change implementation.
+
+Do **not** skip this gate unless the user has already provided a clear, explicit decision for the exact trade-off.
+
+## Agent Protocol Handshake (required)
+
+Follow this handshake in order.
+
+### 1) Detect boundary
+Classify the current step as:
+- `high_stakes`
+- `ambiguous`
+- `both`
+- `clear` (no gate needed)
+
+If classification is not `clear`, continue.
+
+### 2) Gather evidence first
+Before asking, gather context from available tools (`read`, `bash`, `exa`, `ref`, etc.).
+Do not ask the user to decide blind.
+
+### 3) Synthesize context
+Prepare a short neutral summary (3-7 bullets or short paragraph) covering:
+- current state
+- key constraints
+- trade-offs
+- recommendation (if any)
+
+### 4) Ask one focused question
+Call `ask_user` with one decision at a time:
+- `question`: concrete decision prompt
+- `context`: synthesized summary
+- `options`: 2-5 clear choices when possible
+- `allowMultiple`: `false` unless independent selections are genuinely needed
+- `allowFreeform`: usually `true`
+
+### 5) Commit the decision
+After response:
+- restate the decision in plain language
+- state what will be done next
+- proceed with implementation
+
+### 6) Re-open only on new ambiguity
+Ask again only if materially new uncertainty appears.
+Avoid repetitive confirmation loops.
+
+## Anti-overasking guardrails (required)
+
+Apply a strict question budget per decision boundary:
+
+- **Max 1** `ask_user` call per decision boundary in normal cases.
+- **Max 2** `ask_user` calls for the same boundary when first response is unclear/cancelled.
+- Never ask the same trade-off again without new evidence.
+
+Escalation ladder:
+
+1. **Attempt 1:** structured options + concise context.
+2. **Attempt 2 (only if needed):** narrower question with agent recommendation and explicit choices:
+   - `Proceed with recommended option`
+   - `Choose another option` (freeform)
+   - `Stop for now`
+
+After attempt 2:
+
+- If boundary is `high_stakes` or `both`: **stop and mark blocked**. Do not keep asking.
+- If boundary is `ambiguous` only and user says “your call” or equivalent: proceed with the most reversible default and state assumptions explicitly.
+
+## `ask_user` payload quality standard
+
+### Question quality
+Use:
+- “Which option should we adopt for X?”
+- “Do you want A (fast) or B (safer) for Y?”
+
+Avoid:
+- broad/open prompts with no decision boundary
+- multiple unrelated decisions in one question
+- questions that should be answered by reading code/docs first
+
+### Option quality
+Options must be:
+- mutually understandable
+- short and outcome-oriented
+- explicit on trade-offs
+
+Good options include a short description when trade-offs are non-obvious.
+
+## Recommended patterns
+
+### Single-select architecture decision
+
+```json
+{
+  "question": "Which caching strategy should we use for the first release?",
+  "context": "Current API has p95 latency issues. Redis is fastest but adds infra complexity; in-memory cache is simpler but not shared across instances.",
+  "options": [
+    { "title": "In-memory cache", "description": "Simpler rollout, weaker horizontal consistency" },
+    { "title": "Redis cache", "description": "Better consistency and scalability, more ops overhead" }
+  ],
+  "allowMultiple": false,
+  "allowFreeform": true
+}
+```
+
+### Multi-select when decisions are independent
+
+```json
+{
+  "question": "Select the first-wave hardening items to implement now.",
+  "context": "We can ship quickly with baseline controls, then add targeted hardening. Budget is limited to 1-2 days.",
+  "options": [
+    "Rate limiting",
+    "Audit logging",
+    "Input schema validation",
+    "Secrets rotation"
+  ],
+  "allowMultiple": true,
+  "allowFreeform": true
+}
+```
+
+## Anti-patterns
+
+- Asking `ask_user` without first gathering context
+- Using it for trivial formatting choices
+- Forcing options when freeform is clearly better
+- Asking the same question repeatedly without new information
+- Proceeding with high-stakes implementation after unclear/cancelled answer
+
+## If user cancels or answer is unclear
+
+Pause execution and explain what is blocked.
+Use at most one narrower follow-up `ask_user` question (attempt 2).
+After that, do not continue asking in a loop:
+- for high-stakes decisions: remain blocked until explicit decision
+- for ambiguity-only decisions: proceed only if user delegated the choice ("your call")
+
+## Additional reference
+
+For full trigger matrix, UX conventions, and extension interaction details, read:
+- `references/ask-user-skill-extension-spec.md`

package/skills/ask-user/references/ask-user-skill-extension-spec.md

@@ -0,0 +1,250 @@
+# Ask User Skill × Extension Interaction Spec
+
+## Purpose
+
+Define how the `ask-user` skill (prompt-time behavior) and the `ask_user` extension tool (runtime UI) cooperate to create reliable human-in-the-loop decisions.
+
+This spec optimizes for:
+- explicit user control at decision boundaries
+- low-friction interactive UX
+- minimal context bloat (progressive disclosure)
+- deterministic behavior across high-stakes workflows
+
+---
+
+## 1) 2026 Pattern Alignment
+
+This design intentionally follows three emerging patterns used by modern agent systems.
+
+### A. Progressive Disclosure
+
+The skill uses layered loading:
+
+1. **Metadata layer** (`name`, `description`) always in prompt.
+2. **Core protocol layer** (`SKILL.md`) loaded only when relevant.
+3. **Detailed reference layer** (`references/*.md`) loaded only when needed.
+
+Implication: keep `SKILL.md` concise and decision-focused; move large examples and policy details into references.
+
+### B. Agent Protocol Handshakes
+
+High-impact actions require a handshake:
+
+`detect boundary -> summarize evidence -> ask -> explicit user choice -> commit -> execute`
+
+The handshake prevents implicit assumptions from silently becoming implementation decisions.
+
+### C. Context-Aware Loading
+
+Questions must be formed from current evidence (repo state, docs, logs, external research), not from generic prompts.
+
+The `context` field in `ask_user` is the transport for this condensed evidence.
+
+---
+
+## 2) System Model
+
+### Components
+
+1. **Skill layer (`skills/ask-user/SKILL.md`)**
+   - decides *when* user interaction is mandatory
+   - enforces handshake behavior
+
+2. **Extension layer (`index.ts`, tool `ask_user`)**
+   - renders question UX (single-select, multi-select, freeform)
+   - returns normalized answer text to the agent
+
+3. **Model runtime**
+   - interprets skill guidance
+   - calls `ask_user` with structured payload
+   - resumes execution after explicit user response
+
+### Contract boundary
+
+- Skill controls policy and decision gating.
+- Extension controls interaction mechanics.
+- Model must not bypass skill policy for high-stakes/ambiguous decisions.
+
+---
+
+## 3) Trigger Matrix (When to Call `ask_user`)
+
+| Scenario | Must Ask? | Why |
+|---|---:|---|
+| Architecture trade-off (e.g., queue vs cron, SQL vs KV) | Yes | Preference-sensitive, high blast radius |
+| Data schema / migration path selection | Yes | Costly to reverse |
+| Security/compliance posture trade-off | Yes | Risk ownership is human |
+| Requirements conflict or ambiguity | Yes | Need explicit intent |
+| Non-trivial scope cut/prioritization | Yes | Product decision, not purely technical |
+| Purely local refactor with identical behavior | Usually no | No policy-level decision |
+| Formatting-only edits | No | Trivial |
+| User already gave explicit choice for exact trade-off | No (unless new ambiguity) | Decision already captured |
+
+---
+
+## 4) Handshake State Machine
+
+```text
+DISCOVER -> CLASSIFY -> (CLEAR -> EXECUTE)
+                     -> (AMBIGUOUS/HIGH_STAKES -> EVIDENCE -> ASK -> WAIT -> COMMIT -> EXECUTE)
+```
+
+### State definitions
+
+- **DISCOVER**: inspect task and current project state.
+- **CLASSIFY**: decide whether decision gate is required.
+- **EVIDENCE**: gather and compress decision context.
+- **ASK**: invoke `ask_user` with a single focused decision.
+- **WAIT**: pause implementation until response arrives.
+- **COMMIT**: restate chosen option and intended next action.
+- **EXECUTE**: implement according to confirmed decision.
+
+### Cancellation behavior
+
+If user cancels or response is unclear:
+- enforce a **max two-attempt budget** for the same decision boundary
+- attempt 1: normal structured question
+- attempt 2: narrower question with explicit recommendation + `Proceed with recommendation / Choose another / Stop`
+
+After attempt 2:
+- for `high_stakes` or `both`: do not continue; report blocked status
+- for `ambiguous` only: proceed only when user delegates choice (e.g., "your call"), using the most reversible default and explicit assumptions
+
+---
+
+## 5) `ask_user` Payload Design Standard
+
+### Field mapping
+
+| Field | Required | Rule |
+|---|---:|---|
+| `question` | Yes | One decision only, concrete and action-bound |
+| `context` | Recommended | 3-7 bullets or short paragraph with evidence and trade-offs |
+| `options` | Optional | Prefer 2-5 choices when stable alternatives exist |
+| `allowMultiple` | Optional | `true` only for independent selections |
+| `allowFreeform` | Optional | Usually `true`; set `false` only when strict menu required |
+
+### Style rules
+
+- Keep options concise, decision-oriented, and contrastive.
+- Include brief descriptions for non-obvious trade-offs.
+- Avoid stacking unrelated questions.
+- Ask after evidence gathering, not before.
+
+---
+
+## 6) UX Guidance for Best Outcomes
+
+### Good interaction shape
+
+1. Agent summarizes known constraints.
+2. Agent asks one clear question.
+3. User selects an option quickly (or writes freeform).
+4. Agent confirms and proceeds.
+
+### Avoid
+
+- long speculative context dumps
+- “What do you want?” without options
+- repeated confirmation of unchanged decisions
+- more than two attempts for the same decision boundary
+- hidden assumptions after user response
+
+### Recommended defaults
+
+- `allowFreeform: true`
+- `allowMultiple: false`
+- `options`: include concise titles + descriptions for trade-offs
+
+---
+
+## 7) Runtime and Fallback Semantics
+
+The extension already provides these behavior guarantees:
+
+1. **Interactive mode with UI**
+   - single-select list, multi-select list, or freeform editor
+
+2. **No options provided**
+   - freeform input prompt is used
+
+3. **No interactive UI available**
+   - tool returns an error-style textual fallback that includes question/context/options
+
+Design implication:
+- skill should prefer structured options when ambiguity is high
+- but always permit freeform for unanticipated requirements
+
+---
+
+## 8) Quality Rubric
+
+A decision-gated interaction is successful when all are true:
+
+- [ ] High-stakes or ambiguous boundary was detected
+- [ ] Context was gathered before asking
+- [ ] At most two decision questions were asked for the same boundary (normally one)
+- [ ] User response was explicit
+- [ ] Agent restated decision before execution
+- [ ] Implementation followed the selected path
+
+Failure signals:
+- agent made architectural choice without user decision
+- question lacked trade-off context
+- user answer ignored or overwritten
+
+---
+
+## 9) Example Protocol Templates
+
+### Template: architecture fork
+
+```json
+{
+  "question": "Which implementation path should we use for v1?",
+  "context": "Path A is faster to ship but less extensible. Path B takes longer but supports plugin-style growth. Existing deadline is 2 weeks.",
+  "options": [
+    { "title": "Path A (ship fast)", "description": "Lowest scope, revisit architecture later" },
+    { "title": "Path B (extensible)", "description": "Higher initial effort, cleaner long-term composition" }
+  ],
+  "allowMultiple": false,
+  "allowFreeform": true
+}
+```
+
+### Template: ambiguity cleanup
+
+```json
+{
+  "question": "Which requirement should be prioritized first?",
+  "context": "Current request mixes performance tuning and UI redesign. Doing both now risks delaying delivery.",
+  "options": [
+    "Performance first",
+    "UI redesign first",
+    "Do a minimal pass on both"
+  ],
+  "allowMultiple": false,
+  "allowFreeform": true
+}
+```
+
+---
+
+## 10) Packaging + Distribution Notes
+
+To ship this skill with the extension package:
+
+- include `skills/` in npm package files
+- register skills in `package.json` under `pi.skills`
+
+This ensures the skill is discoverable at startup and available for implicit invocation.
+
+---
+
+## 11) Future Enhancements (Optional)
+
+- **Decision memory log**: append chosen options to a lightweight session decision ledger.
+- **Adaptive option generation**: tailor options by repo language/framework context.
+- **Confidence thresholding**: auto-trigger ask gate when model confidence in requirements is low.
+
+These are optional and not required for initial rollout.