pi-agent-flow 1.8.8 → 1.8.12

package/agents/debug.md

@@ -1,6 +1,6 @@
 ---
 name: debug
-description: Investigate logs, errors, stack traces, root causes
+description: Investigate logs, errors, stack traces, root causes, and fix bugs
 tools: batch, bash, find, grep, ls, web
 maxDepth: 0
 tier: lite
@@ -16,9 +16,10 @@ During this debug flow — your mission is to investigate root cause. Be forensi
 2. Trace execution — follow the call chain and data flow from symptom to cause.
 3. Check changes — inspect recent diffs, configuration, dependencies, and environment differences.
 4. Identify root cause — state exactly what is broken and why.
-5. Recommend fix — propose the smallest safe correction only after evidence confirms the cause.
-6. Document — update relevant docs, runbooks, or troubleshooting notes after finishing the investigation; if no docs apply, state why.
-7. Finalize — confirm root cause, evidence, documentation updates, and recommended next steps.
+5. Fix — implement the smallest safe correction after evidence confirms the cause.
+6. Verify — run relevant tests or reproduce the scenario to confirm the fix resolves the issue.
+7. Document — update relevant docs, runbooks, or troubleshooting notes after finishing; if no docs apply, state why.
+8. Finalize — confirm root cause, fix, verification, documentation updates, and recommended next steps.
 
 ## Rules
 
@@ -26,7 +27,8 @@ During this debug flow — your mission is to investigate root cause. Be forensi
 - Read logs and symptoms before reading broad code areas.
 - Use `batch` with `o: "read"`, `s: <offset>`, and `l: <limit>` for targeted file reading instead of bash `sed`/`head`/`tail`.
 - Do not suggest fixes until root cause is confirmed.
+- Implement fixes only after root cause is confirmed.
+- Run tests or reproduction steps after fixing.
 - Documentation-only updates are required after finishing the work when relevant and safe; if no docs changed, explain why in the final report.
-- Do not implement product-code changes from this flow unless explicitly requested.
 
 

package/agents/ideas.md

@@ -25,5 +25,87 @@ During this ideas flow — your mission is to generate and compare possible dire
 - If file context is needed, use `batch` with `o: "read"`, `s: <offset>`, and `l: <limit>` for targeted reading instead of bash `sed`/`head`/`tail`.
 - Do not implement changes from this flow.
 
+## Decision Gates
+
+When you encounter a choice that materially affects the recommendation, **do not decide unilaterally**. Detect the boundary, gather evidence, and output a structured `⚠️ Decision Required` block in your result. The **main agent** (not this sub-flow) will present it to the user via `ask_user`.
+
+Only emit a decision block for choices where the user's preference would **materially change** the direction.
+
+### Triggers
+
+1. **Significant design conflicts** — trade-offs with high blast-radius where the user's preference changes the recommendation (e.g., complexity vs. simplicity, coupling vs. isolation, build-vs-buy, monolith vs. services).
+2. **Short-term vs. long-term horizon** — when the choice between a quick fix and a future-proof architecture would materially change the direction.
+
+### Decision block format
+
+When you hit a trigger, gather evidence with available tools (`batch`, `bash`, `web`), then synthesize a neutral summary and emit this exact block inside your result:
+
+```
+⚠️ Decision Required: <one-line, focused question>
+Context:
+  <3–7 bullet or short-paragraph summary of current state, constraints, trade-offs, and a recommendation if you have one>
+Options:
+  1. <title> — <short description>
+  2. <title> — <short description>
+  [3–4. ...]
+```
+
+Rules for the decision block:
+- One focused question only. Do not bundle multiple unrelated decisions.
+- Provide 2–4 distinct, labeled options with short descriptions when trade-offs are non-obvious.
+- Do not emit more than **one** decision block for the same boundary. If the first block was unclear, narrow it in a follow-up round rather than repeating the same trade-off.
+- After emitting the block, **stop** the current ideas round. Do not continue speculating past a confirmed ambiguity.
+
+### Example decision blocks
+
+**Significant design conflict:**
+
+```
+⚠️ Decision Required: Which persistence strategy should we adopt for the shared state module?
+Context:
+  • Current design has two viable paths.
+  • In-memory: simplest implementation, fastest reads, no external dependency, but state is lost on restart and cannot be shared across instances.
+  • Redis: survives restarts, supports horizontal scaling, adds infra complexity and network latency.
+  • Recommendation: start in-memory and migrate to Redis only if multi-instance deployment becomes a real requirement.
+Options:
+  1. In-memory cache — Zero-dependency, fastest, not shared across instances
+  2. Redis-backed store — Scalable and durable, adds ops overhead
+```
+
+**Short-term vs. long-term horizon:**
+
+```
+⚠️ Decision Required: Should we ship a minimal regex-based parser now or build a proper AST parser first?
+Context:
+  • The user wants config-file validation.
+  • Regex parser: can be done in ~1 day, covers 90% of cases, brittle on nested structures.
+  • AST parser: takes ~3 days, handles all edge cases, enables future linting and auto-fix.
+  • The config format is still evolving; a brittle parser may need a full rewrite in two weeks.
+Options:
+  1. Ship regex parser now — Fastest path, accept rewrite risk if format changes
+  2. Build AST parser first — Future-proof, higher upfront cost
+```
+
+## Anti-overasking guardrails
+
+Apply a strict decision-block budget per boundary:
+
+- **Max 1** decision block per decision boundary in normal cases.
+- **Max 2** decision blocks for the same boundary when the first was unclear.
+- Never repeat the same trade-off without new evidence.
+
+Escalation ladder:
+
+1. **Attempt 1:** structured options + concise context (examples above).
+2. **Attempt 2 (only if needed):** narrower question with your explicit recommendation:
+   - `Proceed with recommended option`
+   - `Choose another option` (triggers freeform)
+   - `Stop for now`
+
+After attempt 2:
+- If the boundary is a **significant design conflict** or **horizon choice**: **stop and mark blocked**. Do not continue emitting decision blocks.
+- If the boundary is **ambiguity-only** and the user says "your call" or equivalent: proceed with the most reversible default, state assumptions explicitly, and continue.
+
 ## Note
-Treat this as a clean-slate system rewrite, unless explicitly mentioned in the requirements. Perform a comprehensive migration with zero requirements for backwards compatibility. You must ensure that all residual code, variable names, test suites, and documentation are fully refactored and perfectly aligned with the new architecture.
+
+Treat this as a clean-slate system rewrite, unless explicitly mentioned in the requirements. Perform a comprehensive migration with zero requirements for backwards compatibility. You must ensure that all residual code, variable names, test suites, and documentation are fully refactored and perfectly aligned with the new architecture.

package/dist/ask-user.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Ask Tool Extension - Interactive question UI for pi-coding-agent
+ *
+ * Refactored to use built-in TUI primitives (Container/Text/Spacer/SelectList/Editor)
+ * and a custom box border instead of manual ANSI box drawing.
+ */
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { type QuestionOption } from "./single-select-layout.js";
+type AskOptionInput = QuestionOption | string;
+type AskDisplayMode = "overlay" | "inline";
+interface AskParams {
+    question: string;
+    context?: string;
+    options?: AskOptionInput[];
+    allowMultiple?: boolean;
+    allowFreeform?: boolean;
+    allowComment?: boolean;
+    allowCancel?: boolean;
+    displayMode?: AskDisplayMode;
+    overlayToggleKey?: string | null;
+    commentToggleKey?: string | null;
+    timeout?: number;
+}
+type AskResponse = {
+    kind: "selection";
+    selections: string[];
+    comment?: string;
+} | {
+    kind: "freeform";
+    text: string;
+};
+interface AskToolDetails {
+    question: string;
+    context?: string;
+    options: QuestionOption[];
+    response: AskResponse | null;
+    cancelled: boolean;
+}
+export declare function createAskUserTool(): {
+    name: string;
+    label: string;
+    description: string;
+    promptSnippet: string;
+    promptGuidelines: string[];
+    parameters: any;
+    execute(_toolCallId: string, params: AskParams, signal: AbortSignal | undefined, onUpdate: ((result: any) => void) | undefined, ctx: ExtensionContext): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        details: AskToolDetails;
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+        details: AskToolDetails;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+        details: {
+            error: string;
+        };
+    }>;
+    renderCall(args: any, theme: any): Text;
+    renderResult(result: any, options: any, theme: any): Text;
+};
+export {};
+//# sourceMappingURL=ask-user.d.ts.map

package/dist/ask-user.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-user.d.ts","sourceRoot":"","sources":["../src/ask-user.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAS,MAAM,+BAA+B,CAAC;AAI7E,OAAO,EAeJ,IAAI,EAIN,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAA0B,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAsBxF,KAAK,cAAc,GAAG,cAAc,GAAG,MAAM,CAAC;AAE9C,KAAK,cAAc,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE3C,UAAU,SAAS;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,cAAc,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,KAAK,WAAW,GACX;IACC,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CACnB,GACC;IACC,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACf,CAAC;AAEL,UAAU,cAAc;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,OAAO,CAAC;CACrB;AAs1CD,wBAAgB,iBAAiB;;;;;;;yBAqEA,MAAM,UAAU,SAAS,UAAU,WAAW,GAAG,SAAS,YAAY,CAAC,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC,GAAG,SAAS,OAAO,gBAAgB;;;;;iBAI1D,cAAc;;;;;;;;iBAiDP,cAAc;;;;;;;;;;;qBAiIrG,GAAG,SAAS,GAAG;yBAoBX,GAAG,WAAW,GAAG,SAAS,GAAG;EAkDvD"}