From 49d55d972e3c14d58024269adcd0ec32f18e8b0c Mon Sep 17 00:00:00 2001 From: Jerop Kipruto Date: Tue, 10 Feb 2026 22:02:20 -0500 Subject: [PATCH] feat(core): formalize 5-phase sequential planning workflow (#18759) --- docs/cli/plan-mode.md | 6 ++- packages/core/src/prompts/snippets.ts | 58 +++++++++++++++++---------- 2 files changed, 41 insertions(+), 23 deletions(-) diff --git a/docs/cli/plan-mode.md b/docs/cli/plan-mode.md index 8d28994aac..0d6b72206e 100644 --- a/docs/cli/plan-mode.md +++ b/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. -4. **Review:** You review the plan. +3. **Design:** The agent proposes alternative approaches with a recommended + 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. diff --git a/packages/core/src/prompts/snippets.ts b/packages/core/src/prompts/snippets.ts index e110128c03..16b3feaa43 100644 --- a/packages/core/src/prompts/snippets.ts +++ b/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 -- Analyze the user's request to identify core requirements and constraints -- If critical information is missing or ambiguous, ask clarifying questions using the ${formatToolName(ASK_USER_TOOL_NAME)} tool -- When using ${formatToolName(ASK_USER_TOOL_NAME)}, prefer providing multiple-choice options for the user to select from when possible -- Do NOT explore the project or create a plan yet +### Phase 2: Exploration +- Only begin this phase after requirements are clear. +- Use the available read-only tools to explore the project. +- Map relevant code paths, dependencies, and architectural patterns. +- 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 -- Only begin this phase after requirements are clear -- Use the available read-only tools to explore the project -- Identify existing patterns, conventions, and architectural decisions +### Phase 3: Design +- Only begin this phase after exploration is complete. +- **Identify Approaches:** + - 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 -- Only begin this phase after exploration is complete -- Create a detailed implementation plan with clear steps -- The plan MUST include: - - Iterative development steps (e.g., "Implement X, then verify with test Y") - - Specific verification steps (unit tests, manual checks, build commands) - - File paths, function signatures, and code snippets where helpful -- Save the implementation plan to the designated plans directory +### Phase 4: Planning +- Pre-requisite: You MUST have a user-selected approach from Phase 3 before generating the plan. +- Create a detailed implementation plan and save it to the designated plans directory. +- **Document Structure:** The plan MUST be a structured Markdown document (focused on implementation guidance, not workflow logging) using exactly these H2 headings: + - \`## Problem Statement\` - Describe the problem or need this change addresses. + - \`## Proposed Solution\` - Provide technical details of the implementation. + - \`## Implementation Plan\` - List ordered steps with specific file paths and the nature of each change. + - \`## 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 rejected, address the feedback and iterate on the plan +- If plan is approved, you can begin implementation. +- If plan is rejected, address the feedback and iterate on the plan. ${renderApprovedPlanSection(options.approvedPlanPath)}