Planning | Creor

Plan mode lets you analyze your codebase and create structured implementation plans without modifying any files. Think before you code.

What Is Plan Mode

Plan mode switches the agent from its default build configuration to a read-only Plan agent. In this mode, the agent can explore your entire codebase -- reading files, searching with grep and glob, analyzing dependencies -- but it cannot edit files, run destructive shell commands, or make any changes to your project.

The output is a structured markdown plan saved to the .creor/plans/ directory in your project. These plans break down a task into concrete, ordered steps with file references, code snippets, and rationale for each decision.

Tip

Plan mode is ideal for unfamiliar codebases. Before making changes, ask the agent to create a plan so you can review the approach, catch potential issues, and understand the scope of changes before any code is touched.

Entering Plan Mode

There are several ways to enter plan mode.

Keyboard Shortcut

Press Shift+Cmd+P (macOS) or Shift+Ctrl+P (Windows/Linux) to toggle plan mode on or off. When active, you will see a plan indicator in the chat input area.

Slash Command

Type /plan in the chat input followed by your request. This activates plan mode for that specific message.

/plan Add authentication with OAuth2 to the user service

Chat Command

You can also ask the agent directly to plan something. The agent will recognize planning intent and switch to the plan workflow.

Create a plan for migrating the database from PostgreSQL to MySQL

Note

Plan mode persists across messages in a session until you exit it. To exit, press the keyboard shortcut again, type /plan to toggle it off, or start a new session.

The Plan Agent

The Plan agent is a distinct agent configuration with restricted tool access. It is not simply the Build agent with fewer permissions -- it has its own system prompt optimized for analysis and planning.

Capability	Plan Agent	Build Agent
Read files	Yes	Yes
Search with glob/grep	Yes	Yes
Write/edit files	No	Yes
Run shell commands	Read-only (e.g., git log)	Yes
Write plans to .creor/plans/	Yes	No (writes code instead)
Web search	Yes	Yes
LSP code intelligence	Yes	Yes

Because the Plan agent cannot modify your project, it is safe to run on production repositories, shared codebases, or any project where you want to analyze without risk.

Plan File Format

Plans are saved as markdown files in the .creor/plans/ directory at your project root. Each plan follows a structured format with a title, overview, and numbered steps.

# Add OAuth2 Authentication

## Overview

Add OAuth2 authentication to the user service using the

existing session middleware. This requires changes to 4 files

and the addition of 2 new modules.

## Steps

### 1. Create the OAuth2 provider configuration

- File: src/auth/providers.ts (new file)

- Define provider interfaces for Google and GitHub

- Export a configuration factory function

### 2. Add token exchange endpoint

- File: src/routes/auth.ts (modify)

- Add POST /auth/callback route

- Validate state parameter against session

### 3. Update session middleware

- File: src/middleware/session.ts (modify)

- Extend session type to include OAuth tokens

- Add token refresh logic

### 4. Add integration tests

- File: tests/auth.test.ts (new file)

- Test token exchange flow

- Test session persistence

- Test token refresh

## Dependencies

- No new packages required

- Uses existing express-session middleware

## Risks

- Token refresh timing may cause race conditions

under high concurrency

Reviewing Plans

After the agent generates a plan, you should review it before executing. Plans appear in both the chat panel and as files in .creor/plans/ that you can open in the editor.

What to Check

Are all the files referenced correct? Does the agent understand the existing structure?
Are the steps in the right order? Dependencies between steps should flow logically.
Is the scope appropriate? Plans that touch too many files may indicate the task should be broken down further.
Are there any missing steps? Check for things like updating tests, documentation, or configuration.
Are the risks and tradeoffs clearly identified?

Refining Plans

You can ask the agent to refine the plan by sending follow-up messages. The agent will update the plan file with your feedback.

The plan looks good but step 3 should happen before step 2.
Also, we need to add rate limiting to the callback endpoint.

Executing Plans

Once you are satisfied with a plan, exit plan mode and ask the Build agent to execute it. The agent will read the plan file and follow the steps, asking for clarification where needed.

Execute the plan in .creor/plans/add-oauth2-authentication.md

The Build agent treats the plan as a high-level guide, not a rigid script. It will adapt to the actual state of the code it encounters, handle edge cases the plan did not anticipate, and may adjust the order of steps if it discovers dependencies.

Warning

Always exit plan mode before asking the agent to execute a plan. The Plan agent cannot write code -- it will attempt to create another plan instead.

Best Practices

Start complex tasks with a plan. The 5 minutes spent reviewing a plan can save hours of debugging incorrect implementations.
Use plan mode for code reviews. Ask the agent to analyze a PR or diff and create a review plan with specific feedback.
Plan before refactoring. Large refactors benefit from a plan that maps out all affected files and the order of changes.
Break large plans into phases. If a plan has more than 10 steps, ask the agent to split it into phases that can be executed and verified independently.
Keep plans in version control. The .creor/plans/ directory is part of your project, so plans are tracked in git and visible to your team.