pi-plan-task 1.0.0 → 1.0.2

package/README.md

@@ -1,19 +1,45 @@
 # pi-plan-task
 
+[![npm version](https://img.shields.io/npm/v/pi-plan-task.svg)](https://www.npmjs.com/package/pi-plan-task)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 One Pi package: `/plan`, `/build`, `/goal`, and `/tasks`. Progress lives on disk, so a new session or a Pi restart can continue from the next unfinished task.
 
+Structured questions use [`@juicesharp/rpiv-ask-user-question`](https://pi.dev/packages/@juicesharp/rpiv-ask-user-question). This package does not register `ask_user_question`.
+
+## Install
+
+```bash
+pi install npm:@juicesharp/rpiv-ask-user-question
+pi install npm:pi-plan-task
+```
+
+Restart Pi or run `/reload`. If juicesharp is missing, this package warns on session start.
+
+Local checkout (development):
+
+```bash
+pi install /absolute/path/to/pi-plan-task
+```
+
+Or add the source to `packages` in `~/.pi/agent/settings.json`.
+
 ## Commands
 
 | Command | What it does |
-|---|---|
-| `/plan [file|goal]` | Read-only planning. Writes `.plan_task/plan.md` and `.plan_task/task.md`. |
-| `/build` | Execute the next unfinished task, then ask whether to continue here or in a new session. |
+| --- | --- |
+| `/plan [file or goal]` | Read-only planning. Writes `.plan_task/plan.md` and `.plan_task/task.md`. |
+| `/build` | Ask where to run, execute the next unfinished task, then ask whether to continue here or in a new session. |
+| `/build here` | Same as `/build`, but skip the first session prompt and stay in this session. |
+| `/build new` | Same as `/build`, but skip the first session prompt and start a new session. |
 | `/goal` | Execute remaining tasks until `task.md` is complete. No session prompts. |
 | `/tasks` | Show the current task list and progress. |
 
 Restarting Pi does not auto-start work. Run `/build` again.
 
-`/plan` accepts a spec file, a prompt, or a file plus extra notes:
+`/goal` never asks about sessions. After a `/build` task finishes, the continue-here / new-session prompt still appears. Those prompts use this package's `select` dialog, not `ask_user_question`.
+
+### `/plan` arguments
 
 ```
 /plan
@@ -36,7 +62,6 @@ That file keeps the same section headings as `planning-and-task-breakdown.md`, s
 
 This package does not install or load a skill. It also does not modify Pi's system prompt.
 
-
 ## Prompt injection
 
 Phase instructions are conversation messages, not system-prompt patches:
@@ -50,13 +75,13 @@ Session history still stores the injected messages. Filtering is non-destructive
 
 ## Ask user
 
-`ask_user_question` is available in every mode, not just `/plan`. Use it for consequential choices the repo cannot answer:
+`/plan` and `/build` keep juicesharp's `ask_user_question` available and tell the model to call it for consequential choices the repo cannot answer:
 
-- 2-4 selectable options
-- optional recommended default, shown with ★
-- free-form Other path (on by default; set `allowOther: false` to hide it)
+- 1-4 questions per call, each with a short `header` and 2-4 described options
+- recommended option first, with `(Recommended)` on the label
+- do not author `Other` or `Type something.` — juicesharp appends a custom-answer row
 
-In the TUI, pick an option or choose **Other / type my answer**. Without a UI, the tool asks the agent to pose the question in chat.
+Do not also register another `ask_user_question` tool. The names collide and the schemas differ.
 
 ## Files
 
@@ -89,12 +114,8 @@ Allowed `/plan` tools:
 }
 ```
 
-During `/plan`, `write` and `edit` stay available but can only touch the two plan files. Bash is limited to read-only commands.
+During `/plan`, `write` and `edit` stay available but can only touch the two plan files. Bash is limited to read-only commands. `plan_task` and `ask_user_question` stay available in every mode.
 
-## Install
-
-```bash
-pi install D:/work/tools/pi-plan-task
-```
+## License
 
-Or add the path to `packages` in `~/.pi/agent/settings.json`, then restart Pi or run `/reload`.
+MIT

package/extensions/build-session.test.ts

@@ -0,0 +1,18 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { parseBuildPlacement } from "./build-session.ts";
+
+describe("parseBuildPlacement", () => {
+	it("asks by default", () => {
+		assert.equal(parseBuildPlacement(""), "ask");
+		assert.equal(parseBuildPlacement("  "), "ask");
+		assert.equal(parseBuildPlacement("unknown"), "ask");
+	});
+
+	it("accepts here and new aliases", () => {
+		assert.equal(parseBuildPlacement("here"), "here");
+		assert.equal(parseBuildPlacement(" --here extra"), "here");
+		assert.equal(parseBuildPlacement("NEW"), "new");
+		assert.equal(parseBuildPlacement("--new"), "new");
+	});
+});

package/extensions/build-session.ts

@@ -0,0 +1,8 @@
+export type BuildPlacement = "ask" | "here" | "new";
+
+export function parseBuildPlacement(args: string): BuildPlacement {
+	const token = args.trim().split(/\s+/)[0]?.toLowerCase() ?? "";
+	if (token === "here" || token === "--here") return "here";
+	if (token === "new" || token === "--new") return "new";
+	return "ask";
+}

package/extensions/index.ts

@@ -1,17 +1,14 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import {
 	type ExtensionAPI,
+	type ExtensionCommandContext,
 	type ExtensionContext,
 	isToolCallEventType,
 } from "@earendil-works/pi-coding-agent";
 import { matchesKey, Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { isSafePlanCommand } from "./bash-guard.ts";
-import {
-	ASK_QUESTION_GUIDELINES,
-	ASK_USER_QUESTION_TOOL,
-	executeAskQuestion,
-} from "./ask-question.ts";
+import { parseBuildPlacement, type BuildPlacement } from "./build-session.ts";
 import { ensureDefaultGlobalConfig, loadConfig } from "./config.ts";
 import {
 	ensurePlanDir,
@@ -40,8 +37,30 @@ type Mode = "idle" | "plan" | "build";
 
 const CONTINUE_THIS = "Continue in this session";
 const CONTINUE_NEW = "Continue in a new session";
+const BUILD_HERE_COMMAND = "/build here";
+
+async function chooseBuildPlacement(ctx: ExtensionCommandContext): Promise<"here" | "new" | undefined> {
+	if (!ctx.hasUI) return "here";
+	const choice = await ctx.ui.select("Start this task where?", [CONTINUE_THIS, CONTINUE_NEW]);
+	if (choice === CONTINUE_THIS) return "here";
+	if (choice === CONTINUE_NEW) return "new";
+	return undefined;
+}
+
+async function startBuildInNewSession(ctx: ExtensionCommandContext): Promise<void> {
+	const parentSession = ctx.sessionManager.getSessionFile();
+	const result = await ctx.newSession({
+		parentSession,
+		withSession: async (nextCtx) => {
+			await nextCtx.sendUserMessage(BUILD_HERE_COMMAND, { expandPromptTemplates: true });
+		},
+	});
+	if (result.cancelled) {
+		ctx.ui.notify("New session cancelled.", "info");
+	}
+}
 
-const ALWAYS_ON_TOOLS = ["plan_task", ASK_USER_QUESTION_TOOL] as const;
+const ALWAYS_ON_TOOLS = ["plan_task", "ask_user_question"] as const;
 
 function unique(names: string[]): string[] {
 	return [...new Set(names)];
@@ -317,43 +336,6 @@ export default async function planTaskExtension(pi: ExtensionAPI): Promise<void>
 		},
 	});
 
-	pi.registerTool({
-		name: ASK_USER_QUESTION_TOOL,
-		label: "Ask User Question",
-		description:
-			"Ask user a clarifying question with selectable options, a recommended default, and optional free-form input. Works in any mode.",
-		promptSnippet:
-			"Ask user a clarifying question with 2-4 options and a recommended default; works in any mode",
-		promptGuidelines: ASK_QUESTION_GUIDELINES,
-		parameters: Type.Object({
-			question: Type.String({ description: "The clarifying question to ask" }),
-			options: Type.Array(
-				Type.Object({
-					label: Type.String({ description: "Option label" }),
-					description: Type.Optional(Type.String({ description: "Optional explanation" })),
-				}),
-				{ description: "Options to choose from (2-4 required)", minItems: 2, maxItems: 4 },
-			),
-			recommended: Type.Optional(
-				Type.String({
-					description:
-						"Label of the recommended option (must match one option label). It is shown with a ★ marker.",
-				}),
-			),
-			allowOther: Type.Optional(Type.Boolean({ description: "Allow free-form user answer; default true" })),
-		}),
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			return executeAskQuestion(params, ctx);
-		},
-		renderCall(args, theme) {
-			const question = typeof args.question === "string" ? args.question : "";
-			return new Text(
-				theme.fg("toolTitle", theme.bold("ask_user_question ")) + theme.fg("muted", question),
-				0,
-				0,
-			);
-		},
-	});
 	pi.registerCommand("plan", {
 		description: "Write .plan_task/plan.md and .plan_task/task.md from a file path or prompt",
 		handler: async (args, ctx) => {
@@ -384,7 +366,11 @@ export default async function planTaskExtension(pi: ExtensionAPI): Promise<void>
 		},
 	});
 
-	async function beginBuild(ctx: ExtensionContext, runAll: boolean): Promise<void> {
+	async function beginBuild(
+		ctx: ExtensionCommandContext,
+		runAll: boolean,
+		placement: BuildPlacement = "ask",
+	): Promise<void> {
 		const file = await loadTaskFile(ctx.cwd);
 		if (!file) {
 			ctx.ui.notify("No plan found. Run /plan first.", "error");
@@ -398,6 +384,14 @@ export default async function planTaskExtension(pi: ExtensionAPI): Promise<void>
 			ctx.ui.notify("All tasks are complete.", "info");
 			return;
 		}
+		if (!runAll) {
+			const resolved = placement === "ask" ? await chooseBuildPlacement(ctx) : placement;
+			if (!resolved) return;
+			if (resolved === "new") {
+				await startBuildInNewSession(ctx);
+				return;
+			}
+		}
 		continueAll = runAll;
 		await enterBuildMode(ctx);
 		ctx.ui.notify(runAll ? "Building remaining tasks." : "Building the next task.", "info");
@@ -405,9 +399,9 @@ export default async function planTaskExtension(pi: ExtensionAPI): Promise<void>
 	}
 
 	pi.registerCommand("build", {
-		description: "Execute the next planned task",
-		handler: async (_args, ctx) => {
-			await beginBuild(ctx, false);
+		description: "Choose this session or a new session, then execute the next planned task",
+		handler: async (args, ctx) => {
+			await beginBuild(ctx, false, parseBuildPlacement(args));
 		},
 	});
 
@@ -434,16 +428,7 @@ export default async function planTaskExtension(pi: ExtensionAPI): Promise<void>
 	pi.registerCommand("build-next-session", {
 		description: "Continue the next planned task in a new session",
 		handler: async (_args, ctx) => {
-			const parentSession = ctx.sessionManager.getSessionFile();
-			const result = await ctx.newSession({
-				parentSession,
-				withSession: async (nextCtx) => {
-					await nextCtx.sendUserMessage("/build", { expandPromptTemplates: true });
-				},
-			});
-			if (result.cancelled) {
-				ctx.ui.notify("New session cancelled.", "info");
-			}
+			await startBuildInNewSession(ctx);
 		},
 	});
 
@@ -457,6 +442,12 @@ export default async function planTaskExtension(pi: ExtensionAPI): Promise<void>
 		planSource = EMPTY_PLAN_SOURCE;
 		resetFraming();
 		pi.setActiveTools(withAlwaysOnTools(pi.getActiveTools()));
+		if (!pi.getAllTools().some((tool) => tool.name === "ask_user_question")) {
+			ctx.ui.notify(
+				"ask_user_question is missing. Install npm:@juicesharp/rpiv-ask-user-question.",
+				"warning",
+			);
+		}
 		updateStatus(ctx);
 	});
 

package/extensions/prompts.test.ts

@@ -19,6 +19,8 @@ describe("planPrompt", () => {
 		assert.doesNotMatch(prompt, /Planning skill/);
 		assert.doesNotMatch(prompt, /tasks\/todo\.md/);
 		assert.match(prompt, /ask_user_question/);
+		assert.match(prompt, /questions/);
+		assert.match(prompt, /\(Recommended\)/);
 	});
 
 	it("inlines a spec file and extra notes", () => {
@@ -51,6 +53,8 @@ describe("buildPrompt", () => {
 		assert.match(prompt, /Form submits/);
 		assert.match(prompt, /acceptance criteria/);
 		assert.match(prompt, /ask_user_question/);
+		assert.match(prompt, /questions/);
+		assert.match(prompt, /\(Recommended\)/);
 		assert.match(prompt, /Do not start the next task/);
 	});
 });

package/extensions/prompts.ts

@@ -35,7 +35,7 @@ Runtime rules:
 - Follow the planning method below for process, task sizing, templates, and verification.
 - The checklist lines in \`.plan_task/task.md\` must stay in the exact form \`- [ ] N. Title\` so later sessions can resume.
 - If a spec file is provided, treat it as the primary requirements.
-- If a consequential, user-answerable decision remains, call \`ask_user_question\` with 2-4 options, a recommended default, and an Other path. Do not leave blocking decisions as open questions in the plan.
+- If a consequential, user-answerable decision remains, call \`ask_user_question\` with a \`questions\` array (1-4 questions). Each question needs a short \`header\` and 2-4 options with labels and descriptions. Put the recommended option first and append "(Recommended)" to its label. Do not author "Other" or "Type something." labels. Batch every blocking decision into one call. Do not leave blocking decisions as open questions in the plan.
 - When both files are written, stop and wait for /build.
 
 ${loadPlanningMethod()}`;
@@ -64,7 +64,7 @@ Rules:
 - Leave the system in a working state when the task ends.
 - Verify against this task's acceptance criteria and verification steps before marking it done.
 - Do not mark the task complete if acceptance criteria are unmet or verification failed.
-- If a consequential decision is still ambiguous, call \`ask_user_question\` instead of guessing.
+- If a consequential decision is still ambiguous, call \`ask_user_question\` instead of guessing. Use a \`questions\` array with a short \`header\` and 2-4 described options. Put the recommended option first and append "(Recommended)" to its label. Do not author "Other" or "Type something." labels. Group related questions into one call.
 - When the task is done, call the plan_task tool with action "complete" and this task id, and keep the matching checklist box checked in \`.plan_task/task.md\`.
 - ${stopRule}`;
 }

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "pi-plan-task",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "license": "MIT",
-  "description": "Pi package: /plan, /build, /goal, /tasks.",
-  "keywords": ["pi-package"],
+  "description": "Pi package: /plan, /build, /goal, and /tasks.",
+  "keywords": ["pi-package", "pi-extension", "plan", "build"],
   "files": ["extensions", "README.md"],
   "type": "module",
   "pi": {
@@ -13,6 +13,7 @@
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
+    "@juicesharp/rpiv-ask-user-question": ">=2.7.0",
     "typebox": "*"
   }
 }

package/extensions/ask-question.test.ts

@@ -1,91 +0,0 @@
-import assert from "node:assert/strict";
-import { describe, it } from "node:test";
-import {
-	OTHER_LABEL,
-	questionDisplayLabels,
-	validateQuestionParams,
-} from "./ask-question.ts";
-
-const options = [
-	{ label: "SQLite", description: "Local file" },
-	{ label: "Postgres", description: "Shared DB" },
-];
-
-describe("validateQuestionParams", () => {
-	it("accepts 2-4 unique labels and a matching recommended option", () => {
-		const result = validateQuestionParams({
-			question: "Which database?",
-			options,
-			recommended: "postgres",
-		});
-		assert.equal(result.recommendedIndex, 1);
-		assert.equal(result.options.length, 2);
-	});
-
-	it("rejects blank, duplicate, Other-conflicting, and unmatched recommended labels", () => {
-		assert.throws(() => validateQuestionParams({ question: "Q", options: [{ label: "A" }, { label: " " }] }), /non-blank/);
-		assert.throws(
-			() => validateQuestionParams({ question: "Q", options: [{ label: "A" }, { label: "A" }] }),
-			/unique/,
-		);
-		assert.throws(
-			() => validateQuestionParams({ question: "Q", options: [{ label: "A" }, { label: "Other path" }] }),
-			/Other/,
-		);
-		assert.throws(
-			() => validateQuestionParams({ question: "Q", options, recommended: "Redis" }),
-			/recommended/,
-		);
-	});
-});
-
-describe("questionDisplayLabels", () => {
-	it("marks the recommended option with a star", () => {
-		assert.deepEqual(questionDisplayLabels(options, 1), [
-			"SQLite — Local file",
-			"★ Postgres — Shared DB",
-		]);
-		assert.equal(OTHER_LABEL, "Other / type my answer");
-	});
-});
-
-describe("executeAskQuestion", () => {
-	it("asks in chat when no UI is available", async () => {
-		const { executeAskQuestion } = await import("./ask-question.ts");
-		const result = await executeAskQuestion(
-			{ question: "Which database?", options },
-			{ hasUI: false } as never,
-		);
-		assert.match(result.content[0]?.text ?? "", /UI is not available/);
-		assert.equal(result.details.answer, null);
-	});
-
-	it("selects the starred option and accepts a free-form Other answer", async () => {
-		const { executeAskQuestion, OTHER_LABEL } = await import("./ask-question.ts");
-		const selected = await executeAskQuestion(
-			{ question: "Which database?", options, recommended: "Postgres" },
-			{
-				hasUI: true,
-				ui: {
-					select: async (_question: string, labels: string[]) => labels.find((label) => label.startsWith("★")),
-					editor: async () => undefined,
-				},
-			} as never,
-		);
-		assert.equal(selected.details.answer, "Postgres");
-		assert.equal(selected.details.wasCustom, false);
-
-		const custom = await executeAskQuestion(
-			{ question: "Which database?", options },
-			{
-				hasUI: true,
-				ui: {
-					select: async () => OTHER_LABEL,
-					editor: async () => "  Redis  ",
-				},
-			} as never,
-		);
-		assert.equal(custom.details.answer, "Redis");
-		assert.equal(custom.details.wasCustom, true);
-	});
-});

package/extensions/ask-question.ts

@@ -1,145 +0,0 @@
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-
-export const ASK_USER_QUESTION_TOOL = "ask_user_question";
-export const OTHER_LABEL = "Other / type my answer";
-
-export interface QuestionOption {
-	label: string;
-	description?: string;
-}
-
-export interface QuestionParams {
-	question: string;
-	options: QuestionOption[];
-	recommended?: string;
-	allowOther?: boolean;
-}
-
-export const ASK_QUESTION_GUIDELINES = [
-	"Use only when repo research leaves a consequential ambiguity.",
-	"Prefer 2-4 concrete options. Use short labels.",
-	"Don't ask what's discoverable from repo.",
-	"Respect user's stated preference.",
-	"Provide a recommended option when one choice is clearly preferable.",
-];
-
-
-export function validateQuestionParams(params: QuestionParams): {
-	options: QuestionOption[];
-	recommendedIndex: number | null;
-} {
-	const question = params.question?.trim() ?? "";
-	if (!question) throw new Error("question must be non-blank.");
-	const options = params.options ?? [];
-	if (options.length < 2 || options.length > 4) {
-		throw new Error("Provide 2-4 options.");
-	}
-	const labels = options.map((option) => option.label.trim());
-	if (labels.some((label) => !label)) {
-		throw new Error("Each option must have a non-blank label.");
-	}
-	if (new Set(labels).size !== labels.length) {
-		throw new Error("Option labels must be unique.");
-	}
-	if (labels.some((label) => label.toLowerCase() === "other" || label.toLowerCase().startsWith("other "))) {
-		throw new Error('Option labels cannot conflict with the "Other" label.');
-	}
-	let recommendedIndex: number | null = null;
-	if (params.recommended) {
-		const recommended = params.recommended.trim();
-		const matchIdx = labels.findIndex((label) => label.toLowerCase() === recommended.toLowerCase());
-		if (matchIdx === -1) {
-			throw new Error("recommended must match one of the option labels.");
-		}
-		recommendedIndex = matchIdx;
-	}
-	return { options, recommendedIndex };
-}
-
-export function questionDisplayLabels(
-	options: QuestionOption[],
-	recommendedIndex: number | null,
-): string[] {
-	return options.map((option, index) => {
-		const star = recommendedIndex !== null && index === recommendedIndex && options.length > 1 ? "★ " : "";
-		return option.description ? `${star}${option.label} — ${option.description}` : `${star}${option.label}`;
-	});
-}
-
-function textResult(
-	text: string,
-	details: Record<string, unknown>,
-): { content: [{ type: "text"; text: string }]; details: Record<string, unknown> } {
-	return { content: [{ type: "text", text }], details };
-}
-
-export async function executeAskQuestion(
-	params: unknown,
-	ctx: ExtensionContext,
-): Promise<{ content: [{ type: "text"; text: string }]; details: Record<string, unknown> }> {
-	const typed = params as QuestionParams;
-	let options: QuestionOption[];
-	let recommendedIndex: number | null;
-	try {
-		({ options, recommendedIndex } = validateQuestionParams(typed));
-	} catch (error) {
-		return textResult(error instanceof Error ? error.message : String(error), {
-			question: typed.question,
-			answer: null,
-			cancelled: false,
-			wasCustom: false,
-		});
-	}
-	if (!ctx.hasUI) {
-		return textResult("UI is not available. Ask this question directly in chat and wait for the user's answer.", {
-			question: typed.question,
-			options,
-			answer: null,
-			wasCustom: false,
-			cancelled: false,
-		});
-	}
-	const allowOther = typed.allowOther !== false;
-	const displayLabels = questionDisplayLabels(options, recommendedIndex);
-	const choice = await ctx.ui.select(typed.question, allowOther ? [...displayLabels, OTHER_LABEL] : displayLabels);
-	if (!choice) {
-		return textResult("User cancelled the question.", {
-			question: typed.question,
-			options,
-			answer: null,
-			cancelled: true,
-			wasCustom: false,
-		});
-	}
-	if (choice === OTHER_LABEL) {
-		const answer = (await ctx.ui.editor("Your answer", ""))?.trim();
-		if (!answer) {
-			return textResult("User cancelled the question.", {
-				question: typed.question,
-				options,
-				answer: null,
-				cancelled: true,
-				wasCustom: false,
-			});
-		}
-		return textResult(`User wrote: ${answer}`, {
-			question: typed.question,
-			options,
-			answer,
-			wasCustom: true,
-			cancelled: false,
-		});
-	}
-	const selectedIndex = displayLabels.indexOf(choice);
-	const selected = options[selectedIndex];
-	const answer = selected?.label ?? choice;
-	return textResult(`User selected: ${answer}`, {
-		question: typed.question,
-		options,
-		answer,
-		selectedIndex,
-		recommendedIndex,
-		wasCustom: false,
-		cancelled: false,
-	});
-}