feat(core): formalize 5-phase sequential planning workflow (#18759)

docs/cli/plan-mode.md

@@ -68,8 +68,10 @@ You can enter Plan Mode in three ways:
 1.  **Requirements:** The agent clarifies goals using `ask_user`.
 2.  **Exploration:** The agent uses read-only tools (like [`read_file`]) to map
     the codebase and validate assumptions.
-3.  **Planning:** A detailed plan is written to a temporary Markdown file.
+3.  **Design:** The agent proposes alternative approaches with a recommended
-4.  **Review:** You review the plan.
+    solution for you to choose from.
+4.  **Planning:** A detailed plan is written to a temporary Markdown file.
+5.  **Review:** You review the plan.
     - **Approve:** Exit Plan Mode and start implementation (switching to
       Auto-Edit or Default approval mode).
     - **Iterate:** Provide feedback to refine the plan.

packages/core/src/prompts/snippets.ts

@@ -428,34 +428,50 @@ ${options.planModeToolsList}
 - You are restricted to writing files within this directory while in Plan Mode.
 - Use descriptive filenames: \`feature-name.md\` or \`bugfix-description.md\`
 
+## Workflow Rules
+1.  Sequential Execution: Complete ONE phase at a time. Do NOT skip ahead or combine phases.
+2.  User Confirmation: Wait for user input/approval before proceeding to the next phase.
+3.  Step Back Protocol: If new information discovered during Exploration or Design invalidates previous assumptions or requirements, you MUST pause, inform the user, and request to return to the appropriate previous phase.
+
 ## Workflow Phases
 
-**IMPORTANT: Complete ONE phase at a time. Do NOT skip ahead or combine phases. Wait for user input before proceeding to the next phase.**
+### Phase 1: Requirements
+- Analyze the user's request to identify core requirements and constraints.
+- Proactively identify ambiguities, implicit assumptions, and edge cases.
+- Categorize questions: functional requirements, non-functional constraints (performance, compatibility), and scope boundaries.
+- Use the ${formatToolName(ASK_USER_TOOL_NAME)} tool with well-structured options to clarify ambiguities. Prefer providing multiple-choice options for the user to select from when possible.
 
-### Phase 1: Requirements Understanding
+### Phase 2: Exploration
-- Analyze the user's request to identify core requirements and constraints
+- Only begin this phase after requirements are clear.
-- If critical information is missing or ambiguous, ask clarifying questions using the ${formatToolName(ASK_USER_TOOL_NAME)} tool
+- Use the available read-only tools to explore the project.
-- When using ${formatToolName(ASK_USER_TOOL_NAME)}, prefer providing multiple-choice options for the user to select from when possible
+- Map relevant code paths, dependencies, and architectural patterns.
-- Do NOT explore the project or create a plan yet
+- Identify existing utilities, patterns, and abstractions that can be reused.
+- Note potential constraints (e.g., existing conventions, test infrastructure).
+- Output: Summarize key findings to the user before proceeding to design.
 
-### Phase 2: Project Exploration
+### Phase 3: Design
-- Only begin this phase after requirements are clear
+- Only begin this phase after exploration is complete.
-- Use the available read-only tools to explore the project
+- **Identify Approaches:**
-- Identify existing patterns, conventions, and architectural decisions
+    - For Complex Tasks: Identify at least 2 viable implementation approaches. Document the approach summary, pros, cons, complexity estimate, and risk factors for each.
+    - For Canonical Tasks: If there is only one reasonable, standard approach (e.g., a standard library pattern or specific bug fix), detail it and explicitly explain why no other viable alternatives were considered.
+- Mandatory User Interaction: Present the analysis to the user via ${formatToolName(ASK_USER_TOOL_NAME)} and recommend a preferred approach.
+- Wait for Selection: You MUST pause and wait for the user to select an approach before proceeding. Do NOT assume the user will agree with your recommendation.
 
-### Phase 3: Design & Planning
+### Phase 4: Planning
-- Only begin this phase after exploration is complete
+- Pre-requisite: You MUST have a user-selected approach from Phase 3 before generating the plan.
-- Create a detailed implementation plan with clear steps
+- Create a detailed implementation plan and save it to the designated plans directory.
-- The plan MUST include:
+- **Document Structure:** The plan MUST be a structured Markdown document (focused on implementation guidance, not workflow logging) using exactly these H2 headings:
-  - Iterative development steps (e.g., "Implement X, then verify with test Y")
+  - \`## Problem Statement\` - Describe the problem or need this change addresses.
-  - Specific verification steps (unit tests, manual checks, build commands)
+  - \`## Proposed Solution\` - Provide technical details of the implementation.
-  - File paths, function signatures, and code snippets where helpful
+  - \`## Implementation Plan\` - List ordered steps with specific file paths and the nature of each change.
-- Save the implementation plan to the designated plans directory
+  - \`## Verification Plan\` - Define specific tests or manual steps to verify the change works and breaks nothing else.
+  - \`## Risks & Mitigations\` - Identify potential failure modes and mitigation strategies.
+  - \`## Alternatives Considered\` - Provide a brief analysis of other approaches considered and why they were rejected.
 
-### Phase 4: Review & Approval
+### Phase 5: Approval
 - Present the plan and request approval for the finalized plan using the ${formatToolName(EXIT_PLAN_MODE_TOOL_NAME)} tool
-- If plan is approved, you can begin implementation
+- If plan is approved, you can begin implementation.
-- If plan is rejected, address the feedback and iterate on the plan
+- If plan is rejected, address the feedback and iterate on the plan.
 
 ${renderApprovedPlanSection(options.approvedPlanPath)}