Plan Mode

The biggest mistake developers make with AI coding agents is running them without reviewing the plan. Plan mode exists to prevent that mistake from becoming a production incident.

Without plan mode, Copilot CLI goes from prompt to execution in one step. It reads what it needs to read, then it starts writing. For a small, well-scoped task — fix the return type on this function, add a field to this config — that is fine. The scope is clear and the risk is low. But for anything that touches multiple files, crosses module boundaries, or involves a sequence of dependent changes, the gap between what you intended and what Copilot CLI assumed can diverge in ways you will not catch until the tests fail or, worse, until the code ships.

Plan mode inserts a human review step in that gap.

Entering plan mode

There are two ways to invoke plan mode in a session:

/plan "Add structured request logging to the API. The middleware should log
method, path, status code, and duration in JSON."

The /plan command takes your task description and creates an implementation plan before any coding starts. Alternatively, press Shift+Tab to cycle between the interaction modes (standard, plan, and autopilot) — in plan mode, every prompt you type produces a plan rather than immediate execution.

When to use plan mode

The decision is not complicated. A simple heuristic covers 90% of cases:

If you would mentally sketch a checklist before starting the task yourself, use plan mode. Copilot CLI will produce a more thorough version of that checklist and you will catch things you did not think of. If the task is obviously scoped — one file, one change, known outcome — skip it.

The six-step workflow

The workflow is linear with one critical branch: the Review step. This is where you read plan.md and decide whether to proceed. You have three options:

1. Approve — Copilot CLI proceeds with implementation exactly as planned.
2. Edit — You modify plan.md directly (or tell Copilot CLI to revise it), then approve the revised version.
3. Reject — You close the plan and prompt again with a more precise task description.

Editing the plan is underused. If the plan is 80% right but one step is wrong — Copilot CLI planned to modify a file you do not want it to touch, or it missed a dependency — edit the plan and proceed. You do not need to reject and start over.

What a plan looks like

Copilot CLI generates plan.md in your session state directory. Here is a representative excerpt for a task like "add request-level logging to the API":

## Task
Add structured request logging to the Express API using the existing logger.

## Files to Change
- src/middleware/logging.ts (create) — new request logging middleware
- src/app.ts (edit) — register the logging middleware before routes
- src/config/env.ts (edit) — add LOG_LEVEL environment variable

## Steps
1. Read src/app.ts to understand middleware registration pattern
2. Read src/config/env.ts to understand env variable pattern
3. Create src/middleware/logging.ts with request logging middleware
4. Edit src/app.ts to import and register the middleware (before route handlers)
5. Edit src/config/env.ts to add LOG_LEVEL with default 'info'
6. Run npm test to verify no regressions

## Risks
- Middleware order matters in Express — logging must be before auth middleware or logs will miss auth errors

That "Risks" section at the bottom is frequently the most valuable part. Copilot CLI catches ordering constraints, dependency conflicts, and side effects in the plan that would not surface until you ran the tests — or until a user hit a bug.

Re-reading the plan mid-task

Plans are stored with your session artifacts in the session-state directory (~/.copilot/session-state/). Even if you approved and execution started, you can open the stored plan at any point to re-read it — or simply ask the session to restate the current plan. If something unexpected happened during implementation — a test failure Copilot CLI is now trying to debug — re-reading the plan gives you the map.

Lesson Drill

1. Identify a multi-file task in your current project that you have been deferring. Run it with plan mode. Read the full plan before approving.
2. Find one thing in the generated plan that you would have changed or gotten wrong if you had not seen the plan. Note it.
3. Edit the plan (add a constraint or modify a step) before execution and observe how Copilot CLI adapts its implementation to match.

Bottom Line

Plan mode generates an explicit, reviewable plan.md before Copilot CLI touches anything. Use it for multi-file tasks. Read the plan the way you would read a pull request. Edit rather than reject when the plan is mostly right. The Risks section is often the highest-value part of the output.

The next lesson covers session state and context management — how Copilot CLI tracks what it knows, and how you stay in control of that knowledge across long sessions.