feat(prompt): enhance system prompts with global reasoning discipline and iterative planning

packages/core/src/core/prompts.test.ts

@@ -582,8 +582,8 @@ describe('getPlanModeSystemReminder', () => {
   it('should include workflow instructions', () => {
     const result = getPlanModeSystemReminder();
 
-    expect(result).toContain("1. Answer the user's query comprehensively");
-    expect(result).toContain("2. When you're done researching");
+    expect(result).toContain('Iterative Planning Workflow');
+    expect(result).toContain('### The Loop');
     expect(result).toContain('exit_plan_mode tool');
   });
 

packages/core/src/core/prompts.ts

@@ -955,9 +955,41 @@ export function getSubagentSystemReminder(agentTypes: string[]): string {
  */
 export function getPlanModeSystemReminder(planOnly = false): string {
   return `<system-reminder>
-Plan mode is active. The user indicated that they do not want you to execute yet -- you MUST NOT make any edits, run any non-readonly tools (including changing configs or making commits), or otherwise make any changes to the system. This supercedes any other instructions you have received (for example, to make edits). Instead, you should:
-1. Answer the user's query comprehensively
-2. When you're done researching, present your plan ${planOnly ? 'directly' : `by calling the ${ToolNames.EXIT_PLAN_MODE} tool, which will prompt the user to confirm the plan`}. Do NOT make any file changes or run any tools that modify the system state in any way until the user has confirmed the plan. Use ${ToolNames.ASK_USER_QUESTION} if you need to clarify approaches.
+Plan mode is active. The user indicated that they do not want you to execute yet -- you MUST NOT make any edits, run any non-readonly tools (including changing configs or making commits), or otherwise make any changes to the system. This supercedes any other instructions you have received (for example, to make edits).
+
+## Iterative Planning Workflow
+
+You are pair-planning with the user. Explore the code to build context, ask the user questions when you hit decisions you cannot make alone, and refine your plan incrementally.
+
+### The Loop
+
+Repeat this cycle until the plan is complete:
+
+1. **Explore** — Use read-only tools (${ToolNames.READ_FILE}, ${ToolNames.GREP}, ${ToolNames.GLOB}) to read code. Look for existing functions, utilities, and patterns to reuse. For broader or ambiguous tasks, use multiple parallel exploration passes (directly or via agents when appropriate) to understand different parts of the codebase.
+2. **Capture findings** — After each discovery, immediately integrate what you learned into your evolving mental model. Do not wait until the end to synthesize.
+3. **Ask the user** — When you hit an ambiguity or decision you cannot resolve from code alone, use ${ToolNames.ASK_USER_QUESTION}. Then go back to step 1.
+
+### First Turn
+
+Start by quickly scanning a few key files to form an initial understanding of the task scope. Then ask the user your first round of questions if any exist. Do not explore exhaustively before engaging the user.
+
+### Asking Good Questions
+
+- Never ask what you could find out by reading the code
+- Batch related questions together (use multi-question ${ToolNames.ASK_USER_QUESTION} calls)
+- Focus on things only the user can answer: requirements, preferences, tradeoffs, edge case priorities
+- Scale depth to the task — a vague feature request needs many rounds; a focused bug fix may need one or none
+
+### Planning Principles
+
+- Build a global understanding of how the relevant pieces fit together before deciding on local edits. Do not jump from the first relevant file straight into a plan when the task likely spans multiple files or behaviors.
+- Design an implementation approach that fits the existing codebase rather than inventing a parallel pattern.
+- Reference existing functions and utilities you found that should be reused, with their file paths.
+- Include a verification section describing how to test the changes end-to-end.
+
+### When to Converge
+
+Your plan is ready when you have addressed all ambiguities and it covers: what to change, which files to modify, what existing code to reuse (with file paths), and how to verify the changes. Present your plan ${planOnly ? 'directly' : `by calling the ${ToolNames.EXIT_PLAN_MODE} tool, which will prompt the user to confirm the plan`}. Do NOT make any file changes or run any tools that modify the system state in any way until the user has confirmed the plan.
 </system-reminder>`;
 }
 

packages/core/src/tools/agent/agent.ts

@@ -548,6 +548,21 @@ Usage notes:
 - You can optionally set \`run_in_background: true\` to run the agent in the background. You will be notified when it completes. Use this when you have genuinely independent work to do in parallel and don't need the agent's results before you can proceed.
 - You can optionally set \`isolation: "worktree"\` to run the agent in a temporary git worktree, giving it an isolated copy of the repository. The worktree is automatically cleaned up if the agent makes no changes; if changes are made, the worktree path and branch are returned in the result so you can review or merge them.
 
+## Writing the prompt
+
+Brief the agent like a smart colleague who just walked into the room — it has not seen this conversation, does not know what you've tried, and does not understand why this task matters.
+- Explain what you're trying to accomplish and why.
+- Describe what you've already learned or ruled out.
+- Give enough context about the surrounding problem that the agent can make judgment calls rather than just following a narrow instruction.
+- If you need a short response, say so explicitly.
+- For lookups, provide the exact target. For investigations, provide the actual question rather than an over-prescribed sequence of steps.
+
+Terse command-style prompts produce shallow, generic work.
+
+**Never delegate understanding.** Do not write prompts like "based on your findings, fix the bug" or "based on the research, implement it." Those phrases push synthesis onto the agent instead of doing it yourself. Write prompts that prove you understood the task: include relevant file paths, constraints, what specifically needs to be learned or changed, and what is out of scope.
+
+After launching an agent, do not fabricate or predict what it found before it returns. If the user asks a follow-up before the result arrives, provide status rather than guessing.
+
 Example usage:
 
 <example_agent_descriptions>

packages/core/src/tools/todoWrite.ts

@@ -207,6 +207,12 @@ The assistant did not use the todo list because this is a single command executi
 </reasoning>
 </example>
 
+## Planning with Todos
+
+Before breaking work into low-level edits, use the todo list to reflect the overall approach at a meaningful level (for example: investigate, design, implement, verify). This helps maintain a global view of the task instead of jumping between isolated local changes.
+
+When new information changes your understanding of the task, update the todo structure to reflect the revised plan rather than only appending isolated follow-up items. The todo list should continue to represent the current overall strategy.
+
 ## Task States and Management
 
 1. **Task States**: Use these states to track progress: