Refactor plan file template for clarity and structure

Author: vinhnx

docs/guides/PLAN_MODE.md

@@ -44,47 +44,28 @@ vtcode --permission-mode plan
 1. **Start in Plan Mode**: `vtcode --permission-mode plan`
 2. **Describe your goal**: Explain what you want to build or change
 3. **Iterate on the plan**: Ask clarifying questions, explore files, refine the approach
-4. **Review the plan**: The agent emits a structured reasoning + decision log, then one `<proposed_plan>` block
+4. **Review the plan**: The agent captures repository facts, closes any open decisions, then emits one `<proposed_plan>` block
 5. **Choose next action**: Use the implementation prompt to switch to Edit mode or continue planning (fallback: manually switch with `/plan off` or `/mode`, or `Shift+Tab`/`Alt+M`)
 6. **Execute the plan**: If approved, coding proceeds in Edit mode
 
 ## Plan Output Format
 
-When in Plan Mode, the agent should follow this exact structure:
+When in Plan Mode, the agent should keep the output decision-complete but sparse:
 
 ```markdown
-• Scope checkpoint: [what is locked] / [what remains open].
-• Decision needed: [single high-impact choice] and why it affects
-implementation.
+Repository facts checked:
+- [file, symbol, or behavior confirmed from the repo]
+- [existing pattern or constraint verified before planning]
 
-• Questions 1/1 answered
-• [exact question text]
-answer: [selected option label]
-
-• Locked decision: [choice], so implementation will [concrete consequence].
-• Next open decision: [if any], otherwise: "No remaining scope decisions;
-drafting final plan."
+Next open decision: [if any], otherwise: No remaining scope decisions.
 
 <proposed_plan>
-• Proposed Plan
-
-
 # [Task Title]
 
 ## Summary
 [2-4 lines: goal, user impact, what will change, what will not]
 
-## Scope Locked
-1. [Decision A]
-2. [Decision B]
-3. [Decision C]
-
-## Public API / Interface Changes
-1. [Removed/added/changed API, command, config, schema]
-2. [Tooling/runtime behavior changes]
-3. [Compatibility or break behavior]
-
-## Implementation Plan
+## Implementation Steps
 1. [Step] -> files: [paths] -> verify: [check]
 2. [Step] -> files: [paths] -> verify: [check]
 3. [Step] -> files: [paths] -> verify: [check]
@@ -93,15 +74,14 @@ drafting final plan."
 1. Build and lint: [project build and lint command(s) based on detected toolchain]
 2. Tests: [project test command(s) based on detected toolchain]
 3. Targeted behavior checks: [explicit commands/manual checks]
-4. Regression checks: [what must not break]
 
 ## Assumptions and Defaults
 1. [Explicit assumption]
 2. [Default chosen when user did not specify]
 3. [Out-of-scope items intentionally not changed]
 </proposed_plan>
 
-> Note: Edit this plan directly at `[plan file path]`.
+Only `Next open decision` is used as the explicit reopen marker for follow-up planning.
 ```
 
 ## Plan Review Gate

src/agent/runloop/unified/incremental_system_prompt_tests.rs

@@ -450,8 +450,9 @@ async fn test_plan_mode_notice_appended() {
     assert!(prompt.contains(vtcode_core::prompts::system::PLAN_MODE_READ_ONLY_HEADER));
     assert!(prompt.contains(vtcode_core::prompts::system::PLAN_MODE_EXIT_INSTRUCTION_LINE));
     assert!(prompt.contains(vtcode_core::prompts::system::PLAN_MODE_PLAN_QUALITY_LINE));
-    assert!(prompt.contains("Scope checkpoint"));
-    assert!(prompt.contains("• Proposed Plan"));
+    assert!(prompt.contains("<proposed_plan>"));
+    assert!(prompt.contains("Next open decision"));
+    assert!(!prompt.contains("Scope checkpoint"));
     assert!(prompt.contains(vtcode_core::prompts::system::PLAN_MODE_NO_AUTO_EXIT_LINE));
     assert!(prompt.contains(vtcode_core::prompts::system::PLAN_MODE_TASK_TRACKER_LINE));
 }

src/agent/runloop/unified/turn/turn_processing/plan_mode.rs

@@ -449,11 +449,6 @@ pub(crate) fn maybe_force_plan_mode_interview(
 }
 
 fn has_open_decision_markers(text: &str) -> bool {
-    let lowered = text.to_ascii_lowercase();
-    if contains_any(&lowered, &["to be decided", "tbd", "pending decision"]) {
-        return true;
-    }
-
     text.lines().any(line_has_open_decision_marker)
 }
 
@@ -464,22 +459,15 @@ fn line_has_open_decision_marker(line: &str) -> bool {
     }
 
     let lower = trimmed.to_ascii_lowercase();
-    if !contains_any(
-        &lower,
-        &[
-            "decision needed",
-            "next open decision",
-            "open question",
-            "unresolved decision",
-        ],
-    ) {
+    if !lower.contains("next open decision") {
         return false;
     }
 
     !contains_any(
         &lower,
         &[
             "none",
+            "no remaining",
             "no further",
             "resolved",
             "closed",

src/agent/runloop/unified/turn/turn_processing/plan_mode/tests.rs

@@ -488,6 +488,20 @@ fn collect_interview_research_context_includes_custom_note_policy() {
     );
 }
 
+#[test]
+fn line_has_open_decision_marker_only_tracks_next_open_decision() {
+    assert!(line_has_open_decision_marker(
+        "Next open decision: validate migration order"
+    ));
+    assert!(!line_has_open_decision_marker(
+        "Decision needed: choose validation scope"
+    ));
+    assert!(!line_has_open_decision_marker("Next open decision: none"));
+    assert!(!line_has_open_decision_marker(
+        "Next open decision: No remaining scope decisions."
+    ));
+}
+
 #[test]
 fn collect_interview_research_context_extracts_recent_paths_and_symbols() {
     let stats = SessionStats::default();

src/agent/runloop/unified/turn/turn_processing/response_processing.rs

@@ -672,43 +672,30 @@ mod tests {
     }
 
     #[test]
-    fn process_llm_response_golden_transcript_requires_kiss_dry_plan_sections() {
+    fn process_llm_response_extracts_sparse_proposed_plan_blocks() {
         let response = LLMResponse {
             content: Some(
                 r#"Intro
+Next open decision: none.
 <proposed_plan>
-• Proposed Plan
-
-# Enforce Plan Mode Blueprint
+# Apply Slate-Style Prompting
 
 ## Summary
-Make Plan Mode output deterministic by enforcing one shared blueprint for reasoning logs and final plans.
-
-## Scope Locked
-1. Use hard contract enforcement.
-2. Keep the 4-way HITL gate text.
-3. Remove legacy section contract tests.
-
-## Public API / Interface Changes
-1. Update plan prompt contract wording.
-2. Update Plan Mode scaffold template.
-3. Treat old section contract checks as deprecated.
+Keep the default runtime prompt sparse and consistent with Plan Mode.
 
-## Implementation Plan
+## Implementation Steps
 1. Update prompt constants -> files: [vtcode-core/src/prompts/system.rs] -> verify: [cargo check]
-2. Update template + docs -> files: [vtcode-core/src/tools/handlers/plan_mode.rs, docs/guides/PLAN_MODE.md] -> verify: [cargo check]
-3. Update tests -> files: [src/agent/runloop/unified/turn/turn_processing/response_processing.rs] -> verify: [cargo test -p vtcode process_llm_response_golden_transcript_requires_kiss_dry_plan_sections -- --nocapture]
+2. Update plan scaffold -> files: [vtcode-core/src/tools/handlers/plan_mode.rs] -> verify: [cargo test -p vtcode-core test_enter_plan_mode -- --nocapture]
+3. Update parser tests -> files: [src/agent/runloop/unified/turn/turn_processing/response_processing.rs] -> verify: [cargo test -p vtcode process_llm_response_extracts_sparse_proposed_plan_blocks -- --nocapture]
 
 ## Test Cases and Validation
 1. Build and lint: [project build and lint command(s) based on detected toolchain]
 2. Tests: [project test command(s) based on detected toolchain]
-3. Targeted behavior checks: plan-mode transcript checks
-4. Regression checks: proposed plan extraction still strips wrapper tags only
+3. Targeted behavior checks: plan-mode transcript extraction
 
 ## Assumptions and Defaults
-1. Title/content can vary, section headers stay fixed.
-2. Reasoning log appears before proposed plan.
-3. Non-plan execution flow remains unchanged.
+1. `Next open decision` remains the only explicit reopen marker.
+2. The proposed plan stays decision-complete without rigid extra sections.
 </proposed_plan>
 Outro"#
                     .to_string(),
@@ -737,11 +724,8 @@ Outro"#
             } => {
                 let plan = proposed_plan.expect("expected extracted proposed plan");
                 for required_section in [
-                    "• Proposed Plan",
                     "## Summary",
-                    "## Scope Locked",
-                    "## Public API / Interface Changes",
-                    "## Implementation Plan",
+                    "## Implementation Steps",
                     "## Test Cases and Validation",
                     "## Assumptions and Defaults",
                 ] {
@@ -750,6 +734,8 @@ Outro"#
                         "proposed_plan missing required section: {required_section}"
                     );
                 }
+                assert!(!plan.contains("## Scope Locked"));
+                assert!(!plan.contains("## Public API / Interface Changes"));
                 assert!(!text.contains("<proposed_plan>"));
                 assert!(text.contains("Intro"));
                 assert!(text.contains("Outro"));

src/agent/runloop/welcome.rs

@@ -73,6 +73,7 @@ pub(crate) async fn prepare_session_bootstrap(
             &onboarding_cfg,
             language_summary.as_deref(),
             guideline_highlights.as_deref(),
+            todo_planning_enabled,
         )
     } else {
         None
@@ -331,6 +332,7 @@ fn build_prompt_addendum(
     onboarding_cfg: &AgentOnboardingConfig,
     language_summary: Option<&str>,
     guideline_highlights: Option<&[String]>,
+    todo_planning_enabled: bool,
 ) -> Option<String> {
     let mut lines = Vec::with_capacity(15); // Estimate 15 lines for prompt addendum
     lines.push("## SESSION CONTEXT".to_string());
@@ -352,6 +354,11 @@ fn build_prompt_addendum(
         }
     }
 
+    if todo_planning_enabled {
+        lines.push("### Workflow Hint".to_string());
+        lines.push("- Start with the goal, use `@file` or IDE context to focus, switch to Plan Mode for research/spec work, and use `task_tracker` for multi-step execution.".to_string());
+    }
+
     push_prompt_usage_tips(&mut lines, &onboarding_cfg.usage_tips);
     push_prompt_recommended_actions(&mut lines, &onboarding_cfg.recommended_actions);
 

src/agent/runloop/welcome_tests.rs

@@ -110,6 +110,10 @@ async fn test_prepare_session_bootstrap_builds_sections() {
 
     let prompt = bootstrap.prompt_addendum.expect("prompt addendum");
     assert!(prompt.contains("## SESSION CONTEXT"));
+    assert!(prompt.contains("Workflow Hint"));
+    assert!(prompt.contains("@file"));
+    assert!(prompt.contains("Plan Mode"));
+    assert!(prompt.contains("task_tracker"));
     assert!(prompt.contains("Suggested Next Actions"));
 
     assert_eq!(bootstrap.placeholder.as_deref(), Some("Type your plan"));
@@ -212,4 +216,9 @@ async fn test_prepare_session_bootstrap_hides_placeholder_when_planning_disabled
 
     let bootstrap = prepare_session_bootstrap(&runtime_cfg, Some(&vt_cfg), None).await;
     assert!(bootstrap.placeholder.is_none());
+
+    if let Some(prompt) = bootstrap.prompt_addendum.as_deref() {
+        assert!(!prompt.contains("Workflow Hint"));
+        assert!(!prompt.contains("task_tracker"));
+    }
 }