From 429932c663a134f3b792ae203c9f0d1744975170 Mon Sep 17 00:00:00 2001 From: Jerop Kipruto Date: Fri, 20 Feb 2026 10:56:49 -0500 Subject: [PATCH] docs: refine Plan Mode documentation structure and workflow (#19644) --- docs/cli/plan-mode.md | 255 ++++++++++++++++++++++-------------------- 1 file changed, 134 insertions(+), 121 deletions(-) diff --git a/docs/cli/plan-mode.md b/docs/cli/plan-mode.md index 03da2a6ac9..d5e78f6fb5 100644 --- a/docs/cli/plan-mode.md +++ b/docs/cli/plan-mode.md @@ -1,50 +1,61 @@ # Plan Mode (experimental) -Plan Mode is a safe, read-only mode for researching and designing complex -changes. It prevents modifications while you research, design and plan an -implementation strategy. +Plan Mode is a read-only environment for architecting robust solutions before +implementation. It allows you to: -> **Note: Plan Mode is currently an experimental feature.** -> -> Experimental features are subject to change. To use Plan Mode, enable it via -> `/settings` (search for `Plan`) or add the following to your `settings.json`: -> -> ```json -> { -> "experimental": { -> "plan": true -> } -> } -> ``` -> -> Your feedback is invaluable as we refine this feature. If you have ideas, +- **Research:** Explore the project in a read-only state to prevent accidental + changes. +- **Design:** Understand problems, evaluate trade-offs, and choose a solution. +- **Plan:** Align on an execution strategy before any code is modified. + +> **Note:** This is a preview feature currently under active development. Your +> feedback is invaluable as we refine this feature. If you have ideas, > suggestions, or encounter issues: > -> - Use the `/bug` command within the CLI to file an issue. > - [Open an issue](https://github.com/google-gemini/gemini-cli/issues) on > GitHub. +> - Use the **/bug** command within Gemini CLI to file an issue. -- [Starting in Plan Mode](#starting-in-plan-mode) +- [Enabling Plan Mode](#enabling-plan-mode) - [How to use Plan Mode](#how-to-use-plan-mode) - [Entering Plan Mode](#entering-plan-mode) - - [The Planning Workflow](#the-planning-workflow) + - [Planning Workflow](#planning-workflow) - [Exiting Plan Mode](#exiting-plan-mode) - [Tool Restrictions](#tool-restrictions) - [Customizing Planning with Skills](#customizing-planning-with-skills) - [Customizing Policies](#customizing-policies) + - [Example: Allow git commands in Plan Mode](#example-allow-git-commands-in-plan-mode) + - [Example: Enable research subagents in Plan Mode](#example-enable-research-subagents-in-plan-mode) + - [Custom Plan Directory and Policies](#custom-plan-directory-and-policies) -## Starting in Plan Mode +## Enabling Plan Mode -You can configure Gemini CLI to start directly in Plan Mode by default: +To use Plan Mode, enable it via **/settings** (search for **Plan**) or add the +following to your `settings.json`: -1. Type `/settings` in the CLI. -2. Search for `Default Approval Mode`. -3. Set the value to `Plan`. +```json +{ + "experimental": { + "plan": true + } +} +``` -Other ways to start in Plan Mode: +## How to use Plan Mode -- **CLI Flag:** `gemini --approval-mode=plan` -- **Manual Settings:** Manually update your `settings.json`: +### Entering Plan Mode + +You can configure Gemini CLI to start in Plan Mode by default or enter it +manually during a session. + +- **Configuration:** Configure Gemini CLI to start directly in Plan Mode by + default: + 1. Type `/settings` in the CLI. + 2. Search for **Default Approval Mode**. + 3. Set the value to **Plan**. + + Alternatively, use the `gemini --approval-mode=plan` CLI flag or manually + update: ```json { @@ -54,43 +65,44 @@ Other ways to start in Plan Mode: } ``` -## How to use Plan Mode +- **Keyboard Shortcut:** Press `Shift+Tab` to cycle through approval modes + (`Default` -> `Auto-Edit` -> `Plan`). -### Entering Plan Mode + > **Note:** Plan Mode is automatically removed from the rotation when Gemini + > CLI is actively processing or showing confirmation dialogs. -You can enter Plan Mode in three ways: +- **Command:** Type `/plan` in the input box. -1. **Keyboard Shortcut:** Press `Shift+Tab` to cycle through approval modes - (`Default` -> `Auto-Edit` -> `Plan`). +- **Natural Language:** Ask Gemini CLI to "start a plan for...". Gemini CLI then + calls the [`enter_plan_mode`] tool to switch modes. + > **Note:** This tool is not available when Gemini CLI is in [YOLO mode]. - > **Note:** Plan Mode is automatically removed from the rotation when the - > agent is actively processing or showing confirmation dialogs. +### Planning Workflow -2. **Command:** Type `/plan` in the input box. -3. **Natural Language:** Ask the agent to "start a plan for...". The agent will - then call the [`enter_plan_mode`] tool to switch modes. - - **Note:** This tool is not available when the CLI is in YOLO mode. - -### The Planning Workflow - -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. **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). +1. **Explore & Analyze:** Analyze requirements and use read-only tools to map + the codebase and validate assumptions. For complex tasks, identify at least + two viable implementation approaches. +2. **Consult:** Present a summary of the identified approaches via [`ask_user`] + to obtain a selection. For simple or canonical tasks, this step may be + skipped. +3. **Draft:** Once an approach is selected, write a detailed implementation + plan to the plans directory. +4. **Review & Approval:** Use the [`exit_plan_mode`] tool to present the plan + and formally request approval. + - **Approve:** Exit Plan Mode and start implementation. - **Iterate:** Provide feedback to refine the plan. +For more complex or specialized planning tasks, you can +[customize the planning workflow with skills](#customizing-planning-with-skills). + ### Exiting Plan Mode -To exit Plan Mode: +To exit Plan Mode, you can: -1. **Keyboard Shortcut:** Press `Shift+Tab` to cycle to the desired mode. -2. **Tool:** The agent calls the [`exit_plan_mode`] tool to present the - finalized plan for your approval. +- **Keyboard Shortcut:** Press `Shift+Tab` to cycle to the desired mode. + +- **Tool:** Gemini CLI calls the [`exit_plan_mode`] tool to present the + finalized plan for your approval. ## Tool Restrictions @@ -103,30 +115,78 @@ These are the only allowed tools: - **Interaction:** [`ask_user`] - **MCP Tools (Read):** Read-only [MCP tools] (e.g., `github_read_issue`, `postgres_read_schema`) are allowed. -- **Planning (Write):** [`write_file`] and [`replace`] ONLY allowed for `.md` - files in the `~/.gemini/tmp///plans/` directory. +- **Planning (Write):** [`write_file`] and [`replace`] only allowed for `.md` + files in the `~/.gemini/tmp///plans/` directory or your + [custom plans directory](#custom-plan-directory-and-policies). - **Skills:** [`activate_skill`] (allows loading specialized instructions and resources in a read-only manner) ### Customizing Planning with Skills -You can leverage [Agent Skills](./skills.md) to customize how Gemini CLI -approaches planning for specific types of tasks. When a skill is activated -during Plan Mode, its specialized instructions and procedural workflows will -guide the research and design phases. +You can use [Agent Skills](./skills.md) to customize how Gemini CLI approaches +planning for specific types of tasks. When a skill is activated during Plan +Mode, its specialized instructions and procedural workflows will guide the +research, design and planning phases. For example: - A **"Database Migration"** skill could ensure the plan includes data safety checks and rollback strategies. -- A **"Security Audit"** skill could prompt the agent to look for specific +- A **"Security Audit"** skill could prompt Gemini CLI to look for specific vulnerabilities during codebase exploration. -- A **"Frontend Design"** skill could guide the agent to use specific UI +- A **"Frontend Design"** skill could guide Gemini CLI to use specific UI components and accessibility standards in its proposal. -To use a skill in Plan Mode, you can explicitly ask the agent to "use the -[skill-name] skill to plan..." or the agent may autonomously activate it based -on the task description. +To use a skill in Plan Mode, you can explicitly ask Gemini CLI to "use the +`` skill to plan..." or Gemini CLI may autonomously activate it +based on the task description. + +### Customizing Policies + +Plan Mode is designed to be read-only by default to ensure safety during the +research phase. However, you may occasionally need to allow specific tools to +assist in your planning. + +Because user policies (Tier 2) have a higher base priority than built-in +policies (Tier 1), you can override Plan Mode's default restrictions by creating +a rule in your `~/.gemini/policies/` directory. + +#### Example: Allow git commands in Plan Mode + +This rule allows you to check the repository status and see changes while in +Plan Mode. + +`~/.gemini/policies/git-research.toml` + +```toml +[[rule]] +toolName = "run_shell_command" +commandPrefix = ["git status", "git diff"] +decision = "allow" +priority = 100 +modes = ["plan"] +``` + +#### Example: Enable research subagents in Plan Mode + +You can enable experimental research [subagents] like `codebase_investigator` to +help gather architecture details during the planning phase. + +`~/.gemini/policies/research-subagents.toml` + +```toml +[[rule]] +toolName = "codebase_investigator" +decision = "allow" +priority = 100 +modes = ["plan"] +``` + +Tell Gemini CLI it can use these tools in your prompt, for example: _"You can +check ongoing changes in git."_ + +For more information on how the policy engine works, see the [policy engine] +docs. ### Custom Plan Directory and Policies @@ -152,11 +212,10 @@ locations defined within a project's workspace cannot be used to escape and overwrite sensitive files elsewhere. Any user-configured directory must reside within the project boundary. -Because Plan Mode is read-only by default, using a custom directory requires -updating your [Policy Engine] configurations to allow `write_file` and `replace` -in that specific location. For example, to allow writing to the `.gemini/plans` -directory within your project, create a policy file at -`~/.gemini/policies/plan-custom-directory.toml`: +Using a custom directory requires updating your [policy engine] configurations +to allow `write_file` and `replace` in that specific location. For example, to +allow writing to the `.gemini/plans` directory within your project, create a +policy file at `~/.gemini/policies/plan-custom-directory.toml`: ```toml [[rule]] @@ -166,56 +225,9 @@ priority = 100 modes = ["plan"] # Adjust the pattern to match your custom directory. # This example matches any .md file in a .gemini/plans directory within the project. -argsPattern = "\"file_path\":\".*\\\\.gemini/plans/.*\\\\.md\"" +argsPattern = "\"file_path\":\"[^\"]*/\\.gemini/plans/[a-zA-Z0-9_-]+\\.md\"" ``` -### Customizing Policies - -Plan Mode is designed to be read-only by default to ensure safety during the -research phase. However, you may occasionally need to allow specific tools to -assist in your planning. - -Because user policies (Tier 2) have a higher base priority than built-in -policies (Tier 1), you can override Plan Mode's default restrictions by creating -a rule in your `~/.gemini/policies/` directory. - -#### Example: Allow `git status` and `git diff` in Plan Mode - -This rule allows you to check the repository status and see changes while in -Plan Mode. - -`~/.gemini/policies/git-research.toml` - -```toml -[[rule]] -toolName = "run_shell_command" -commandPrefix = ["git status", "git diff"] -decision = "allow" -priority = 100 -modes = ["plan"] -``` - -#### Example: Enable research sub-agents in Plan Mode - -You can enable [experimental research sub-agents] like `codebase_investigator` -to help gather architecture details during the planning phase. - -`~/.gemini/policies/research-subagents.toml` - -```toml -[[rule]] -toolName = "codebase_investigator" -decision = "allow" -priority = 100 -modes = ["plan"] -``` - -Tell the agent it can use these tools in your prompt, for example: _"You can -check ongoing changes in git."_ - -For more information on how the policy engine works, see the [Policy Engine -Guide]. - [`list_directory`]: /docs/tools/file-system.md#1-list_directory-readfolder [`read_file`]: /docs/tools/file-system.md#2-read_file-readfile [`grep_search`]: /docs/tools/file-system.md#5-grep_search-searchtext @@ -225,8 +237,9 @@ Guide]. [`replace`]: /docs/tools/file-system.md#6-replace-edit [MCP tools]: /docs/tools/mcp-server.md [`activate_skill`]: /docs/cli/skills.md -[experimental research sub-agents]: /docs/core/subagents.md -[Policy Engine Guide]: /docs/reference/policy-engine.md +[subagents]: /docs/core/subagents.md +[policy engine]: /docs/reference/policy-engine.md [`enter_plan_mode`]: /docs/tools/planning.md#1-enter_plan_mode-enterplanmode [`exit_plan_mode`]: /docs/tools/planning.md#2-exit_plan_mode-exitplanmode [`ask_user`]: /docs/tools/ask-user.md +[YOLO mode]: /docs/reference/configuration.md#command-line-arguments