docs: refine Plan Mode documentation structure and workflow (#19644)

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
+Plan Mode is a read-only environment for architecting robust solutions before
-changes. It prevents modifications while you research, design and plan an
+implementation. It allows you to:
-implementation strategy.
 
-> **Note: Plan Mode is currently an experimental feature.**
+- **Research:** Explore the project in a read-only state to prevent accidental
->
+  changes.
-> Experimental features are subject to change. To use Plan Mode, enable it via
+- **Design:** Understand problems, evaluate trade-offs, and choose a solution.
-> `/settings` (search for `Plan`) or add the following to your `settings.json`:
+- **Plan:** Align on an execution strategy before any code is modified.
->
+
-> ```json
+> **Note:** This is a preview feature currently under active development. Your
-> {
+> feedback is invaluable as we refine this feature. If you have ideas,
->   "experimental": {
->     "plan": true
->   }
-> }
-> ```
->
-> 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.
+```json
-2.  Search for `Default Approval Mode`.
+{
-3.  Set the value to `Plan`.
+  "experimental": {
+    "plan": true
+  }
+}
+```
 
-Other ways to start in Plan Mode:
+## How to use Plan Mode
 
-- **CLI Flag:** `gemini --approval-mode=plan`
+### Entering Plan Mode
-- **Manual Settings:** Manually update your `settings.json`:
+
+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
+- **Natural Language:** Ask Gemini CLI to "start a plan for...". Gemini CLI then
-    (`Default` -> `Auto-Edit` -> `Plan`).
+  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
+### Planning Workflow
-    > agent is actively processing or showing confirmation dialogs.
 
-2.  **Command:** Type `/plan` in the input box.
+1.  **Explore & Analyze:** Analyze requirements and use read-only tools to map
-3.  **Natural Language:** Ask the agent to "start a plan for...". The agent will
+    the codebase and validate assumptions. For complex tasks, identify at least
-    then call the [`enter_plan_mode`] tool to switch modes.
+    two viable implementation approaches.
-    - **Note:** This tool is not available when the CLI is in YOLO mode.
+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
-### The Planning Workflow
+    skipped.
-
+3.  **Draft:** Once an approach is selected, write a detailed implementation
-1.  **Requirements:** The agent clarifies goals using [`ask_user`].
+    plan to the plans directory.
-2.  **Exploration:** The agent uses read-only tools (like [`read_file`]) to map
+4.  **Review & Approval:** Use the [`exit_plan_mode`] tool to present the plan
-    the codebase and validate assumptions.
+    and formally request approval.
-3.  **Design:** The agent proposes alternative approaches with a recommended
+    - **Approve:** Exit Plan Mode and start implementation.
-    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.
 
+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.
+- **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.
+- **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`
+- **Planning (Write):** [`write_file`] and [`replace`] only allowed for `.md`
-  files in the `~/.gemini/tmp/<project>/<session-id>/plans/` directory.
+  files in the `~/.gemini/tmp/<project>/<session-id>/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
+You can use [Agent Skills](./skills.md) to customize how Gemini CLI approaches
-approaches planning for specific types of tasks. When a skill is activated
+planning for specific types of tasks. When a skill is activated during Plan
-during Plan Mode, its specialized instructions and procedural workflows will
+Mode, its specialized instructions and procedural workflows will guide the
-guide the research and design phases.
+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
+To use a skill in Plan Mode, you can explicitly ask Gemini CLI to "use the
-[skill-name] skill to plan..." or the agent may autonomously activate it based
+`<skill-name>` skill to plan..." or Gemini CLI may autonomously activate it
-on the task description.
+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
+Using a custom directory requires updating your [policy engine] configurations
-updating your [Policy Engine] configurations to allow `write_file` and `replace`
+to allow `write_file` and `replace` in that specific location. For example, to
-in that specific location. For example, to allow writing to the `.gemini/plans`
+allow writing to the `.gemini/plans` directory within your project, create a
-directory within your project, create a policy file at
+policy file at `~/.gemini/policies/plan-custom-directory.toml`:
-`~/.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
+[subagents]: /docs/core/subagents.md
-[Policy Engine Guide]: /docs/reference/policy-engine.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