Planning mode (#2370)

AGENTS.md

@@ -240,3 +240,13 @@ When running GitHub Actions with `pull_request_target` on cross-repo PRs (from f
 
 - Wrapping `ToggleGroupItem` in `TooltipTrigger` without `render` also breaks `:first-child`/`:last-child` CSS selectors for rounded corners on the group.
 - For drag handles and resize rails, prefer the native `title` attribute over `Tooltip` — tooltips appear immediately on hover and interfere with drag interactions, while `title` has a built-in delay.
+
+### Drizzle migration conflicts during rebase
+
+When rebasing a branch that has drizzle migrations conflicting with upstream (e.g., both have `0023_*.sql`):
+
+1. Keep upstream's migration files (they're already deployed to production)
+2. Rename the PR's conflicting migration to the next available index (e.g., `0023_romantic_mantis.sql` → `0025_romantic_mantis.sql`)
+3. Update `drizzle/meta/_journal.json` to include all migrations with correct indices
+4. Create/update the snapshot file (`drizzle/meta/00XX_snapshot.json`) with the new index, updating `prevId` to reference the previous snapshot's `id`
+5. If the PR had subsequent commits that deleted/modified its migration files, those changes become no-ops after renaming — just accept the deletion conflicts by staging the renamed files

CLAUDE.md

-AGENTS.md
\ No newline at end of file
+AGENTS.md

drizzle/0025_romantic_mantis.sql

+CREATE TABLE `plans` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`app_id` integer NOT NULL,
+	`chat_id` integer,
+	`title` text NOT NULL,
+	`summary` text,
+	`content` text NOT NULL,
+	`status` text DEFAULT 'draft' NOT NULL,
+	`created_at` integer DEFAULT (unixepoch()) NOT NULL,
+	`updated_at` integer DEFAULT (unixepoch()) NOT NULL,
+	FOREIGN KEY (`app_id`) REFERENCES `apps`(`id`) ON UPDATE no action ON DELETE cascade,
+	FOREIGN KEY (`chat_id`) REFERENCES `chats`(`id`) ON UPDATE no action ON DELETE set null
+);

drizzle/meta/0023_snapshot.json → drizzle/meta/0025_snapshot.json

 {
   "version": "6",
   "dialect": "sqlite",
-  "id": "58bbbbba-abef-41e9-b0f8-000fbb4f59ac",
-  "prevId": "ce28ff48-ebcb-4c8e-90aa-623ebe456839",
+  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "prevId": "39604cc7-898f-4dde-a4dd-a46a8cc7680a",
   "tables": {
     "apps": {
       "name": "apps",
@@ -682,6 +682,13 @@
           "notNull": false,
           "autoincrement": false
         },
+        "using_free_agent_mode_quota": {
+          "name": "using_free_agent_mode_quota",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
         "created_at": {
           "name": "created_at",
           "type": "integer",
@@ -711,6 +718,109 @@
       "uniqueConstraints": {},
       "checkConstraints": {}
     },
+    "plans": {
+      "name": "plans",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "app_id": {
+          "name": "app_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "chat_id": {
+          "name": "chat_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "summary": {
+          "name": "summary",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "content": {
+          "name": "content",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'draft'"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(unixepoch())"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(unixepoch())"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "plans_app_id_apps_id_fk": {
+          "name": "plans_app_id_apps_id_fk",
+          "tableFrom": "plans",
+          "tableTo": "apps",
+          "columnsFrom": [
+            "app_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "plans_chat_id_chats_id_fk": {
+          "name": "plans_chat_id_chats_id_fk",
+          "tableFrom": "plans",
+          "tableTo": "chats",
+          "columnsFrom": [
+            "chat_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
     "prompts": {
       "name": "prompts",
       "columns": {
@@ -853,4 +963,4 @@
   "internal": {
     "indexes": {}
   }
-}
\ No newline at end of file
+}

drizzle/meta/_journal.json

@@ -176,6 +176,13 @@
       "when": 1769582904159,
       "tag": "0024_useful_skin",
       "breakpoints": true
+    },
+    {
+      "idx": 25,
+      "version": "6",
+      "when": 1769600000000,
+      "tag": "0025_romantic_mantis",
+      "breakpoints": true
     }
   ]
-}
\ No newline at end of file
+}

e2e-tests/fixtures/engine/local-agent/accept-plan.ts

+import type { LocalAgentFixture } from "../../../../testing/fake-llm-server/localAgentTypes";
+
+export const fixture: LocalAgentFixture = {
+  description: "Present an implementation plan to the user",
+  turns: [
+    {
+      text: "I'll create a plan for you.",
+      toolCalls: [
+        {
+          name: "write_plan",
+          args: {
+            title: "Test Plan",
+            summary: "A test implementation plan for E2E testing.",
+            plan: "## Overview\n\nThis is a test plan.\n\n## Steps\n\n1. Step one\n2. Step two",
+          },
+        },
+      ],
+    },
+    {
+      text: "I've presented the implementation plan. You can review it in the preview panel and accept it when ready.",
+    },
+  ],
+};

e2e-tests/fixtures/engine/local-agent/exit-plan.ts

+import type { LocalAgentFixture } from "../../../../testing/fake-llm-server/localAgentTypes";
+
+export const fixture: LocalAgentFixture = {
+  description: "Exit plan mode after user accepts the plan",
+  turns: [
+    {
+      text: "Great, let's proceed with the implementation.",
+      toolCalls: [
+        {
+          name: "exit_plan",
+          args: {
+            confirmation: true,
+          },
+        },
+      ],
+    },
+    {
+      text: "Plan accepted. Switching to implementation mode.",
+    },
+  ],
+};

e2e-tests/fixtures/engine/local-agent/questionnaire.ts

+import type { LocalAgentFixture } from "../../../../testing/fake-llm-server/localAgentTypes";
+
+export const fixture: LocalAgentFixture = {
+  description: "Present a planning questionnaire to the user",
+  turns: [
+    {
+      text: "Let me ask you a few questions to understand your requirements.",
+      toolCalls: [
+        {
+          name: "planning_questionnaire",
+          args: {
+            title: "Project Requirements",
+            description: "Help me understand your project needs",
+            questions: [
+              {
+                id: "framework",
+                type: "radio",
+                question: "Which framework do you prefer?",
+                options: ["React", "Vue", "Svelte"],
+                required: true,
+              },
+            ],
+          },
+        },
+      ],
+    },
+    {
+      text: "Thanks, I'll wait for your responses before proceeding.",
+    },
+  ],
+};

e2e-tests/helpers/test_helper.ts

@@ -477,7 +477,7 @@ export class PageObject {
   }
 
   async selectChatMode(
-    mode: "build" | "ask" | "agent" | "local-agent" | "basic-agent",
+    mode: "build" | "ask" | "agent" | "local-agent" | "basic-agent" | "plan",
   ) {
     await this.page.getByTestId("chat-mode-selector").click();
     const mapping: Record<string, string> = {
@@ -486,6 +486,7 @@ export class PageObject {
       agent: "Build with MCP",
       "local-agent": "Agent v2",
       "basic-agent": "Basic Agent", // For free users
+      plan: "Plan.*Design before you build",
     };
     const optionName = mapping[mode];
     await this.page

e2e-tests/plan_mode.spec.ts

+import fs from "node:fs";
+import path from "node:path";
+import { expect } from "@playwright/test";
+import { Timeout, test } from "./helpers/test_helper";
+
+test("plan mode - accept plan redirects to new chat and saves to disk", async ({
+  po,
+}) => {
+  test.setTimeout(180000);
+  await po.setUpDyadPro({ localAgent: true });
+  await po.importApp("minimal");
+  await po.selectChatMode("plan");
+
+  // Get app path before accepting (needed to check saved plan)
+  const appPath = await po.getCurrentAppPath();
+
+  // Trigger write_plan fixture
+  await po.sendPrompt("tc=local-agent/accept-plan");
+
+  // Capture current chat ID from URL
+  const initialUrl = po.page.url();
+  const initialChatIdMatch = initialUrl.match(/[?&]id=(\d+)/);
+  expect(initialChatIdMatch).not.toBeNull();
+  const initialChatId = initialChatIdMatch![1];
+
+  // Wait for plan panel to appear
+  const acceptButton = po.page.getByRole("button", { name: "Accept Plan" });
+  await expect(acceptButton).toBeVisible({ timeout: Timeout.MEDIUM });
+
+  // Accept the plan (plans are now always saved to .dyad/plans/)
+  await acceptButton.click();
+
+  // Wait for navigation to a different chat
+  await expect(async () => {
+    const currentUrl = po.page.url();
+    const match = currentUrl.match(/[?&]id=(\d+)/);
+    expect(match).not.toBeNull();
+    expect(match![1]).not.toEqual(initialChatId);
+  }).toPass({ timeout: Timeout.MEDIUM });
+
+  // Verify plan was saved to .dyad/plans/
+  const planDir = path.join(appPath!, ".dyad", "plans");
+  let mdFiles: string[] = [];
+  await expect(async () => {
+    const files = fs.readdirSync(planDir);
+    mdFiles = files.filter((f) => f.endsWith(".md"));
+    expect(mdFiles.length).toBeGreaterThan(0);
+  }).toPass({ timeout: Timeout.MEDIUM });
+
+  // Verify plan content
+  const planContent = fs.readFileSync(path.join(planDir, mdFiles[0]), "utf-8");
+  expect(planContent).toContain("Test Plan");
+});
+
+test("plan mode - questionnaire flow", async ({ po }) => {
+  test.setTimeout(180000);
+  await po.setUpDyadPro({ localAgent: true });
+  await po.importApp("minimal");
+  await po.selectChatMode("plan");
+
+  // Trigger questionnaire fixture
+  await po.sendPrompt("tc=local-agent/questionnaire");
+
+  // Wait for questionnaire UI to appear
+  await expect(po.page.getByText("Project Requirements")).toBeVisible({
+    timeout: Timeout.MEDIUM,
+  });
+
+  // Select "React" radio option
+  await po.page.getByLabel("React").click();
+
+  // Click Submit (single question → Submit button shown)
+  await po.page.getByRole("button", { name: /Submit/ }).click();
+
+  // Wait for the LLM response to the submitted answers
+  await po.waitForChatCompletion();
+
+  // Snapshot the messages
+  await po.snapshotMessages();
+});

e2e-tests/snapshots/plan_mode.spec.ts_plan-mode---questionnaire-flow-1.aria.yml

+- paragraph: tc=local-agent/questionnaire
+- paragraph: Let me ask you a few questions to understand your requirements.
+- button:
+  - img
+- img
+- text: Approved
+- img
+- text: claude-opus-4-5
+- img
+- text: less than a minute ago
+- button "Request ID":
+  - img
+- paragraph: "Here are my responses to the questionnaire:"
+- paragraph:
+  - strong: Which framework do you prefer?
+  - text: React
+- img
+- text: file1.txt
+- button "Edit":
+  - img
+- img
+- text: file1.txt
+- paragraph: More EOM
+- button:
+  - img
+- img
+- text: claude-opus-4-5
+- img
+- text: less than a minute ago
+- button "Request ID":
+  - img
+- button "Undo":
+  - img
+- button "Retry":
+  - img
\ No newline at end of file

package-lock.json

@@ -451,7 +451,6 @@
       "resolved": "https://registry.npmjs.org/@babel/core/-/core-7.28.4.tgz",
       "integrity": "sha512-2BCOP7TN8M+gVDj7/ht3hsaO/B/n5oDbiAyyvnRlNOs+u1o+JWNYTQrmpuNp1/Wq2gcFrI01JAW+paEKDMx/CA==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@babel/code-frame": "^7.27.1",
         "@babel/generator": "^7.28.3",
@@ -1419,7 +1418,6 @@
       "integrity": "sha512-zx0EIq78WlY/lBb1uXlziZmDZI4ubcCXIMJ4uGjXzZW0nS19TjSPeXPAjzzTmKQlJUZm0SbmZhPKP7tuQ1SsEw==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "chalk": "^4.1.1",
         "fs-extra": "^9.0.1",
@@ -2904,6 +2902,7 @@
       "os": [
         "darwin"
       ],
+      "peer": true,
       "engines": {
         "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
       },
@@ -2926,6 +2925,7 @@
       "os": [
         "darwin"
       ],
+      "peer": true,
       "engines": {
         "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
       },
@@ -2948,6 +2948,7 @@
       "os": [
         "darwin"
       ],
+      "peer": true,
       "funding": {
         "url": "https://opencollective.com/libvips"
       }
@@ -2964,6 +2965,7 @@
       "os": [
         "darwin"
       ],
+      "peer": true,
       "funding": {
         "url": "https://opencollective.com/libvips"
       }
@@ -2980,6 +2982,7 @@
       "os": [
         "linux"
       ],
+      "peer": true,
       "funding": {
         "url": "https://opencollective.com/libvips"
       }
@@ -2996,6 +2999,7 @@
       "os": [
         "linux"
       ],
+      "peer": true,
       "funding": {
         "url": "https://opencollective.com/libvips"
       }
@@ -3012,6 +3016,7 @@
       "os": [
         "linux"
       ],
+      "peer": true,
       "funding": {
         "url": "https://opencollective.com/libvips"
       }
@@ -3028,6 +3033,7 @@
       "os": [
         "linux"
       ],
+      "peer": true,
       "funding": {
         "url": "https://opencollective.com/libvips"
       }
@@ -3044,6 +3050,7 @@
       "os": [
         "linux"
       ],
+      "peer": true,
       "funding": {
         "url": "https://opencollective.com/libvips"
       }
@@ -3060,6 +3067,7 @@
       "os": [
         "linux"
       ],
+      "peer": true,
       "funding": {
         "url": "https://opencollective.com/libvips"
       }
@@ -3076,6 +3084,7 @@
       "os": [
         "linux"
       ],
+      "peer": true,
       "funding": {
         "url": "https://opencollective.com/libvips"
       }
@@ -3092,6 +3101,7 @@
       "os": [
         "linux"
       ],
+      "peer": true,
       "engines": {
         "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
       },
@@ -3114,6 +3124,7 @@
       "os": [
         "linux"
       ],
+      "peer": true,
       "engines": {
         "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
       },
@@ -3136,6 +3147,7 @@
       "os": [
         "linux"
       ],
+      "peer": true,
       "engines": {
         "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
       },
@@ -3158,6 +3170,7 @@
       "os": [
         "linux"
       ],
+      "peer": true,
       "engines": {
         "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
       },
@@ -3180,6 +3193,7 @@
       "os": [
         "linux"
       ],
+      "peer": true,
       "engines": {
         "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
       },
@@ -3202,6 +3216,7 @@
       "os": [
         "linux"
       ],
+      "peer": true,
       "engines": {
         "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
       },
@@ -3224,6 +3239,7 @@
       "os": [
         "linux"
       ],
+      "peer": true,
       "engines": {
         "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
       },
@@ -3243,6 +3259,7 @@
       ],
       "license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT",
       "optional": true,
+      "peer": true,
       "dependencies": {
         "@emnapi/runtime": "^1.4.4"
       },
@@ -3265,6 +3282,7 @@
       "os": [
         "win32"
       ],
+      "peer": true,
       "engines": {
         "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
       },
@@ -3284,6 +3302,7 @@
       "os": [
         "win32"
       ],
+      "peer": true,
       "engines": {
         "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
       },
@@ -3303,6 +3322,7 @@
       "os": [
         "win32"
       ],
+      "peer": true,
       "engines": {
         "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
       },
@@ -3588,7 +3608,6 @@
       "integrity": "sha512-yl43JD/86CIj3Mz5mvvLJqAOfIup7ncxfJ0Btnl0/v5TouVUyeEdcpknfgc+yMevS/48oH9WAkkw93m7otLb/A==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@inquirer/checkbox": "^3.0.1",
         "@inquirer/confirm": "^4.0.1",
@@ -4352,6 +4371,7 @@
       "resolved": "https://registry.npmjs.org/@lexical/utils/-/utils-0.35.0.tgz",
       "integrity": "sha512-2H393EYDnFznYCDFOW3MHiRzwEO5M/UBhtUjvTT+9kc+qhX4U3zc8ixQalo5UmZ5B2nh7L/inXdTFzvSRXtsRA==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@lexical/list": "0.35.0",
         "@lexical/selection": "0.35.0",
@@ -4364,6 +4384,7 @@
       "resolved": "https://registry.npmjs.org/@lexical/clipboard/-/clipboard-0.35.0.tgz",
       "integrity": "sha512-ko7xSIIiayvDiqjNDX6fgH9RlcM6r9vrrvJYTcfGVBor5httx16lhIi0QJZ4+RNPvGtTjyFv4bwRmsixRRwImg==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@lexical/html": "0.35.0",
         "@lexical/list": "0.35.0",
@@ -4377,6 +4398,7 @@
       "resolved": "https://registry.npmjs.org/@lexical/html/-/html-0.35.0.tgz",
       "integrity": "sha512-rXGFE5S5rKsg3tVnr1s4iEgOfCApNXGpIFI3T2jGEShaCZ5HLaBY9NVBXnE9Nb49e9bkDkpZ8FZd1qokCbQXbw==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@lexical/selection": "0.35.0",
         "@lexical/utils": "0.35.0",
@@ -4388,6 +4410,7 @@
       "resolved": "https://registry.npmjs.org/@lexical/list/-/list-0.35.0.tgz",
       "integrity": "sha512-owsmc8iwgExBX8sFe8fKTiwJVhYULt9hD1RZ/HwfaiEtRZZkINijqReOBnW2mJfRxBzhFSWc4NG3ISB+fHYzqw==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@lexical/selection": "0.35.0",
         "@lexical/utils": "0.35.0",
@@ -4399,6 +4422,7 @@
       "resolved": "https://registry.npmjs.org/@lexical/selection/-/selection-0.35.0.tgz",
       "integrity": "sha512-mMtDE7Q0nycXdFTTH/+ta6EBrBwxBB4Tg8QwsGntzQ1Cq//d838dpXpFjJOqHEeVHUqXpiuj+cBG8+bvz/rPRw==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "lexical": "0.35.0"
       }
@@ -4408,6 +4432,7 @@
       "resolved": "https://registry.npmjs.org/@lexical/table/-/table-0.35.0.tgz",
       "integrity": "sha512-9jlTlkVideBKwsEnEkqkdg7A3mije1SvmfiqoYnkl1kKJCLA5iH90ywx327PU0p+bdnURAytWUeZPXaEuEl2OA==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@lexical/clipboard": "0.35.0",
         "@lexical/utils": "0.35.0",
@@ -4418,7 +4443,8 @@
       "version": "0.35.0",
       "resolved": "https://registry.npmjs.org/lexical/-/lexical-0.35.0.tgz",
       "integrity": "sha512-3VuV8xXhh5xJA6tzvfDvE0YBCMkIZUmxtRilJQDDdCgJCc+eut6qAv2qbN+pbqvarqcQqPN1UF+8YvsjmyOZpw==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/@lexical/yjs": {
       "version": "0.33.1",
@@ -4573,7 +4599,6 @@
       "resolved": "https://registry.npmjs.org/@neondatabase/serverless/-/serverless-1.0.1.tgz",
       "integrity": "sha512-O6yC5TT0jbw86VZVkmnzCZJB0hfxBl0JJz6f+3KHoZabjb/X08r9eFA+vuY06z1/qaovykvdkrXYq3SPUuvogA==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@types/node": "^22.15.30",
         "@types/pg": "^8.8.0"
@@ -4586,7 +4611,8 @@
       "version": "15.5.2",
       "resolved": "https://registry.npmjs.org/@next/env/-/env-15.5.2.tgz",
       "integrity": "sha512-Qe06ew4zt12LeO6N7j8/nULSOe3fMXE4dM6xgpBQNvdzyK1sv5y4oAP3bq4LamrvGCZtmRYnW8URFCeX5nFgGg==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/@next/swc-darwin-arm64": {
       "version": "15.5.2",
@@ -4600,6 +4626,7 @@
       "os": [
         "darwin"
       ],
+      "peer": true,
       "engines": {
         "node": ">= 10"
       }
@@ -4616,6 +4643,7 @@
       "os": [
         "darwin"
       ],
+      "peer": true,
       "engines": {
         "node": ">= 10"
       }
@@ -4632,6 +4660,7 @@
       "os": [
         "linux"
       ],
+      "peer": true,
       "engines": {
         "node": ">= 10"
       }
@@ -4648,6 +4677,7 @@
       "os": [
         "linux"
       ],
+      "peer": true,
       "engines": {
         "node": ">= 10"
       }
@@ -4664,6 +4694,7 @@
       "os": [
         "linux"
       ],
+      "peer": true,
       "engines": {
         "node": ">= 10"
       }
@@ -4680,6 +4711,7 @@
       "os": [
         "linux"
       ],
+      "peer": true,
       "engines": {
         "node": ">= 10"
       }
@@ -4696,6 +4728,7 @@
       "os": [
         "win32"
       ],
+      "peer": true,
       "engines": {
         "node": ">= 10"
       }
@@ -4712,6 +4745,7 @@
       "os": [
         "win32"
       ],
+      "peer": true,
       "engines": {
         "node": ">= 10"
       }
@@ -4838,7 +4872,6 @@
       "integrity": "sha512-/g2d4sW9nUDJOMz3mabVQvOGhVa4e/BN/Um7yca9Bb2XTzPPnfTWHWQg+IsEYO7M3Vx+EXvaM/I2pJWIMun1bg==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@octokit/auth-token": "^4.0.0",
         "@octokit/graphql": "^7.1.0",
@@ -5400,7 +5433,6 @@
       "integrity": "sha512-04IXzPwHrW69XusN/SIdDdKZBzMfOT9UNT/YiJit/xpy2VuAoB8NHc8Aplb96zsWDddLnbkPL3TsmrS04ZU2xQ==",
       "devOptional": true,
       "license": "Apache-2.0",
-      "peer": true,
       "dependencies": {
         "playwright": "1.55.0"
       },
@@ -6969,6 +7001,7 @@
       "resolved": "https://registry.npmjs.org/@swc/helpers/-/helpers-0.5.15.tgz",
       "integrity": "sha512-JQ5TuMi45Owi4/BIMAJBoSQoOJu12oOk/gADqlcUL9JEdHB8vyjUSsxqeNXnmXHjYKMi2WcYtezGEEhqUI/E2g==",
       "license": "Apache-2.0",
+      "peer": true,
       "dependencies": {
         "tslib": "^2.8.0"
       }
@@ -7608,7 +7641,6 @@
       "integrity": "sha512-NMv9ASNARoKksWtsq/SHakpYAYnhBrQgGD8zkLYk/jaK8jUGn08CfEdTRgYhMypUQAfzSP8W6gNLe0q19/t4VA==",
       "devOptional": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@types/node": "*"
       }
@@ -7854,7 +7886,6 @@
       "resolved": "https://registry.npmjs.org/@types/react/-/react-19.1.12.tgz",
       "integrity": "sha512-cMoR+FoAf/Jyq6+Df2/Z41jISvGZZ2eTlnsaJRptmZ76Caldwy1odD4xTr/gNV9VLj0AWgg/nmkevIyUfIIq5w==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "csstype": "^3.0.2"
       }
@@ -7865,7 +7896,6 @@
       "integrity": "sha512-qXRuZaOsAdXKFyOhRBg6Lqqc0yay13vN7KrIg4L7N4aaHN68ma9OK3NE1BoDFgFOTfM7zg+3/8+2n8rLUH3OKQ==",
       "devOptional": true,
       "license": "MIT",
-      "peer": true,
       "peerDependencies": {
         "@types/react": "^19.0.0"
       }
@@ -7974,7 +8004,6 @@
       "integrity": "sha512-VlJEV0fOQ7BExOsHYAGrgbEiZoi8D+Bl2+f6V2RrXerRSylnp+ZBHmPvaIa8cz0Ajx7WO7Z5RqfgYg7ED1nRhA==",
       "dev": true,
       "license": "BSD-2-Clause",
-      "peer": true,
       "dependencies": {
         "@typescript-eslint/scope-manager": "5.62.0",
         "@typescript-eslint/types": "5.62.0",
@@ -8410,7 +8439,6 @@
       "integrity": "sha512-hGISOaP18plkzbWEcP/QvtRW1xDXF2+96HbEX6byqQhAUbiS5oH6/9JwW+QsQCIYON2bI6QZBF+2PvOmrRZ9wA==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@vitest/utils": "3.2.4",
         "fflate": "^0.8.2",
@@ -8702,7 +8730,6 @@
       "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
       "devOptional": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -9175,7 +9202,6 @@
       "integrity": "sha512-Ixm8tFfoKKIPYdCCKYTsqv+Fd4IJ0DQqMyEimo+pxUOMUR9cVPlwTrFt9Avu+3cb6Zp3mAzl+t1MrG2fxxKsxw==",
       "devOptional": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@babel/types": "^7.26.0"
       }
@@ -9322,7 +9348,6 @@
       "integrity": "sha512-8VYKM3MjCa9WcaSAI3hzwhmyHVlH8tiGFwf0RlTsZPWJ1I5MkzjiudCo4KC4DxOaL/53A5B1sI/IbldNFDbsKA==",
       "hasInstallScript": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "bindings": "^1.5.0",
         "prebuild-install": "^7.1.1"
@@ -9451,7 +9476,6 @@
         }
       ],
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "baseline-browser-mapping": "^2.9.0",
         "caniuse-lite": "^1.0.30001759",
@@ -10028,7 +10052,8 @@
       "version": "0.0.1",
       "resolved": "https://registry.npmjs.org/client-only/-/client-only-0.0.1.tgz",
       "integrity": "sha512-IV3Ou0jSMzZrd3pZ48nLkT9DA7Ag1pnPzaiQhpW7c3RbcqqzvzzVu+L8gfqMp/8IM2MQtSiqaCxrrcfu8I8rMA==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/cliui": {
       "version": "8.0.1",
@@ -10149,6 +10174,7 @@
       "integrity": "sha512-1rXeuUUiGGrykh+CeBdu5Ie7OJwinCgQY0bc7GCRxy5xVHy+moaqkpL/jqQq0MtQOeYcrqEz4abc5f0KtU7W4A==",
       "license": "MIT",
       "optional": true,
+      "peer": true,
       "dependencies": {
         "color-convert": "^2.0.1",
         "color-string": "^1.9.0"
@@ -10181,6 +10207,7 @@
       "integrity": "sha512-shrVawQFojnZv6xM40anx4CkoDP+fZsw/ZerEMsW/pyzsRbElpsL/DBVW7q3ExxwusdNXI3lXpuhEZkzs8p5Eg==",
       "license": "MIT",
       "optional": true,
+      "peer": true,
       "dependencies": {
         "color-name": "^1.0.0",
         "simple-swizzle": "^0.2.2"
@@ -12430,7 +12457,6 @@
       "deprecated": "This version is no longer supported. Please see https://eslint.org/version-support for other options.",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.2.0",
         "@eslint-community/regexpp": "^4.6.1",
@@ -13803,7 +13829,6 @@
       "integrity": "sha512-Newg9X7mRYskoBjSw70l1YnJ/ZGbq64VPyR821H5WVkTGpHG2O0mQILxCeUhxdYERLFY9B4tUyKLyf3uMTjtKw==",
       "devOptional": true,
       "license": "Apache-2.0",
-      "peer": true,
       "dependencies": {
         "@petamoriken/float16": "^3.8.7",
         "debug": "^4.3.4",
@@ -14296,7 +14321,6 @@
       "integrity": "sha512-UVIHeVhxmxedbWPCfgS55Jg2rDfwf2BCKeylcPSqazLz5w3Kri7Q4xdBJubsr/+VUzFLh0VjIvh13RaDA2/Xug==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "webidl-conversions": "^7.0.0",
         "whatwg-mimetype": "^3.0.0"
@@ -15444,6 +15468,7 @@
       "resolved": "https://registry.npmjs.org/isomorphic.js/-/isomorphic.js-0.2.5.tgz",
       "integrity": "sha512-PIeMbHqMt4DnUP3MA/Flc0HElYjMXArsw1qwJZcm9sqR8mq3l8NYizFMty0pWwE/tzIGH3EKK5+jes5mAr85yw==",
       "license": "MIT",
+      "peer": true,
       "funding": {
         "type": "GitHub Sponsors ❤",
         "url": "https://github.com/sponsors/dmonad"
@@ -15757,8 +15782,7 @@
           "url": "https://github.com/sponsors/lavrton"
         }
       ],
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
     },
     "node_modules/levn": {
       "version": "0.4.1",
@@ -15778,8 +15802,7 @@
       "version": "0.33.1",
       "resolved": "https://registry.npmjs.org/lexical/-/lexical-0.33.1.tgz",
       "integrity": "sha512-+kiCS/GshQmCs/meMb8MQT4AMvw3S3Ef0lSCv2Xi6Itvs59OD+NjQWNfYkDteIbKtVE/w0Yiqh56VyGwIb8UcA==",
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
     },
     "node_modules/lexical-beautiful-mentions": {
       "version": "0.1.48",
@@ -15799,6 +15822,7 @@
       "resolved": "https://registry.npmjs.org/lib0/-/lib0-0.2.114.tgz",
       "integrity": "sha512-gcxmNFzA4hv8UYi8j43uPlQ7CGcyMJ2KQb5kZASw6SnAKAf10hK12i2fjrS3Cl/ugZa5Ui6WwIu1/6MIXiHttQ==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "isomorphic.js": "^0.2.4"
       },
@@ -17997,8 +18021,7 @@
       "version": "0.52.2",
       "resolved": "https://registry.npmjs.org/monaco-editor/-/monaco-editor-0.52.2.tgz",
       "integrity": "sha512-GEQWEZmfkOGLdd3XK8ryrfWz3AIP8YymVXiPHEdewrUq7mh0qrKrfHLNCXcbB6sTnMLnOZ3ztSiKcciFUkIJwQ==",
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
     },
     "node_modules/motion-dom": {
       "version": "12.23.12",
@@ -19173,6 +19196,7 @@
         }
       ],
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "nanoid": "^3.3.6",
         "picocolors": "^1.0.0",
@@ -19622,7 +19646,6 @@
       "resolved": "https://registry.npmjs.org/react/-/react-19.2.1.tgz",
       "integrity": "sha512-DGrYcCWK7tvYMnWh79yrPHt+vdx9tY+1gPZa7nJQtO/p8bLTDaHp4dzwEhQB7pZ4Xe3ok4XKuEPrVuc+wlpkmw==",
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=0.10.0"
       }
@@ -19664,7 +19687,6 @@
       "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.1.tgz",
       "integrity": "sha512-ibrK8llX2a4eOskq1mXKu/TGZj9qzomO+sNfO98M6d9zIPOEhlBkMkBUBLd1vgS0gQsLDBzA+8jJBVXDnfHmJg==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "scheduler": "^0.27.0"
       },
@@ -20452,7 +20474,6 @@
       "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.50.1.tgz",
       "integrity": "sha512-78E9voJHwnXQMiQdiqswVLZwJIzdBKJ1GdI5Zx6XwoFKUIk09/sSrr+05QFzvYb8q6Y9pPV45zzDuYa3907TZA==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@types/estree": "1.0.8"
       },
@@ -20653,7 +20674,6 @@
       "integrity": "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "fast-deep-equal": "^3.1.3",
         "fast-uri": "^3.0.1",
@@ -20794,7 +20814,6 @@
       "resolved": "https://registry.npmjs.org/seroval/-/seroval-1.3.2.tgz",
       "integrity": "sha512-RbcPH1n5cfwKrru7v7+zrZvjLurgHhGyso3HTyGtRivGWgYjbOmGuivCQaORNELjNONoK35nj28EoWul9sb1zQ==",
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=10"
       }
@@ -20907,6 +20926,7 @@
       "hasInstallScript": true,
       "license": "Apache-2.0",
       "optional": true,
+      "peer": true,
       "dependencies": {
         "color": "^4.2.3",
         "detect-libc": "^2.0.4",
@@ -21299,6 +21319,7 @@
       "integrity": "sha512-JA//kQgZtbuY83m+xT+tXJkmJncGMTFT+C+g2h2R9uxkYIrE2yy9sgmcLhCnw57/WSD+Eh3J97FPEDFnbXnDUg==",
       "license": "MIT",
       "optional": true,
+      "peer": true,
       "dependencies": {
         "is-arrayish": "^0.3.1"
       }
@@ -21308,7 +21329,8 @@
       "resolved": "https://registry.npmjs.org/is-arrayish/-/is-arrayish-0.3.2.tgz",
       "integrity": "sha512-eVRqCvVlZbuw3GrM63ovNSNAeA1K16kaR/LRY/92w0zxQ5/1YzwblUX652i4Xs9RwAGjW9d9y6X88t8OaAJfWQ==",
       "license": "MIT",
-      "optional": true
+      "optional": true,
+      "peer": true
     },
     "node_modules/sirv": {
       "version": "3.0.2",
@@ -21993,6 +22015,7 @@
       "resolved": "https://registry.npmjs.org/styled-jsx/-/styled-jsx-5.1.6.tgz",
       "integrity": "sha512-qSVyDTeMotdvQYoHWLNGwRFJHC+i+ZvdBRYosOFgC+Wg1vx4frN2/RG/NA7SYqqvKNLf39P2LSRA2pu6n0XYZA==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "client-only": "0.0.1"
       },
@@ -22070,8 +22093,7 @@
       "version": "4.1.13",
       "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.1.13.tgz",
       "integrity": "sha512-i+zidfmTqtwquj4hMEwdjshYYgMbOrPzb9a0M3ZgNa0JMoZeFC6bxZvO8yr8ozS6ix2SDz0+mvryPeBs2TFE+w==",
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
     },
     "node_modules/tapable": {
       "version": "2.3.0",
@@ -22738,7 +22760,6 @@
       "integrity": "sha512-CWBzXQrc/qOkhidw1OzBTQuYRbfyxDXJMVJ1XNwUHGROVmuaeiEm3OslpZ1RV96d7SKKjZKrSJu3+t/xlw3R9A==",
       "dev": true,
       "license": "Apache-2.0",
-      "peer": true,
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"
@@ -23261,7 +23282,6 @@
       "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.20.tgz",
       "integrity": "sha512-j3lYzGC3P+B5Yfy/pfKNgVEg4+UtcIJcVRt2cDjIOmhLourAqPqf8P7acgxeiSgUB7E3p2P8/3gNIgDLpwzs4g==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "esbuild": "^0.21.3",
         "postcss": "^8.4.43",
@@ -23793,7 +23813,6 @@
       "integrity": "sha512-LUCP5ev3GURDysTWiP47wRRUpLKMOfPh+yKTx3kVIEiu5KOMeqzpnYNsKyOoVrULivR8tLcks4+lga33Whn90A==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@types/chai": "^5.2.2",
         "@vitest/expect": "3.2.4",
@@ -24446,7 +24465,6 @@
       "resolved": "https://registry.npmjs.org/zod/-/zod-4.3.6.tgz",
       "integrity": "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==",
       "license": "MIT",
-      "peer": true,
       "funding": {
         "url": "https://github.com/sponsors/colinhacks"
       }

shared/xmlEscape.ts

@@ -10,8 +10,9 @@
  * Escapes special characters in XML attribute values.
  * Handles: & " < >
  */
-export function escapeXmlAttr(str: string): string {
-  return str
+export function escapeXmlAttr(str: string | null | undefined): string {
+  if (str == null) return "";
+  return String(str)
     .replace(/&/g, "&amp;")
     .replace(/"/g, "&quot;")
     .replace(/</g, "&lt;")
@@ -34,8 +35,12 @@ export function unescapeXmlAttr(str: string): string {
  * Escapes special characters in XML content (text between tags).
  * Handles: & < >
  */
-export function escapeXmlContent(str: string): string {
-  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+export function escapeXmlContent(str: string | null | undefined): string {
+  if (str == null) return "";
+  return String(str)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
 }
 
 /**

src/app/layout.tsx

@@ -16,6 +16,7 @@ import { useSettings } from "@/hooks/useSettings";
 import type { ZoomLevel } from "@/lib/schemas";
 import { selectedComponentsPreviewAtom } from "@/atoms/previewAtoms";
 import { chatInputValueAtom } from "@/atoms/chatAtoms";
+import { usePlanEvents } from "@/hooks/usePlanEvents";
 
 const DEFAULT_ZOOM_LEVEL: ZoomLevel = "100";
 
@@ -32,6 +33,9 @@ export default function RootLayout({ children }: { children: ReactNode }) {
   const selectedAppId = useAtomValue(selectedAppIdAtom);
   const setConsoleEntries = useSetAtom(appConsoleEntriesAtom);
 
+  // Initialize plan events listener
+  usePlanEvents();
+
   useEffect(() => {
     const zoomLevel = settings?.zoomLevel ?? DEFAULT_ZOOM_LEVEL;
     const zoomFactor = Number(zoomLevel) / 100;

src/atoms/appAtoms.ts

@@ -8,7 +8,13 @@ export const selectedAppIdAtom = atom<number | null>(null);
 export const appsListAtom = atom<ListedApp[]>([]);
 export const versionsListAtom = atom<Version[]>([]);
 export const previewModeAtom = atom<
-  "preview" | "code" | "problems" | "configure" | "publish" | "security"
+  | "preview"
+  | "code"
+  | "problems"
+  | "configure"
+  | "publish"
+  | "security"
+  | "plan"
 >("preview");
 export const selectedVersionIdAtom = atom<string | null>(null);
 

src/atoms/chatAtoms.ts

@@ -31,3 +31,6 @@ export const pendingAgentConsentsAtom = atom<PendingAgentConsent[]>([]);
 
 // Agent todos per chat
 export const agentTodosByChatIdAtom = atom<Map<number, AgentTodo[]>>(new Map());
+
+// Flag: set when user switches to plan mode from another mode in a chat with messages
+export const needsFreshPlanChatAtom = atom<boolean>(false);

src/atoms/planAtoms.ts

+import { atom } from "jotai";
+import type { PlanQuestionnairePayload } from "@/ipc/types/plan";
+
+export interface PlanData {
+  content: string;
+  title: string;
+  summary?: string;
+}
+
+export interface PlanState {
+  plansByChatId: Map<number, PlanData>;
+  acceptedChatIds: Set<number>;
+  transitioningChatIds: Set<number>;
+}
+
+export const planStateAtom = atom<PlanState>({
+  plansByChatId: new Map(),
+  acceptedChatIds: new Set<number>(),
+  transitioningChatIds: new Set<number>(),
+});
+
+export interface PendingPlanImplementation {
+  chatId: number;
+  title: string;
+  planSlug: string;
+}
+
+export const pendingPlanImplementationAtom =
+  atom<PendingPlanImplementation | null>(null);
+
+export const pendingQuestionnaireAtom = atom<PlanQuestionnairePayload | null>(
+  null,
+);

src/components/ChatModeSelector.tsx

@@ -85,6 +85,8 @@ export function ChatModeSelector() {
       case "local-agent":
         // Show "Basic Agent" for non-Pro users, "Agent" for Pro users
         return isProEnabled ? "Agent" : "Basic Agent";
+      case "plan":
+        return "Plan";
       default:
         return "Build";
     }
@@ -103,7 +105,9 @@ export function ChatModeSelector() {
               data-testid="chat-mode-selector"
               className={cn(
                 "h-6 w-fit px-1.5 py-0 text-xs-sm font-medium shadow-none gap-0.5",
-                selectedMode === "build" || selectedMode === "local-agent"
+                selectedMode === "build" ||
+                  selectedMode === "local-agent" ||
+                  selectedMode === "plan"
                   ? "bg-background hover:bg-muted/50 focus:bg-muted/50"
                   : "bg-primary/10 hover:bg-primary/20 focus:bg-primary/20 text-primary border-primary/20 dark:bg-primary/20 dark:hover:bg-primary/30 dark:focus:bg-primary/30",
               )}
@@ -119,17 +123,30 @@ export function ChatModeSelector() {
       </Tooltip>
       <SelectContent align="start">
         {isProEnabled && (
-          <SelectItem value="local-agent">
-            <div className="flex flex-col items-start">
-              <div className="flex items-center gap-1.5">
-                <span className="font-medium">Agent v2</span>
-                <NewBadge />
+          <>
+            <SelectItem value="local-agent">
+              <div className="flex flex-col items-start">
+                <div className="flex items-center gap-1.5">
+                  <span className="font-medium">Agent v2</span>
+                  <NewBadge />
+                </div>
+                <span className="text-xs text-muted-foreground">
+                  Better at bigger tasks and debugging
+                </span>
               </div>
-              <span className="text-xs text-muted-foreground">
-                Better at bigger tasks and debugging
-              </span>
-            </div>
-          </SelectItem>
+            </SelectItem>
+            <SelectItem value="plan">
+              <div className="flex flex-col items-start">
+                <div className="flex items-center gap-1.5">
+                  <span className="font-medium">Plan</span>
+                  <NewBadge />
+                </div>
+                <span className="text-xs text-muted-foreground">
+                  Design before you build
+                </span>
+              </div>
+            </SelectItem>
+          </>
         )}
         {!isProEnabled && (
           <SelectItem value="local-agent" disabled={isQuotaExceeded}>

src/components/chat/ChatInput.tsx

@@ -18,7 +18,7 @@ import {
   Lock,
 } from "lucide-react";
 import type React from "react";
-import { useCallback, useEffect, useState, useMemo } from "react";
+import { useCallback, useEffect, useRef, useState, useMemo } from "react";
 
 import { useSettings } from "@/hooks/useSettings";
 import { ipc } from "@/ipc/types";
@@ -28,6 +28,7 @@ import {
   selectedChatIdAtom,
   pendingAgentConsentsAtom,
   agentTodosByChatIdAtom,
+  needsFreshPlanChatAtom,
 } from "@/atoms/chatAtoms";
 import { atom, useAtom, useSetAtom, useAtomValue } from "jotai";
 import { useStreamChat } from "@/hooks/useStreamChat";
@@ -53,12 +54,13 @@ import { useVersions } from "@/hooks/useVersions";
 import { useAttachments } from "@/hooks/useAttachments";
 import { AttachmentsList } from "./AttachmentsList";
 import { DragDropOverlay } from "./DragDropOverlay";
-import { showExtraFilesToast } from "@/lib/toast";
+import { showExtraFilesToast, showInfo } from "@/lib/toast";
 import { useSummarizeInNewChat } from "./SummarizeInNewChatButton";
 import { ChatInputControls } from "../ChatInputControls";
 import { ChatErrorBox } from "./ChatErrorBox";
 import { AgentConsentBanner } from "./AgentConsentBanner";
 import { TodoList } from "./TodoList";
+import { QuestionnaireInput } from "./QuestionnaireInput";
 import {
   selectedComponentsPreviewAtom,
   previewIframeRefAtom,
@@ -182,6 +184,24 @@ export function ChatInput({ chatId }: { chatId?: number }) {
   }, [chatId, messagesById]);
 
   const { userBudget } = useUserBudgetInfo();
+  const [needsFreshPlanChat, setNeedsFreshPlanChat] = useAtom(
+    needsFreshPlanChatAtom,
+  );
+
+  // Detect transition to plan mode from another mode in a chat with messages
+  const prevModeRef = useRef(settings?.selectedChatMode);
+  useEffect(() => {
+    const prevMode = prevModeRef.current;
+    const currentMode = settings?.selectedChatMode;
+    prevModeRef.current = currentMode;
+
+    if (prevMode && prevMode !== "plan" && currentMode === "plan") {
+      const messages = chatId ? (messagesById.get(chatId) ?? []) : [];
+      if (messages.length > 0) {
+        setNeedsFreshPlanChat(true);
+      }
+    }
+  }, [settings?.selectedChatMode, chatId, messagesById, setNeedsFreshPlanChat]);
 
   // Token counting for context limit banner
   const { result: tokenCountResult } = useCountTokens(
@@ -224,6 +244,30 @@ export function ChatInput({ chatId }: { chatId?: number }) {
       return;
     }
 
+    // If switching to plan mode from another mode in a chat with messages,
+    // create a new chat for a clean context.
+    if (needsFreshPlanChat && settings?.selectedChatMode === "plan" && appId) {
+      const currentInput = inputValue;
+      setInputValue("");
+      setNeedsFreshPlanChat(false);
+
+      const newChatId = await ipc.chat.createChat(appId);
+      setSelectedChatId(newChatId);
+      navigate({ to: "/chat", search: { id: newChatId } });
+      queryClient.invalidateQueries({ queryKey: queryKeys.chats.all });
+      showInfo("We've switched you to a new chat for a clean context");
+
+      await streamMessage({
+        prompt: currentInput,
+        chatId: newChatId,
+        attachments,
+        redo: false,
+      });
+      clearAttachments();
+      posthog.capture("chat:submit", { chatMode: settings?.selectedChatMode });
+      return;
+    }
+
     const currentInput = inputValue;
     setInputValue("");
 
@@ -389,6 +433,9 @@ export function ChatInput({ chatId }: { chatId?: number }) {
           onDragLeave={handleDragLeave}
           onDrop={handleDrop}
         >
+          {/* Show active questionnaire if exists */}
+          <QuestionnaireInput />
+
           {/* Show todo list if there are todos for this chat */}
           {chatTodos.length > 0 && <TodoList todos={chatTodos} />}
           {/* Show agent consent banner if there's a pending consent request */}

src/components/chat/DyadExitPlan.tsx

+import React, { useState, useEffect } from "react";
+import { useAtomValue } from "jotai";
+import { CheckCircle, ArrowRight } from "lucide-react";
+import { planStateAtom } from "@/atoms/planAtoms";
+import { selectedChatIdAtom } from "@/atoms/chatAtoms";
+
+interface DyadExitPlanProps {
+  node: {
+    properties: {
+      notes?: string;
+    };
+  };
+}
+
+export const DyadExitPlan: React.FC<DyadExitPlanProps> = ({ node }) => {
+  const { notes } = node.properties;
+  const chatId = useAtomValue(selectedChatIdAtom);
+  const planState = useAtomValue(planStateAtom);
+  const isTransitioning = chatId
+    ? planState.transitioningChatIds.has(chatId)
+    : false;
+
+  const [dotCount, setDotCount] = useState(0);
+  useEffect(() => {
+    if (!isTransitioning) return;
+    const interval = setInterval(() => {
+      setDotCount((prev) => (prev + 1) % 4);
+    }, 400);
+    return () => clearInterval(interval);
+  }, [isTransitioning]);
+
+  return (
+    <div className="my-4 flex items-center gap-3 p-4 bg-green-50 dark:bg-green-900/20 border border-green-200 dark:border-green-800 rounded-lg">
+      <CheckCircle className="text-green-500 flex-shrink-0" size={24} />
+      <div className="flex-1">
+        <div className="flex items-center gap-2">
+          <span className="font-semibold text-green-800 dark:text-green-200">
+            Plan Accepted
+          </span>
+          <ArrowRight className="text-green-500" size={16} />
+          <span className="text-green-700 dark:text-green-300">
+            {isTransitioning
+              ? `Preparing a new chat${".".repeat(dotCount + 1)}`
+              : "Opening new chat for implementation"}
+          </span>
+        </div>
+        {notes && (
+          <p className="text-sm text-green-600 dark:text-green-400 mt-1">
+            {notes}
+          </p>
+        )}
+      </div>
+    </div>
+  );
+};

src/components/chat/DyadMarkdownParser.tsx

@@ -34,6 +34,8 @@ import { DyadDatabaseSchema } from "./DyadDatabaseSchema";
 import { DyadSupabaseTableSchema } from "./DyadSupabaseTableSchema";
 import { DyadSupabaseProjectInfo } from "./DyadSupabaseProjectInfo";
 import { DyadStatus } from "./DyadStatus";
+import { DyadWritePlan } from "./DyadWritePlan";
+import { DyadExitPlan } from "./DyadExitPlan";
 import { mapActionToButton } from "./ChatInput";
 import { SuggestedAction } from "@/lib/schemas";
 import { FixAllErrorsButton } from "./FixAllErrorsButton";
@@ -69,6 +71,9 @@ const DYAD_CUSTOM_TAGS = [
   "dyad-supabase-table-schema",
   "dyad-supabase-project-info",
   "dyad-status",
+  // Plan mode tags
+  "dyad-write-plan",
+  "dyad-exit-plan",
 ];
 
 interface DyadMarkdownParserProps {
@@ -709,6 +714,33 @@ function renderCustomTag(
         </DyadStatus>
       );
 
+    case "dyad-write-plan":
+      return (
+        <DyadWritePlan
+          node={{
+            properties: {
+              title: attributes.title || "Implementation Plan",
+              summary: attributes.summary,
+              complete: attributes.complete,
+              state: getState({ isStreaming, inProgress }),
+            },
+          }}
+        >
+          {content}
+        </DyadWritePlan>
+      );
+
+    case "dyad-exit-plan":
+      return (
+        <DyadExitPlan
+          node={{
+            properties: {
+              notes: attributes.notes,
+            },
+          }}
+        />
+      );
+
     default:
       return null;
   }

src/components/chat/DyadWritePlan.tsx

+import React, { useState } from "react";
+import { FileText, Eye, ChevronDown, ChevronUp, Loader2 } from "lucide-react";
+import { useSetAtom } from "jotai";
+import { previewModeAtom } from "@/atoms/appAtoms";
+import { CustomTagState } from "./stateTypes";
+import { usePlan } from "@/hooks/usePlan";
+
+interface DyadWritePlanProps {
+  node: {
+    properties: {
+      title: string;
+      summary?: string;
+      complete?: string;
+      state?: CustomTagState;
+    };
+  };
+  children?: React.ReactNode;
+}
+
+export const DyadWritePlan: React.FC<DyadWritePlanProps> = ({ node }) => {
+  const { title, summary, complete, state } = node.properties;
+  const [showSummary, setShowSummary] = useState(false);
+  const setPreviewMode = useSetAtom(previewModeAtom);
+
+  // Consider in progress if state is pending OR complete is explicitly "false"
+  const isInProgress = state === "pending" || complete === "false";
+
+  const { savedPlan, hasPlanInMemory } = usePlan({ enabled: !isInProgress });
+
+  const hasPlan = hasPlanInMemory || !!savedPlan;
+
+  return (
+    <div
+      className={`my-4 border rounded-lg overflow-hidden ${
+        isInProgress ? "border-primary/60" : "border-primary/20"
+      } bg-primary/5`}
+    >
+      <div className="px-4 py-3 flex items-center justify-between">
+        <div className="flex items-center gap-2">
+          <FileText
+            className={`text-primary ${isInProgress ? "animate-pulse" : ""}`}
+            size={20}
+          />
+          <div className="flex items-center gap-2">
+            <span className="font-semibold text-foreground">{title}</span>
+            {summary && (
+              <button
+                type="button"
+                onClick={() => setShowSummary(!showSummary)}
+                className="text-primary hover:text-primary/80 transition-colors"
+                aria-label={showSummary ? "Hide summary" : "Show summary"}
+              >
+                {showSummary ? (
+                  <ChevronUp size={16} />
+                ) : (
+                  <ChevronDown size={16} />
+                )}
+              </button>
+            )}
+          </div>
+        </div>
+        <div className="flex items-center">
+          {!isInProgress && hasPlan && (
+            <button
+              type="button"
+              onClick={() => setPreviewMode("plan")}
+              className="flex items-center gap-1.5 text-xs font-medium text-primary-foreground px-4 py-1.5 bg-primary rounded-md hover:bg-primary/90 transition-colors"
+            >
+              <Eye size={14} />
+              View Plan
+            </button>
+          )}
+          {isInProgress && (
+            <span className="flex items-center gap-1.5 text-xs text-primary px-3 py-1 bg-primary/20 rounded-md font-medium">
+              <Loader2 size={12} className="animate-spin" />
+              Generating plan...
+            </span>
+          )}
+        </div>
+      </div>
+      {isInProgress && (
+        <div className="px-4 pb-3">
+          <div
+            className="h-1.5 w-full rounded-full overflow-hidden"
+            style={{
+              background:
+                "linear-gradient(90deg, transparent 0%, hsl(var(--primary) / 0.3) 50%, transparent 100%)",
+              backgroundSize: "200% 100%",
+              animation: "shimmer 1.5s ease-in-out infinite",
+            }}
+          />
+        </div>
+      )}
+      {summary && showSummary && (
+        <div className="px-4 pb-3 pt-0">
+          <p className="text-sm text-muted-foreground pl-7">{summary}</p>
+        </div>
+      )}
+    </div>
+  );
+};

src/components/chat/QuestionnaireInput.tsx

+import React, { useState, useEffect } from "react";
+import { useAtom, useAtomValue } from "jotai";
+import { pendingQuestionnaireAtom } from "@/atoms/planAtoms";
+import { useStreamChat } from "@/hooks/useStreamChat";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";
+import { Checkbox } from "@/components/ui/checkbox";
+import {
+  Send,
+  ArrowLeft,
+  ArrowRight,
+  ClipboardList,
+  ChevronDown,
+  ChevronUp,
+  Circle,
+} from "lucide-react";
+import { selectedChatIdAtom } from "@/atoms/chatAtoms";
+
+const MAX_DISPLAYED_OPTIONS = 3;
+
+export function QuestionnaireInput() {
+  const [questionnaire, setQuestionnaire] = useAtom(pendingQuestionnaireAtom);
+  const chatId = useAtomValue(selectedChatIdAtom);
+  const { streamMessage, isStreaming } = useStreamChat();
+
+  // Track current question index
+  const [currentIndex, setCurrentIndex] = useState(0);
+  // Store all responses
+  const [responses, setResponses] = useState<Record<string, string | string[]>>(
+    {},
+  );
+  // Store additional free-form text for each question
+  const [additionalTexts, setAdditionalTexts] = useState<
+    Record<string, string>
+  >({});
+  // Expand/collapse state
+  const [isExpanded, setIsExpanded] = useState(true);
+
+  // Reset state when questionnaire changes
+  useEffect(() => {
+    setCurrentIndex(0);
+    setResponses(() => {
+      // Auto-select the first option for radio questions
+      const initial: Record<string, string | string[]> = {};
+      if (questionnaire) {
+        for (const q of questionnaire.questions) {
+          if (q.type === "radio" && q.options && q.options.length > 0) {
+            initial[q.id] = q.options[0];
+          }
+        }
+      }
+      return initial;
+    });
+    setAdditionalTexts({});
+    setIsExpanded(true);
+  }, [
+    questionnaire?.chatId,
+    questionnaire?.title,
+    questionnaire?.questions?.length,
+  ]);
+
+  if (!questionnaire || questionnaire.chatId !== chatId) return null;
+
+  const currentQuestion = questionnaire.questions[currentIndex];
+
+  // Guard against empty questions array or out-of-bounds index
+  if (!currentQuestion) {
+    return null;
+  }
+
+  // Calculate if we're on the last question
+  const isLastQuestion = currentIndex === questionnaire.questions.length - 1;
+
+  // Sentinel value for the custom free-form radio option
+  const CUSTOM_OPTION = "__custom__";
+
+  // Get the final response value (combining selected option with additional text)
+  const getFinalResponse = (questionId: string): string => {
+    const response = responses[questionId];
+    const additionalText = additionalTexts[questionId];
+
+    // For radio/select: if custom option selected, use the typed text
+    if (response === CUSTOM_OPTION) {
+      return additionalText || "(no answer)";
+    }
+
+    let formattedResponse: string;
+    if (Array.isArray(response)) {
+      formattedResponse = response.join(", ");
+    } else {
+      formattedResponse = response || "";
+    }
+
+    // For checkbox: append additional text if present
+    if (additionalText) {
+      if (formattedResponse) {
+        return `${formattedResponse}, ${additionalText}`;
+      }
+      return additionalText;
+    }
+
+    return formattedResponse || "(no answer)";
+  };
+
+  // Check if the current question has a valid answer
+  const hasValidAnswer = (): boolean => {
+    const currentResponse = responses[currentQuestion.id];
+    const additionalText = additionalTexts[currentQuestion.id];
+
+    // Custom option requires typed text
+    if (currentResponse === CUSTOM_OPTION) {
+      return !!additionalText;
+    }
+
+    const hasResponse = Array.isArray(currentResponse)
+      ? currentResponse.length > 0
+      : !!currentResponse;
+    const hasAdditionalText = !!additionalText;
+
+    return hasResponse || hasAdditionalText;
+  };
+
+  const handleNext = () => {
+    if (currentQuestion.required !== false && !hasValidAnswer()) {
+      return;
+    }
+
+    if (isLastQuestion) {
+      handleSubmit();
+    } else {
+      setCurrentIndex((prev) => prev + 1);
+    }
+  };
+
+  const handleSubmit = () => {
+    if (!chatId) return;
+
+    const formattedResponses = questionnaire.questions
+      .map((q) => {
+        const answer = getFinalResponse(q.id);
+        return `**${q.question}**\n${answer}`;
+      })
+      .join("\n\n");
+
+    streamMessage({
+      chatId,
+      prompt: `Here are my responses to the questionnaire:\n\n${formattedResponses}`,
+    });
+
+    // Clear questionnaire after submission
+    setQuestionnaire(null);
+  };
+
+  // Helper to determine if Next button should be disabled
+  const isNextDisabled = () => {
+    if (isStreaming && isLastQuestion) return true;
+    if (currentQuestion.required === false) return false;
+    return !hasValidAnswer();
+  };
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === "Enter" && !e.shiftKey) {
+      e.preventDefault();
+      if (!isNextDisabled()) {
+        handleNext();
+      }
+    }
+  };
+
+  return (
+    <div className="border-b border-border bg-muted/30">
+      <button
+        type="button"
+        onClick={() => setIsExpanded(!isExpanded)}
+        className="w-full flex items-center justify-between px-3 py-2 hover:bg-muted/50 transition-colors"
+      >
+        <div className="flex items-center gap-2.5 min-w-0 flex-1">
+          {isExpanded ? (
+            <>
+              <ClipboardList className="w-4 h-4 text-muted-foreground flex-shrink-0" />
+              <span className="text-sm">{questionnaire.title}</span>
+            </>
+          ) : (
+            <>
+              <Circle className="w-4 h-4 text-blue-500 flex-shrink-0" />
+              <span className="text-sm truncate">
+                {currentQuestion.question}
+              </span>
+              <span className="text-xs text-muted-foreground tabular-nums flex-shrink-0">
+                ({currentIndex + 1}/{questionnaire.questions.length})
+              </span>
+            </>
+          )}
+        </div>
+        <div className="flex items-center gap-2 flex-shrink-0 ml-3">
+          <span className="text-xs text-muted-foreground tabular-nums">
+            {currentIndex + 1} of {questionnaire.questions.length}
+          </span>
+          {isExpanded ? (
+            <ChevronUp className="w-4 h-4 text-muted-foreground" />
+          ) : (
+            <ChevronDown className="w-4 h-4 text-muted-foreground" />
+          )}
+        </div>
+      </button>
+
+      {isExpanded && (
+        <div className="px-3 pb-3">
+          {/* Current question input */}
+          <div className="space-y-3">
+            <div className="space-y-2">
+              <Label className="text-sm font-medium text-foreground">
+                {currentQuestion.question}
+                {currentQuestion.required !== false && (
+                  <span className="text-red-500 ml-1">*</span>
+                )}
+              </Label>
+              {currentQuestion.placeholder && (
+                <p className="text-xs text-muted-foreground">
+                  {currentQuestion.placeholder}
+                </p>
+              )}
+
+              <div className="mt-2">
+                {currentQuestion.type === "text" && (
+                  <Input
+                    autoFocus
+                    placeholder="Type your answer..."
+                    value={(responses[currentQuestion.id] as string) || ""}
+                    onChange={(e) =>
+                      setResponses((prev) => ({
+                        ...prev,
+                        [currentQuestion.id]: e.target.value,
+                      }))
+                    }
+                    onKeyDown={handleKeyDown}
+                  />
+                )}
+
+                {currentQuestion.type === "radio" &&
+                  currentQuestion.options && (
+                    <RadioGroup
+                      value={(responses[currentQuestion.id] as string) || ""}
+                      onValueChange={(value: string) => {
+                        setResponses((prev) => ({
+                          ...prev,
+                          [currentQuestion.id]: value,
+                        }));
+                        // Clear custom text when selecting a predefined option
+                        if (value !== CUSTOM_OPTION) {
+                          setAdditionalTexts((prev) => ({
+                            ...prev,
+                            [currentQuestion.id]: "",
+                          }));
+                        }
+                      }}
+                      className="space-y-0.5"
+                    >
+                      {currentQuestion.options
+                        .slice(0, MAX_DISPLAYED_OPTIONS)
+                        .map((option) => (
+                          <div
+                            key={option}
+                            className="flex items-center space-x-2 py-1 px-2 rounded hover:bg-muted/50 transition-colors"
+                          >
+                            <RadioGroupItem
+                              value={option}
+                              id={`${currentQuestion.id}-${option}`}
+                            />
+                            <Label
+                              htmlFor={`${currentQuestion.id}-${option}`}
+                              className="text-sm font-normal cursor-pointer flex-1"
+                            >
+                              {option}
+                            </Label>
+                          </div>
+                        ))}
+                      {/* Custom free-form option integrated as a radio item */}
+                      <div className="flex items-center space-x-2 py-1 px-2 rounded hover:bg-muted/50 transition-colors">
+                        <RadioGroupItem
+                          value={CUSTOM_OPTION}
+                          id={`${currentQuestion.id}-custom`}
+                        />
+                        <Input
+                          placeholder="Other..."
+                          className="flex-1 h-7 text-sm"
+                          value={additionalTexts[currentQuestion.id] || ""}
+                          onFocus={() => {
+                            // Auto-select the custom radio when input is focused
+                            setResponses((prev) => ({
+                              ...prev,
+                              [currentQuestion.id]: CUSTOM_OPTION,
+                            }));
+                          }}
+                          onChange={(e) => {
+                            setAdditionalTexts((prev) => ({
+                              ...prev,
+                              [currentQuestion.id]: e.target.value,
+                            }));
+                            // Auto-select the custom radio when typing
+                            setResponses((prev) => ({
+                              ...prev,
+                              [currentQuestion.id]: CUSTOM_OPTION,
+                            }));
+                          }}
+                          onKeyDown={handleKeyDown}
+                        />
+                      </div>
+                    </RadioGroup>
+                  )}
+
+                {currentQuestion.type === "checkbox" &&
+                  currentQuestion.options && (
+                    <div className="space-y-0.5">
+                      {currentQuestion.options
+                        .slice(0, MAX_DISPLAYED_OPTIONS)
+                        .map((option) => (
+                          <div
+                            key={option}
+                            className="flex items-center space-x-2 py-1 px-2 rounded hover:bg-muted/50 transition-colors"
+                          >
+                            <Checkbox
+                              id={`${currentQuestion.id}-${option}`}
+                              checked={(
+                                (responses[currentQuestion.id] as
+                                  | string[]
+                                  | undefined) || []
+                              ).includes(option)}
+                              onCheckedChange={(checked) => {
+                                setResponses((prev) => {
+                                  const current =
+                                    (prev[currentQuestion.id] as
+                                      | string[]
+                                      | undefined) || [];
+                                  if (checked) {
+                                    return {
+                                      ...prev,
+                                      [currentQuestion.id]: [
+                                        ...current,
+                                        option,
+                                      ],
+                                    };
+                                  }
+                                  return {
+                                    ...prev,
+                                    [currentQuestion.id]: current.filter(
+                                      (o) => o !== option,
+                                    ),
+                                  };
+                                });
+                              }}
+                            />
+                            <Label
+                              htmlFor={`${currentQuestion.id}-${option}`}
+                              className="text-sm font-normal cursor-pointer flex-1"
+                            >
+                              {option}
+                            </Label>
+                          </div>
+                        ))}
+                      {/* Free-form text input as an inline row (no checkbox) */}
+                      <div className="flex items-center py-1 px-2 rounded hover:bg-muted/50 transition-colors">
+                        <Input
+                          placeholder="Other..."
+                          className="flex-1 h-7 text-sm"
+                          value={additionalTexts[currentQuestion.id] || ""}
+                          onChange={(e) =>
+                            setAdditionalTexts((prev) => ({
+                              ...prev,
+                              [currentQuestion.id]: e.target.value,
+                            }))
+                          }
+                          onKeyDown={handleKeyDown}
+                        />
+                      </div>
+                    </div>
+                  )}
+              </div>
+            </div>
+
+            <div className="flex justify-between">
+              <Button
+                onClick={() => setCurrentIndex((prev) => prev - 1)}
+                disabled={currentIndex === 0}
+                variant="ghost"
+                size="sm"
+              >
+                <ArrowLeft size={14} className="mr-1.5" />
+                Back
+              </Button>
+              <Button
+                onClick={handleNext}
+                disabled={isNextDisabled()}
+                size="sm"
+              >
+                {isLastQuestion ? (
+                  <>
+                    <Send size={14} className="mr-1.5" />
+                    Submit
+                  </>
+                ) : (
+                  <>
+                    Next
+                    <ArrowRight size={14} className="ml-1.5" />
+                  </>
+                )}
+              </Button>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

src/components/preview_panel/PlanPanel.tsx

+import React, { useEffect, useState } from "react";
+import { useAtomValue, useSetAtom } from "jotai";
+import { Button } from "@/components/ui/button";
+import { Check, FileText } from "lucide-react";
+import { VanillaMarkdownParser } from "@/components/chat/DyadMarkdownParser";
+import { planStateAtom } from "@/atoms/planAtoms";
+import { previewModeAtom } from "@/atoms/appAtoms";
+import { selectedChatIdAtom } from "@/atoms/chatAtoms";
+import { useStreamChat } from "@/hooks/useStreamChat";
+import { usePlan } from "@/hooks/usePlan";
+import { useSettings } from "@/hooks/useSettings";
+
+export const PlanPanel: React.FC = () => {
+  const chatId = useAtomValue(selectedChatIdAtom);
+  const planState = useAtomValue(planStateAtom);
+  const previewMode = useAtomValue(previewModeAtom);
+  const setPreviewMode = useSetAtom(previewModeAtom);
+  const { streamMessage, isStreaming } = useStreamChat();
+  const { savedPlan } = usePlan();
+  const { settings } = useSettings();
+
+  const planData = chatId ? planState.plansByChatId.get(chatId) : null;
+  const currentPlan = planData?.content ?? null;
+  const currentTitle = planData?.title ?? null;
+  const currentSummary = planData?.summary ?? null;
+  const isAccepted = chatId ? planState.acceptedChatIds.has(chatId) : false;
+  // Plan was already saved if we found it in the filesystem
+  const isSavedPlan = !!savedPlan;
+
+  // If there's no plan content, switch back to preview mode
+  useEffect(() => {
+    if (!currentPlan && previewMode === "plan") {
+      setPreviewMode("preview");
+    }
+  }, [currentPlan, previewMode, setPreviewMode]);
+
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  const handleAccept = () => {
+    if (!chatId) return;
+    if (settings?.selectedChatMode !== "plan") return;
+    if (isSubmitting) return;
+    setIsSubmitting(true);
+
+    streamMessage({
+      chatId,
+      prompt:
+        "I accept this plan. Call the exit_plan tool now with confirmation: true to begin implementation.",
+    });
+  };
+
+  // Don't render anything if there's no plan - effect will switch to preview mode
+  if (!currentPlan) {
+    return null;
+  }
+
+  return (
+    <div className="h-full flex flex-col">
+      <div className="flex-1 overflow-y-auto p-4">
+        <div className="border rounded-lg bg-card">
+          <div className="px-4 py-3 border-b">
+            <div className="flex items-center gap-2">
+              <FileText className="text-blue-500" size={20} />
+              <h2 className="text-lg font-semibold">
+                {currentTitle || "Implementation Plan"}
+              </h2>
+            </div>
+            {currentSummary && (
+              <p className="text-sm text-muted-foreground mt-1">
+                {currentSummary}
+              </p>
+            )}
+          </div>
+          <div className="p-4">
+            <div className="prose dark:prose-invert prose-sm max-w-none">
+              <VanillaMarkdownParser content={currentPlan} />
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <div className="border-t p-4 space-y-4 bg-background">
+        {isAccepted || isSavedPlan ? (
+          <div className="flex items-center gap-2 text-green-700 dark:text-green-300">
+            <Check size={16} />
+            <span className="text-sm font-medium">
+              Plan accepted — implementation started in a new chat
+            </span>
+          </div>
+        ) : (
+          <div className="flex gap-2">
+            <Button
+              onClick={handleAccept}
+              disabled={isStreaming || isSubmitting}
+              className="flex-1"
+            >
+              <Check size={16} className="mr-2" />
+              Accept Plan
+            </Button>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+};

src/components/preview_panel/PreviewPanel.tsx

@@ -17,6 +17,7 @@ import { Console } from "./Console";
 import { useRunApp } from "@/hooks/useRunApp";
 import { PublishPanel } from "./PublishPanel";
 import { SecurityPanel } from "./SecurityPanel";
+import { PlanPanel } from "./PlanPanel";
 import { useSupabase } from "@/hooks/useSupabase";
 
 interface ConsoleHeaderProps {
@@ -147,6 +148,8 @@ export function PreviewPanel() {
                 <PublishPanel />
               ) : previewMode === "security" ? (
                 <SecurityPanel />
+              ) : previewMode === "plan" ? (
+                <PlanPanel />
               ) : (
                 <Problems />
               )}

src/components/ui/radio-group.tsx

+"use client";
+
+import * as React from "react";
+import { RadioGroup as BaseRadioGroup } from "@base-ui/react/radio-group";
+import { Radio } from "@base-ui/react/radio";
+import { Circle } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+
+const RadioGroup = React.forwardRef<
+  HTMLDivElement,
+  React.ComponentPropsWithoutRef<typeof BaseRadioGroup> & {
+    onValueChange?: (value: string) => void;
+  }
+>(({ className, onValueChange, ...props }, ref) => {
+  return (
+    <BaseRadioGroup
+      className={cn("grid gap-2", className)}
+      onValueChange={(value) => onValueChange?.(value as string)}
+      {...props}
+      ref={ref}
+    />
+  );
+});
+RadioGroup.displayName = "RadioGroup";
+
+const RadioGroupItem = React.forwardRef<
+  HTMLButtonElement,
+  React.ComponentPropsWithoutRef<typeof Radio.Root>
+>(({ className, ...props }, ref) => {
+  return (
+    <Radio.Root
+      ref={ref}
+      className={cn(
+        "aspect-square h-4 w-4 rounded-full border border-primary text-primary ring-offset-background focus:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 flex items-center justify-center",
+        className,
+      )}
+      {...props}
+    >
+      <Radio.Indicator className="flex items-center justify-center">
+        <Circle className="h-2.5 w-2.5 fill-current text-current" />
+      </Radio.Indicator>
+    </Radio.Root>
+  );
+});
+RadioGroupItem.displayName = "RadioGroupItem";
+
+export { RadioGroup, RadioGroupItem };

src/hooks/usePlan.ts

+import { useEffect } from "react";
+import { useSetAtom, useAtomValue } from "jotai";
+import { useQuery } from "@tanstack/react-query";
+import { selectedAppIdAtom } from "@/atoms/appAtoms";
+import { planStateAtom } from "@/atoms/planAtoms";
+import { selectedChatIdAtom } from "@/atoms/chatAtoms";
+import { planClient } from "@/ipc/types/plan";
+import { queryKeys } from "@/lib/queryKeys";
+
+/**
+ * Loads a saved plan from disk and syncs it into memory state for the current chat.
+ *
+ * @param options.enabled - Extra condition to suppress the query (e.g. while plan is streaming). Defaults to true.
+ */
+export function usePlan({ enabled = true }: { enabled?: boolean } = {}) {
+  const chatId = useAtomValue(selectedChatIdAtom);
+  const appId = useAtomValue(selectedAppIdAtom);
+  const planState = useAtomValue(planStateAtom);
+  const setPlanState = useSetAtom(planStateAtom);
+
+  const hasPlanInMemory = chatId ? planState.plansByChatId.has(chatId) : false;
+
+  const { data: savedPlan, isLoading } = useQuery({
+    queryKey: queryKeys.plans.forChat({
+      appId: appId ?? null,
+      chatId: chatId ?? null,
+    }),
+    queryFn: async () => {
+      if (!appId || !chatId) return null;
+      return planClient.getPlanForChat({ appId, chatId });
+    },
+    enabled: !!appId && !!chatId && !hasPlanInMemory && enabled,
+    staleTime: 1000 * 60 * 5, // 5 minutes
+  });
+
+  // Sync saved plan into memory state
+  useEffect(() => {
+    if (savedPlan && chatId && !hasPlanInMemory) {
+      setPlanState((prev) => {
+        const nextPlans = new Map(prev.plansByChatId);
+        nextPlans.set(chatId, {
+          content: savedPlan.content,
+          title: savedPlan.title,
+          summary: savedPlan.summary ?? undefined,
+        });
+        return {
+          ...prev,
+          plansByChatId: nextPlans,
+        };
+      });
+    }
+  }, [savedPlan, chatId, hasPlanInMemory, setPlanState]);
+
+  return {
+    savedPlan,
+    hasPlanInMemory,
+    isLoading,
+  };
+}

src/hooks/usePlanEvents.ts

+import { useEffect, useRef } from "react";
+import { useAtomValue, useSetAtom } from "jotai";
+import { useNavigate } from "@tanstack/react-router";
+import { useQueryClient } from "@tanstack/react-query";
+import { useSettings } from "./useSettings";
+import { queryKeys } from "@/lib/queryKeys";
+import {
+  planStateAtom,
+  pendingPlanImplementationAtom,
+  pendingQuestionnaireAtom,
+} from "@/atoms/planAtoms";
+import { previewModeAtom, selectedAppIdAtom } from "@/atoms/appAtoms";
+import { selectedChatIdAtom } from "@/atoms/chatAtoms";
+import {
+  planEventClient,
+  planClient,
+  type PlanUpdatePayload,
+  type PlanExitPayload,
+  type PlanQuestionnairePayload,
+} from "@/ipc/types/plan";
+import { ipc } from "@/ipc/types";
+import { showError } from "@/lib/toast";
+
+/**
+ * Hook to handle plan mode IPC events.
+ * Should be called at the app root level to listen for plan events.
+ */
+export function usePlanEvents() {
+  const setPlanState = useSetAtom(planStateAtom);
+  const planState = useAtomValue(planStateAtom);
+  const setPreviewMode = useSetAtom(previewModeAtom);
+  const selectedAppId = useAtomValue(selectedAppIdAtom);
+  const setPendingPlanImplementation = useSetAtom(
+    pendingPlanImplementationAtom,
+  );
+  const setPendingQuestionnaire = useSetAtom(pendingQuestionnaireAtom);
+  const setSelectedChatId = useSetAtom(selectedChatIdAtom);
+  const navigate = useNavigate();
+  const queryClient = useQueryClient();
+  const { settings, updateSettings } = useSettings();
+
+  // Use refs for values accessed in event handlers to avoid stale closures
+  const planStateRef = useRef(planState);
+  const selectedAppIdRef = useRef(selectedAppId);
+  const settingsRef = useRef(settings);
+
+  // Keep refs up to date
+  planStateRef.current = planState;
+  selectedAppIdRef.current = selectedAppId;
+  settingsRef.current = settings;
+
+  useEffect(() => {
+    // Handle plan updates
+    const unsubscribeUpdate = planEventClient.onUpdate(
+      (payload: PlanUpdatePayload) => {
+        // Update plan state
+        setPlanState((prev) => {
+          const nextPlans = new Map(prev.plansByChatId);
+          nextPlans.set(payload.chatId, {
+            content: payload.plan,
+            title: payload.title,
+            summary: payload.summary,
+          });
+          return {
+            ...prev,
+            plansByChatId: nextPlans,
+          };
+        });
+
+        // Switch to plan preview mode
+        setPreviewMode("plan");
+      },
+    );
+
+    // Handle plan exit (transition to implementation)
+    const unsubscribeExit = planEventClient.onExit(
+      async (payload: PlanExitPayload) => {
+        // Mark this chat's plan as accepted
+        setPlanState((prev) => {
+          const nextAccepted = new Set(prev.acceptedChatIds);
+          nextAccepted.add(payload.chatId);
+          return {
+            ...prev,
+            acceptedChatIds: nextAccepted,
+          };
+        });
+
+        // Immediately cancel the current stream so we can start the plan implementation
+        try {
+          await ipc.chat.cancelStream(payload.chatId);
+        } catch (error) {
+          console.error("Failed to cancel stream:", error);
+        }
+
+        // Show transitioning state while we prepare the implementation
+        setPlanState((prev) => {
+          const nextTransitioning = new Set(prev.transitioningChatIds);
+          nextTransitioning.add(payload.chatId);
+          return { ...prev, transitioningChatIds: nextTransitioning };
+        });
+
+        // Pause so the user can see the "Plan accepted" confirmation
+        await new Promise((resolve) => setTimeout(resolve, 2500));
+
+        // Clear transitioning state
+        setPlanState((prev) => {
+          const nextTransitioning = new Set(prev.transitioningChatIds);
+          nextTransitioning.delete(payload.chatId);
+          return { ...prev, transitioningChatIds: nextTransitioning };
+        });
+
+        // Read latest values from refs to avoid stale closure
+        const currentState = planStateRef.current;
+        const planData = currentState.plansByChatId.get(payload.chatId);
+
+        // Switch chat mode to local-agent for implementation (only if currently in plan mode)
+        if (settingsRef.current?.selectedChatMode === "plan") {
+          updateSettings({ selectedChatMode: "local-agent" });
+        }
+
+        // Switch preview back to preview mode
+        setPreviewMode("preview");
+
+        // Create a new chat for implementation and navigate to it
+        if (!planData || !selectedAppIdRef.current) {
+          console.error("Failed to start implementation: missing plan data", {
+            hasContent: !!planData,
+            hasAppId: !!selectedAppIdRef.current,
+          });
+          return;
+        }
+
+        // Always persist the plan to .dyad/plans/
+        let planSlug: string;
+        try {
+          planSlug = await planClient.createPlan({
+            appId: selectedAppIdRef.current,
+            chatId: payload.chatId,
+            title: planData.title,
+            summary: planData.summary,
+            content: planData.content,
+          });
+        } catch {
+          showError("Failed to save plan. Please try again.");
+          return;
+        }
+
+        try {
+          const newChatId = await ipc.chat.createChat(selectedAppIdRef.current);
+
+          // Navigate to the new chat
+          setSelectedChatId(newChatId);
+          navigate({ to: "/chat", search: { id: newChatId } });
+
+          // Refresh the chat list so the new chat appears in the sidebar
+          queryClient.invalidateQueries({
+            queryKey: queryKeys.chats.all,
+          });
+
+          // Queue the plan for implementation in the new chat
+          setPendingPlanImplementation({
+            chatId: newChatId,
+            title: planData.title,
+            planSlug,
+          });
+        } catch (error) {
+          console.error("Failed to create new chat for implementation:", error);
+        }
+      },
+    );
+
+    // Handle questionnaire events
+    const unsubscribeQuestionnaire = planEventClient.onQuestionnaire(
+      (payload: PlanQuestionnairePayload) => {
+        setPendingQuestionnaire(payload);
+      },
+    );
+
+    return () => {
+      unsubscribeUpdate();
+      unsubscribeExit();
+      unsubscribeQuestionnaire();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    setPlanState,
+    setPreviewMode,
+    updateSettings,
+    setPendingPlanImplementation,
+    setPendingQuestionnaire,
+    setSelectedChatId,
+    navigate,
+    queryClient,
+  ]);
+}

src/hooks/usePlanImplementation.ts

+import { useEffect, useRef } from "react";
+import { useAtomValue, useSetAtom } from "jotai";
+import { pendingPlanImplementationAtom } from "@/atoms/planAtoms";
+import {
+  isStreamingByIdAtom,
+  chatMessagesByIdAtom,
+  chatErrorByIdAtom,
+} from "@/atoms/chatAtoms";
+import { ipc } from "@/ipc/types";
+
+/**
+ * Hook to handle starting plan implementation when a plan is accepted.
+ * Watches for pending plan implementations and sends the plan to the agent
+ * AFTER the current stream completes.
+ */
+export function usePlanImplementation() {
+  const pendingPlan = useAtomValue(pendingPlanImplementationAtom);
+  const setPendingPlan = useSetAtom(pendingPlanImplementationAtom);
+  const isStreamingById = useAtomValue(isStreamingByIdAtom);
+  const setIsStreamingById = useSetAtom(isStreamingByIdAtom);
+  const setMessagesById = useSetAtom(chatMessagesByIdAtom);
+  const setErrorById = useSetAtom(chatErrorByIdAtom);
+
+  // Track if we've already triggered implementation for this pending plan
+  const hasTriggeredRef = useRef(false);
+  // Track the previous streaming state for the pending chat
+  const wasStreamingRef = useRef(false);
+  // Track mounted state to prevent state updates after unmount
+  const isMountedRef = useRef(true);
+
+  useEffect(() => {
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+    };
+  }, []);
+
+  useEffect(() => {
+    // Reset trigger flag when pending plan changes
+    if (!pendingPlan) {
+      hasTriggeredRef.current = false;
+      wasStreamingRef.current = false;
+      return;
+    }
+
+    // Check current streaming state for the pending chat
+    const isNowStreaming = isStreamingById.get(pendingPlan.chatId) ?? false;
+    const wasStreaming = wasStreamingRef.current;
+
+    // Update the ref for next render
+    wasStreamingRef.current = isNowStreaming;
+
+    // Only trigger when:
+    // 1. We haven't triggered yet
+    // 2. Streaming just completed (was true, now false) OR was never streaming
+    const streamJustCompleted = wasStreaming && !isNowStreaming;
+    const neverWasStreaming = !wasStreaming && !isNowStreaming;
+
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+    if (
+      !hasTriggeredRef.current &&
+      (streamJustCompleted || neverWasStreaming)
+    ) {
+      // Set immediately to prevent duplicate scheduling on rapid re-renders
+      hasTriggeredRef.current = true;
+
+      // Capture pending plan value before the timeout to avoid stale closure
+      const planToImplement = pendingPlan;
+
+      // Add a small delay to ensure React state has settled after mode switch
+      timeoutId = setTimeout(() => {
+        const chatId = planToImplement.chatId;
+
+        // Send /implement-plan= command — expanded server-side in chat_stream_handlers
+        const prompt = `/implement-plan=${planToImplement.planSlug}`;
+
+        // Set streaming state to true
+        setIsStreamingById((prev) => {
+          const next = new Map(prev);
+          next.set(chatId, true);
+          return next;
+        });
+
+        // Clear any previous errors
+        setErrorById((prev) => {
+          const next = new Map(prev);
+          next.set(chatId, null);
+          return next;
+        });
+
+        // Send the message to start implementation using IPC directly
+        // (We can't use useStreamChat here because it has conditional hooks)
+        ipc.chatStream.start(
+          {
+            chatId,
+            prompt,
+            selectedComponents: [],
+          },
+          {
+            onChunk: ({ messages: updatedMessages }) => {
+              if (!isMountedRef.current) return;
+              // Update the messages so the UI shows the streaming response
+              setMessagesById((prev) => {
+                const next = new Map(prev);
+                next.set(chatId, updatedMessages);
+                return next;
+              });
+            },
+            onEnd: () => {
+              if (!isMountedRef.current) return;
+              // Stream completed - update streaming state
+              setIsStreamingById((prev) => {
+                const next = new Map(prev);
+                next.set(chatId, false);
+                return next;
+              });
+            },
+            onError: ({ error }) => {
+              if (!isMountedRef.current) return;
+              console.error("Plan implementation stream error:", error);
+              // Update error state
+              setErrorById((prev) => {
+                const next = new Map(prev);
+                next.set(chatId, error);
+                return next;
+              });
+              // Also set streaming to false on error
+              setIsStreamingById((prev) => {
+                const next = new Map(prev);
+                next.set(chatId, false);
+                return next;
+              });
+            },
+          },
+        );
+
+        // Clear the pending plan after triggering
+        setPendingPlan(null);
+      }, 100); // Small delay to let state settle
+    }
+
+    return () => {
+      if (timeoutId !== undefined) {
+        clearTimeout(timeoutId);
+      }
+    };
+  }, [
+    pendingPlan,
+    isStreamingById,
+    setPendingPlan,
+    setIsStreamingById,
+    setMessagesById,
+    setErrorById,
+  ]);
+}

src/ipc/handlers/chat_stream_handlers.ts

@@ -83,6 +83,7 @@ import { parseAppMentions } from "@/shared/parse_mention_apps";
 import { prompts as promptsTable } from "../../db/schema";
 import { inArray } from "drizzle-orm";
 import { replacePromptReference } from "../utils/replacePromptReference";
+import { parsePlanFile, validatePlanId } from "./planUtils";
 import { mcpManager } from "../utils/mcp_manager";
 import z from "zod";
 import {
@@ -367,6 +368,42 @@ export function registerChatStreamHandlers() {
         logger.error("Failed to inline referenced prompts:", e);
       }
 
+      // Expand /implement-plan= into full implementation prompt
+      // Keep the original short form for display in the UI; the expanded
+      // content is only injected into the AI message history.
+      let implementPlanDisplayPrompt: string | undefined;
+      const implementPlanMatch = userPrompt.match(/^\/implement-plan=(.+)$/);
+      if (implementPlanMatch) {
+        try {
+          implementPlanDisplayPrompt = userPrompt;
+          const planSlug = implementPlanMatch[1];
+          validatePlanId(planSlug);
+          const appPath = getDyadAppPath(chat.app.path);
+          const planFilePath = path.join(
+            appPath,
+            ".dyad",
+            "plans",
+            `${planSlug}.md`,
+          );
+          const raw = await fs.promises.readFile(planFilePath, "utf-8");
+          const { meta, content } = parsePlanFile(raw);
+
+          const planPath = `.dyad/plans/${planSlug}.md`;
+
+          userPrompt = `Please implement the following plan:
+
+## ${meta.title || "Implementation Plan"}
+
+${content}
+
+Start implementing this plan now. Follow the steps outlined and create/modify the necessary files.
+You may update the plan at \`${planPath}\` to mark your progress.`;
+        } catch (e) {
+          implementPlanDisplayPrompt = undefined;
+          logger.error("Failed to expand /implement-plan= prompt:", e);
+        }
+      }
+
       const componentsToProcess = req.selectedComponents || [];
 
       if (componentsToProcess.length > 0) {
@@ -416,7 +453,7 @@ ${componentSnippet}
         .values({
           chatId: req.chatId,
           role: "user",
-          content: userPrompt,
+          content: implementPlanDisplayPrompt ?? userPrompt,
         })
         .returning({ id: messages.id });
       const userMessageId = insertedUserMessage.id;
@@ -579,6 +616,21 @@ ${componentSnippet}
           commitHash: message.commitHash,
         }));
 
+        // The DB stores the short /implement-plan= display form; inject the
+        // expanded plan content into the AI message history so the model
+        // receives the full plan.
+        if (implementPlanDisplayPrompt) {
+          for (let i = messageHistory.length - 1; i >= 0; i--) {
+            if (messageHistory[i].role === "user") {
+              messageHistory[i] = {
+                ...messageHistory[i],
+                content: userPrompt,
+              };
+              break;
+            }
+          }
+        }
+
         // For Dyad Pro + Deep Context, we set to 200 chat turns (+1)
         // this is to enable more cache hits. Practically, users should
         // rarely go over this limit because they will hit the model's
@@ -1073,6 +1125,30 @@ This conversation includes one or more image attachments. When the user uploads
           return;
         }
 
+        // Handle plan mode: use local-agent with plan tools only
+        // Plan mode is for requirements gathering and creating implementation plans
+        if (
+          settings.selectedChatMode === "plan" &&
+          !mentionedAppsCodebases.length
+        ) {
+          // Reconstruct system prompt for plan mode
+          const planModeSystemPrompt = constructSystemPrompt({
+            aiRules,
+            chatMode: "plan",
+            enableTurboEditsV2: false,
+            themePrompt,
+          });
+
+          await handleLocalAgentStream(event, req, abortController, {
+            placeholderMessageId: placeholderAssistantMessage.id,
+            systemPrompt: planModeSystemPrompt,
+            dyadRequestId: dyadRequestId ?? "[no-request-id]",
+            planModeOnly: true,
+            messageOverride: isSummarizeIntent ? chatMessages : undefined,
+          });
+          return;
+        }
+
         // Handle local-agent mode (Agent v2)
         // Mentioned apps can't be handled by the local agent (defer to balanced smart context
         // in build mode)

src/ipc/handlers/planUtils.ts

+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Ensures `.dyad/` is listed in the project's `.gitignore`.
+ * Creates `.gitignore` if it doesn't exist.
+ */
+export async function ensureDyadGitignored(appPath: string): Promise<void> {
+  const gitignorePath = path.join(appPath, ".gitignore");
+  let content = "";
+  try {
+    content = await fs.promises.readFile(gitignorePath, "utf-8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+    // .gitignore doesn't exist yet — will be created below
+  }
+
+  // Check if .dyad or .dyad/ is already ignored
+  const lines = content.split(/\r?\n/);
+  const alreadyIgnored = lines.some(
+    (line) => line.trim() === ".dyad" || line.trim() === ".dyad/",
+  );
+  if (alreadyIgnored) return;
+
+  // Append .dyad/ to the end, ensuring a leading newline if file has content
+  const suffix = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
+  await fs.promises.writeFile(
+    gitignorePath,
+    content + suffix + ".dyad/\n",
+    "utf-8",
+  );
+}
+
+export function slugify(text: string): string {
+  const result = text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .substring(0, 60);
+  return result || "untitled";
+}
+
+export function buildFrontmatter(meta: Record<string, string>): string {
+  const lines = Object.entries(meta).map(
+    ([k, v]) =>
+      `${k}: "${v.replace(/\\/g, "\\\\").replace(/\n/g, " ").replace(/"/g, '\\"')}"`,
+  );
+  return `---\n${lines.join("\n")}\n---\n\n`;
+}
+
+export function validatePlanId(planId: string): void {
+  if (!/^[a-z0-9-]+$/.test(planId)) {
+    throw new Error("Invalid plan ID");
+  }
+}
+
+export function parsePlanFile(raw: string): {
+  meta: Record<string, string>;
+  content: string;
+} {
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n*([\s\S]*)$/);
+  if (!match) return { meta: {}, content: raw };
+  const meta: Record<string, string> = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const idx = line.indexOf(":");
+    if (idx > 0) {
+      const key = line.slice(0, idx).trim();
+      let val = line.slice(idx + 1).trim();
+      if (val.startsWith('"') && val.endsWith('"')) {
+        val = val.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+      }
+      meta[key] = val;
+    }
+  }
+  return { meta, content: match[2].trim() };
+}

src/ipc/handlers/plan_handlers.ts

+import fs from "node:fs";
+import path from "node:path";
+import { db } from "../../db";
+import { apps } from "../../db/schema";
+import { eq } from "drizzle-orm";
+import { getDyadAppPath } from "../../paths/paths";
+import log from "electron-log";
+import { createTypedHandler } from "./base";
+import { planContracts } from "../types/plan";
+import {
+  slugify,
+  buildFrontmatter,
+  validatePlanId,
+  parsePlanFile,
+  ensureDyadGitignored,
+} from "./planUtils";
+
+const logger = log.scope("plan_handlers");
+
+async function getPlanDir(appId: number): Promise<string> {
+  const app = await db.query.apps.findFirst({ where: eq(apps.id, appId) });
+  if (!app) throw new Error("App not found");
+  const appPath = getDyadAppPath(app.path);
+  const planDir = path.join(appPath, ".dyad", "plans");
+  await fs.promises.mkdir(planDir, { recursive: true });
+  await ensureDyadGitignored(appPath);
+  return planDir;
+}
+
+export function registerPlanHandlers() {
+  createTypedHandler(planContracts.createPlan, async (_, params) => {
+    const { appId, chatId, title, summary, content } = params;
+    const planDir = await getPlanDir(appId);
+    const now = new Date().toISOString();
+    const slug = `chat-${chatId}-${slugify(title)}-${Date.now()}`;
+    validatePlanId(slug);
+
+    const meta: Record<string, string> = {
+      title,
+      summary: summary ?? "",
+      chatId: String(chatId),
+      createdAt: now,
+      updatedAt: now,
+    };
+    const frontmatter = buildFrontmatter(meta);
+
+    const filePath = path.join(planDir, `${slug}.md`);
+    await fs.promises.writeFile(filePath, frontmatter + content, "utf-8");
+
+    logger.info("Created plan:", slug, "for app:", appId, "with title:", title);
+
+    return slug;
+  });
+
+  createTypedHandler(planContracts.getPlan, async (_, { appId, planId }) => {
+    validatePlanId(planId);
+    const planDir = await getPlanDir(appId);
+    const filePath = path.join(planDir, `${planId}.md`);
+    let raw: string;
+    try {
+      raw = await fs.promises.readFile(filePath, "utf-8");
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        throw new Error(`Plan not found: ${planId}`);
+      }
+      throw err;
+    }
+    const { meta, content } = parsePlanFile(raw);
+
+    return {
+      id: planId,
+      appId,
+      chatId: meta.chatId ? Number(meta.chatId) : null,
+      title: meta.title ?? "",
+      summary: meta.summary || null,
+      content,
+      createdAt: meta.createdAt ?? new Date().toISOString(),
+      updatedAt: meta.updatedAt ?? new Date().toISOString(),
+    };
+  });
+
+  createTypedHandler(
+    planContracts.getPlanForChat,
+    async (_, { appId, chatId }) => {
+      const planDir = await getPlanDir(appId);
+      let files: string[];
+      try {
+        files = await fs.promises.readdir(planDir);
+      } catch {
+        return null;
+      }
+
+      const mdFiles = files.filter((f) => f.endsWith(".md"));
+
+      const prefix = `chat-${chatId}-`;
+      const matches = mdFiles.filter((f) => f.startsWith(prefix));
+      if (matches.length === 0) return null;
+      // Sort to get the latest plan (filenames contain timestamps)
+      matches.sort();
+      const match = matches[matches.length - 1];
+
+      const filePath = path.join(planDir, match);
+      const raw = await fs.promises.readFile(filePath, "utf-8");
+      const { meta, content } = parsePlanFile(raw);
+      const slug = match.replace(/\.md$/, "");
+      return {
+        id: slug,
+        appId,
+        chatId: meta.chatId ? Number(meta.chatId) : chatId,
+        title: meta.title ?? "",
+        summary: meta.summary || null,
+        content,
+        createdAt: meta.createdAt ?? new Date().toISOString(),
+        updatedAt: meta.updatedAt ?? new Date().toISOString(),
+      };
+    },
+  );
+
+  createTypedHandler(planContracts.updatePlan, async (_, params) => {
+    const { appId, id, ...updates } = params;
+    validatePlanId(id);
+    const planDir = await getPlanDir(appId);
+    const filePath = path.join(planDir, `${id}.md`);
+    const raw = await fs.promises.readFile(filePath, "utf-8");
+    const { meta, content } = parsePlanFile(raw);
+
+    if (updates.title !== undefined) meta.title = updates.title;
+    if (updates.summary !== undefined) meta.summary = updates.summary;
+    meta.updatedAt = new Date().toISOString();
+
+    const newContent =
+      updates.content !== undefined ? updates.content : content;
+    const frontmatter = buildFrontmatter(meta);
+    await fs.promises.writeFile(filePath, frontmatter + newContent, "utf-8");
+
+    logger.info("Updated plan:", id);
+  });
+
+  createTypedHandler(planContracts.deletePlan, async (_, { appId, planId }) => {
+    validatePlanId(planId);
+    const planDir = await getPlanDir(appId);
+    const filePath = path.join(planDir, `${planId}.md`);
+    try {
+      await fs.promises.unlink(filePath);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        throw new Error(`Plan not found: ${planId}`);
+      }
+      throw err;
+    }
+    logger.info("Deleted plan:", planId);
+  });
+}

src/ipc/ipc_host.ts

@@ -37,6 +37,7 @@ import { registerSecurityHandlers } from "./handlers/security_handlers";
 import { registerVisualEditingHandlers } from "../pro/main/ipc/handlers/visual_editing_handlers";
 import { registerAgentToolHandlers } from "../pro/main/ipc/handlers/local_agent/agent_tool_handlers";
 import { registerFreeAgentQuotaHandlers } from "./handlers/free_agent_quota_handlers";
+import { registerPlanHandlers } from "./handlers/plan_handlers";
 
 export function registerIpcHandlers() {
   // Register all IPC handlers by category
@@ -79,4 +80,5 @@ export function registerIpcHandlers() {
   registerVisualEditingHandlers();
   registerAgentToolHandlers();
   registerFreeAgentQuotaHandlers();
+  registerPlanHandlers();
 }

src/ipc/preload/channels.ts

@@ -38,6 +38,7 @@ import { visualEditingContracts } from "../types/visual-editing";
 import { securityContracts } from "../types/security";
 import { miscContracts, miscEvents } from "../types/misc";
 import { freeAgentQuotaContracts } from "../types/free_agent_quota";
+import { planEvents, planContracts } from "../types/plan";
 
 // =============================================================================
 // Invoke Channels (derived from all contracts)
@@ -91,6 +92,7 @@ export const VALID_INVOKE_CHANNELS = [
   ...getInvokeChannels(securityContracts),
   ...getInvokeChannels(miscContracts),
   ...getInvokeChannels(freeAgentQuotaContracts),
+  ...getInvokeChannels(planContracts),
 
   // Test-only channels
   ...TEST_INVOKE_CHANNELS,
@@ -115,6 +117,7 @@ export const VALID_RECEIVE_CHANNELS = [
   ...getReceiveChannels(mcpEvents),
   ...getReceiveChannels(systemEvents),
   ...getReceiveChannels(miscEvents),
+  ...getReceiveChannels(planEvents),
 ] as const;
 
 // =============================================================================

src/ipc/types/plan.ts

+import { z } from "zod";
+import {
+  defineEvent,
+  createEventClient,
+  defineContract,
+  createClient,
+} from "../contracts/core";
+
+// Plan Schemas
+
+export const PlanUpdateSchema = z.object({
+  chatId: z.number(),
+  title: z.string(),
+  summary: z.string().optional(),
+  plan: z.string(),
+});
+
+export type PlanUpdatePayload = z.infer<typeof PlanUpdateSchema>;
+
+export const PlanExitSchema = z.object({
+  chatId: z.number(),
+});
+
+export type PlanExitPayload = z.infer<typeof PlanExitSchema>;
+
+const TextQuestionSchema = z.object({
+  id: z.string(),
+  type: z.literal("text"),
+  question: z.string(),
+  required: z.boolean().optional(),
+  placeholder: z.string().optional(),
+});
+
+const MultipleChoiceQuestionSchema = z.object({
+  id: z.string(),
+  type: z.enum(["radio", "checkbox"]),
+  question: z.string(),
+  options: z.array(z.string()).min(1),
+  required: z.boolean().optional(),
+  placeholder: z.string().optional(),
+});
+
+export const QuestionSchema = z.union([
+  TextQuestionSchema,
+  MultipleChoiceQuestionSchema,
+]);
+
+export type Question = z.infer<typeof QuestionSchema>;
+
+export const PlanQuestionnaireSchema = z.object({
+  chatId: z.number(),
+  title: z.string(),
+  description: z.string().optional(),
+  questions: z.array(QuestionSchema),
+});
+
+export type PlanQuestionnairePayload = z.infer<typeof PlanQuestionnaireSchema>;
+
+export const PlanSchema = z.object({
+  id: z.string(),
+  appId: z.number(),
+  chatId: z.number().nullable(),
+  title: z.string(),
+  summary: z.string().nullable(),
+  content: z.string(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+export type Plan = z.infer<typeof PlanSchema>;
+
+export const CreatePlanParamsSchema = z.object({
+  appId: z.number(),
+  chatId: z.number(),
+  title: z.string(),
+  summary: z.string().optional(),
+  content: z.string(),
+});
+
+export type CreatePlanParams = z.infer<typeof CreatePlanParamsSchema>;
+
+export const UpdatePlanParamsSchema = z.object({
+  appId: z.number(),
+  id: z.string(),
+  title: z.string().optional(),
+  summary: z.string().optional(),
+  content: z.string().optional(),
+});
+
+export type UpdatePlanParams = z.infer<typeof UpdatePlanParamsSchema>;
+
+// Plan Event Contracts (Main -> Renderer)
+
+export const planEvents = {
+  update: defineEvent({
+    channel: "plan:update",
+    payload: PlanUpdateSchema,
+  }),
+
+  exit: defineEvent({
+    channel: "plan:exit",
+    payload: PlanExitSchema,
+  }),
+
+  questionnaire: defineEvent({
+    channel: "plan:questionnaire",
+    payload: PlanQuestionnaireSchema,
+  }),
+} as const;
+
+// Plan CRUD Contracts (Invoke/Response)
+
+export const planContracts = {
+  createPlan: defineContract({
+    channel: "plan:create",
+    input: CreatePlanParamsSchema,
+    output: z.string(),
+  }),
+
+  getPlan: defineContract({
+    channel: "plan:get",
+    input: z.object({ appId: z.number(), planId: z.string() }),
+    output: PlanSchema,
+  }),
+
+  getPlanForChat: defineContract({
+    channel: "plan:get-for-chat",
+    input: z.object({ appId: z.number(), chatId: z.number() }),
+    output: PlanSchema.nullable(),
+  }),
+
+  updatePlan: defineContract({
+    channel: "plan:update-plan",
+    input: UpdatePlanParamsSchema,
+    output: z.void(),
+  }),
+
+  deletePlan: defineContract({
+    channel: "plan:delete",
+    input: z.object({ appId: z.number(), planId: z.string() }),
+    output: z.void(),
+  }),
+} as const;
+
+// Plan Clients
+
+export const planEventClient = createEventClient(planEvents);
+
+export const planClient = createClient(planContracts);

src/lib/queryKeys.ts

@@ -36,6 +36,20 @@ export const queryKeys = {
       ["chats", "search", appId, query] as const,
   },
 
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Plans
+  // ─────────────────────────────────────────────────────────────────────────────
+  plans: {
+    all: ["plans"] as const,
+    forChat: ({
+      appId,
+      chatId,
+    }: {
+      appId: number | null;
+      chatId: number | null;
+    }) => ["plans", "forChat", appId, chatId] as const,
+  },
+
   // ─────────────────────────────────────────────────────────────────────────────
   // Proposals
   // ─────────────────────────────────────────────────────────────────────────────
@@ -264,6 +278,7 @@ export type QueryKeyOf<T> = T extends readonly unknown[]
 export type AppQueryKey =
   | QueryKeyOf<(typeof queryKeys.apps)[keyof typeof queryKeys.apps]>
   | QueryKeyOf<(typeof queryKeys.chats)[keyof typeof queryKeys.chats]>
+  | QueryKeyOf<(typeof queryKeys.plans)[keyof typeof queryKeys.plans]>
   | QueryKeyOf<(typeof queryKeys.proposals)[keyof typeof queryKeys.proposals]>
   | QueryKeyOf<(typeof queryKeys.versions)[keyof typeof queryKeys.versions]>
   | QueryKeyOf<(typeof queryKeys.branches)[keyof typeof queryKeys.branches]>

src/lib/schemas.ts

@@ -143,7 +143,13 @@ export type RuntimeMode = z.infer<typeof RuntimeModeSchema>;
 export const RuntimeMode2Schema = z.enum(["host", "docker"]);
 export type RuntimeMode2 = z.infer<typeof RuntimeMode2Schema>;
 
-export const ChatModeSchema = z.enum(["build", "ask", "agent", "local-agent"]);
+export const ChatModeSchema = z.enum([
+  "build",
+  "ask",
+  "agent",
+  "local-agent",
+  "plan",
+]);
 export type ChatMode = z.infer<typeof ChatModeSchema>;
 
 export const GitHubSecretsSchema = z.object({

src/pages/chat.tsx

@@ -13,6 +13,7 @@ import { useAtom, useAtomValue, useSetAtom } from "jotai";
 import { isPreviewOpenAtom, isChatPanelHiddenAtom } from "@/atoms/viewAtoms";
 import { useChats } from "@/hooks/useChats";
 import { selectedAppIdAtom } from "@/atoms/appAtoms";
+import { usePlanImplementation } from "@/hooks/usePlanImplementation";
 
 const DEFAULT_CHAT_PANEL_SIZE = 50;
 
@@ -30,6 +31,9 @@ export default function ChatPage() {
   const previousSizeRef = useRef<number>(DEFAULT_CHAT_PANEL_SIZE);
   const isInitialMountRef = useRef(true);
 
+  // Handle plan implementation when a plan is accepted
+  usePlanImplementation();
+
   useEffect(() => {
     if (!chatId && chats.length && !loading) {
       // Not a real navigation, just a redirect, when the user navigates to /chat

src/pro/main/ipc/handlers/local_agent/local_agent_handler.ts

@@ -59,6 +59,9 @@ import { TOOL_DEFINITIONS } from "./tool_definitions";
 import { parseAiMessagesJson } from "@/ipc/utils/ai_messages_utils";
 import { parseMcpToolKey, sanitizeMcpName } from "@/ipc/utils/mcp_tool_utils";
 import { addIntegrationTool } from "./tools/add_integration";
+import { planningQuestionnaireTool } from "./tools/planning_questionnaire";
+import { writePlanTool } from "./tools/write_plan";
+import { exitPlanTool } from "./tools/exit_plan";
 
 const logger = log.scope("local_agent_handler");
 
@@ -110,6 +113,7 @@ export async function handleLocalAgentStream(
     systemPrompt,
     dyadRequestId,
     readOnly = false,
+    planModeOnly = false,
     messageOverride,
   }: {
     placeholderMessageId: number;
@@ -120,6 +124,11 @@ export async function handleLocalAgentStream(
      * State-modifying tools are disabled, and no commits/deploys are made.
      */
     readOnly?: boolean;
+    /**
+     * If true, only include tools allowed in plan mode.
+     * This includes read-only exploration tools and planning-specific tools.
+     */
+    planModeOnly?: boolean;
     /**
      * If provided, use these messages instead of fetching from the database.
      * Used for summarization where messages need to be transformed.
@@ -237,8 +246,10 @@ export async function handleLocalAgentStream(
     // Build tool set (agent tools + MCP tools)
     // In read-only mode, only include read-only tools and skip MCP tools
     // (since we can't determine if MCP tools modify state)
-    const agentTools = buildAgentToolSet(ctx, { readOnly });
-    const mcpTools = readOnly ? {} : await getMcpTools(event, ctx);
+    // In plan mode, only include planning tools (read + questionnaire/plan tools)
+    const agentTools = buildAgentToolSet(ctx, { readOnly, planModeOnly });
+    const mcpTools =
+      readOnly || planModeOnly ? {} : await getMcpTools(event, ctx);
     const allTools: ToolSet = { ...agentTools, ...mcpTools };
 
     // Prepare message history with graceful fallback
@@ -270,7 +281,22 @@ export async function handleLocalAgentStream(
       system: systemPrompt,
       messages: messageHistory,
       tools: allTools,
-      stopWhen: [stepCountIs(25), hasToolCall(addIntegrationTool.name)], // Allow multiple tool call rounds, stop on add_integration
+      stopWhen: [
+        stepCountIs(25),
+        hasToolCall(addIntegrationTool.name),
+        // In plan mode, stop immediately after presenting a questionnaire,
+        // writing a plan, or exiting plan mode so the agent yields control
+        // back to the user. Without this, some models (e.g. Gemini Pro 3)
+        // ignore the prompt-level "STOP" instruction and keep calling tools
+        // in a loop.
+        ...(planModeOnly
+          ? [
+              hasToolCall(planningQuestionnaireTool.name),
+              hasToolCall(writePlanTool.name),
+              hasToolCall(exitPlanTool.name),
+            ]
+          : []),
+      ],
       abortSignal: abortController.signal,
       // Inject pending user messages (e.g., images from web_crawl) between steps
       // We must re-inject all accumulated messages each step because the AI SDK
@@ -437,8 +463,8 @@ export async function handleLocalAgentStream(
       logger.warn("Failed to save AI messages JSON:", err);
     }
 
-    // In read-only mode, skip deploys and commits
-    if (!readOnly) {
+    // In read-only and plan mode, skip deploys and commits
+    if (!readOnly && !planModeOnly) {
       // Deploy all Supabase functions if shared modules changed
       await deployAllFunctionsIfNeeded(ctx);
 

src/pro/main/ipc/handlers/local_agent/tool_definitions.ts

@@ -27,6 +27,9 @@ import { updateTodosTool } from "./tools/update_todos";
 import { runTypeChecksTool } from "./tools/run_type_checks";
 import { grepTool } from "./tools/grep";
 import { codeSearchTool } from "./tools/code_search";
+import { planningQuestionnaireTool } from "./tools/planning_questionnaire";
+import { writePlanTool } from "./tools/write_plan";
+import { exitPlanTool } from "./tools/exit_plan";
 import type { LanguageModelV3ToolResultOutput } from "@ai-sdk/provider";
 import {
   escapeXmlAttr,
@@ -61,6 +64,10 @@ export const TOOL_DEFINITIONS: readonly ToolDefinition[] = [
   webCrawlTool,
   updateTodosTool,
   runTypeChecksTool,
+  // Plan mode tools
+  planningQuestionnaireTool,
+  writePlanTool,
+  exitPlanTool,
 ];
 // ============================================================================
 // Agent Tool Name Type (derived from TOOL_DEFINITIONS)
@@ -263,6 +270,11 @@ export interface BuildAgentToolSetOptions {
    * Used for read-only modes like "ask" mode.
    */
   readOnly?: boolean;
+  /**
+   * If true, only include tools that are allowed in plan mode.
+   * Plan mode has access to read-only tools plus planning-specific tools.
+   */
+  planModeOnly?: boolean;
 }
 
 const FILE_EDIT_TOOLS: Set<FileEditToolName> = new Set(FILE_EDIT_TOOL_NAMES);
@@ -292,6 +304,16 @@ function trackFileEditTool(
   ctx.fileEditTracker[filePath][toolName as FileEditToolName]++;
 }
 
+/**
+ * Planning-specific tools that are only available in plan mode.
+ * In plan mode, all non-state-modifying tools are also included automatically.
+ */
+const PLANNING_SPECIFIC_TOOLS = new Set([
+  "planning_questionnaire",
+  "write_plan",
+  "exit_plan",
+]);
+
 /**
  * Build ToolSet for AI SDK from tool definitions
  */
@@ -307,6 +329,15 @@ export function buildAgentToolSet(
       continue;
     }
 
+    // In plan mode, skip state-modifying tools unless they're planning-specific
+    if (
+      options.planModeOnly &&
+      tool.modifiesState &&
+      !PLANNING_SPECIFIC_TOOLS.has(tool.name)
+    ) {
+      continue;
+    }
+
     // In read-only mode, skip tools that modify state
     if (options.readOnly && tool.modifiesState) {
       continue;

src/pro/main/ipc/handlers/local_agent/tools/exit_plan.ts

+import { z } from "zod";
+import log from "electron-log";
+import { ToolDefinition, AgentContext } from "./types";
+import { safeSend } from "@/ipc/utils/safe_sender";
+
+const logger = log.scope("exit_plan");
+
+const exitPlanSchema = z.object({
+  confirmation: z
+    .literal(true)
+    .describe("Must be true to confirm the user has accepted the plan"),
+});
+
+const DESCRIPTION = `
+Exit planning mode after the user has accepted the implementation plan.
+
+IMPORTANT: Only use this tool when:
+1. A plan has been presented using the write_plan tool
+2. The user has EXPLICITLY accepted the plan (said "yes", "accept", "looks good", etc.)
+3. You are ready to begin implementation
+
+This will:
+- Switch to Agent mode for implementation
+- Change the preview panel back to app preview
+- Begin the implementation phase
+
+Do NOT use this tool if:
+- The user has requested changes to the plan
+- The user has asked questions about the plan
+- No plan has been presented yet
+
+Example usage after user says "Looks good, let's build it!":
+{
+  "confirmation": true
+}
+`;
+
+export const exitPlanTool: ToolDefinition<z.infer<typeof exitPlanSchema>> = {
+  name: "exit_plan",
+  description: DESCRIPTION,
+  inputSchema: exitPlanSchema,
+  defaultConsent: "always",
+  modifiesState: true,
+
+  getConsentPreview: () => "Exit plan mode and start implementation",
+
+  buildXml: (args) => {
+    if (!args.confirmation) return undefined;
+
+    return `<dyad-exit-plan></dyad-exit-plan>`;
+  },
+
+  execute: async (_args, ctx: AgentContext) => {
+    logger.log("Exiting plan mode, transitioning to implementation");
+
+    safeSend(ctx.event.sender, "plan:exit", {
+      chatId: ctx.chatId,
+    });
+
+    return "Plan accepted. Switching to Agent mode to begin implementation. The agreed plan will guide the implementation process.";
+  },
+};

src/pro/main/ipc/handlers/local_agent/tools/planning_questionnaire.ts

+import { z } from "zod";
+import log from "electron-log";
+import { ToolDefinition, AgentContext } from "./types";
+import { safeSend } from "@/ipc/utils/safe_sender";
+
+const logger = log.scope("planning_questionnaire");
+
+const BaseQuestionFields = {
+  id: z.string().describe("Unique identifier for this question"),
+  question: z.string().describe("The question text to display to the user"),
+  required: z
+    .boolean()
+    .optional()
+    .describe("Whether this question requires an answer (defaults to true)"),
+  placeholder: z
+    .string()
+    .optional()
+    .describe("Placeholder text for text inputs"),
+};
+
+const TextQuestionSchema = z.object({
+  ...BaseQuestionFields,
+  type: z.literal("text"),
+});
+
+const MultipleChoiceQuestionSchema = z.object({
+  ...BaseQuestionFields,
+  type: z
+    .enum(["radio", "checkbox"])
+    .describe("radio for single choice, checkbox for multiple choice"),
+  options: z
+    .array(z.string())
+    .min(1)
+    .max(3)
+    .describe(
+      "Options for the question. Keep to max 3 — users can always provide a custom answer via the free-form text input.",
+    ),
+});
+
+const QuestionSchema = z.union([
+  TextQuestionSchema,
+  MultipleChoiceQuestionSchema,
+]);
+
+const planningQuestionnaireSchema = z.object({
+  title: z.string().describe("Title of this questionnaire section"),
+  description: z
+    .string()
+    .optional()
+    .describe(
+      "Brief description or context for why these questions are being asked",
+    ),
+  questions: z
+    .array(QuestionSchema)
+    .min(1)
+    .max(3)
+    .describe("Array of 1-3 questions to present to the user"),
+});
+
+const DESCRIPTION = `
+Present a structured questionnaire to gather requirements from the user during the planning phase.
+
+**CRITICAL**: After calling this tool, you MUST STOP and wait for the user's responses before proceeding. Do NOT create a plan or take further action until the user has answered all questions. The user's responses will be sent as a follow-up message.
+
+Use this tool to collect specific information about:
+- Feature requirements and expected behavior
+- Technology preferences or constraints
+- Design and UX choices
+- Priority decisions
+- Edge cases and error handling expectations
+
+Question Types:
+- \`text\`: Free-form text input for open-ended questions
+- \`radio\`: Single choice from multiple options (with additional free-form text input)
+- \`checkbox\`: Multiple choice (with additional free-form text input)
+
+**NOTE**: All question types (except pure text) include a free-form text input where users can provide custom answers or additional details. This ensures users are never limited to just the predefined options.
+
+Best Practices:
+- Ask 1-3 focused questions at a time
+- Keep options to a maximum of 3 per question — users can always type a custom answer
+- Users can always type a custom answer, so you don't need to cover every possible option
+- Group related questions together
+- Provide clear options when using radio/checkbox
+- Explain why you're asking if it's not obvious
+
+Example:
+{
+  "title": "Authentication Preferences",
+  "description": "Help me understand your authentication requirements",
+  "questions": [
+    {
+      "id": "auth_method",
+      "type": "radio",
+      "question": "Which authentication method would you prefer?",
+      "options": ["Email/Password", "OAuth (Google, GitHub)", "Magic Link"],
+      "required": true
+    }
+  ]
+}
+`;
+
+export const planningQuestionnaireTool: ToolDefinition<
+  z.infer<typeof planningQuestionnaireSchema>
+> = {
+  name: "planning_questionnaire",
+  description: DESCRIPTION,
+  inputSchema: planningQuestionnaireSchema,
+  defaultConsent: "always",
+  modifiesState: true,
+
+  getConsentPreview: (args) =>
+    `Questionnaire: ${args.title} (${args.questions.length} questions)`,
+
+  execute: async (args, ctx: AgentContext) => {
+    logger.log(
+      `Presenting questionnaire: ${args.title} (${args.questions.length} questions)`,
+    );
+
+    safeSend(ctx.event.sender, "plan:questionnaire", {
+      chatId: ctx.chatId,
+      title: args.title,
+      description: args.description,
+      questions: args.questions,
+    });
+
+    return `Questionnaire "${args.title}" presented to the user. STOP HERE and wait for the user to respond. Do NOT create a plan or continue until you receive the user's answers in a follow-up message.`;
+  },
+};

src/pro/main/ipc/handlers/local_agent/tools/write_plan.ts

+import { z } from "zod";
+import log from "electron-log";
+import { ToolDefinition, AgentContext, escapeXmlAttr } from "./types";
+import { safeSend } from "@/ipc/utils/safe_sender";
+
+const logger = log.scope("write_plan");
+
+const writePlanSchema = z.object({
+  title: z.string().describe("Title of the implementation plan"),
+  summary: z
+    .string()
+    .describe("Brief summary (1-2 sentences) of what will be built"),
+  plan: z
+    .string()
+    .describe(
+      "Full implementation plan in markdown format. Include sections for: feature overview, UI/UX design, considerations, technical approach, implementation steps, code changes, and testing strategy. Put product/UX sections first, technical sections last.",
+    ),
+});
+
+const DESCRIPTION = `
+Present an implementation plan to the user in the preview panel.
+
+The plan should be comprehensive and include (in this order — product/UX first, technical last):
+- **Overview**: Clear description of what will be built or changed
+- **UI/UX Design**: User flows, layout, component placement, interactions
+- **Considerations**: Potential challenges, trade-offs, edge cases, or alternatives
+- **Technical Approach**: Architecture decisions, patterns to use, libraries needed
+- **Implementation Steps**: Ordered, granular tasks with file-level specificity
+- **Code Changes**: Specific files to modify/create and what changes are needed
+- **Testing Strategy**: How the feature should be validated
+
+Format the plan in markdown for clear readability. Use headers, bullet points, and code blocks for file paths.
+
+After presenting the plan, the user can:
+- Accept the plan (use exit_plan tool to proceed to implementation)
+- Request changes (update the plan based on their feedback)
+
+Example:
+{
+  "title": "User Authentication System",
+  "summary": "Implement a complete authentication system with email/password login, session management, and protected routes.",
+  "plan": "## Overview\\n\\nImplement a secure authentication system...\\n\\n## Technical Approach\\n\\n- Use JWT for session management...\\n\\n## Implementation Steps\\n\\n1. Create auth context...\\n2. Build login form...\\n\\n## Testing Strategy\\n\\n- Unit tests for auth hooks..."
+}
+`;
+
+export const writePlanTool: ToolDefinition<z.infer<typeof writePlanSchema>> = {
+  name: "write_plan",
+  description: DESCRIPTION,
+  inputSchema: writePlanSchema,
+  defaultConsent: "always",
+  modifiesState: true,
+
+  getConsentPreview: (args) => `Plan: ${args.title}`,
+
+  buildXml: (args, isComplete) => {
+    if (!args.title) return undefined;
+
+    const title = escapeXmlAttr(args.title);
+    const summary = args.summary ? escapeXmlAttr(args.summary) : "";
+
+    return `<dyad-write-plan title="${title}" summary="${summary}" complete="${isComplete}"></dyad-write-plan>`;
+  },
+
+  execute: async (args, ctx: AgentContext) => {
+    logger.log(`Writing plan: ${args.title}`);
+
+    safeSend(ctx.event.sender, "plan:update", {
+      chatId: ctx.chatId,
+      title: args.title,
+      summary: args.summary,
+      plan: args.plan,
+    });
+
+    return `Implementation plan "${args.title}" has been presented to the user. They can review it in the preview panel and either accept it or request changes.`;
+  },
+};

src/prompts/plan_mode_prompt.ts

+export const PLAN_MODE_SYSTEM_PROMPT = `
+<role>
+You are Dyad Plan Mode, an AI planning assistant specialized in gathering requirements and creating detailed implementation plans for software changes. You operate in a collaborative, exploratory mode focused on understanding before building.
+</role>
+
+# Core Mission
+
+Your goal is to have a thoughtful brainstorming session with the user to fully understand their request, then create a comprehensive implementation plan. Think of yourself as a technical product manager who asks insightful questions and creates detailed specifications.
+
+# Planning Process Workflow
+
+## Phase 1: Discovery & Requirements Gathering
+
+1. **Initial Understanding**: When a user describes what they want, first acknowledge their request and identify what you already understand about it.
+
+2. **Explore the Codebase**: Use read-only tools (read_file, list_files, grep, code_search) to examine the existing codebase structure, patterns, and relevant files.
+
+3. **Ask Clarifying Questions**: Use the \`planning_questionnaire\` tool to ask targeted questions about:
+   - Specific functionality and behavior
+   - Edge cases and error handling
+   - UI/UX expectations
+   - Integration points with existing code
+   - Performance or security considerations
+   - User workflows and interactions
+
+   **IMPORTANT**: After calling \`planning_questionnaire\`, you MUST STOP and wait for the user's responses. Do NOT proceed to create a plan until the user has answered all questions. The user's responses will appear in a follow-up message.
+
+4. **Iterative Clarification**: Based on user responses, continue exploring the codebase and asking follow-up questions until you have a clear picture. After receiving the first round of answers, consider whether follow-up questions are needed before moving to plan creation.
+
+## Phase 2: Plan Creation
+
+Once you have sufficient context, create a detailed implementation plan using the \`write_plan\` tool. The plan should include (in this order — product/UX first, technical last):
+
+- **Overview**: Clear description of what will be built or changed
+- **UI/UX Design**: User flows, layout, component placement, interactions
+- **Considerations**: Potential challenges, trade-offs, edge cases, or alternatives
+- **Technical Approach**: Architecture decisions, patterns to use, libraries needed
+- **Implementation Steps**: Ordered, granular tasks with file-level specificity
+- **Code Changes**: Specific files to modify/create and what changes are needed
+- **Testing Strategy**: How the feature should be validated
+
+## Phase 3: Plan Refinement & Approval
+
+After presenting the plan:
+- If user suggests changes: Acknowledge their feedback, investigate how to incorporate suggestions (explore codebase if needed), and update the plan using \`write_plan\` tool again
+- **If user accepts**: You MUST immediately call the \`exit_plan\` tool with \`confirmation: true\`. Do NOT respond with any text — your entire response must be the \`exit_plan\` tool call and nothing else. This is critical for the system to transition correctly.
+
+# Communication Guidelines
+
+## Tone & Style
+- Be collaborative and conversational, like a thoughtful colleague brainstorming together
+- Show genuine curiosity about the user's vision
+- Think out loud about trade-offs and options
+- Be concise but thorough - avoid over-explaining obvious points
+- Use natural language, not overly formal or robotic phrasing
+
+## Question Strategy
+- Ask 1-3 focused questions at a time (don't overwhelm)
+- Prioritize questions that unblock multiple decisions
+- Frame questions as options when possible ("Would you prefer A or B?")
+- Explain why you're asking if it's not obvious
+- Group related questions together
+
+## Exploration Approach
+- Proactively examine the codebase to understand context
+- Share relevant findings: "I noticed you're using [X pattern] in [Y file]..."
+- Identify existing patterns to follow for consistency
+- Call out potential integration challenges early
+
+# Available Tools
+
+## Read-Only Tools (for exploration)
+- \`read_file\` - Read file contents
+- \`list_files\` - List directory contents
+- \`grep\` - Search for patterns in files
+- \`code_search\` - Semantic code search
+
+## Planning Tools (for interaction)
+- \`planning_questionnaire\` - Present structured questions to the user (supports text, radio, and checkbox question types)
+- \`write_plan\` - Present or update the implementation plan as a markdown document
+- \`exit_plan\` - Transition to implementation mode after plan approval
+
+# Important Constraints
+
+- **NEVER write code or make file changes in plan mode**
+- **NEVER use <dyad-write>, <dyad-edit>, <dyad-delete>, <dyad-add-dependency> or any code-producing tags**
+- Focus entirely on requirements gathering and planning
+- Keep plans clear, actionable, and well-structured
+- Ask clarifying questions proactively
+- Break complex changes into discrete implementation steps
+- Only use \`exit_plan\` when the user explicitly accepts the plan
+- **CRITICAL**: When the user accepts the plan, you MUST call \`exit_plan\` immediately as your only action. Do not output any text before or after the tool call. Failure to call \`exit_plan\` will block the user from proceeding to implementation.
+
+[[AI_RULES]]
+
+# Remember
+
+Your job is to:
+1. Understand what the user wants to accomplish
+2. Explore the existing codebase to inform the plan
+3. Ask questions to clarify requirements
+4. Create a comprehensive implementation plan
+5. Refine the plan based on user feedback
+6. Transition to implementation only after explicit approval — by calling \`exit_plan\` (not by generating text)
+
+You are NOT building anything yet - you are planning what will be built.
+`;
+
+const DEFAULT_PLAN_AI_RULES = `# Tech Stack Context
+When exploring the codebase, identify:
+- Frontend framework (React, Vue, etc.)
+- Styling approach (Tailwind, CSS modules, etc.)
+- State management patterns
+- Component architecture
+- Routing approach
+- API patterns
+
+Use this context to inform your implementation plan and ensure consistency with existing patterns.
+`;
+
+export function constructPlanModePrompt(
+  aiRules: string | undefined,
+  themePrompt?: string,
+): string {
+  let prompt = PLAN_MODE_SYSTEM_PROMPT.replace(
+    "[[AI_RULES]]",
+    aiRules ?? DEFAULT_PLAN_AI_RULES,
+  );
+
+  if (themePrompt) {
+    prompt += "\n\n" + themePrompt;
+  }
+
+  return prompt;
+}

src/prompts/system_prompt.ts

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import log from "electron-log";
 import { TURBO_EDITS_V2_SYSTEM_PROMPT } from "../pro/main/prompts/turbo_edits_v2_prompt";
 import { constructLocalAgentPrompt } from "./local_agent_prompt";
+import { constructPlanModePrompt } from "./plan_mode_prompt";
 
 const logger = log.scope("system_prompt");
 
@@ -513,7 +514,7 @@ export const constructSystemPrompt = ({
   basicAgentMode,
 }: {
   aiRules: string | undefined;
-  chatMode?: "build" | "ask" | "agent" | "local-agent";
+  chatMode?: "build" | "ask" | "agent" | "local-agent" | "plan";
   enableTurboEditsV2: boolean;
   themePrompt?: string;
   /** If true, use read-only mode for local-agent (ask mode with tools) */
@@ -521,6 +522,10 @@ export const constructSystemPrompt = ({
   /** If true, use basic agent mode (free tier with limited tools) */
   basicAgentMode?: boolean;
 }) => {
+  if (chatMode === "plan") {
+    return constructPlanModePrompt(aiRules, themePrompt);
+  }
+
   if (chatMode === "local-agent") {
     return constructLocalAgentPrompt(aiRules, themePrompt, {
       readOnly,

testing/fake-llm-server/chatCompletionHandler.ts

@@ -54,6 +54,11 @@ export const createChatCompletionHandler =
       if (localAgentFixture) {
         return handleLocalAgentFixture(req, res, localAgentFixture);
       }
+
+      // Route plan acceptance message to exit-plan fixture
+      if (textContent.includes("I accept this plan")) {
+        return handleLocalAgentFixture(req, res, "exit-plan");
+      }
     }
 
     let messageContent = CANNED_MESSAGE;