@janvitos/pi-plan-build 0.1.37 → 0.1.39

package/README.md

@@ -91,7 +91,7 @@ Both actions leave Plan mode active, stop the agent, and wait for the next user
 
 When Pi uses `"tuiMode": "fullscreen"` and the saved plan contains top-level `- [ ]` items under `## Implementation Steps`, `plan_exit` offers the additional **Implement step by step** approval action. This is opt-in per plan; it does not replace either one-shot implementation option or **Stay in Plan mode**.
 
-The passive 64-column right panel reserves terminal columns, so the transcript and editor reflow instead of being covered. Long step instructions wrap across aligned continuation rows rather than being clipped. It never accepts focus or keyboard input and collapses below 132 terminal columns. The panel is a visual status aid only; all control happens through ordinary prompts. The agent interprets intent contextually, so these are examples rather than required commands:
+The passive 64-column right panel reserves terminal columns, so the transcript and editor reflow instead of being covered. Long step instructions and panel guidance wrap instead of being clipped. It never accepts focus or keyboard input and collapses below 132 terminal columns. The panel is a visual status aid only; all control happens through ordinary prompts. Its guidance remains visible, and the main transcript says, “Awaiting your instructions.” The agent interprets intent contextually, so these are examples rather than required commands:
 
 - “Implement the next step,” “Start step 2,” or simply “Approved” / “Go ahead.”
 - “Step 1 is complete,” “I verified that one,” or “I already handled this.”
@@ -99,7 +99,7 @@ The passive 64-column right panel reserves terminal columns, so the transcript a
 - “Pause the plan,” “hide the plan,” or “show the plan.”
 - “Cancel this plan” at any point to end step-by-step execution immediately.
 
-The extension exposes these actions to the agent through `plan_step_control`; project mutations remain blocked until the user clearly approves a ready step or explicitly indicates that it is already complete. A ready step may be marked complete without implementation when the user says they already handled or verified it. An implemented step is marked completed immediately after verification, and the next step becomes ready without a review or acceptance phase. The agent interprets intent contextually rather than requiring exact phrases, while the extension validates every resulting state transition. Step tool results identify the affected step, for example `Step 2: complete`, rather than presenting a plan-wide completion label. When the final step is completed or skipped, the panel and execution guards are removed immediately and the main window receives a completion confirmation with a concise plan summary. Cancelling removes the panel and execution guards immediately, restores the full-width layout, and preserves the saved plan file for reference. The agent implements only that step, calls `plan_step_complete`, and waits for the user's next prompt. Progress, revisions, summaries, and panel visibility survive reload/resume. If such a session is opened in regular mode, progress is retained but cannot advance until fullscreen mode is restored; no overlay fallback is used.
+The extension exposes these actions to the agent through `plan_step_control`; project mutations remain blocked until the user clearly approves a ready step or explicitly indicates that it is already complete. A ready step may be marked complete without implementation when the user says they already handled or verified it. An implemented step is marked completed immediately after verification, and the next step becomes ready without a review or acceptance phase. The agent interprets intent contextually rather than requiring exact phrases, while the extension validates every resulting state transition. Step tool results identify the affected step, for example `Step 2: complete`, rather than presenting a plan-wide completion label. When the final step is completed or skipped, the panel and execution guards are removed immediately and the main window receives a Markdown-formatted completion summary with plan-style headings, spacing, and colors. Cancelling removes the panel and execution guards immediately, restores the full-width layout, and preserves the saved plan file for reference. The agent implements only that step, calls `plan_step_complete`, and waits for the user's next prompt. Progress, revisions, summaries, and panel visibility survive reload/resume. If such a session is opened in regular mode, progress is retained but cannot advance until fullscreen mode is restored; no overlay fallback is used.
 
 Enable fullscreen in `~/.pi/agent/settings.json` and restart Pi:
 

package/index.ts

@@ -53,6 +53,7 @@ import {
 	PLAN_EXIT_FRESH_CHOICE,
 	PLAN_EXIT_STAY_ACKNOWLEDGEMENT,
 	PLAN_EXIT_STAY_CHOICE,
+	PLAN_STEP_READY_ACKNOWLEDGEMENT,
 	renderModeComposer,
 	type Mode,
 	unique,
@@ -64,6 +65,7 @@ const PLAN_REVIEW_ENTRY_TYPE = "pi-plan-build-review";
 const LEGACY_PLAN_REVIEW_ENTRY_TYPE = "opencode-plan-review";
 const MODE_NOTICE_ENTRY_TYPE = "pi-plan-build-notice";
 const LEGACY_MODE_NOTICE_ENTRY_TYPE = "opencode-mode-notice";
+const PLAN_STEP_GUIDANCE_ENTRY_TYPE = "pi-plan-build-step-guidance";
 const STATUS_KEY = "pi-plan-build-mode";
 const PLAN_STEP_CHOICE = "Implement step by step";
 const PANEL_WIDTH = 64;
@@ -119,10 +121,13 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 		const message = typeof entry.data?.message === "string" ? entry.data.message : "Plan mode unchanged.";
 		return new Text(theme.fg("warning", message), 0, 0);
 	};
+	const renderPlanStepGuidance: EntryRenderer = (_entry, _options, theme) =>
+		new Text(theme.fg("success", PLAN_STEP_READY_ACKNOWLEDGEMENT), 0, 0);
 	pi.registerEntryRenderer<{ plan: string }>(PLAN_REVIEW_ENTRY_TYPE, renderPlanReview);
 	pi.registerEntryRenderer<{ plan: string }>(LEGACY_PLAN_REVIEW_ENTRY_TYPE, renderPlanReview);
 	pi.registerEntryRenderer<{ message: string }>(MODE_NOTICE_ENTRY_TYPE, renderModeNotice);
 	pi.registerEntryRenderer<{ message: string }>(LEGACY_MODE_NOTICE_ENTRY_TYPE, renderModeNotice);
+	pi.registerEntryRenderer(PLAN_STEP_GUIDANCE_ENTRY_TYPE, renderPlanStepGuidance);
 
 	function stateData(): StoredState {
 		return { version: 1, selectedMode, pendingReminder, toolsBeforeModes, ...(execution ? { execution } : {}) };
@@ -412,9 +417,9 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 			const target = params.step === undefined
 				? execution.steps.find((step) => step.status === "ready")
 				: execution.steps[Math.floor(params.step) - 1];
-			const finish = (message: string) => ({
+			const finish = (message: string, extraDetails?: { planCompleted?: boolean }) => ({
 				content: [{ type: "text" as const, text: message }],
-				details: { action: params.action, stepId: target?.id },
+				details: { action: params.action, stepId: target?.id, ...extraDetails },
 				terminate: true,
 			});
 
@@ -443,11 +448,17 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 			}
 			if (params.action === "complete") {
 				const completion = applyExecutionTransition(completePlanStep(execution, target.id));
-				return finish(completion ?? "The step was marked complete. The next step is ready and awaits user instruction.");
+				return finish(
+					completion ?? "The step was marked complete. The next step is ready and awaits user instruction.",
+					{ planCompleted: completion !== undefined },
+				);
 			}
 			if (params.action === "skip") {
 				const completion = applyExecutionTransition(skipPlanStep(execution, target.id));
-				return finish(completion ?? "The step was skipped. The next step awaits user instruction.");
+				return finish(
+					completion ?? "The step was skipped. The next step awaits user instruction.",
+					{ planCompleted: completion !== undefined },
+				);
 			}
 			if (!params.instruction?.trim()) throw new Error("Revising a step requires a replacement instruction");
 			const plan = await fs.promises.readFile(planPath, "utf8");
@@ -466,6 +477,8 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 		},
 		renderResult(result, _options, theme, context) {
 			const text = result.content.find((item) => item.type === "text")?.text ?? "Plan state updated";
+			const details = result.details as { planCompleted?: boolean } | undefined;
+			if (details?.planCompleted && !context.isError) return new Markdown(text, 0, 0, getMarkdownTheme());
 			return new Text(theme.fg(context.isError ? "error" : "success", text), 0, 0);
 		},
 	});
@@ -484,7 +497,7 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 			const completion = applyExecutionTransition(completePlanStep(execution, step.id, params.summary));
 			return {
 				content: [{ type: "text", text: completion ?? "The step was completed. The next step is ready and awaits user instruction." }],
-				details: { stepId: step.id, completed: true },
+				details: { stepId: step.id, completed: true, planCompleted: completion !== undefined },
 				terminate: true,
 			};
 		},
@@ -493,6 +506,8 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 		},
 		renderResult(result, _options, theme, context) {
 			const text = result.content.find((item) => item.type === "text")?.text ?? "Plan step completed";
+			const details = result.details as { planCompleted?: boolean } | undefined;
+			if (details?.planCompleted && !context.isError) return new Markdown(text, 0, 0, getMarkdownTheme());
 			return new Text(theme.fg(context.isError ? "error" : "success", text), 0, 0);
 		},
 	});
@@ -541,6 +556,7 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 				await selectMode("build", ctx, "tool");
 				updateExecution(stepExecution);
 				ensurePanelLayout();
+				pi.appendEntry(PLAN_STEP_GUIDANCE_ENTRY_TYPE);
 				return {
 					content: [{ type: "text", text: "Step-by-step execution is ready. Stop now and wait for the user's natural-language instruction in the composer; the plan panel is visual-only." }],
 					details: { approved: true, action: "step-by-step", mode: "build", planPath },
@@ -588,7 +604,7 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 		renderResult(result, _options, theme, context) {
 			const details = result.details as { approved?: boolean; action?: string } | undefined;
 			if (details?.action === "step-by-step" && !context.isError) {
-				return new Text(theme.fg("success", "Step-by-step execution ready — waiting for your instruction."), 0, 0);
+				return new Text(theme.fg("success", "Step-by-step execution ready"), 0, 0);
 			}
 			if (details?.action === "implement-fresh" && !context.isError) {
 				return new Text(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@janvitos/pi-plan-build",
-  "version": "0.1.37",
+  "version": "0.1.39",
   "description": "Plan safely, approve explicitly, then implement here or in a clean session.",
   "type": "module",
   "license": "MIT",

package/plan-execution.ts

@@ -114,11 +114,12 @@ function makeNextReady(state: PlanExecutionState, afterId: string): void {
 }
 
 export function formatPlanCompletionSummary(state: PlanExecutionState): string {
-	const lines = ["Plan complete.", "", "Summary:"];
+	const lines = ["# Plan complete", "", "## Summary", ""];
 	for (const [index, step] of state.steps.entries()) {
 		const outcome = step.status === "skipped" ? "Skipped" : "Completed";
-		lines.push(`${index + 1}. ${outcome}: ${step.text}`);
-		if (step.summary?.trim()) lines.push(`   ${step.summary.trim()}`);
+		lines.push(`${index + 1}. **${outcome}:** ${step.text}`);
+		if (step.summary?.trim()) lines.push("", `   ${step.summary.trim()}`);
+		if (index < state.steps.length - 1) lines.push("");
 	}
 	return lines.join("\n");
 }

package/plan-panel.ts

@@ -34,6 +34,9 @@ export class PlanPanel implements Component {
 			const clipped = truncateToWidth(content, contentWidth, "");
 			return `${border("│")} ${clipped}${" ".repeat(Math.max(0, contentWidth - visibleWidth(clipped)))} ${border("│")}`;
 		};
+		const pushWrapped = (lines: string[], content: string) => {
+			for (const line of wrapTextWithAnsi(content, contentWidth)) lines.push(pad(line));
+		};
 		const done = this.state.steps.filter((step) => step.status === "completed" || step.status === "skipped").length;
 		const status = this.state.status === "completed" ? "complete" : this.state.status;
 		const currentIndex = this.state.steps.findIndex((step) => step.id === this.state.selectedStepId);
@@ -65,8 +68,8 @@ export class PlanPanel implements Component {
 		}
 		lines.push(border(`├${"─".repeat(inner)}┤`));
 		if (this.state.status === "completed") lines.push(pad(this.theme.fg("success", "Plan complete")));
-		else if (this.state.status === "paused") lines.push(pad("Tell the agent to resume, cancel, or hide the plan."));
-		else if (current?.status === "ready") lines.push(pad("Tell the agent to implement, complete, edit, skip, cancel, or hide this step."));
+		else if (this.state.status === "paused") pushWrapped(lines, "Tell the agent to resume, cancel, or hide the plan.");
+		else if (current?.status === "ready") pushWrapped(lines, "Tell the agent to implement, complete, edit, or skip steps. You can also cancel or hide the plan.");
 		lines.push(border(`╰${"─".repeat(inner)}╯`));
 		return lines.map((line) => truncateToWidth(line, safeWidth, ""));
 	}

package/utils.ts

@@ -136,6 +136,7 @@ export const PLAN_EXIT_FRESH_CHOICE = "Start fresh and implement";
 export const PLAN_EXIT_STAY_CHOICE = "Stay in Plan mode";
 export const PLAN_EXIT_STAY_ACKNOWLEDGEMENT =
 	"Staying in Plan mode. Let me know when you’re ready to revise or implement the plan.";
+export const PLAN_STEP_READY_ACKNOWLEDGEMENT = "Awaiting your instructions.";
 
 export type PlanExitDecision = "implement-here" | "implement-fresh" | "stay";