@janvitos/pi-plan-build 0.1.30 → 0.1.32

package/README.md

@@ -13,12 +13,13 @@ A global [Pi coding agent](https://github.com/badlogic/pi-mono) extension that a
 - Per-session plans at `~/.pi/agent/plans/<session-id>.md`.
 - In Plan mode, built-in `edit` and `write` are restricted to the exact plan file.
 - Interactive `question`, `plan_enter`, and `plan_exit` tools.
-- Informational questions are answered directly in Plan mode, with read-only inspection when needed and no plan or approval ceremony.
+- Plan mode supports read-only conversation and research across multiple turns, then persists the final plan when it is ready for approval.
 - The complete saved plan is rendered in the transcript before approval—without the built-in write preview's truncation.
-- Three approval actions:
+- Existing approval actions remain available:
   - **Switch to Build and implement here**
   - **Start fresh and implement**
   - **Stay in Plan mode**
+- **Experimental:** In fullscreen TUI, valid checklist plans also offer **Implement step by step**: a passive, non-overlapping docked right panel keeps the plan visible while natural-language prompts gate steps and return completed work for review. This feature is still under active development.
 - Staying in Plan mode—or pressing Escape in the approval dialog—produces a durable acknowledgement and stops the run until the user responds.
 - Mode state survives reloads, resumes, and forks.
 - When Pi recreates the custom editor, the latest 100 user prompts from the active session branch are restored for Up/Down history navigation.
@@ -28,6 +29,7 @@ A global [Pi coding agent](https://github.com/badlogic/pi-mono) extension that a
 - Pi `0.84.2` or newer
 - Node.js `22.6` or newer for the test command
 - TUI or RPC UI support for interactive questions and approval dialogs
+- Pi fullscreen TUI mode for the optional docked step-by-step plan panel; regular mode and all existing workflows remain supported
 
 ## Install
 
@@ -82,25 +84,53 @@ Selecting **Stay in Plan mode**, or pressing Escape while the approval dialog is
 
 Both actions leave Plan mode active, stop the agent, and wait for the next user message.
 
+### Step-by-step execution panel (Experimental)
+
+> **Experimental feature:** Step-by-step execution is still being developed. Expect UI and workflow changes, and please report issues or unexpected behavior.
+
+When Pi uses `"tuiMode": "fullscreen"` and the saved plan contains top-level `- [ ]` items under `## Implementation Steps`, `plan_exit` also offers **Implement step by step**. This is opt-in per plan; it does not replace either one-shot implementation option.
+
+The passive 72-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. Control the workflow entirely through natural-language prompts, for example:
+
+- “Implement the next step” or “Start step 2.”
+- “Step 1 is complete,” “I verified that one,” or “I already handled this.”
+- “Change step 3 to …” or “Skip this step.”
+- “Accept this result” or “Correct it by …”
+- “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. The agent interprets intent contextually rather than requiring exact phrases, while the extension validates every resulting state transition. 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. Accepting a result makes the next step ready but never starts it automatically. 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:
+
+```json
+{
+  "tuiMode": "fullscreen"
+}
+```
+
+The integration uses Pi 0.84.2's public fullscreen layout primitives plus a guarded read of its runtime layout root because the current extension API exposes `setLayoutRoot()` but not a corresponding getter.
+
 ## Plan-mode permissions
 
 Normal tools remain visible so the model can inspect the project. While a Plan run is active:
 
 - `edit` and `write` are permitted only for the canonical session plan file;
+- the Plan prompt reserves those mutations for finalizing or explicitly revising the plan, not ordinary conversation or research;
 - other `edit` and `write` calls are blocked by the extension;
 - bash is not restricted at the permission layer, but the Plan prompt explicitly permits read-only exploration only.
 
 This mirrors the intended permission-oriented workflow rather than hiding normal tool schemas.
 
-### Informational questions
+### Conversational planning
 
-Plan mode distinguishes informational Q&A from implementation planning. If a request only asks for an explanation or information, the agent answers directly and ends normally. It may inspect the project with read-only tools when the answer depends on local context, but it does not create or update a plan, ask planning questions unnecessarily, or call `plan_exit`. Plan mode remains selected for the next request.
+Plan mode follows OpenCode’s standard conversational lifecycle while retaining this extension’s persisted approval flow. The agent can answer informational questions, discuss requirements and tradeoffs, inspect the project with read-only tools, and ask follow-up questions across multiple turns. Ordinary conversation and research do not create or update the plan file and do not invoke `plan_exit`.
 
-Requests to change code or produce an implementation plan continue through the normal plan-file and approval workflow.
+Once the request is sufficiently understood and the agent is ready to present the final implementation plan—or the user explicitly asks it to finalize—the agent writes the complete canonical plan and calls `plan_exit`. An existing plan file does not trigger automatic edits during unrelated discussion.
 
 ## Design and attribution
 
-Pi Plan & Build is an independent extension with its own workflow and UI behavior. Its original mode prompts and transition semantics were informed by OpenCode 1.18.16, while clean-session implementation ideas were informed by the former `pi-plan-mode` extension. Those behaviors have since been adapted and extended for Pi; this project is not affiliated with either project.
+Pi Plan & Build is an independent extension with its own workflow and UI behavior. Its conversational read-only lifecycle follows OpenCode’s standard Plan agent, while persisted finalization and approval are adapted for Pi. Earlier prompt and transition semantics were informed by OpenCode 1.18.16, and clean-session implementation ideas were informed by the former `pi-plan-mode` extension. This project is not affiliated with either project.
 
 The Plan workflow uses Pi's native exploration tools directly and does not bundle or require subagents.
 
@@ -111,7 +141,7 @@ npm test
 npm pack --dry-run
 ```
 
-The tests cover state decoding, safe plan paths, mutation restrictions, deferred transitions, mode and provider rendering, session-based prompt history restoration, complete plan rendering, approval decisions, stop behavior, fresh-session settings and handoff content, and question formatting.
+The tests cover state decoding, safe plan paths, mutation restrictions, deferred transitions, mode and provider rendering, conversational Plan guidance, session-based prompt history restoration, complete plan rendering, approval decisions, stop behavior, fresh-session settings and handoff content, question formatting and cancellation, structured checklist parsing, step state transitions, safe instruction revisions, and responsive panel rendering.
 
 ### Publishing
 

package/index.ts

@@ -2,15 +2,34 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { CustomEditor, getAgentDir, getMarkdownTheme, type EntryRenderer, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Key, Markdown, matchesKey, Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { HStack, Key, Markdown, matchesKey, Text, truncateToWidth, visibleWidth, isViewportTUI, type Component, type TUI, type ViewportTUI } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { registerQuestionTool } from "./question-ui.ts";
 import {
 	buildPlanReminder,
+	buildPlanStepReminder,
+	buildPlanStepWaitingReminder,
 	PLAN_ENTER_DESCRIPTION,
 	PLAN_EXIT_DESCRIPTION,
+	PLAN_STEP_COMPLETE_DESCRIPTION,
 	PLAN_TO_BUILD_REMINDER,
 } from "./prompts.ts";
+import {
+	acceptPlanStep,
+	activePlanStep,
+	completePlanStep,
+	createPlanExecution,
+	decodePlanExecution,
+	pausePlanExecution,
+	requestPlanStepCorrections,
+	revisePlanStep,
+	skipPlanStep,
+	startPlanStep,
+	submitPlanStepForReview,
+	updatePlanChecklistStep,
+	type PlanExecutionState,
+} from "./plan-execution.ts";
+import { PlanPanel } from "./plan-panel.ts";
 import {
 	applyManualSelection,
 	buildFreshImplementationHandoff,
@@ -48,7 +67,10 @@ 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 STATUS_KEY = "pi-plan-build-mode";
-const MANAGED_TOOLS = new Set(["question", "plan_enter", "plan_exit"]);
+const PLAN_STEP_CHOICE = "Implement step by step";
+const PANEL_WIDTH = 72;
+const PANEL_MIN_TERMINAL_WIDTH = 132;
+const MANAGED_TOOLS = new Set(["question", "plan_enter", "plan_exit", "plan_step_control", "plan_step_complete"]);
 const MODE_ADDED_TOOLS = new Set([...MANAGED_TOOLS, "edit", "write"]);
 const EMPTY_PARAMETERS = Type.Object({});
 
@@ -58,6 +80,7 @@ interface StoredState {
 	selectedMode: Mode;
 	pendingReminder?: "plan" | "build";
 	toolsBeforeModes?: string[];
+	execution?: PlanExecutionState;
 }
 
 function shorten(filePath: string, cwd: string): string {
@@ -76,6 +99,12 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 	let currentContext: ExtensionContext | undefined;
 	let requestEditorRender: (() => void) | undefined;
 	let freshImplementationRequest: FreshImplementationRequest | undefined;
+	let execution: PlanExecutionState | undefined;
+	let panel: PlanPanel | undefined;
+	let panelTui: (TUI & Partial<ViewportTUI>) | undefined;
+	let originalLayoutRoot: Component | undefined;
+	let panelLayoutRoot: Component | undefined;
+	let fullscreenPanelCapable = false;
 
 	pi.registerFlag("plan", {
 		description: "Start in Plan mode",
@@ -98,13 +127,57 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 	pi.registerEntryRenderer<{ message: string }>(LEGACY_MODE_NOTICE_ENTRY_TYPE, renderModeNotice);
 
 	function stateData(): StoredState {
-		return { version: 1, selectedMode, pendingReminder, toolsBeforeModes };
+		return { version: 1, selectedMode, pendingReminder, toolsBeforeModes, ...(execution ? { execution } : {}) };
 	}
 
 	function persist(): void {
 		pi.appendEntry(STATE_TYPE, stateData());
 	}
 
+	function updateExecution(next: PlanExecutionState): void {
+		execution = next;
+		panel?.setState(next);
+		persist();
+		panelTui?.requestRender();
+	}
+
+	function removePanelLayout(): void {
+		if (panelLayoutRoot && panelTui && originalLayoutRoot) panelTui.setLayoutRoot?.(originalLayoutRoot);
+		panelLayoutRoot = undefined;
+		panel = undefined;
+		panelTui?.requestRender();
+	}
+
+	function cancelPlanExecution(): void {
+		execution = undefined;
+		removePanelLayout();
+		persist();
+		applyTools("build");
+	}
+
+	function ensurePanelLayout(): boolean {
+		if (!execution || !fullscreenPanelCapable || !panelTui || !originalLayoutRoot || !currentContext) return false;
+		if (!panel) panel = new PlanPanel(execution, currentContext.ui.theme);
+		else panel.setState(execution);
+		if (!panelLayoutRoot) {
+			panelLayoutRoot = new HStack([
+				{ component: originalLayoutRoot, basis: 0, grow: 1, shrink: 1, minSize: 58 },
+				{
+					component: panel,
+					basis: PANEL_WIDTH,
+					grow: 0,
+					shrink: 0,
+					minSize: PANEL_WIDTH,
+					maxSize: PANEL_WIDTH,
+					visible: (viewport) => execution?.panelVisible !== false && viewport.width >= PANEL_MIN_TERMINAL_WIDTH,
+				},
+			]);
+			panelTui.setLayoutRoot?.(panelLayoutRoot);
+		}
+		panelTui.requestRender();
+		return true;
+	}
+
 	function updateModeIndicator(ctx: ExtensionContext): void {
 		// Clear the legacy footer status; the mode is now rendered inside the editor.
 		ctx.ui.setStatus(STATUS_KEY, undefined);
@@ -122,7 +195,13 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 		if (mode === "plan") {
 			pi.setActiveTools(unique([...base, "edit", "write", "question", "plan_exit"]));
 		} else {
-			pi.setActiveTools(unique([...base, "question", "plan_enter"]));
+			pi.setActiveTools(unique([
+				...base,
+				"question",
+				"plan_enter",
+				...(execution ? ["plan_step_control"] : []),
+				...(activePlanStep(execution) ? ["plan_step_complete"] : []),
+			]));
 		}
 	}
 
@@ -130,6 +209,12 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 		await fs.promises.mkdir(path.dirname(planPath), { recursive: true });
 	}
 
+	function describePlanFile(): string {
+		return fs.existsSync(planPath)
+			? `A plan file already exists at ${planPath}. Read it when relevant, but leave it unchanged while discussing or researching. Use the edit tool only when finalizing or explicitly revising the plan.`
+			: `No plan file exists yet. When ready to finalize, create your plan at ${planPath} using the write tool.`;
+	}
+
 	async function selectMode(mode: Mode, ctx: ExtensionContext, source: "manual" | "tool"): Promise<void> {
 		if (mode === selectedMode && (source === "manual" || mode === runMode)) return;
 		const previous = selectedMode;
@@ -278,12 +363,8 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 		executionMode: "sequential",
 		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
 			await selectMode("plan", ctx, "tool");
-			const exists = fs.existsSync(planPath);
-			const info = exists
-				? `A plan file already exists at ${planPath}. You can read it and make incremental edits using the edit tool.`
-				: `No plan file exists yet. You should create your plan at ${planPath} using the write tool.`;
 			return {
-				content: [{ type: "text", text: buildPlanReminder(info) }],
+				content: [{ type: "text", text: buildPlanReminder(describePlanFile()) }],
 				details: { mode: "plan", planPath },
 			};
 		},
@@ -295,6 +376,128 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 		},
 	});
 
+	pi.registerTool({
+		name: "plan_step_control",
+		label: "Control Plan Execution",
+		description: `Use this tool to translate the user's natural-language instructions into one step-by-step plan action. Available actions: start a ready step, complete a clearly finished ready or reviewed step, accept a reviewed step, request corrections, skip a ready step, revise an unimplemented instruction, pause/resume or cancel execution, or hide/show the visual plan panel. Interpret clear user intent semantically, including direct completion statements, but do not advance based on hypothetical, uncertain, or unrelated conversation.`,
+		parameters: Type.Object({
+			action: Type.Union([
+				Type.Literal("start"),
+				Type.Literal("complete"),
+				Type.Literal("accept"),
+				Type.Literal("correct"),
+				Type.Literal("skip"),
+				Type.Literal("revise"),
+				Type.Literal("pause"),
+				Type.Literal("resume"),
+				Type.Literal("cancel"),
+				Type.Literal("hide"),
+				Type.Literal("show"),
+			]),
+			step: Type.Optional(Type.Number({ description: "One-based step number; defaults to the current ready/review step", minimum: 1 })),
+			instruction: Type.Optional(Type.String({ description: "Replacement instruction required for revise" })),
+		}),
+		executionMode: "sequential",
+		async execute(_toolCallId, params) {
+			if (!execution) throw new Error("No step-by-step plan is active");
+			const target = params.step === undefined
+				? execution.steps.find((step) => step.status === "ready" || step.status === "review")
+				: execution.steps[Math.floor(params.step) - 1];
+			const finish = (message: string) => ({
+				content: [{ type: "text" as const, text: message }],
+				details: { action: params.action, stepId: target?.id },
+				terminate: true,
+			});
+
+			if (params.action === "cancel") {
+				cancelPlanExecution();
+				return finish("Step-by-step execution was cancelled. The panel and execution guards were removed; the saved plan file remains available.");
+			}
+			if (params.action === "hide" || params.action === "show") {
+				updateExecution({ ...execution, panelVisible: params.action === "show" });
+				if (params.action === "show") ensurePanelLayout();
+				return finish(`The visual plan panel is now ${params.action === "show" ? "visible" : "hidden"}. Progress is unchanged.`);
+			}
+			if (execution.status === "completed") throw new Error("The plan is complete; only hide or show actions remain available");
+			if (params.action === "pause" || params.action === "resume") {
+				if ((params.action === "pause") === (execution.status === "paused")) return finish(`Plan execution is already ${params.action === "pause" ? "paused" : "running"}.`);
+				updateExecution(pausePlanExecution(execution));
+				return finish(`Plan execution is now ${params.action === "pause" ? "paused" : "running"}.`);
+			}
+			if (!target) throw new Error("No matching plan step is available for that action");
+			if (params.action === "start") {
+				if (execution.status === "paused") throw new Error("Resume plan execution before starting a step");
+				updateExecution(startPlanStep(execution, target.id));
+				applyTools("build");
+				pi.sendUserMessage(`Implement plan step ${execution.steps.findIndex((step) => step.id === target.id) + 1}: ${target.text}`, { deliverAs: "followUp" });
+				return finish("The requested step is approved. Its implementation is starting in a follow-up turn.");
+			}
+			if (params.action === "complete") {
+				updateExecution(completePlanStep(execution, target.id));
+				return finish(execution.status === "completed" ? "The step was marked complete and the plan is complete." : "The step was marked complete. The next step is ready and awaits user instruction.");
+			}
+			if (params.action === "accept") {
+				updateExecution(acceptPlanStep(execution, target.id));
+				return finish(execution.status === "completed" ? "The reviewed step was accepted and the plan is complete." : "The reviewed step was accepted. The next step is ready and awaits user instruction.");
+			}
+			if (params.action === "correct") {
+				updateExecution(requestPlanStepCorrections(execution, target.id));
+				applyTools("build");
+				pi.sendUserMessage(`Apply the corrections requested in the user's preceding message to plan step ${execution.steps.findIndex((step) => step.id === target.id) + 1}.`, { deliverAs: "followUp" });
+				return finish("The reviewed step was reopened. The requested corrections are starting in a follow-up turn.");
+			}
+			if (params.action === "skip") {
+				updateExecution(skipPlanStep(execution, target.id));
+				return finish(execution.status === "completed" ? "The step was skipped and the plan is complete." : "The step was skipped. The next step awaits user instruction.");
+			}
+			if (!params.instruction?.trim()) throw new Error("Revising a step requires a replacement instruction");
+			const plan = await fs.promises.readFile(planPath, "utf8");
+			const updatedPlan = updatePlanChecklistStep(plan, target.sourceLine, params.instruction);
+			await fs.promises.writeFile(planPath, updatedPlan, "utf8");
+			updateExecution(revisePlanStep(execution, target.id, params.instruction, updatedPlan));
+			return finish("The plan step instruction was revised and is awaiting user approval.");
+		},
+		renderCall(args, theme) {
+			const requestedStep = typeof args.step === "number" && Number.isFinite(args.step) ? Math.max(1, Math.floor(args.step)) : undefined;
+			const inferredStep = requestedStep ?? (execution
+				? execution.steps.findIndex((step) => step.status === "ready" || step.status === "review") + 1
+				: 0);
+			const label = inferredStep > 0 ? `Step ${inferredStep}: ${args.action}` : `Plan: ${args.action}`;
+			return new Text(theme.fg("toolTitle", theme.bold(label)), 0, 0);
+		},
+		renderResult(result, _options, theme, context) {
+			const text = result.content.find((item) => item.type === "text")?.text ?? "Plan state updated";
+			return new Text(theme.fg(context.isError ? "error" : "success", text), 0, 0);
+		},
+	});
+
+	pi.registerTool({
+		name: "plan_step_complete",
+		label: "Complete Plan Step",
+		description: PLAN_STEP_COMPLETE_DESCRIPTION,
+		parameters: Type.Object({
+			summary: Type.String({ description: "Concise summary of what was implemented and verified" }),
+		}),
+		executionMode: "sequential",
+		async execute(_toolCallId, params) {
+			const step = activePlanStep(execution);
+			if (!execution || !step) throw new Error("No plan step is currently active");
+			updateExecution(submitPlanStepForReview(execution, step.id, params.summary));
+			applyTools("build");
+			return {
+				content: [{ type: "text", text: "The active plan step is awaiting user review. Stop now and do not begin another step." }],
+				details: { stepId: step.id, review: true },
+				terminate: true,
+			};
+		},
+		renderCall(_args, theme) {
+			return new Text(theme.fg("toolTitle", theme.bold("Submit plan step for review")), 0, 0);
+		},
+		renderResult(_result, _options, theme, context) {
+			return new Text(theme.fg(context.isError ? "error" : "success", context.isError ? "Plan step submission failed" : "Plan step ready for review"), 0, 0);
+		},
+	});
+
 	pi.registerTool({
 		name: "plan_exit",
 		label: "Exit Plan Mode",
@@ -313,10 +516,43 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 			if (!plan.trim()) throw new Error("Cannot request plan approval because the plan file is empty");
 			pi.appendEntry(PLAN_REVIEW_ENTRY_TYPE, { plan, planPath });
 			const displayPath = shorten(planPath, ctx.cwd);
+			let stepExecution: PlanExecutionState | undefined;
+			let checklistError: string | undefined;
+			const panelAvailable = fullscreenPanelCapable && (panelTui?.terminal.columns ?? 0) >= PANEL_MIN_TERMINAL_WIDTH;
+			if (panelAvailable) {
+				try {
+					stepExecution = createPlanExecution(plan);
+				} catch (error: unknown) {
+					checklistError = error instanceof Error ? error.message : String(error);
+				}
+			}
+			const choices = [
+				PLAN_EXIT_APPROVE_CHOICE,
+				...(stepExecution ? [PLAN_STEP_CHOICE] : []),
+				PLAN_EXIT_FRESH_CHOICE,
+				PLAN_EXIT_STAY_CHOICE,
+			];
 			const selection = normalizePlanExitChoice(await ctx.ui.select(
 				`Build Agent: Plan at ${displayPath} is complete. What would you like to do?`,
-				[PLAN_EXIT_APPROVE_CHOICE, PLAN_EXIT_FRESH_CHOICE, PLAN_EXIT_STAY_CHOICE],
+				choices,
 			));
+			if (selection.choice === PLAN_STEP_CHOICE && stepExecution) {
+				freshImplementationRequest = undefined;
+				execution = stepExecution;
+				await selectMode("build", ctx, "tool");
+				updateExecution(stepExecution);
+				ensurePanelLayout();
+				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 },
+					terminate: true,
+				};
+			}
+			if (panelAvailable && !stepExecution && checklistError) {
+				ctx.ui.notify(`Step-by-step execution is unavailable: ${checklistError}.`, "warning");
+			} else if (fullscreenPanelCapable && !panelAvailable) {
+				ctx.ui.notify(`Step-by-step execution requires a terminal at least ${PANEL_MIN_TERMINAL_WIDTH} columns wide.`, "warning");
+			}
 			const decision = classifyPlanExitChoice(selection.choice);
 			if (decision === "stay") {
 				freshImplementationRequest = undefined;
@@ -352,6 +588,9 @@ 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);
+			}
 			if (details?.action === "implement-fresh" && !context.isError) {
 				return new Text(
 					theme.fg("success", "Clean-session implementation selected — starting automatically."),
@@ -367,6 +606,12 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 	});
 
 	pi.on("tool_call", async (event, ctx) => {
+		if ((runMode ?? selectedMode) === "build" && execution && execution.status !== "completed" && !activePlanStep(execution) && (event.toolName === "edit" || event.toolName === "write" || event.toolName === "bash")) {
+			return {
+				block: true,
+				reason: "Step-by-step execution is waiting for an explicit natural-language instruction from the user; no step is approved for project mutations.",
+			};
+		}
 		if (runMode !== "plan" || (event.toolName !== "edit" && event.toolName !== "write")) return;
 		const inputPath = (event.input as { path?: unknown }).path;
 		if (isAllowedPlanMutation(ctx.cwd, inputPath, planPath)) return;
@@ -382,12 +627,12 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 		let content: string | undefined;
 		if (runMode === "plan") {
 			await ensurePlanDirectory();
-			const exists = fs.existsSync(planPath);
-			content = buildPlanReminder(
-				exists
-					? `A plan file already exists at ${planPath}. You can read it and make incremental edits using the edit tool.`
-					: `No plan file exists yet. You should create your plan at ${planPath} using the write tool.`,
-			);
+			content = buildPlanReminder(describePlanFile());
+		} else if (activePlanStep(execution)) {
+			const step = activePlanStep(execution)!;
+			content = buildPlanStepReminder(planPath, execution!.steps.findIndex((item) => item.id === step.id) + 1, execution!.steps.length, step.text);
+		} else if (execution && execution.status !== "completed") {
+			content = buildPlanStepWaitingReminder(execution.steps.map((step, index) => `${index + 1}. [${step.status}] ${step.text}`).join("\n"));
 		} else if (pendingReminder === "build") {
 			content = PLAN_TO_BUILD_REMINDER;
 			if (fs.existsSync(planPath)) content += `\n\nA plan file exists at ${planPath}. You should execute the plan defined within it.`;
@@ -402,6 +647,7 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 		runMode = undefined;
 		applyTools(selectedMode);
 		updateModeIndicator(ctx);
+		if (execution) ensurePanelLayout();
 	});
 
 	pi.on("session_start", async (event, ctx) => {
@@ -416,13 +662,15 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 			.pop() as { data?: unknown } | undefined;
 		const decoded = decodeModeState(latest?.data);
 		const raw = latest?.data as StoredState | undefined;
+		execution = decodePlanExecution(raw?.execution);
 		selectedMode = decoded?.selectedMode ?? (pi.getFlag("plan") === true ? "plan" : "build");
 		pendingReminder = raw?.pendingReminder ?? (decoded ? undefined : pi.getFlag("plan") === true ? "plan" : undefined);
 		toolsBeforeModes = Array.isArray(raw?.toolsBeforeModes)
 			? raw.toolsBeforeModes.filter((name): name is string => typeof name === "string" && !MANAGED_TOOLS.has(name))
 			: pi.getActiveTools().filter((name) => !MANAGED_TOOLS.has(name));
 		planPath = makePlanPath(path.join(getAgentDir(), "plans"), ctx.sessionManager.getSessionId());
-		if (selectedMode === "plan") await ensurePlanDirectory();
+		if (selectedMode === "plan" || execution) await ensurePlanDirectory();
+		if (execution && !fs.existsSync(planPath)) await fs.promises.writeFile(planPath, execution.planMarkdown, "utf8");
 		applyTools(selectedMode);
 		updateModeIndicator(ctx);
 
@@ -572,6 +820,13 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 				const editor = new ModeEditor(tui, theme, keybindings);
 				for (const prompt of promptHistory) editor.addToHistory(prompt);
 				requestEditorRender = () => editor.requestModeRender();
+				panelTui = tui;
+				fullscreenPanelCapable = isViewportTUI(tui) && typeof (tui as ViewportTUI).setLayoutRoot === "function";
+				if (fullscreenPanelCapable && !originalLayoutRoot) {
+					originalLayoutRoot = (tui as TUI & { layoutRoot?: Component }).layoutRoot;
+					fullscreenPanelCapable = originalLayoutRoot !== undefined;
+				}
+				if (execution) ensurePanelLayout();
 				editor.onCycle = () => {
 					if (currentContext) void selectMode(nextMode(selectedMode), currentContext, "manual");
 				};
@@ -586,14 +841,23 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 				};
 				return editor;
 			});
+			if (execution && !fullscreenPanelCapable) {
+				ctx.ui.notify("Step-by-step progress was restored, but its plan panel requires fullscreen TUI mode. Progress is preserved.", "warning");
+			}
 		}
 	});
 
 	pi.on("session_shutdown", async (_event, ctx) => {
+		removePanelLayout();
 		ctx.ui.setStatus(STATUS_KEY, undefined);
 		ctx.ui.setFooter(undefined);
 		ctx.ui.setEditorComponent(undefined);
 		requestEditorRender = undefined;
+		panel = undefined;
+		panelTui = undefined;
+		panelLayoutRoot = undefined;
+		originalLayoutRoot = undefined;
+		fullscreenPanelCapable = false;
 		currentContext = undefined;
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@janvitos/pi-plan-build",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "description": "Plan safely, approve explicitly, then implement here or in a clean session.",
   "type": "module",
   "license": "MIT",
@@ -23,13 +23,15 @@
     "index.ts",
     "prompts.ts",
     "question-ui.ts",
+    "plan-execution.ts",
+    "plan-panel.ts",
     "utils.ts"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "test": "node --experimental-strip-types --test utils.test.ts question-ui.test.ts",
+    "test": "node --experimental-strip-types --test utils.test.ts question-ui.test.ts plan-execution.test.ts plan-panel.test.ts",
     "prepublishOnly": "npm test"
   },
   "peerDependencies": {

package/plan-execution.ts

@@ -0,0 +1,185 @@
+export type PlanStepStatus = "pending" | "ready" | "active" | "review" | "completed" | "skipped";
+
+export interface PlanStep {
+	id: string;
+	text: string;
+	status: PlanStepStatus;
+	sourceLine: number;
+	summary?: string;
+}
+
+export interface PlanExecutionState {
+	version: 1;
+	status: "running" | "paused" | "completed";
+	steps: PlanStep[];
+	planMarkdown: string;
+	selectedStepId?: string;
+	panelVisible: boolean;
+}
+
+const IMPLEMENTATION_HEADING = /^##\s+Implementation Steps\s*$/i;
+const NEXT_H2 = /^##\s+/;
+const CHECKLIST_ITEM = /^- \[ \]\s+(.+?)\s*$/;
+
+export function parseImplementationSteps(plan: string): PlanStep[] {
+	const lines = plan.replace(/\r\n?/g, "\n").split("\n");
+	const heading = lines.findIndex((line) => IMPLEMENTATION_HEADING.test(line.trim()));
+	if (heading < 0) throw new Error("The plan needs a ‘## Implementation Steps’ section");
+
+	const steps: PlanStep[] = [];
+	const seen = new Set<string>();
+	for (let index = heading + 1; index < lines.length; index++) {
+		const line = lines[index]!;
+		if (NEXT_H2.test(line.trim())) break;
+		const match = CHECKLIST_ITEM.exec(line);
+		if (!match) continue;
+		const text = match[1]!.trim();
+		const normalized = text.toLocaleLowerCase();
+		if (!text) throw new Error(`Implementation step on line ${index + 1} is empty`);
+		if (seen.has(normalized)) throw new Error(`Duplicate implementation step: ${text}`);
+		seen.add(normalized);
+		steps.push({ id: `step-${steps.length + 1}`, text, status: "pending", sourceLine: index });
+	}
+	if (steps.length === 0) throw new Error("The Implementation Steps section has no top-level ‘- [ ]’ items");
+	return steps;
+}
+
+export function createPlanExecution(plan: string): PlanExecutionState {
+	const steps = parseImplementationSteps(plan);
+	steps[0]!.status = "ready";
+	return { version: 1, status: "running", steps, planMarkdown: plan, selectedStepId: steps[0]!.id, panelVisible: true };
+}
+
+export function decodePlanExecution(value: unknown): PlanExecutionState | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const candidate = value as Partial<PlanExecutionState>;
+	if (candidate.version !== 1 || !["running", "paused", "completed"].includes(candidate.status ?? "")) return undefined;
+	if (!Array.isArray(candidate.steps) || candidate.steps.length === 0 || typeof candidate.planMarkdown !== "string") return undefined;
+	const validStatuses = new Set<PlanStepStatus>(["pending", "ready", "active", "review", "completed", "skipped"]);
+	const steps: PlanStep[] = [];
+	for (const raw of candidate.steps) {
+		if (!raw || typeof raw !== "object") return undefined;
+		const step = raw as Partial<PlanStep>;
+		if (typeof step.id !== "string" || typeof step.text !== "string" || !validStatuses.has(step.status as PlanStepStatus)) return undefined;
+		if (!Number.isInteger(step.sourceLine) || (step.sourceLine ?? -1) < 0) return undefined;
+		steps.push({ id: step.id, text: step.text, status: step.status as PlanStepStatus, sourceLine: step.sourceLine!, ...(typeof step.summary === "string" ? { summary: step.summary } : {}) });
+	}
+	return {
+		version: 1,
+		status: candidate.status!,
+		steps,
+		planMarkdown: candidate.planMarkdown,
+		selectedStepId: typeof candidate.selectedStepId === "string" ? candidate.selectedStepId : undefined,
+		panelVisible: candidate.panelVisible !== false,
+	};
+}
+
+function clone(state: PlanExecutionState): PlanExecutionState {
+	return { ...state, steps: state.steps.map((step) => ({ ...step })) };
+}
+
+function findStep(state: PlanExecutionState, id: string): PlanStep {
+	const step = state.steps.find((candidate) => candidate.id === id);
+	if (!step) throw new Error(`Unknown plan step: ${id}`);
+	return step;
+}
+
+function makeNextReady(state: PlanExecutionState, afterId: string): void {
+	const index = state.steps.findIndex((step) => step.id === afterId);
+	const next = state.steps.slice(index + 1).find((step) => step.status === "pending");
+	if (next) {
+		next.status = "ready";
+		state.selectedStepId = next.id;
+		return;
+	}
+	if (state.steps.every((step) => step.status === "completed" || step.status === "skipped")) {
+		state.status = "completed";
+		state.selectedStepId = undefined;
+	}
+}
+
+export function startPlanStep(state: PlanExecutionState, id: string): PlanExecutionState {
+	const next = clone(state);
+	if (next.status === "completed") throw new Error("The plan is already complete");
+	const step = findStep(next, id);
+	if (step.status !== "ready") throw new Error("Only a ready step can be implemented");
+	step.status = "active";
+	next.status = "running";
+	next.selectedStepId = id;
+	return next;
+}
+
+export function submitPlanStepForReview(state: PlanExecutionState, id: string, summary: string): PlanExecutionState {
+	const next = clone(state);
+	const step = findStep(next, id);
+	if (step.status !== "active") throw new Error("Only the active step can be submitted for review");
+	step.status = "review";
+	step.summary = summary.trim();
+	next.selectedStepId = id;
+	return next;
+}
+
+export function completePlanStep(state: PlanExecutionState, id: string): PlanExecutionState {
+	const next = clone(state);
+	const step = findStep(next, id);
+	if (step.status !== "ready" && step.status !== "review") {
+		throw new Error("Only a ready or reviewed step can be marked complete");
+	}
+	step.status = "completed";
+	makeNextReady(next, id);
+	return next;
+}
+
+export function acceptPlanStep(state: PlanExecutionState, id: string): PlanExecutionState {
+	const step = findStep(state, id);
+	if (step.status !== "review") throw new Error("Only a step awaiting review can be accepted");
+	return completePlanStep(state, id);
+}
+
+export function requestPlanStepCorrections(state: PlanExecutionState, id: string): PlanExecutionState {
+	const next = clone(state);
+	const step = findStep(next, id);
+	if (step.status !== "review") throw new Error("Only a step awaiting review can receive corrections");
+	step.status = "active";
+	next.selectedStepId = id;
+	return next;
+}
+
+export function skipPlanStep(state: PlanExecutionState, id: string): PlanExecutionState {
+	const next = clone(state);
+	const step = findStep(next, id);
+	if (step.status !== "ready") throw new Error("Only a ready step can be skipped");
+	step.status = "skipped";
+	makeNextReady(next, id);
+	return next;
+}
+
+export function revisePlanStep(state: PlanExecutionState, id: string, text: string, planMarkdown = state.planMarkdown): PlanExecutionState {
+	const revised = text.trim();
+	if (!revised) throw new Error("A plan step cannot be empty");
+	const next = clone(state);
+	const step = findStep(next, id);
+	if (step.status !== "pending" && step.status !== "ready") throw new Error("Only an unimplemented step can be edited");
+	step.text = revised;
+	next.planMarkdown = planMarkdown;
+	return next;
+}
+
+export function pausePlanExecution(state: PlanExecutionState): PlanExecutionState {
+	if (state.status === "completed") return state;
+	return { ...clone(state), status: state.status === "paused" ? "running" : "paused" };
+}
+
+export function updatePlanChecklistStep(plan: string, sourceLine: number, text: string): string {
+	const newline = plan.includes("\r\n") ? "\r\n" : "\n";
+	const lines = plan.replace(/\r\n?/g, "\n").split("\n");
+	if (!Number.isInteger(sourceLine) || sourceLine < 0 || sourceLine >= lines.length || !CHECKLIST_ITEM.test(lines[sourceLine]!)) {
+		throw new Error("The saved plan changed and the selected checklist item can no longer be updated safely");
+	}
+	lines[sourceLine] = `- [ ] ${text.trim()}`;
+	return lines.join(newline);
+}
+
+export function activePlanStep(state: PlanExecutionState | undefined): PlanStep | undefined {
+	return state?.steps.find((step) => step.status === "active");
+}

package/plan-panel.ts

@@ -0,0 +1,75 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component } from "@earendil-works/pi-tui";
+import type { PlanExecutionState } from "./plan-execution.ts";
+
+const GLYPHS = {
+	pending: "○",
+	ready: "▷",
+	active: "▶",
+	review: "◆",
+	completed: "✓",
+	skipped: "–",
+} as const;
+
+export class PlanPanel implements Component {
+	private state: PlanExecutionState;
+	private readonly theme: Theme;
+
+	constructor(state: PlanExecutionState, theme: Theme) {
+		this.state = state;
+		this.theme = theme;
+	}
+
+	setState(state: PlanExecutionState): void {
+		this.state = state;
+	}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		const safeWidth = Math.max(12, width);
+		const inner = Math.max(1, safeWidth - 2);
+		const contentWidth = Math.max(1, safeWidth - 4);
+		const border = (text: string) => this.theme.fg("borderMuted", text);
+		const pad = (content = "") => {
+			const clipped = truncateToWidth(content, contentWidth, "");
+			return `${border("│")} ${clipped}${" ".repeat(Math.max(0, contentWidth - visibleWidth(clipped)))} ${border("│")}`;
+		};
+		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);
+		const lines = [
+			border(`╭${"─".repeat(inner)}╮`),
+			pad(`${this.theme.bold(this.theme.fg("accent", "Plan"))} ${this.theme.fg("dim", `${done}/${this.state.steps.length}`)}`),
+			pad(this.theme.fg(this.state.status === "paused" ? "warning" : "muted", status)),
+			border(`├${"─".repeat(inner)}┤`),
+		];
+		for (let index = 0; index < this.state.steps.length; index++) {
+			const step = this.state.steps[index]!;
+			const glyphColor = step.status === "completed" ? "success" : step.status === "review" ? "warning" : step.status === "active" || step.status === "ready" ? "accent" : "muted";
+			const prefix = `${this.theme.fg(glyphColor, GLYPHS[step.status])} ${index + 1}. `;
+			const text = step.status === "completed" || step.status === "skipped" ? this.theme.fg("muted", step.text) : step.text;
+			const wrapped = wrapTextWithAnsi(text, Math.max(1, contentWidth - visibleWidth(prefix)));
+			lines.push(pad(`${prefix}${wrapped[0] ?? ""}`));
+			const continuationIndent = " ".repeat(visibleWidth(prefix));
+			for (const continuation of wrapped.slice(1)) lines.push(pad(`${continuationIndent}${continuation}`));
+		}
+		const current = currentIndex >= 0 ? this.state.steps[currentIndex] : undefined;
+		if (current) {
+			lines.push(border(`├${"─".repeat(inner)}┤`));
+			for (const detail of wrapTextWithAnsi(current.text, contentWidth).slice(0, 5)) lines.push(pad(detail));
+			if (current.summary) {
+				lines.push(pad(this.theme.fg("dim", "Result:")));
+				for (const summary of wrapTextWithAnsi(current.summary, contentWidth).slice(0, 4)) lines.push(pad(summary));
+			}
+		}
+		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 (current?.status === "review") lines.push(pad("Tell the agent to accept, correct, or cancel the plan."));
+		else lines.push(pad("Plan progress updates automatically from your prompts."));
+		lines.push(border(`╰${"─".repeat(inner)}╯`));
+		return lines.map((line) => truncateToWidth(line, safeWidth, ""));
+	}
+}

package/prompts.ts

@@ -1,5 +1,5 @@
-// Prompt text pinned to OpenCode 1.18.16. The subagent phases are intentionally
-// adapted to direct Pi exploration/design, as documented in README.md.
+// Conversational read-only behavior follows OpenCode's standard Plan agent.
+// Persisted finalization and approval are Pi-specific adaptations documented in README.md.
 
 export const PLAN_TO_BUILD_REMINDER = `<system-reminder>
 Your operational mode has changed from plan to build.
@@ -9,60 +9,73 @@ You are permitted to make file changes, run shell commands, and utilize your ars
 
 export function buildPlanReminder(planInfo: string): string {
 	return `<system-reminder>
-Plan mode is active. The user indicated that they do not want you to execute yet -- you MUST NOT make any edits (with the exception of the plan file mentioned below), run any non-readonly tools (including changing configs or making commits), or otherwise make any changes to the system. This supersedes any other instructions you have received.
+# Plan Mode - System Reminder
 
-## Plan File Info:
-${planInfo}
-Only when the current request requires an implementation plan should you build the plan incrementally by writing to or editing this file. NOTE that this is the only file you are allowed to edit - other than this you are only allowed to take READ-ONLY actions.
+Plan mode is active. The user indicated that they do not want you to execute yet -- you MUST NOT make edits (except to the plan file when finalizing as described below), run non-readonly tools (including changing configs or making commits), or otherwise make changes to the system. You may only observe, analyze, discuss, and plan. This supersedes any other instructions you have received.
+
+## Responsibility
+
+Think, read, search, and discuss with the user to construct a well-formed implementation plan that accomplishes their goal. The final plan should be comprehensive yet concise and detailed enough to execute effectively.
 
-## Informational Questions
+## Conversation and Research
 
-If the user asks an informational question and does not ask you to make changes or produce an implementation plan, answer the question directly instead of starting the workflow below.
+Plan mode does not require every response to be a final plan. While you are still understanding the request, researching the project, or discussing the approach:
 
-- You may use read-only tools to inspect the project when the answer depends on it.
+- Answer informational questions and converse normally.
+- Use read-only tools when the answer or design depends on the project.
+- Discuss requirements, tradeoffs, and possible approaches with the user.
+- Ask clarifying questions when needed, either conversationally or with the question tool when structured choices would help.
 - Do not create or update the plan file.
-- Do not call the question tool merely because the request is phrased as a question; use it only when clarification is actually needed.
 - Do not call plan_exit.
-- End your response normally after answering. Plan mode remains active for future requests.
+- End your response normally when the conversation should continue.
 
-## Plan Workflow
+Do not assume that a plan file must be changed merely because Plan mode is active or because a plan file already exists. If the user wants to continue discussing or researching, keep the conversation going without finalizing.
 
-### Phase 1: Initial Understanding
-Goal: Gain a comprehensive understanding of the user's request by reading through code and asking them questions.
+## Finalizing the Plan
 
-1. Focus on understanding the user's request and the code associated with their request.
-2. Explore the codebase directly with Pi's read, grep, find, ls, and read-only shell operations. Read the minimum set of high-value files needed to understand existing patterns and testing.
-3. After exploring the code, use the question tool to clarify ambiguities in the user request up front.
+Once you have enough information and are ready to present the final implementation plan, or when the user explicitly asks you to finalize it, write the complete plan to the plan file and call plan_exit at the end of that turn.
 
-### Phase 2: Design
-Goal: Design an implementation approach.
+### Plan File Info
+${planInfo}
 
-Design the implementation directly based on the user's intent and your exploration results. Consider simplicity, correctness, maintainability, existing patterns, edge cases, and verification. Skip extended design only for truly trivial tasks such as typo fixes, single-line changes, or simple renames.
+The plan file is the only file you may edit, and only while finalizing the plan or explicitly revising an existing plan. The final plan should:
 
-### Phase 3: Review
-Goal: Review the design and ensure alignment with the user's intentions.
-1. Read the critical files identified during exploration to deepen your understanding.
-2. Ensure that the design aligns with the user's original request.
-3. Use question tool to clarify any remaining questions with the user.
+- Include only the recommended approach, not every alternative considered.
+- Be concise enough to scan quickly but detailed enough to implement.
+- Identify the critical files that need modification.
+- Include verification steps for testing the change end-to-end.
+- End with a \`## Implementation Steps\` section containing the executable top-level steps as \`- [ ] ...\` checklist items. Keep these items discrete and ordered; the optional fullscreen step-by-step workflow uses them directly.
 
-### Phase 4: Final Plan
-Goal: Write your final plan to the plan file (the only file you can edit).
-- Include only your recommended approach, not all alternatives.
-- Ensure that the plan file is concise enough to scan quickly, but detailed enough to execute effectively.
-- Include the paths of critical files to be modified.
-- Include a verification section describing how to test the changes end-to-end (run the code, use available tools, run tests).
+After writing the complete plan, call plan_exit to request approval. Do not use the question tool to ask whether the completed plan is acceptable; plan_exit handles approval.
+</system-reminder>`;
+}
+
+export const PLAN_ENTER_DESCRIPTION = `Use this tool when the user asks you to plan, when a request needs investigation before implementation, or when switching to the plan agent is the safest next step. The tool changes the current continuation to Plan mode.`;
 
-### Phase 5: Call plan_exit tool
-At the very end of your turn, once you have asked the user questions and are happy with your final plan file - you should always call plan_exit to indicate to the user that you are done planning.
-This is critical - your turn should only end with either asking the user a question or calling plan_exit. Do not stop unless it's for these 2 reasons.
+export function buildPlanStepReminder(planPath: string, stepNumber: number, totalSteps: number, step: string): string {
+	return `<system-reminder>
+# Step-by-Step Plan Execution
 
-**Important:** Use question tool to clarify requirements/approach, use plan_exit to request plan approval. Do NOT use question tool to ask "Is this plan okay?" - that's what plan_exit does.
+The approved plan is at ${planPath}. Implement only step ${stepNumber} of ${totalSteps}:
 
-NOTE: At any point in time through this workflow you should feel free to ask the user questions or clarifications. Don't make large assumptions about user intent. The goal is to present a well researched plan to the user, and tie any loose ends before implementation begins.
+${step}
+
+Do not begin any later plan step. Complete and verify this step, then call plan_step_complete with a concise result summary. If the user requests corrections, continue working only on this same step and submit it for review again.
 </system-reminder>`;
 }
 
-export const PLAN_ENTER_DESCRIPTION = `Use this tool when the user asks you to plan, when a request needs investigation before implementation, or when switching to the plan agent is the safest next step. The tool changes the current continuation to Plan mode.`;
+export function buildPlanStepWaitingReminder(progress: string): string {
+	return `<system-reminder>
+Step-by-step execution is waiting for the user's natural-language instruction. No plan step is currently approved for implementation. Do not modify the project or begin a pending step directly.
+
+Current progress:
+${progress}
+
+Interpret the user's intent contextually rather than requiring exact phrases. Clear statements, confirmations, and feedback may request a state transition even when phrased non-imperatively. For example, a statement that a ready step is finished can use the complete action, while a positive review of agent work can use accept. If multiple materially different actions are plausible, ask a brief clarification. Cancellation is always available when the user clearly wants to stop. Do not advance based on hypothetical, uncertain, or unrelated discussion. The sidebar is a passive visual aid and cannot receive input.
+</system-reminder>`;
+}
+
+export const PLAN_STEP_COMPLETE_DESCRIPTION = `Call this tool after implementing and verifying the currently active plan step. It stops execution and returns control to the user for review. Do not call it before the active step is complete, and never begin the next step yourself.`;
 
 export const PLAN_EXIT_DESCRIPTION = `Use this tool when you have completed the planning phase and are ready to exit plan agent.
 
@@ -76,5 +89,4 @@ Call this tool:
 Do NOT call this tool:
 - Before you have created or finalized the plan
 - If you still have unanswered questions about the implementation
-- If the user has indicated they want to continue planning
-- After directly answering an informational question that did not require an implementation plan`;
+- If the user has indicated they want to continue planning`;