@janvitos/pi-plan-build 0.1.30 → 0.1.31

package/README.md

@@ -13,7 +13,7 @@ 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:
   - **Switch to Build and implement here**
@@ -87,20 +87,21 @@ Both actions leave Plan mode active, stop the agent, and wait for the next user
 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 +112,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, and question formatting and cancellation.
 
 ### Publishing
 

package/index.ts

@@ -130,6 +130,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 +284,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 },
 			};
 		},
@@ -382,12 +384,7 @@ 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 (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.`;

package/package.json

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

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,56 +9,43 @@ 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.
-
-## Informational Questions
+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.
 
-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.
+## Responsibility
 
-- You may use read-only tools to inspect the project when the answer depends on it.
-- 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.
+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.
 
-## Plan Workflow
+## Conversation and Research
 
-### Phase 1: Initial Understanding
-Goal: Gain a comprehensive understanding of the user's request by reading through code and asking them questions.
+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:
 
-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.
+- 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 plan_exit.
+- End your response normally when the conversation should continue.
 
-### Phase 2: Design
-Goal: Design an implementation approach.
+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.
 
-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.
+## Finalizing the Plan
 
-### 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.
+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 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).
+### Plan File Info
+${planInfo}
 
-### 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.
+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:
 
-**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.
+- 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.
 
-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.
+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>`;
 }
 
@@ -76,5 +63,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`;