@janvitos/pi-plan-build 0.1.31 → 0.1.33

package/README.md

@@ -15,10 +15,11 @@ A global [Pi coding agent](https://github.com/badlogic/pi-mono) extension that a
 - Interactive `question`, `plan_enter`, and `plan_exit` tools.
 - 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. The panel is visual-only and never captures keyboard input. 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
 
@@ -71,8 +73,9 @@ The agent may also enter Plan mode with `plan_enter` when planning or investigat
 When planning is complete, `plan_exit` displays the entire persisted plan and asks whether to:
 
 1. implement in the current session;
-2. start a clean linked implementation session; or
-3. stay in Plan mode.
+2. start a clean linked implementation session;
+3. stay in Plan mode; or
+4. **experimentally implement step by step** in fullscreen TUI when the plan contains a valid checklist.
 
 Selecting **Start fresh and implement** stops the current run and automatically dispatches `/build-fresh`. Pi 0.84.2 or newer is required for extension command dispatch from an injected user message. The command creates a linked child session, copies the approved plan to its canonical plan file, preserves the model and thinking level selected for the action, switches it to Build, and starts implementation without transferring the planning conversation.
 
@@ -82,6 +85,33 @@ 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` 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:
+
+- “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. A ready step may be marked complete without implementation when the user says they already handled or verified it. A reviewed implementation may be accepted, while ambiguous feedback prompts clarification. 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. 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:
@@ -112,7 +142,7 @@ npm test
 npm pack --dry-run
 ```
 
-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, and question formatting and cancellation.
+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 = 64;
+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"] : []),
+			]));
 		}
 	}
 
@@ -297,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",
@@ -315,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;
@@ -354,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."),
@@ -369,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;
@@ -385,6 +628,11 @@ export default function planBuildModes(pi: ExtensionAPI): void {
 		if (runMode === "plan") {
 			await ensurePlanDirectory();
 			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.`;
@@ -399,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) => {
@@ -413,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);
 
@@ -569,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");
 				};
@@ -583,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.31",
+  "version": "0.1.33",
   "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,76 @@
+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}`));
+			if (index < this.state.steps.length - 1) lines.push(pad());
+		}
+		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

@@ -44,6 +44,7 @@ The plan file is the only file you may edit, and only while finalizing the plan
 - 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.
 
 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>`;
@@ -51,6 +52,31 @@ After writing the complete plan, call plan_exit to request approval. Do not use
 
 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 buildPlanStepReminder(planPath: string, stepNumber: number, totalSteps: number, step: string): string {
+	return `<system-reminder>
+# Step-by-Step Plan Execution
+
+The approved plan is at ${planPath}. Implement only step ${stepNumber} of ${totalSteps}:
+
+${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 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.
 
 This tool displays the complete plan and asks the user whether to implement it in this session, prepare a clean-session implementation, or stay in Plan mode.