Plan mode

What this accomplishes

Review a structured plan before the agent edits files or runs shell commands.

Plan mode is read-only. The agent describes what it would do — file paths, steps, expected outcomes — but cannot write files or run shell commands until you switch to another execution mode.

Current availability

This page documents behaviour verified in Miton development builds. Miton is still pre-release and is not publicly downloadable; invited beta users will receive a signed desktop build with automatic updates.

Before you start

• A Miton development build and an active project containing source code.
• A connected model. Trust the project before allowing file, terminal or Git actions.

What plan mode does

Plan mode injects a read-only system prompt (<mode:plan>) that tells the agent:

• Do not write files or run shell commands.
• Produce a detailed plan with file paths, data flow, and expected outcomes.
• Emit the plan as a fenced plan block with Overview, Architecture, Deliverables, Files affected, Steps, and optional estimates.
• The user will Apply steps into project goals, then switch to another mode to execute.

When the agent returns a plan, Miton renders the structure in Chat so it can be reviewed before the session returns to an execution mode. Unstructured plan text remains ordinary Markdown.

How to enter plan mode

There are three ways to enter plan mode:

1. Mode chip — click the Mode chip in the mode bar (below the message composer) and select Plan.
2. Slash command — type /mode plan in the message composer.
3. Pending auto-change — when a prompt looks like planning work, Miton proposes Plan mode with a 5-second countdown above the composer. Choose Apply Plan, wait for the timer, or Cancel to keep the current mode (ADR-0198).

To exit plan mode, switch to another mode (/mode autoedit, /mode fullaccess, etc.) via the same mechanisms. Implementation-style prompts while already in plan mode may propose Autoedit the same way.

When a pending auto-change is visible, picking a mode from the Mode chip or /mode cancels the pending proposal (manual override wins).

What plan mode enforces

Plan mode is enforced at two levels:

• System prompt — the <mode:plan> block primes the agent to produce plans instead of making changes. The agent sees this as an editorial instruction.
• permission gate — the permission engine blocks file-write and shell-execute tool calls when the session is in plan mode. Even if the agent attempts a write or execute, the permission layer rejects it.

Project plan file

Applying all steps also saves the structured plan to .miton/plan.md. On the next session open, Miton injects that file into context as the project’s written direction (distinct from the live goals task list).

What plan mode does not cover

• Read-only tools still work. The agent can read files, search the codebase, inspect git status, and call any read-only tool while in plan mode.
• Other modes are not affected. Switching to autoedit or fullaccess after reviewing the plan gives the agent full write and execute access.
• No run queue. PlanPanel does not pause or resume execution; switch mode to let the agent act.
• Long-horizon verify loop (GOAL_VERIFIED) remains trail Step 20a / ADR-0207 — after this plan→goals path.

What success looks like

Plan mode is the “think before you act” mode. Switch to it when you want the agent to lay out a plan before touching any code. The agent writes a structured plan in chat. You Apply the steps you want into project goals, then switch to a write-capable mode to let the agent execute.

Common failures and recovery

• Confirm the correct project and branch are active.
• Check the model connection and the permission request shown in Chat.
• Keep the exact error before retrying; use Code troubleshooting when the failure persists.

Related next action

Open Code troubleshooting for recovery steps and diagnostic paths.