diff --git a/codex-rs/core/plan_mode_prompt.md b/codex-rs/core/plan_mode_prompt.md new file mode 100644 index 0000000000..31b3054efc --- /dev/null +++ b/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. diff --git a/codex-rs/core/src/codex.rs b/codex-rs/core/src/codex.rs index a9dc1004ab..5f4ef81436 100644 --- a/codex-rs/core/src/codex.rs +++ b/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(),