@henryqw/pi-prompt-creator 1.0.5 → 1.1.0

package/CONTEXT.md

@@ -21,4 +21,4 @@ Turn repetition and correction in the current Pi conversation into one editable
 | Scripts, Skills, and other automation | Their owning package or repository |
 | This extension | Current-conversation Signal detection, Prompt Candidate generation, and Prompt Review |
 
-The extension stays silent when it finds no Prompt Candidate. Background analysis remains visible while it is running. Every completed candidate waits for explicit user display, so background work never steals editor focus.
+The extension stays silent when it finds no Prompt Candidate. Background analysis remains visible while it is running. Manually requested candidates display when ready; automatic candidates wait for explicit user display, so background work never steals editor focus.

package/README.md

@@ -11,32 +11,31 @@ pi install npm:@henryqw/pi-task-models
 pi install npm:@henryqw/pi-prompt-creator
 ```
 
-Run `/task-models` before analysis. Assign a model to `fast`, or override `pi-prompt-creator/draft`.
+Run `/task-models` before analysis. Assign a model to `fast`, or override `pi-prompt-creator/draft`. Open `/task-models` again and verify the saved route or task assignment.
 
 ## Works with
 
-**Required.** [`@henryqw/pi-task-models`](https://pi.henry.wang/extensions/pi-task-models) provides the isolated draft model route.
+| Package | Relationship | Purpose |
+| --- | --- | --- |
+| [`@henryqw/pi-task-models`](https://pi.henry.wang/extensions/pi-task-models) | Required | Provides the isolated draft model route. |
 
 ## Use
 
 Run `/promptor` in the interactive TUI after a repeated request or correction appears:
 
-1. Choose `Analyze now`. Wait for the `Prompt ready — /promptor` widget.
-2. Run `/promptor` again and choose `Show candidate`.
-3. Ask Main to refine it and return only the complete Final Prompt Draft.
-4. Run `/promptor`, choose `Save latest Main draft`, and enter a lowercase kebab-case name.
+1. Run `/promptor`. The completed candidate appears automatically.
+2. Ask Main to refine it and return only the complete Final Prompt Draft.
+3. Run `/promptor save` to save under the suggested name, or `/promptor save <name>` to rename it.
 
-The prompt is created at `~/.pi/agent/prompts/<name>.md`, then Pi reloads its resources.
+The prompt is created at `~/.pi/agent/prompts/<name>.md`, then Pi reloads its resources. No selection menu or name prompt is required.
 
-The menu adapts to the current state:
-
-| Item | Action |
+| Command | Action |
 | --- | --- |
-| `Analyze now` or `Analyze again` | Start one visible background analysis. |
-| `Automatic On` or `Automatic Off` | Save the automatic setting. |
-| `Show candidate` | Add the candidate to the conversation for review. |
-| `Dismiss candidate` | Forget the pending candidate. |
-| `Save latest Main draft` | Save Main's newest completed review reply after you show a candidate. |
+| `/promptor` | Start analysis, or show a candidate prepared by automatic analysis. |
+| `/promptor analyze` | Analyze again after a candidate has been reviewed or dismissed. |
+| `/promptor save [name]` | Save Main's newest completed review reply, using the suggested name by default. |
+| `/promptor dismiss` | Forget a candidate prepared by automatic analysis. |
+| `/promptor automatic <on\|off>` | Enable or disable automatic analysis. |
 
 ## Flow
 
@@ -54,17 +53,23 @@ Branch changes reset the input counter. Automatic analysis and candidate widgets
 
 Only one analysis can run at a time. A pending candidate blocks another analysis.
 
+Automatic analysis sends the current conversation to the child model configured through `/task-models`.
+
+Its payload includes the active compaction or branch summary, user text, successfully completed assistant text, and effective prompt names and descriptions.
+
+Project context files and prompt templates are disabled for the child. Tool traffic, thinking, images, custom messages, and inactive branches are excluded.
+
 Analysis asks a tool-free child for one JSON response. It has no user extensions, Skills, or saved session. The extension does not retry failed analysis.
 
 New user input does not stop a running child. Branch navigation discards its old result without stopping the child.
 
 ### Review and save
 
-The widget shows `Prompt ready — /promptor` until you show or dismiss the completed candidate.
+A manually requested analysis displays its completed candidate immediately. Automatic background analysis keeps its candidate behind the `Prompt ready — /promptor` widget until you run `/promptor` or `/promptor dismiss`, so background work never interrupts the conversation.
 
-The extension never injects a candidate automatically. `Show candidate` adds one visible message and marks its contents as untrusted.
+Displayed candidates are visible messages marked as untrusted.
 
-Refine the candidate with Main. Ask Main to return only the complete Final Prompt Draft before saving.
+Refine the candidate with Main. Ask Main to return only the complete Final Prompt Draft before saving it with `/promptor save [name]`.
 
 The save item appears only after you show a candidate and Main then completes a valid Markdown review reply.
 
@@ -88,12 +93,12 @@ Use `/task-models` to select the model and thinking level. The extension owns no
 
 ## Config
 
-`~/.pi/agent/config/pi-prompt-creator/config.json`
+Package-owned: `~/.pi/agent/config/pi-prompt-creator/config.json`
 
-| Field | Required | Possible values | Default |
+| Name | Description | Values | Default |
 | --- | --- | --- | --- |
-| `automatic` | No | `true` or `false` | `true` |
-| `inputThreshold` | No | Positive integer | `3` |
+| `automatic` | Runs automatic analysis after enough user inputs. | Boolean. | `true` |
+| `inputThreshold` | Sets the number of non-empty user inputs before automatic analysis. | Positive integer. | `3` |
 
 Edit either field, then run `/reload` to apply the change. Omitted fields use their defaults.
 
@@ -109,59 +114,7 @@ A pending candidate stays in memory only. Automatic mode persists, but counters
 
 Saved prompts live at `~/.pi/agent/prompts/<name>.md`. Saving never replaces an existing file.
 
-## Data, cost, and privacy
-
-Automatic analysis is on by default. It sends the current conversation to the child model configured through `/task-models`.
-
-Disable automatic analysis through `/promptor`.
-
-The payload includes the active compaction or branch summary, user text, and successfully completed assistant text. It also includes effective prompt names and descriptions.
-
-Project context files and prompt templates are disabled for the child.
-
-Tool traffic, thinking, images, custom messages, and inactive branches are excluded.
-
-## Automatic mode
-
-Automatic mode waits for the configured number of non-empty user inputs. The default is three.
-
-It starts at the next idle `agent_settled` event. It starts at most once per extension runtime.
-
-A manual analysis consumes that opportunity. Automatic mode persists, but counters and candidates do not.
-
-Branch changes reset the input counter. Automatic analysis and candidate widgets require the interactive TUI.
-
-## Review and save
-
-A completed candidate stays in memory. The widget shows `Prompt ready — /promptor` until you show or dismiss it.
-
-The extension never injects a candidate automatically. `Show candidate` adds one visible message and marks its contents as untrusted.
-
-Refine the candidate with Main. Ask Main to return only the complete Final Prompt Draft before saving.
-
-The save item appears only after you show a candidate and Main then completes a valid Markdown review reply.
-
-Saving uses that latest retained Main reply as the entire file. Replies before the active compaction or branch summary cannot be saved.
-
-An interrupted, failed, empty, or tool-use reply cannot be saved. The extension never falls back to an older reply.
-
-A successful save ends that review. Show another candidate and complete another Main review reply before saving again.
-
-The menu asks for a lowercase kebab-case name. A candidate name appears only as a hint.
-
-Names start with a letter and contain at most 64 ASCII characters. Existing command names and prompt files are rejected.
-
-Prompts are created at `~/.pi/agent/prompts/<name>.md`. Creation never replaces a file.
-
-A successful save reloads Pi resources. If reload fails, the prompt remains saved and `/reload` can load it.
-
-## Model routing
-
-The extension registers `pi-prompt-creator/draft`. Its default task profile is `fast`.
-
-Use `/task-models` to select the model and thinking level. The extension owns no model configuration.
-
-## Limits and failures
+## Limits and recovery
 
 The child payload stays within 30,000 characters, including its JSON envelope and prompt metadata.
 

package/extensions/prompt-creator.ts

@@ -32,7 +32,7 @@ const NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 const DISALLOWED_MARKDOWN_CONTROLS = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/;
 const READY_WIDGET = "Prompt ready — /promptor";
 const FAILURE_WIDGET = "Prompt analysis failed — /promptor";
-const REFINEMENT_GUIDANCE = "Refine this candidate conversationally with the user. When the user approves it, Main must emit only the complete Final Prompt Draft. Then save that full reply through /promptor.";
+const REFINEMENT_GUIDANCE = "Refine this candidate conversationally with the user. When the user approves it, Main must emit only the complete Final Prompt Draft. Then run /promptor save to use the suggested name, or /promptor save <name>.";
 
 export const DRAFT_TASK = {
 	id: "pi-prompt-creator/draft",
@@ -279,7 +279,6 @@ export default function promptCreatorExtension(pi: ExtensionAPI, options: Prompt
 	let inputCount = 0;
 	let branchGeneration = 0;
 	let closed = false;
-	let analysisRan = false;
 	let candidate: PromptCandidate | undefined;
 	let candidateNameHint: string | undefined;
 	let reviewBoundary: ReviewBoundary | undefined;
@@ -299,7 +298,6 @@ export default function promptCreatorExtension(pi: ExtensionAPI, options: Prompt
 	const resetBranch = (ctx: ExtensionContext) => {
 		branchGeneration += 1;
 		inputCount = 0;
-		analysisRan = false;
 		candidate = undefined;
 		candidateNameHint = undefined;
 		reviewBoundary = undefined;
@@ -311,10 +309,23 @@ export default function promptCreatorExtension(pi: ExtensionAPI, options: Prompt
 		maxTurns: 3,
 		timeout: { idleMs: 2 * 60_000, maxMs: 5 * 60_000 },
 	});
+	const showCandidate = (ctx: ExtensionContext) => {
+		if (!candidate) return;
+		const shown = candidate;
+		const boundaryId = ctx.sessionManager.getLeafId();
+		candidate = undefined;
+		candidateNameHint = shown.name;
+		clearWidget(ctx);
+		pi.sendMessage({
+			customType: CANDIDATE_MESSAGE_TYPE,
+			content: candidateMessage(shown),
+			display: true,
+		}, { triggerTurn: false });
+		reviewBoundary = boundaryId ? { entryId: boundaryId } : undefined;
+	};
 	const startAnalysis = (ctx: ExtensionContext, manual: boolean) => {
 		if (ctx.mode !== "tui" || activeRun || candidate) return;
 		if (manual) automaticConsumed = true;
-		analysisRan = true;
 		failure = false;
 		candidateNameHint = undefined;
 		const payload = analysisPayload(pi, ctx);
@@ -353,7 +364,8 @@ export default function promptCreatorExtension(pi: ExtensionAPI, options: Prompt
 			}
 			candidate = drafted;
 			candidateNameHint = drafted.name;
-			ctx.ui.setWidget(WIDGET_KEY, [READY_WIDGET]);
+			if (manual) showCandidate(ctx);
+			else ctx.ui.setWidget(WIDGET_KEY, [READY_WIDGET]);
 		}).catch(() => {
 			if (isCurrent(run)) showFailure(ctx);
 		}).finally(() => {
@@ -363,13 +375,13 @@ export default function promptCreatorExtension(pi: ExtensionAPI, options: Prompt
 
 	const saveLatestDraft = async (
 		draft: string,
+		requestedName: string | undefined,
 		expectedReview: ReviewBoundary,
 		expectedBranch: number,
 		ctx: ExtensionCommandContext,
 	) => {
-		const requested = await ctx.ui.input("Prompt name", candidateNameHint ?? "my-prompt");
-		if (requested === undefined || expectedBranch !== branchGeneration || reviewBoundary !== expectedReview) return;
-		const name = requested.trim();
+		if (expectedBranch !== branchGeneration || reviewBoundary !== expectedReview) return;
+		const name = requestedName ?? candidateNameHint ?? "";
 		if (!isPromptName(name)) {
 			ctx.ui.notify(`Use lowercase kebab-case starting with a letter, up to ${MAX_NAME_CHARS} characters.`, "warning");
 			return;
@@ -455,31 +467,53 @@ export default function promptCreatorExtension(pi: ExtensionAPI, options: Prompt
 	});
 
 	pi.registerCommand("promptor", {
-		description: "Analyze this conversation and manage prompt candidates",
-		handler: async (_args, ctx) => {
+		description: "Analyze prompts, show a ready candidate, or save with /promptor save [name]",
+		getArgumentCompletions: (prefix) => {
+			const commands = ["analyze", "dismiss", "save", "automatic on", "automatic off"];
+			const matches = commands.filter((command) => command.startsWith(prefix));
+			return matches.length ? matches.map((command) => ({ value: command, label: command })) : null;
+		},
+		handler: async (args, ctx) => {
 			if (ctx.mode !== "tui") {
 				ctx.ui.notify("/promptor requires the interactive TUI.", "warning");
 				return;
 			}
-			const menuBranch = branchGeneration;
+			const commandBranch = branchGeneration;
 			const review = reviewBoundary;
 			const draft = latestAssistantDraft(ctx, review);
-			const analyze = analysisRan ? "Analyze again" : "Analyze now";
-			const toggle = automatic ? "Automatic Off" : "Automatic On";
-			const choices = [
-				...(!activeRun && !candidate ? [analyze] : []),
-				toggle,
-				...(candidate ? ["Show candidate", "Dismiss candidate"] : []),
-				...(draft ? ["Save latest Main draft"] : []),
-			];
-			const selected = await ctx.ui.select("Prompt Creator", choices);
-			if (!selected || menuBranch !== branchGeneration) return;
-			if (selected === analyze) {
-				startAnalysis(ctx, true);
+			const [action = "", ...values] = args.trim().split(/\s+/);
+			if (!action) {
+				if (candidate) showCandidate(ctx);
+				else if (activeRun) ctx.ui.notify("Prompt analysis is already running.", "info");
+				else if (draft) ctx.ui.notify("Run /promptor save to create the reviewed prompt.", "info");
+				else startAnalysis(ctx, true);
+				return;
+			}
+			if (action === "analyze" && values.length === 0) {
+				if (candidate) ctx.ui.notify("Show or dismiss the pending candidate first.", "warning");
+				else if (activeRun) ctx.ui.notify("Prompt analysis is already running.", "info");
+				else startAnalysis(ctx, true);
 				return;
 			}
-			if (selected === toggle) {
-				const next = !automatic;
+			if (action === "dismiss" && values.length === 0) {
+				if (!candidate) ctx.ui.notify("No prompt candidate is waiting.", "warning");
+				else {
+					candidate = undefined;
+					candidateNameHint = undefined;
+					clearWidget(ctx);
+				}
+				return;
+			}
+			if (action === "save" && values.length <= 1) {
+				if (!draft || !review) {
+					ctx.ui.notify("No reviewed Main draft is ready to save.", "warning");
+					return;
+				}
+				await saveLatestDraft(draft, values[0], review, commandBranch, ctx);
+				return;
+			}
+			if (action === "automatic" && values.length === 1 && (values[0] === "on" || values[0] === "off")) {
+				const next = values[0] === "on";
 				try {
 					await configStore.save({ automatic: next, inputThreshold });
 					automatic = next;
@@ -489,29 +523,7 @@ export default function promptCreatorExtension(pi: ExtensionAPI, options: Prompt
 				}
 				return;
 			}
-			if (selected === "Show candidate" && candidate) {
-				const shown = candidate;
-				const boundaryId = ctx.sessionManager.getLeafId();
-				candidate = undefined;
-				candidateNameHint = shown.name;
-				clearWidget(ctx);
-				pi.sendMessage({
-					customType: CANDIDATE_MESSAGE_TYPE,
-					content: candidateMessage(shown),
-					display: true,
-				}, { triggerTurn: false });
-				reviewBoundary = boundaryId ? { entryId: boundaryId } : undefined;
-				return;
-			}
-			if (selected === "Dismiss candidate" && candidate) {
-				candidate = undefined;
-				candidateNameHint = undefined;
-				clearWidget(ctx);
-				return;
-			}
-			if (selected === "Save latest Main draft" && draft && review) {
-				await saveLatestDraft(draft, review, menuBranch, ctx);
-			}
+			ctx.ui.notify("Use /promptor, /promptor analyze, /promptor dismiss, /promptor save [name], or /promptor automatic <on|off>.", "warning");
 		},
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-prompt-creator",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "description": "Turn current Pi conversation signals into user-approved prompt templates.",
   "keywords": [
     "pi-package",