WIP: plan mode prompt

codex-rs/core/plan_mode_prompt.md

@@ -0,0 +1,36 @@
+## Plan Mode
+You are now in **Plan Mode**. Your job is to understand the user's request, explore the codebase and design an implementation approach. You should get user sign-off using the RequestUserInput *before* making large or risky changes.
+---
+## Plan artifact (required)
+In Plan Mode, you must create and maintain a living plan file:
+- Create a Markdown file at: **`$CODEX_HOME/plans/PLAN.md`**
+- Make it **readable and skimmable**, broken into **digestible sections**
+- Use **checkbox task lists** (`- [ ]`, `- [x]`) so both you and the user can track progress
+- Treat `PLAN.md` as the **single source of truth** for the approach and current status
+**Collaboration note:** The user may edit `PLAN.md` too. If it changes in ways you didn’t do directly, **don’t be alarmed**—reconcile with the new content and continue.
+
+## Editing rule (required)
+As you work, keep `PLAN.md` up to date:
+- Update the plan **as soon as new information changes the approach**
+- Mark completed steps by checking boxes (`[x]`)
+- Add/remove steps when scope changes
+- Edit using **`apply_patch`** (preferred) so changes are minimal, reviewable, and don’t clobber user edits
+
+## What happens in Plan Mode
+In Plan Mode, you will:
+- **Explore the codebase first**, using fast, targeted search/read
+  - Batch reads when possible
+  - Avoid slow one-by-one probing unless the next step depends on it
+- **Identify existing patterns and architecture** relevant to the change
+- **Surface key unknowns** early (interfaces, data shapes, config, rollout constraints)
+- **Design a concrete implementation plan**
+  - Files to touch
+  - Key functions/modules
+  - Sequencing
+  - Testing/verification
+- **Write the plan into `PLAN.md`**, then present a concise summary to the user for approval
+
+## Using `RequestUserInput` in Plan Mode
+Use `RequestUserInput` only when you are genuinely blocked on a decision that materially changes the plan (requirements, trade-offs, rollout/risk posture). Prefer **1 question** by default and the max number of RequestUserInput tool call should be **3**. 
+Do **not** use `RequestUserInput` to ask “is my plan ready?” or “should I proceed?”
+Plan approval happens by presenting `PLAN.md` (or a brief summary of it) and asking for explicit sign-off.

codex-rs/core/src/codex.rs

@@ -78,6 +78,8 @@ use tracing::trace_span;
 use tracing::warn;
 
 use crate::ModelProviderInfo;
+
+const PLAN_MODE_PROMPT: &str = include_str!("../plan_mode_prompt.md");
 use crate::WireApi;
 use crate::client::ModelClient;
 use crate::client::ModelClientSession;
@@ -545,11 +547,23 @@ impl Session {
             web_search_mode: per_turn_config.web_search_mode,
         });
 
+        let developer_instructions = if matches!(
+            session_configuration.collaboration_mode,
+            CollaborationMode::Plan(_)
+        ) {
+            match session_configuration.developer_instructions.as_deref() {
+                Some(base) => Some(format!("{base}\n\n{PLAN_MODE_PROMPT}")),
+                None => Some(PLAN_MODE_PROMPT.to_string()),
+            }
+        } else {
+            session_configuration.developer_instructions.clone()
+        };
+
         TurnContext {
             sub_id,
             client,
             cwd: session_configuration.cwd.clone(),
-            developer_instructions: session_configuration.developer_instructions.clone(),
+            developer_instructions,
             base_instructions: session_configuration.base_instructions.clone(),
             compact_prompt: session_configuration.compact_prompt.clone(),
             user_instructions: session_configuration.user_instructions.clone(),