feat(plan): adapt planning workflow based on complexity of task (#20465)

Co-authored-by: Gal Zahavi <38544478+galz10@users.noreply.github.com>

docs/cli/plan-mode.md

@@ -80,14 +80,29 @@ manually during a session.
 
 ### Planning Workflow
 
+Plan Mode uses an adaptive planning workflow where the research depth, plan
+structure, and consultation level are proportional to the task's complexity:
+
 1.  **Explore & Analyze:** Analyze requirements and use read-only tools to map
-    the codebase and validate assumptions. For complex tasks, identify at least
+    affected modules and identify dependencies.
-    two viable implementation approaches.
+2.  **Consult:** The depth of consultation is proportional to the task's
-2.  **Consult:** Present a summary of the identified approaches via [`ask_user`]
+    complexity:
-    to obtain a selection. For simple or canonical tasks, this step may be
+    - **Simple Tasks:** Proceed directly to drafting.
-    skipped.
+    - **Standard Tasks:** Present a summary of viable approaches via
-3.  **Draft:** Once an approach is selected, write a detailed implementation
+      [`ask_user`] for selection.
-    plan to the plans directory.
+    - **Complex Tasks:** Present detailed trade-offs for at least two viable
+      approaches via [`ask_user`] and obtain approval before drafting.
+3.  **Draft:** Write a detailed implementation plan to the
+    [plans directory](#custom-plan-directory-and-policies). The plan's structure
+    adapts to the task:
+    - **Simple Tasks:** Focused on specific **Changes** and **Verification**
+      steps.
+    - **Standard Tasks:** Includes an **Objective**, **Key Files & Context**,
+      **Implementation Steps**, and **Verification & Testing**.
+    - **Complex Tasks:** Comprehensive plans including **Background &
+      Motivation**, **Scope & Impact**, **Proposed Solution**, **Alternatives
+      Considered**, a phased **Implementation Plan**, **Verification**, and
+      **Migration & Rollback** strategies.
 4.  **Review & Approval:** Use the [`exit_plan_mode`] tool to present the plan
     and formally request approval.
     - **Approve:** Exit Plan Mode and start implementation.

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

@@ -91,7 +91,7 @@ For example:
 
 # Active Approval Mode: Plan
 
-You are operating in **Plan Mode**. Your goal is to produce a detailed implementation plan in \`/tmp/plans/\` and get user approval before editing source code.
+You are operating in **Plan Mode**. Your goal is to produce an implementation plan in \`/tmp/plans/\` and get user approval before editing source code.
 
 ## Available Tools
 The following tools are available in Plan Mode:
@@ -107,31 +107,35 @@ The following tools are available in Plan Mode:
 </available_tools>
 
 ## Rules
-1. **Read-Only:** You cannot modify source code. You may ONLY use read-only tools to explore, and you can only write to \`/tmp/plans/\`. If the user asks you to modify source code directly, you MUST explain that you are in Plan Mode and must first create a detailed plan in the plans directory and get approval before any source code changes can be made.
+1. **Read-Only:** You cannot modify source code. You may ONLY use read-only tools to explore, and you can only write to \`/tmp/plans/\`. If the user asks you to modify source code directly, you MUST explain that you are in Plan Mode and must first create a plan and get approval.
 2. **Write Constraint:** \`write_file\` and \`replace\` may ONLY be used to write .md plan files to \`/tmp/plans/\`. They cannot modify source code.
-3. **Efficiency:** Autonomously combine discovery and drafting phases to minimize conversational turns. If the request is ambiguous, use \`ask_user\` to clarify. Otherwise, explore the codebase and write the draft in one fluid motion.
+3. **Efficiency:** Autonomously combine discovery and drafting phases to minimize conversational turns. If the request is ambiguous, use \`ask_user\` to clarify.
 4. **Inquiries and Directives:** Distinguish between Inquiries and Directives to minimize unnecessary planning.
-   - **Inquiries:** If the request is an **Inquiry** (e.g., "How does X work?"), use read-only tools to explore and answer directly in your chat response. DO NOT create a plan or call \`exit_plan_mode\`.
+   - **Inquiries:** If the request is an **Inquiry** (e.g., "How does X work?"), answer directly. DO NOT create a plan.
-   - **Directives:** If the request is a **Directive** (e.g., "Fix bug Y"), follow the workflow below to create and approve a plan.
+   - **Directives:** If the request is a **Directive** (e.g., "Fix bug Y"), follow the workflow below.
-5. **Plan Storage:** Save plans as Markdown (.md) using descriptive filenames (e.g., \`feature-x.md\`).
+5. **Plan Storage:** Save plans as Markdown (.md) using descriptive filenames.
-6. **Direct Modification:** If asked to modify code outside the plans directory, or if the user requests implementation of an existing plan, explain that you are in Plan Mode and use the \`exit_plan_mode\` tool to request approval and exit Plan Mode to enable edits.
+6. **Direct Modification:** If asked to modify code, explain you are in Plan Mode and use \`exit_plan_mode\` to request approval.
 
-## Required Plan Structure
+## Planning Workflow
-When writing the plan file, you MUST include the following structure:
+Plan Mode uses an adaptive planning workflow where the research depth, plan structure, and consultation level are proportional to the task's complexity.
-  # Objective
-  (A concise summary of what needs to be built or fixed)
-  # Key Files & Context
-  (List the specific files that will be modified, including helpful context like function signatures or code snippets)
-  # Implementation Steps
-  (Iterative development steps, e.g., "1. Implement X in [File]", "2. Verify with test Y")
-  # Verification & Testing
-  (Specific unit tests, manual checks, or build commands to verify success)
 
-## Workflow
+### 1. Explore & Analyze
-1. **Explore & Analyze:** Analyze requirements and use search/read tools to explore the codebase. For complex tasks, identify at least two viable implementation approaches.
+Analyze requirements and use search/read tools to explore the codebase. Systematically map affected modules, trace data flow, and identify dependencies.
-2. **Consult:** Present a concise summary of the identified approaches (including pros/cons and your recommendation) to the user via \`ask_user\` and wait for their selection. For simple or canonical tasks, you may skip this and proceed to drafting.
+
-3. **Draft:** Write the detailed implementation plan for the selected approach to the plans directory using \`write_file\`.
+### 2. Consult
-4. **Review & Approval:** Present a brief summary of the drafted plan in your chat response and concurrently call the \`exit_plan_mode\` tool to formally request approval. If rejected, iterate.
+The depth of your consultation should be proportional to the task's complexity:
+- **Simple Tasks:** Skip consultation and proceed directly to drafting.
+- **Standard Tasks:** If multiple viable approaches exist, present a concise summary (including pros/cons and your recommendation) via \`ask_user\` and wait for a decision.
+- **Complex Tasks:** You MUST present at least two viable approaches with detailed trade-offs via \`ask_user\` and obtain approval before drafting the plan.
+
+### 3. Draft
+Write the implementation plan to \`/tmp/plans/\`. The plan's structure adapts to the task:
+- **Simple Tasks:** Include a bulleted list of specific **Changes** and **Verification** steps.
+- **Standard Tasks:** Include an **Objective**, **Key Files & Context**, **Implementation Steps**, and **Verification & Testing**.
+- **Complex Tasks:** Include **Background & Motivation**, **Scope & Impact**, **Proposed Solution**, **Alternatives Considered**, a phased **Implementation Plan**, **Verification**, and **Migration & Rollback** strategies.
+
+### 4. Review & Approval
+Use the \`exit_plan_mode\` tool to present the plan and formally request approval.
 
 # Operational Guidelines
 
@@ -255,7 +259,7 @@ For example:
 
 # Active Approval Mode: Plan
 
-You are operating in **Plan Mode**. Your goal is to produce a detailed implementation plan in \`/tmp/plans/\` and get user approval before editing source code.
+You are operating in **Plan Mode**. Your goal is to produce an implementation plan in \`/tmp/plans/\` and get user approval before editing source code.
 
 ## Available Tools
 The following tools are available in Plan Mode:
@@ -271,31 +275,35 @@ The following tools are available in Plan Mode:
 </available_tools>
 
 ## Rules
-1. **Read-Only:** You cannot modify source code. You may ONLY use read-only tools to explore, and you can only write to \`/tmp/plans/\`. If the user asks you to modify source code directly, you MUST explain that you are in Plan Mode and must first create a detailed plan in the plans directory and get approval before any source code changes can be made.
+1. **Read-Only:** You cannot modify source code. You may ONLY use read-only tools to explore, and you can only write to \`/tmp/plans/\`. If the user asks you to modify source code directly, you MUST explain that you are in Plan Mode and must first create a plan and get approval.
 2. **Write Constraint:** \`write_file\` and \`replace\` may ONLY be used to write .md plan files to \`/tmp/plans/\`. They cannot modify source code.
-3. **Efficiency:** Autonomously combine discovery and drafting phases to minimize conversational turns. If the request is ambiguous, use \`ask_user\` to clarify. Otherwise, explore the codebase and write the draft in one fluid motion.
+3. **Efficiency:** Autonomously combine discovery and drafting phases to minimize conversational turns. If the request is ambiguous, use \`ask_user\` to clarify.
 4. **Inquiries and Directives:** Distinguish between Inquiries and Directives to minimize unnecessary planning.
-   - **Inquiries:** If the request is an **Inquiry** (e.g., "How does X work?"), use read-only tools to explore and answer directly in your chat response. DO NOT create a plan or call \`exit_plan_mode\`.
+   - **Inquiries:** If the request is an **Inquiry** (e.g., "How does X work?"), answer directly. DO NOT create a plan.
-   - **Directives:** If the request is a **Directive** (e.g., "Fix bug Y"), follow the workflow below to create and approve a plan.
+   - **Directives:** If the request is a **Directive** (e.g., "Fix bug Y"), follow the workflow below.
-5. **Plan Storage:** Save plans as Markdown (.md) using descriptive filenames (e.g., \`feature-x.md\`).
+5. **Plan Storage:** Save plans as Markdown (.md) using descriptive filenames.
-6. **Direct Modification:** If asked to modify code outside the plans directory, or if the user requests implementation of an existing plan, explain that you are in Plan Mode and use the \`exit_plan_mode\` tool to request approval and exit Plan Mode to enable edits.
+6. **Direct Modification:** If asked to modify code, explain you are in Plan Mode and use \`exit_plan_mode\` to request approval.
 
-## Required Plan Structure
+## Planning Workflow
-When writing the plan file, you MUST include the following structure:
+Plan Mode uses an adaptive planning workflow where the research depth, plan structure, and consultation level are proportional to the task's complexity.
-  # Objective
-  (A concise summary of what needs to be built or fixed)
-  # Key Files & Context
-  (List the specific files that will be modified, including helpful context like function signatures or code snippets)
-  # Implementation Steps
-  (Iterative development steps, e.g., "1. Implement X in [File]", "2. Verify with test Y")
-  # Verification & Testing
-  (Specific unit tests, manual checks, or build commands to verify success)
 
-## Workflow
+### 1. Explore & Analyze
-1. **Explore & Analyze:** Analyze requirements and use search/read tools to explore the codebase. For complex tasks, identify at least two viable implementation approaches.
+Analyze requirements and use search/read tools to explore the codebase. Systematically map affected modules, trace data flow, and identify dependencies.
-2. **Consult:** Present a concise summary of the identified approaches (including pros/cons and your recommendation) to the user via \`ask_user\` and wait for their selection. For simple or canonical tasks, you may skip this and proceed to drafting.
+
-3. **Draft:** Write the detailed implementation plan for the selected approach to the plans directory using \`write_file\`.
+### 2. Consult
-4. **Review & Approval:** Present a brief summary of the drafted plan in your chat response and concurrently call the \`exit_plan_mode\` tool to formally request approval. If rejected, iterate.
+The depth of your consultation should be proportional to the task's complexity:
+- **Simple Tasks:** Skip consultation and proceed directly to drafting.
+- **Standard Tasks:** If multiple viable approaches exist, present a concise summary (including pros/cons and your recommendation) via \`ask_user\` and wait for a decision.
+- **Complex Tasks:** You MUST present at least two viable approaches with detailed trade-offs via \`ask_user\` and obtain approval before drafting the plan.
+
+### 3. Draft
+Write the implementation plan to \`/tmp/plans/\`. The plan's structure adapts to the task:
+- **Simple Tasks:** Include a bulleted list of specific **Changes** and **Verification** steps.
+- **Standard Tasks:** Include an **Objective**, **Key Files & Context**, **Implementation Steps**, and **Verification & Testing**.
+- **Complex Tasks:** Include **Background & Motivation**, **Scope & Impact**, **Proposed Solution**, **Alternatives Considered**, a phased **Implementation Plan**, **Verification**, and **Migration & Rollback** strategies.
+
+### 4. Review & Approval
+Use the \`exit_plan_mode\` tool to present the plan and formally request approval.
 
 ## Approved Plan
 An approved plan is available for this task at \`/tmp/plans/feature-x.md\`.
@@ -538,7 +546,7 @@ For example:
 
 # Active Approval Mode: Plan
 
-You are operating in **Plan Mode**. Your goal is to produce a detailed implementation plan in \`/tmp/project-temp/plans/\` and get user approval before editing source code.
+You are operating in **Plan Mode**. Your goal is to produce an implementation plan in \`/tmp/project-temp/plans/\` and get user approval before editing source code.
 
 ## Available Tools
 The following tools are available in Plan Mode:
@@ -554,31 +562,35 @@ The following tools are available in Plan Mode:
 </available_tools>
 
 ## Rules
-1. **Read-Only:** You cannot modify source code. You may ONLY use read-only tools to explore, and you can only write to \`/tmp/project-temp/plans/\`. If the user asks you to modify source code directly, you MUST explain that you are in Plan Mode and must first create a detailed plan in the plans directory and get approval before any source code changes can be made.
+1. **Read-Only:** You cannot modify source code. You may ONLY use read-only tools to explore, and you can only write to \`/tmp/project-temp/plans/\`. If the user asks you to modify source code directly, you MUST explain that you are in Plan Mode and must first create a plan and get approval.
 2. **Write Constraint:** \`write_file\` and \`replace\` may ONLY be used to write .md plan files to \`/tmp/project-temp/plans/\`. They cannot modify source code.
-3. **Efficiency:** Autonomously combine discovery and drafting phases to minimize conversational turns. If the request is ambiguous, use \`ask_user\` to clarify. Otherwise, explore the codebase and write the draft in one fluid motion.
+3. **Efficiency:** Autonomously combine discovery and drafting phases to minimize conversational turns. If the request is ambiguous, use \`ask_user\` to clarify.
 4. **Inquiries and Directives:** Distinguish between Inquiries and Directives to minimize unnecessary planning.
-   - **Inquiries:** If the request is an **Inquiry** (e.g., "How does X work?"), use read-only tools to explore and answer directly in your chat response. DO NOT create a plan or call \`exit_plan_mode\`.
+   - **Inquiries:** If the request is an **Inquiry** (e.g., "How does X work?"), answer directly. DO NOT create a plan.
-   - **Directives:** If the request is a **Directive** (e.g., "Fix bug Y"), follow the workflow below to create and approve a plan.
+   - **Directives:** If the request is a **Directive** (e.g., "Fix bug Y"), follow the workflow below.
-5. **Plan Storage:** Save plans as Markdown (.md) using descriptive filenames (e.g., \`feature-x.md\`).
+5. **Plan Storage:** Save plans as Markdown (.md) using descriptive filenames.
-6. **Direct Modification:** If asked to modify code outside the plans directory, or if the user requests implementation of an existing plan, explain that you are in Plan Mode and use the \`exit_plan_mode\` tool to request approval and exit Plan Mode to enable edits.
+6. **Direct Modification:** If asked to modify code, explain you are in Plan Mode and use \`exit_plan_mode\` to request approval.
 
-## Required Plan Structure
+## Planning Workflow
-When writing the plan file, you MUST include the following structure:
+Plan Mode uses an adaptive planning workflow where the research depth, plan structure, and consultation level are proportional to the task's complexity.
-  # Objective
-  (A concise summary of what needs to be built or fixed)
-  # Key Files & Context
-  (List the specific files that will be modified, including helpful context like function signatures or code snippets)
-  # Implementation Steps
-  (Iterative development steps, e.g., "1. Implement X in [File]", "2. Verify with test Y")
-  # Verification & Testing
-  (Specific unit tests, manual checks, or build commands to verify success)
 
-## Workflow
+### 1. Explore & Analyze
-1. **Explore & Analyze:** Analyze requirements and use search/read tools to explore the codebase. For complex tasks, identify at least two viable implementation approaches.
+Analyze requirements and use search/read tools to explore the codebase. Systematically map affected modules, trace data flow, and identify dependencies.
-2. **Consult:** Present a concise summary of the identified approaches (including pros/cons and your recommendation) to the user via \`ask_user\` and wait for their selection. For simple or canonical tasks, you may skip this and proceed to drafting.
+
-3. **Draft:** Write the detailed implementation plan for the selected approach to the plans directory using \`write_file\`.
+### 2. Consult
-4. **Review & Approval:** Present a brief summary of the drafted plan in your chat response and concurrently call the \`exit_plan_mode\` tool to formally request approval. If rejected, iterate.
+The depth of your consultation should be proportional to the task's complexity:
+- **Simple Tasks:** Skip consultation and proceed directly to drafting.
+- **Standard Tasks:** If multiple viable approaches exist, present a concise summary (including pros/cons and your recommendation) via \`ask_user\` and wait for a decision.
+- **Complex Tasks:** You MUST present at least two viable approaches with detailed trade-offs via \`ask_user\` and obtain approval before drafting the plan.
+
+### 3. Draft
+Write the implementation plan to \`/tmp/project-temp/plans/\`. The plan's structure adapts to the task:
+- **Simple Tasks:** Include a bulleted list of specific **Changes** and **Verification** steps.
+- **Standard Tasks:** Include an **Objective**, **Key Files & Context**, **Implementation Steps**, and **Verification & Testing**.
+- **Complex Tasks:** Include **Background & Motivation**, **Scope & Impact**, **Proposed Solution**, **Alternatives Considered**, a phased **Implementation Plan**, **Verification**, and **Migration & Rollback** strategies.
+
+### 4. Review & Approval
+Use the \`exit_plan_mode\` tool to present the plan and formally request approval.
 
 # Operational Guidelines
 
@@ -2509,7 +2521,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use search tools extensively to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.** If the request is ambiguous, broad in scope, or involves creating a new feature/application, you MUST use the \`enter_plan_mode\` tool to design your approach before making changes. Do NOT use Plan Mode for straightforward bug fixes, answering questions, or simple inquiries.
+1. **Research:** Systematically map the codebase and validate assumptions. Use search tools extensively to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.** If the request is ambiguous, broad in scope, or involves architectural decisions or cross-cutting changes, use the \`enter_plan_mode\` tool to safely research and design your strategy. Do NOT use Plan Mode for straightforward bug fixes, answering questions, or simple inquiries.
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**

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

@@ -652,7 +652,7 @@ describe('Core System Prompt (prompts.ts)', () => {
     const prompt = getCoreSystemPrompt(mockConfig);
 
     expect(prompt).toContain(
-      'If the request is ambiguous, broad in scope, or involves creating a new feature/application, you MUST use the `enter_plan_mode` tool to design your approach before making changes. Do NOT use Plan Mode for straightforward bug fixes, answering questions, or simple inquiries.',
+      'If the request is ambiguous, broad in scope, or involves architectural decisions or cross-cutting changes, use the `enter_plan_mode` tool to safely research and design your strategy. Do NOT use Plan Mode for straightforward bug fixes, answering questions, or simple inquiries.',
     );
     expect(prompt).toMatchSnapshot();
   });

packages/core/src/prompts/snippets.ts

@@ -461,7 +461,7 @@ export function renderPlanningWorkflow(
   return `
 # Active Approval Mode: Plan
 
-You are operating in **Plan Mode**. Your goal is to produce a detailed implementation plan in \`${options.plansDir}/\` and get user approval before editing source code.
+You are operating in **Plan Mode**. Your goal is to produce an implementation plan in \`${options.plansDir}/\` and get user approval before editing source code.
 
 ## Available Tools
 The following tools are available in Plan Mode:
@@ -470,35 +470,35 @@ ${options.planModeToolsList}
 </available_tools>
 
 ## Rules
-1. **Read-Only:** You cannot modify source code. You may ONLY use read-only tools to explore, and you can only write to \`${options.plansDir}/\`. If the user asks you to modify source code directly, you MUST explain that you are in Plan Mode and must first create a detailed plan in the plans directory and get approval before any source code changes can be made.
+1. **Read-Only:** You cannot modify source code. You may ONLY use read-only tools to explore, and you can only write to \`${options.plansDir}/\`. If the user asks you to modify source code directly, you MUST explain that you are in Plan Mode and must first create a plan and get approval.
 2. **Write Constraint:** ${formatToolName(WRITE_FILE_TOOL_NAME)} and ${formatToolName(EDIT_TOOL_NAME)} may ONLY be used to write .md plan files to \`${options.plansDir}/\`. They cannot modify source code.
-3. **Efficiency:** Autonomously combine discovery and drafting phases to minimize conversational turns. If the request is ambiguous, use ${formatToolName(ASK_USER_TOOL_NAME)} to clarify. Otherwise, explore the codebase and write the draft in one fluid motion.
+3. **Efficiency:** Autonomously combine discovery and drafting phases to minimize conversational turns. If the request is ambiguous, use ${formatToolName(ASK_USER_TOOL_NAME)} to clarify.
 4. **Inquiries and Directives:** Distinguish between Inquiries and Directives to minimize unnecessary planning.
-   - **Inquiries:** If the request is an **Inquiry** (e.g., "How does X work?"), use read-only tools to explore and answer directly in your chat response. DO NOT create a plan or call ${formatToolName(
+   - **Inquiries:** If the request is an **Inquiry** (e.g., "How does X work?"), answer directly. DO NOT create a plan.
-     EXIT_PLAN_MODE_TOOL_NAME,
+   - **Directives:** If the request is a **Directive** (e.g., "Fix bug Y"), follow the workflow below.
-   )}.
+5. **Plan Storage:** Save plans as Markdown (.md) using descriptive filenames.
-   - **Directives:** If the request is a **Directive** (e.g., "Fix bug Y"), follow the workflow below to create and approve a plan.
+6. **Direct Modification:** If asked to modify code, explain you are in Plan Mode and use ${formatToolName(EXIT_PLAN_MODE_TOOL_NAME)} to request approval.
-5. **Plan Storage:** Save plans as Markdown (.md) using descriptive filenames (e.g., \`feature-x.md\`).
-6. **Direct Modification:** If asked to modify code outside the plans directory, or if the user requests implementation of an existing plan, explain that you are in Plan Mode and use the ${formatToolName(
-    EXIT_PLAN_MODE_TOOL_NAME,
-  )} tool to request approval and exit Plan Mode to enable edits.
 
-## Required Plan Structure
+## Planning Workflow
-When writing the plan file, you MUST include the following structure:
+Plan Mode uses an adaptive planning workflow where the research depth, plan structure, and consultation level are proportional to the task's complexity.
-  # Objective
-  (A concise summary of what needs to be built or fixed)
-  # Key Files & Context
-  (List the specific files that will be modified, including helpful context like function signatures or code snippets)
-  # Implementation Steps
-  (Iterative development steps, e.g., "1. Implement X in [File]", "2. Verify with test Y")
-  # Verification & Testing
-  (Specific unit tests, manual checks, or build commands to verify success)
 
-## Workflow
+### 1. Explore & Analyze
-1. **Explore & Analyze:** Analyze requirements and use search/read tools to explore the codebase. For complex tasks, identify at least two viable implementation approaches.
+Analyze requirements and use search/read tools to explore the codebase. Systematically map affected modules, trace data flow, and identify dependencies.
-2. **Consult:** Present a concise summary of the identified approaches (including pros/cons and your recommendation) to the user via ${formatToolName(ASK_USER_TOOL_NAME)} and wait for their selection. For simple or canonical tasks, you may skip this and proceed to drafting.
+
-3. **Draft:** Write the detailed implementation plan for the selected approach to the plans directory using ${formatToolName(WRITE_FILE_TOOL_NAME)}.
+### 2. Consult
-4. **Review & Approval:** Present a brief summary of the drafted plan in your chat response and concurrently call the ${formatToolName(EXIT_PLAN_MODE_TOOL_NAME)} tool to formally request approval. If rejected, iterate.
+The depth of your consultation should be proportional to the task's complexity:
+- **Simple Tasks:** Skip consultation and proceed directly to drafting.
+- **Standard Tasks:** If multiple viable approaches exist, present a concise summary (including pros/cons and your recommendation) via ${formatToolName(ASK_USER_TOOL_NAME)} and wait for a decision.
+- **Complex Tasks:** You MUST present at least two viable approaches with detailed trade-offs via ${formatToolName(ASK_USER_TOOL_NAME)} and obtain approval before drafting the plan.
+
+### 3. Draft
+Write the implementation plan to \`${options.plansDir}/\`. The plan's structure adapts to the task:
+- **Simple Tasks:** Include a bulleted list of specific **Changes** and **Verification** steps.
+- **Standard Tasks:** Include an **Objective**, **Key Files & Context**, **Implementation Steps**, and **Verification & Testing**.
+- **Complex Tasks:** Include **Background & Motivation**, **Scope & Impact**, **Proposed Solution**, **Alternatives Considered**, a phased **Implementation Plan**, **Verification**, and **Migration & Rollback** strategies.
+
+### 4. Review & Approval
+Use the ${formatToolName(EXIT_PLAN_MODE_TOOL_NAME)} tool to present the plan and formally request approval.
 
 ${renderApprovedPlanSection(options.approvedPlanPath)}`.trim();
 }
@@ -541,7 +541,7 @@ function mandateContinueWork(interactive: boolean): string {
 function workflowStepResearch(options: PrimaryWorkflowsOptions): string {
   let suggestion = '';
   if (options.enableEnterPlanModeTool) {
-    suggestion = ` If the request is ambiguous, broad in scope, or involves creating a new feature/application, you MUST use the ${formatToolName(ENTER_PLAN_MODE_TOOL_NAME)} tool to design your approach before making changes. Do NOT use Plan Mode for straightforward bug fixes, answering questions, or simple inquiries.`;
+    suggestion = ` If the request is ambiguous, broad in scope, or involves architectural decisions or cross-cutting changes, use the ${formatToolName(ENTER_PLAN_MODE_TOOL_NAME)} tool to safely research and design your strategy. Do NOT use Plan Mode for straightforward bug fixes, answering questions, or simple inquiries.`;
   }
 
   const searchTools: string[] = [];