From 1179c3a88f1d544e4eea45de9c051479f615e062 Mon Sep 17 00:00:00 2001
From: Vignesh Natarajan <vigneshnatarajan92@gmail.com>
Date: Sat, 24 Jan 2026 16:31:47 -0800
Subject: [PATCH] feat: add /plan planning-mode instructions

---
 src/agents/system-prompt.test.ts | 10 ++++++++++
 src/agents/system-prompt.ts      | 21 +++++++++++++++++++++
 2 files changed, 31 insertions(+)

diff --git a/src/agents/system-prompt.test.ts b/src/agents/system-prompt.test.ts
index 14f643e55..58e05a7cd 100644
--- a/src/agents/system-prompt.test.ts
+++ b/src/agents/system-prompt.test.ts
@@ -310,6 +310,16 @@ describe("buildAgentSystemPrompt", () => {
     expect(prompt).toContain("/status shows Reasoning");
   });
 
+  it("includes /plan mode instructions", () => {
+    const prompt = buildAgentSystemPrompt({
+      workspaceDir: "/tmp/clawd",
+    });
+
+    expect(prompt).toContain("## Plan Mode (/plan)");
+    expect(prompt).toContain("If the user message starts with /plan");
+    expect(prompt).toContain("plans/<timestamp>-<slug>/");
+  });
+
   it("builds runtime line with agent and channel details", () => {
     const line = buildRuntimeLine(
       {
diff --git a/src/agents/system-prompt.ts b/src/agents/system-prompt.ts
index 41ec9a7d5..c2f6ae802 100644
--- a/src/agents/system-prompt.ts
+++ b/src/agents/system-prompt.ts
@@ -558,6 +558,27 @@ export function buildAgentSystemPrompt(params: {
     );
   }
 
+  // Plan mode is conversational but stateful: compile a messy goal into a structured artifact.
+  if (!isMinimal) {
+    lines.push(
+      "## Plan Mode (/plan)",
+      "If the user message starts with /plan, enter *planning mode*.",
+      "- Treat everything after /plan as the goal.",
+      "- Ask targeted follow-up questions (one at a time) to remove ambiguity.",
+      "- Persist state in the workspace so planning can resume without losing context.",
+      "",
+      "Artifacts:",
+      "- Create a directory plans/<timestamp>-<slug>/ in the workspace.",
+      "- Maintain plans/<id>/answers.json (incremental) and plans/<id>/plan.md (human-readable).",
+      "- Optionally create plans/<id>/plan.json (structured) when helpful.",
+      "",
+      "Rules:",
+      "- Be token-efficient: do not restate the entire plan on every turn; ask the next question.",
+      "- When enough information is collected, produce a crisp plan with milestones + next actions.",
+      "",
+    );
+  }
+
   lines.push(
     "## Runtime",
     buildRuntimeLine(runtimeInfo, runtimeChannel, runtimeCapabilities, params.defaultThinkLevel),