---
name: plan-mode
description: Use when the user asks to enter Plan mode, says /prompts:plan or /plan, or wants a structured execution plan written to plan/.
---

# Plan Mode

## When to Activate

This skill is enabled when the user explicitly requests to enter "Plan mode" or enters `/prompts:plan` / `/plan`. Treat the task description given by the user as `$ARGUMENTS` (if the user directly enters `/prompts:plan <description>`, then `<description>` will be `$ARGUMENTS`).

Goal: Develop a implementable and traceable technical execution plan for the task description `$ARGUMENTS` in the current working directory, and save the plan to the `plan/` directory of this project.

- User explicitly says `/plan`, `/prompts:plan`, or "enter Plan mode".
- User wants a structured execution plan written under `plan/`.
- User asks for planning before implementation and does not want code changes yet.

> Note: This skill only takes effect when the user explicitly triggers Plan mode and does not affect normal conversations.
> In actual use, you can pass:
>
> - Enter `/` and select `/prompts:plan` in the pop-up window; or
> - Configure shortcut keys in the terminal and automatically enter `/prompts:plan` to obtain a one-click experience similar to "/plan".

## When to Activate

- The user explicitly asks for Plan mode, `/prompts:plan`, `/plan`, or a plan file under `plan/`.
- The task should be decomposed before implementation instead of executed directly.
- A previous plan needs a deliberate update or replacement with traceable scope.

## Red Flags

- The task is treated as executable while non-goals, decision boundaries, or lane ownership are unknown.
- A new plan is created when the user meant to update the current plan.
- The plan lacks verification commands, risks, or a clear plan file path.

## Checklist

- [ ] Decide whether this is a new plan or an update to an existing plan.
- [ ] Write or update a `plan/*.md` artifact with snake_case metadata.
- [ ] Include executable phases, key decisions, risks, references, and verification.

## Routing Contract Integration

Plan Mode follows the canonical router in [`workflows/references/routing-contract.md`](../references/routing-contract.md).

- Explicit `/plan` usage is a user override that selects the planning lane.
- User override does not bypass the ambiguity gate. If non-goals, decision boundaries, or delegation ownership are missing, return `clarify_first` questions before writing the plan.
- Once ambiguity is resolved, Plan Mode operates as the `plan_first` planner for one-session work.
- When execution is expected after planning, emit the shared handoff fields: `mode`, `artifacts`, `runtime_pinning_snapshot`, `verification_owner`, `stop_conditions`, and `lane_map`.
- When the plan delegates work, include assignments from [`workflows/references/delegation-contract.md`](../references/delegation-contract.md) before any child-agent write lane starts.

## 1. Overall behavioral agreement (must be observed)

1. You are the planning assistant within the project. You are only responsible for "thinking about what to do" and producing a structured plan. You do not directly change the code on a large scale.
2. Every time you enter Plan mode, reasoning and disassembly are completed **internally** first, and then the final structured plan is output:
   - Directly use the built-in reasoning of the model to complete task disassembly;
   - **Do not ask for or output** a complete chain of thinking/step-by-step reasoning details (chain-of-thought); only give "executable plan + key assumptions/trade-offs".
3. The granularity of the plan should be adaptive with the complexity (rather than a fixed “number of thinking steps”):
   - Simple: 3-5 steps, clearly define where to change and how to verify;
   - medium: 5–8 steps, including testing/regression and risk points;
   - Complex: 8–10 steps (split phases if necessary), including milestones, rollback/downgrade ideas and dependency coordination.
4. After you finish thinking, you need to sort out a concise and executable plan, and try to implement the plan into a file by default (see "4. Plan document implementation specifications").
5. If you cannot write files or call shell due to approval/policy restrictions, explain the reason in your answer and at least give the complete plan text.

## 2. Complexity judgment and planning depth specification

Before calling thinkplanning, the tasks are ranked according to `$ARGUMENTS` and the current context:

- simple：
  - Minor fixes whose scope is limited to a single file/function;
  - The number of steps is expected to be < 5;
  - No cross-service/cross-system impact.
- medium：
  - Involves multiple files/modules, or requires certain design choices (API changes, data structure adjustments, etc.);
  - Requires supplementary testing and simple regression verification.
- complex：
  - Involving cross-services or multiple subsystems (such as front-end and back-end, multiple microservices);
  - Or bring about architectural/performance trade-offs;
  - Or migration, grayscale release, etc. are required.

Planning depth requirements:

  - Directly use the built-in reasoning of the model to do multi-step thinking instead of improvising plans directly in the message;
  - The degree of thinking can be increased/decreased as needed during the thinking process (for example, if more sub-problems are found, add 2-4 steps) until the plan is detailed enough and implementable, then end thinking;
  - Does not require or output complete chain-of-thought details; only use the results to organize a structured plan.

## 3. In-dialogue output format

In Plan mode, your answer should use a fixed structure:

```markdown
Task: <Summarize the current task in one sentence (you can use $ARGUMENTS or your understanding)>

Plan:
- Phase 1: <Step 1, 1–2 sentences, describing the goal rather than implementation details>
- Phase 2: <Step 2>
- Phase 3: <Step 3>
...(maximum 8–10 steps, subdivided if necessary)

Key Decisions:
- <Use 2–4 bullets to summarize the key conclusions/trade-offs drawn from the thinking plan>

Risks:
- <Risk 1 (e.g. data security, performance, stability, etc.)>
- <Risk 2 (e.g. dependence on other teams/services, environment restrictions, etc.)>

Plan File:
- Path: `plan/<the file name you actually created>.md`
- Status: <Created and written / Unable to create (specify reason)>
```

If `$ARGUMENTS` is empty or not specific enough, you can briefly clarify the requirements in 1-2 sentences before planning, but do not get stuck in long questions.

## 4. Plan file implementation specifications (plan/*.md)

For each Plan mode conversation, try to create a new Plan file for the current task and use a unified Markdown structure to facilitate subsequent retrieval and tool processing.

1. Directory and file name
   - Directory: Use the current working directory as the root and create the `plan/` directory in it;
   - File name suggestion: `plan/YYYY-MM-DD_HH-mm-ss-<slug>.md`, where:
     - The timestamp part can be obtained through the methods available in the current system:
       - In a Unix-like environment, you can use: `date +"%Y-%m-%d_%H-%M-%S"`;
       - In Windows PowerShell, you can use: `Get-Date -Format "yyyy-MM-dd_HH-mm-ss"`;
       - If there is another more suitable method, you can choose it yourself, as long as the timestamp in the file name is monotonous and readable.
     - `<slug>` is a short identifier of the task extracted and normalized from `$ARGUMENTS`. Suggested rules:
       - Take some keywords or the first few words from the task description and remove the blanks;
       - Convert to lowercase;
       - Normalize non-alphanumeric characters to `-` and compress consecutive `-`;
       - Truncate to a reasonable length (e.g. 20–32 characters) to avoid overly long file names;
       - Remove the leading and trailing `-`; if it ends up being empty, it will degenerate into a general placeholder (such as `task` or `plan`).
   - Ensure that existing files are not overwritten. If the file already exists, append `<slug>` or a short suffix (such as `-1`, `-2`) to the end of the file name.

2. Plan file content structure (with special style metadata header)

When writing a file, a YAML-style metadata header (frontmatter) must be used at the top of the file, separated from the text by `---` to facilitate human eye recognition and tool parsing. Example:

```markdown
---
mode: plan
cwd: <current working directory, for example /Users/xxx/project>
task: <task title or summary (usually from your summary of $ARGUMENTS)>
complexity: <simple|medium|complex>
planning_method: builtin
created_at: <ISO8601 timestamp or date output>
---

# Plan: <Task brief title>

Task Overview
<Describe the context and goals of the task in 2–3 sentences. >

Plan
1. <Step 1: Describe in one sentence what to do and why>
2. <Step 2>
3. <Step 3>
...(expand based on complexity, generally 4–10 steps)

Risks
- <Risk or Caution 1>
- <Risk or Caution 2>

References
- `<file path:line number>` (e.g. `src/main/java/App.java:42`)
- Other useful links or instructions
```

Require:

- The metadata header must be located at the beginning of the file, in the YAML form wrapped with the above `---`, and clearly separated from the body text;
-Field names remain snake_case (such as `planning_method`) to facilitate script parsing;
- If some fields cannot be determined temporarily (such as complexity), you can use your current best judgment and do not leave the field names blank.

3. Writing method and failure handling

- Use the shell of the current platform to execute the command in the working directory to create the `plan/` directory and write the file. Be careful to avoid using commands that are only applicable to a single platform:
  - In a Unix-like environment, you can use: `mkdir -p plan`;
  - In Windows PowerShell, you can use: `New-Item -ItemType Directory -Force -Path plan`;
  - Then write the Markdown content to the new file using a method appropriate for the current shell (redirect, heredoc, `Set-Content` / `Out-File`, etc.).
- After successful writing, clearly inform the user in the conversation:
  - actual file path;
  - Whether to include PLAN_META block and full plan content.
- If the file cannot be created/written due to approval/policy restrictions or other errors:
  - Give reasons in your answer;
  - Still output the complete plan text, ensuring that the user can manually copy it to a file.

## 5. Recognition and cooperation when Plan mode is triggered multiple times in the same session

In a Codex session, the user may trigger Plan mode multiple times, for example:

- First time: `/prompts:plan Help me design an implementation plan for XXX`
- The second time: `/prompts:plan The previous design is not reasonable, I want to make adjustments` (or the user triggers the same prompt again through shortcut keys)

You need to determine whether to "continue the same Plan" or "create a new Plan" based on the user's intention, and choose to read or create a new Plan file accordingly.

1. Identification rules for the same Plan (the default priority is to consider "the same Plan")
   - If this is the first time in this session that you have entered Plan mode: Create a new Plan file.
   - If there is already a current Plan in this session (you have output the `Plan file: path: plan/....md` in the previous answer):
     - When the user uses expressions such as "previously", "just now", "previous plan", "previous plan", "adjusted on the original basis", etc., it is deemed to continue the same Plan:
       - No new files are created;
       - Use the previously recorded Plan file path as the "current Plan";
       - First read the original plan through `cat plan/XXXX.md`, and modify or incrementally update it based on this.
     - When the user clearly states "new plan", "another task", "change a requirement", "redesign a plan for YYY", it is regarded as a new plan:
       - Create new Plan files for new tasks;
       - Clearly distinguish the file paths of the old Plan and the new Plan in your answer.
   - If the user's speech is unclear, it is impossible to determine whether to continue or create a new one:
     - First ask for clarification in one sentence (for example: "Is this adjusting the previous Plan, or creating a new Plan for a completely new task?"), and then execute according to the user's choice.

2. Behavior when continuing the same Plan
   - Prioritize reading the contents of the current Plan file through the shell (for example, `cat plan/2025-12-01_17-05-30-plan.md`) to quickly review the summary of existing plans;
   - If the user wishes to adjust the plan:
     - In your answer, first give a "Summary of Changes" to explain the main modifications compared to the original Plan;
     - Then provide the updated complete plan fragment (it can replace certain phases or add new phases);
     - Update the same Plan file using append or rewrite, and explain in your answer:
       - Updated Plan file path;
       - If you use a "Change History" or "Revisions" section in your document, briefly describe your structure.

3. Behavior when creating a new Plan
   - Create a new Plan file according to "4. Plan file implementation specifications";
   - Clearly mark this as a new Plan in your answer and give the new file path;
   - If necessary, note "relationship with the old Plan" at the beginning of the new Plan file (for example, rewrite, branch plan, etc.).

Always keep the plan simple, clear, and executable, avoid over-designing for the sake of showing off skills, and adhere to the KISS / YAGNI principle.

## Red Flags

- **Editing during Plan mode** - this mode produces a plan and must not change code unless the user exits planning.
- **Creating a new plan for a continuation** - repeated Plan prompts often mean update the existing plan, not start over.
- **Vague implementation steps** - a plan without files, tests, and done conditions cannot be executed safely.
- **Ignoring routing readiness** - unclear or risky requirements should remain in `clarify_first` or `plan_first`.

## Checklist

- [ ] Determine whether this is a new plan or an update to the current plan.
- [ ] Capture goal, context, constraints, and done-when criteria.
- [ ] Include artifacts, runtime pinning, verification owner, stop conditions, and lane map.
- [ ] Keep implementation work out of Plan mode unless explicitly requested.
- [ ] Record the plan file path when a plan artifact is created or updated.
