🤖 fix: simplify plan mode instructions (#2840)

## Summary

Move the opinionated plan-mode guidance into the built-in `plan` agent
body so custom plan agents can override it, while leaving runtime
injection focused on workspace-specific plan-file constraints.

## Background

Plan guidance was split between the built-in plan spec and
runtime-injected `modeUtils` text. That made the behavior harder to
override and left the instructions more repetitive than necessary.

## Implementation

- trimmed `getPlanModeInstruction()` down to runtime-only facts: exact
plan path, plan-file lifecycle guidance, edit restrictions, and
read-only bash limits
- simplified the built-in `plan` agent instructions while keeping the
key Explore / `ask_user_question` / `propose_plan` workflow expectations
- synced the built-in plan docs snapshot and regenerated built-in agent
content
- tightened tests to cover prompt composition and inherited plan
behavior instead of exact prompt prose

## Validation

- `make static-check`
- `bun test src/common/utils/ui/modeUtils.test.ts
src/node/services/streamContextBuilder.test.ts
src/node/services/agentDefinitions/agentDefinitionsService.test.ts`

## Risks

Low. This changes prompt composition for plan-like agents plus
docs/tests. The main regression risk is accidentally dropping plan-mode
guardrails or prompt ordering, which is covered by the updated prompt
assembly and inheritance tests.

---

_Generated with `mux` • Model: `openai:gpt-5.4` • Thinking: `xhigh` •
Cost: `$44.79`_

<!-- mux-attribution: model=openai:gpt-5.4 thinking=xhigh costs=44.79
-->

Author: ammar-agent

docs/agents/index.mdx

@@ -152,7 +152,7 @@ Tools are controlled via an explicit **whitelist**. The `tools` array lists patt
 
 **Inheritance:** Use `base` to inherit behavior from another agent:
 
-- `base: plan` — Plan-mode behaviors (enables `ask_user_question`, `propose_plan`)
+- `base: plan` — Plan-mode behaviors and built-in planning guidance (enables `ask_user_question`, `propose_plan`)
 - `base: exec` — Exec-mode behaviors (standard coding workflow)
 - `base: <custom-agent-id>` — Inherit from any custom agent
 
@@ -598,44 +598,51 @@ tools:
 
 You are in Plan Mode.
 
-- Every response MUST produce or update a plan—no exceptions.
-- Simple requests deserve simple plans; a straightforward task might only need a few bullet points. Match plan complexity to the problem.
-- Keep the plan scannable; put long rationale in `<details>/<summary>` blocks.
-- Plans must be **self-contained**: include enough context, goals, constraints, and the core "why" so a new assistant can implement without needing the prior chat.
-- When Plan Mode is requested, assume the user wants the actual completed plan; do not merely describe how you would devise one.
+- Every response MUST produce or update a plan.
+- Match the plan's size and structure to the problem.
+- Keep the plan self-contained and scannable.
+- Assume the user wants the completed plan, not a description of how you would make one.
 
-## Investigation step (required)
+## Investigate only what you need
 
-Before proposing a plan, identify what you must verify and delegate repo investigation to Explore
-sub-agents. Do not guess.
+Before proposing a plan, figure out what you need to verify and gather that evidence.
 
-- Use Explore tasks for repo investigation (files, callsites, patterns, feasibility checks)
-  whenever delegation is available.
-- Do not inspect repo files yourself to verify, enrich, or second-guess an Explore report.
-- If reports conflict, feel incomplete, or leave a specific gap, spawn another narrowly focused
-  Explore task for that discrepancy.
-- If task delegation is unavailable in this workspace, use the narrowest read-only repo
-  investigation needed to close that specific gap.
+- When delegation is available, use Explore sub-agents for repo investigation. In Plan Mode, only
+  spawn `agentId: "explore"` tasks.
+- Give each Explore task specific deliverables, and parallelize them when that helps.
+- Trust completed Explore reports for repo facts. Do not re-investigate just to second-guess them.
+  If something is missing, ambiguous, or conflicting, spawn another focused Explore task.
+- If task delegation is unavailable, do the narrowest read-only investigation yourself.
 - Reserve `file_read` for the plan file itself, user-provided text already in this conversation,
-  and that narrow fallback—not for normal repo investigation.
-
-When you do read the plan file itself, prefer `file_read` over `bash cat`: long bash output may be
-compacted, which can hide the middle of a document. Use `file_read` with offset/limit to page
-through larger files.
-
-## Plan format
-
-- Context/Why: Briefly restate the request, goals, and the rationale or user impact so the
-  plan stands alone for a fresh implementer.
-- Evidence: List sources consulted (file paths, tool outputs, or user-provided info) and
-  why they are sufficient. If evidence is missing, still produce a minimal plan and add a
-  Questions section listing what you need to proceed.
-
-- Implementation details: List concrete edits (file paths + symbols) in the order you would implement them.
-  - Where it meaningfully reduces ambiguity, include **reasonably sized** code snippets (fenced code blocks) that show the intended shape of the change.
-  - Keep snippets focused (avoid whole-file dumps); elide unrelated context with `...`.
-
-Detailed plan mode instructions (plan file path, sub-agent delegation, propose_plan workflow) are provided separately.
+  and that narrow fallback. When reading the plan file, prefer `file_read` over `bash cat` so long
+  plans do not get compacted.
+- Wait for any spawned Explore tasks before calling `propose_plan`.
+
+## Write the plan
+
+- Use whatever structure best fits the problem: a few bullets, phases, workstreams, risks, or
+  decision points are all fine.
+- Include the context, constraints, evidence, and concrete path forward somewhere in that
+  structure.
+- Name the files, symbols, or subsystems that matter, and order the work so an implementer can
+  follow it.
+- Keep uncertainty brief and local to the relevant step. Use `ask_user_question` when you need the
+  user to decide something.
+- Include small code snippets only when they materially reduce ambiguity.
+- Put long rationale or background into `<details>/<summary>` blocks.
+
+## Questions and handoff
+
+- If you need clarification from the user, use `ask_user_question` instead of asking in chat or
+  adding an "Open Questions" section to the plan.
+- Ask up to 4 questions at a time (2–4 options each; "Other" remains available for free-form
+  input).
+- After you get answers, update the plan and then call `propose_plan` when it is ready for review.
+- After calling `propose_plan`, do not paste the plan into chat or mention the plan file path.
+- If the user wants edits to other files, ask them to switch to Exec mode.
+
+Workspace-specific runtime instructions (plan file path, edit restrictions, nesting warnings) are
+provided separately.
 ```
 
 </Accordion>

src/common/utils/ui/modeUtils.test.ts

@@ -1,34 +1,13 @@
 import { getPlanFileHint, getPlanModeInstruction } from "./modeUtils";
 
 describe("getPlanModeInstruction", () => {
-  it("provides plan file path context", () => {
-    const instruction = getPlanModeInstruction("/tmp/plan.md", false);
+  it("threads the exact plan file path through both creation and resume flows", () => {
+    const newPlanInstruction = getPlanModeInstruction("/tmp/plan.md", false);
+    const existingPlanInstruction = getPlanModeInstruction("/tmp/plan.md", true);
 
-    expect(instruction).toContain("Plan file path: /tmp/plan.md");
-    expect(instruction).toContain("No plan file exists yet");
-    expect(instruction).toContain("file_edit_* tools");
-  });
-
-  it("routes ambiguous Explore reports to another narrow Explore task", () => {
-    const instruction = getPlanModeInstruction("/tmp/plan.md", false);
-
-    expect(instruction).toContain("Anti-pattern: using `file_read` or `bash` in Plan Mode");
-    expect(instruction).toContain("spawn another narrowly focused Explore task instead");
-    expect(instruction).toContain("plan file itself");
-    expect(instruction).toContain("user-provided text already in this conversation");
-    expect(instruction).toContain("task delegation is unavailable in this workspace");
-    expect(instruction).toContain("use the narrowest read-only investigation needed");
-    expect(instruction).not.toContain(
-      "only re-check if the report is ambiguous or contradicts other evidence"
-    );
-  });
-
-  it("indicates when plan file already exists", () => {
-    const instruction = getPlanModeInstruction("/tmp/existing-plan.md", true);
-
-    expect(instruction).toContain("Plan file path: /tmp/existing-plan.md");
-    expect(instruction).toContain("A plan file already exists");
-    expect(instruction).toContain("read it to determine if it's relevant");
+    expect(newPlanInstruction).toContain("/tmp/plan.md");
+    expect(existingPlanInstruction).toContain("/tmp/plan.md");
+    expect(newPlanInstruction).not.toEqual(existingPlanInstruction);
   });
 });
 
@@ -37,13 +16,10 @@ describe("getPlanFileHint", () => {
     expect(getPlanFileHint("/tmp/plan.md", false)).toBeNull();
   });
 
-  it("includes post-compaction guidance and an ignore escape hatch", () => {
+  it("returns a non-null hint keyed to the saved plan path", () => {
     const hint = getPlanFileHint("/tmp/plan.md", true);
 
-    if (!hint) throw new Error("expected non-null hint");
-
-    expect(hint).toContain("A plan file exists at: /tmp/plan.md");
-    expect(hint).toContain("compaction/context reset");
-    expect(hint).toContain("If it is unrelated to the current request, ignore it.");
+    expect(hint).not.toBeNull();
+    expect(hint).toContain("/tmp/plan.md");
   });
 });

src/common/utils/ui/modeUtils.ts

@@ -1,10 +1,10 @@
 /**
- * Generate the system instruction for Plan Mode with file path context.
+ * Generate runtime-only instructions for plan-like agents.
  *
- * This provides comprehensive plan mode behavioral instructions that are
- * injected for ALL plan-like agents (built-in Plan agent or custom agents
- * that enable propose_plan). The instructions are injected as
- * <additional-instructions> in the system prompt.
+ * These instructions carry workspace-specific facts that agent specs cannot encode,
+ * such as the exact plan file path, whether a plan already exists, and the
+ * non-overridable file-edit restrictions enforced by plan mode.
+ * Opinionated planning guidance lives in the agent spec so users can override it.
  */
 export function getPlanModeInstruction(planFilePath: string, planExists: boolean): string {
   const exactPlanPathRule = planFilePath.startsWith("~/")
@@ -22,35 +22,10 @@ Build your plan incrementally by writing to or editing this file.
 NOTE: The plan file is the only file you are allowed to edit. Other than that you may only take READ-ONLY actions.
 ${exactPlanPathRule}
 
-Keep the plan crisp and focused on actionable recommendations:
-- Put historical context, alternatives considered, or lengthy rationale into collapsible \`<details>/<summary>\` blocks so the core plan stays scannable.
-- When listing implementation details, include **reasonably sized** code snippets (fenced code blocks) for key changes—enough to remove ambiguity, but avoid whole-file dumps. Use ellipses (...) to omit unrelated context.
-- **Aggressively prune completed or irrelevant content.** When sections become outdated—tasks finished, approaches abandoned, questions answered—delete them entirely rather than moving them to an appendix or marking them done. The plan should reflect current state, not accumulate history.
-- Each revision should leave the plan shorter or unchanged in scope, never longer unless the actual work grew.
-
-If you need investigation (codebase exploration, tracing callsites, locating patterns, feasibility checks) before you can produce a good plan, delegate it to Explore sub-agents via the \`task\` tool:
-- In Plan Mode, you MUST ONLY spawn \`agentId: "explore"\` tasks. Do NOT spawn \`agentId: "exec"\` tasks in Plan Mode.
-- Use \`agentId: "explore"\` for read-only repo/code exploration and optional web lookups when relevant.
-- In each task prompt, specify explicit deliverables (what questions to answer, what files/symbols to locate, and the exact output format you want back).
-- Prefer running multiple Explore tasks in parallel with \`run_in_background: true\`, then use \`task_await\` (optionally with \`task_ids\`) until all spawned tasks are \`completed\`.
-- Trust Explore sub-agent reports as authoritative for repo facts (paths/symbols/callsites). Treat them as sufficient evidence for the plan.
-- Anti-pattern: using \`file_read\` or \`bash\` in Plan Mode to verify, enrich, or second-guess an Explore report. If a report is ambiguous, incomplete, or conflicts with another report, spawn another narrowly focused Explore task instead. This anti-pattern does not apply to reading or editing the plan file itself, to user-provided text already in this conversation, or to the narrowest read-only repo investigation needed when task delegation is unavailable in this workspace.
-- While Explore tasks run, and after they complete, do NOT perform repo exploration yourself if delegation is available. If task tools are disabled in this workspace, use the narrowest read-only investigation needed to close the specific gap, then synthesize the plan in this session.
-- Do NOT call \`propose_plan\` until you have awaited and incorporated sub-agent reports.
-
-If you need clarification from the user before you can finalize the plan, you MUST use the ask_user_question tool.
-- Do not ask questions in a normal chat message.
-- Do not include an "Open Questions" section in the plan.
-- Ask up to 4 questions at a time (each with 2–4 options; "Other" is always available for free-form input).
-- After you receive answers, update the plan file and only then call propose_plan.
-- After calling propose_plan, do not repeat/paste the plan contents in chat; the UI already renders the full plan.
-- After calling propose_plan, do not say "the plan is ready at <path>" or otherwise mention the plan file location; it's already shown in the Plan UI.
-
-When you have finished writing your plan and are ready for user approval, call the propose_plan tool.
 Do not make other edits in plan mode. You may have tools like bash but only use them for read-only operations.
 Read-only bash means: no redirects/heredocs, no rm/mv/cp/mkdir/touch, no git add/commit, and no dependency installs.
-
-If the user suggests that you should make edits to other files, ask them to switch to Exec mode first!
+When the plan is ready for user review, call \`propose_plan\`.
+After calling \`propose_plan\`, do not paste the plan into chat or mention the plan file path.
 `;
 }
 

src/node/builtinAgents/plan.md

@@ -28,41 +28,48 @@ tools:
 
 You are in Plan Mode.
 
-- Every response MUST produce or update a plan—no exceptions.
-- Simple requests deserve simple plans; a straightforward task might only need a few bullet points. Match plan complexity to the problem.
-- Keep the plan scannable; put long rationale in `<details>/<summary>` blocks.
-- Plans must be **self-contained**: include enough context, goals, constraints, and the core "why" so a new assistant can implement without needing the prior chat.
-- When Plan Mode is requested, assume the user wants the actual completed plan; do not merely describe how you would devise one.
+- Every response MUST produce or update a plan.
+- Match the plan's size and structure to the problem.
+- Keep the plan self-contained and scannable.
+- Assume the user wants the completed plan, not a description of how you would make one.
 
-## Investigation step (required)
+## Investigate only what you need
 
-Before proposing a plan, identify what you must verify and delegate repo investigation to Explore
-sub-agents. Do not guess.
+Before proposing a plan, figure out what you need to verify and gather that evidence.
 
-- Use Explore tasks for repo investigation (files, callsites, patterns, feasibility checks)
-  whenever delegation is available.
-- Do not inspect repo files yourself to verify, enrich, or second-guess an Explore report.
-- If reports conflict, feel incomplete, or leave a specific gap, spawn another narrowly focused
-  Explore task for that discrepancy.
-- If task delegation is unavailable in this workspace, use the narrowest read-only repo
-  investigation needed to close that specific gap.
+- When delegation is available, use Explore sub-agents for repo investigation. In Plan Mode, only
+  spawn `agentId: "explore"` tasks.
+- Give each Explore task specific deliverables, and parallelize them when that helps.
+- Trust completed Explore reports for repo facts. Do not re-investigate just to second-guess them.
+  If something is missing, ambiguous, or conflicting, spawn another focused Explore task.
+- If task delegation is unavailable, do the narrowest read-only investigation yourself.
 - Reserve `file_read` for the plan file itself, user-provided text already in this conversation,
-  and that narrow fallback—not for normal repo investigation.
+  and that narrow fallback. When reading the plan file, prefer `file_read` over `bash cat` so long
+  plans do not get compacted.
+- Wait for any spawned Explore tasks before calling `propose_plan`.
 
-When you do read the plan file itself, prefer `file_read` over `bash cat`: long bash output may be
-compacted, which can hide the middle of a document. Use `file_read` with offset/limit to page
-through larger files.
+## Write the plan
 
-## Plan format
+- Use whatever structure best fits the problem: a few bullets, phases, workstreams, risks, or
+  decision points are all fine.
+- Include the context, constraints, evidence, and concrete path forward somewhere in that
+  structure.
+- Name the files, symbols, or subsystems that matter, and order the work so an implementer can
+  follow it.
+- Keep uncertainty brief and local to the relevant step. Use `ask_user_question` when you need the
+  user to decide something.
+- Include small code snippets only when they materially reduce ambiguity.
+- Put long rationale or background into `<details>/<summary>` blocks.
 
-- Context/Why: Briefly restate the request, goals, and the rationale or user impact so the
-  plan stands alone for a fresh implementer.
-- Evidence: List sources consulted (file paths, tool outputs, or user-provided info) and
-  why they are sufficient. If evidence is missing, still produce a minimal plan and add a
-  Questions section listing what you need to proceed.
+## Questions and handoff
 
-- Implementation details: List concrete edits (file paths + symbols) in the order you would implement them.
-  - Where it meaningfully reduces ambiguity, include **reasonably sized** code snippets (fenced code blocks) that show the intended shape of the change.
-  - Keep snippets focused (avoid whole-file dumps); elide unrelated context with `...`.
+- If you need clarification from the user, use `ask_user_question` instead of asking in chat or
+  adding an "Open Questions" section to the plan.
+- Ask up to 4 questions at a time (2–4 options each; "Other" remains available for free-form
+  input).
+- After you get answers, update the plan and then call `propose_plan` when it is ready for review.
+- After calling `propose_plan`, do not paste the plan into chat or mention the plan file path.
+- If the user wants edits to other files, ask them to switch to Exec mode.
 
-Detailed plan mode instructions (plan file path, sub-agent delegation, propose_plan workflow) are provided separately.
+Workspace-specific runtime instructions (plan file path, edit restrictions, nesting warnings) are
+provided separately.

src/node/services/agentDefinitions/agentDefinitionsService.test.ts

@@ -131,6 +131,36 @@ Replaced body.
     expect(replacerBody).not.toContain("Base instructions");
   });
 
+  test("project plan agents can replace the built-in plan prompt body without losing inherited frontmatter", async () => {
+    using tempDir = new DisposableTempDir("agent-plan-guidance");
+    const agentsRoot = path.join(tempDir.path, ".mux", "agents");
+    await fs.mkdir(agentsRoot, { recursive: true });
+
+    await fs.writeFile(
+      path.join(agentsRoot, "custom-plan.md"),
+      `---
+name: Custom Plan
+base: plan
+prompt:
+  append: false
+---
+Custom planning instructions.
+`,
+      "utf-8"
+    );
+
+    const runtime = new LocalRuntime(tempDir.path);
+
+    const customPlanBody = await resolveAgentBody(runtime, tempDir.path, "custom-plan");
+    expect(customPlanBody).toBe("Custom planning instructions.\n");
+
+    const customPlanFrontmatter = await resolveAgentFrontmatter(
+      runtime,
+      tempDir.path,
+      "custom-plan"
+    );
+    expect(customPlanFrontmatter.tools?.require).toEqual(["propose_plan"]);
+  });
   test("same-name override: project agent with base: self extends built-in/global, not itself", async () => {
     using project = new DisposableTempDir("agent-same-name");
     using global = new DisposableTempDir("agent-same-name-global");