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 reviewable plan: a decision title, an observable objective, a markdown body, and independently completable steps.
• Call the plan tool (fallback: a fenced plan block with What, Approach, and Steps). For an open project, read files first and cite them in the body. Greenfield product plans stay in product language and do not invent file paths.
• The user Accepts the whole plan. Accept writes .miton/plan.md and archives a copy under .miton/plans/ so later sessions can read it.

When the agent returns a plan, Miton renders it as a compact review card in Chat rather than the full transcript-sized plan text: the plan’s title, its state, a step count, and a capped summary. Opening the card shows the full read-only plan inspector with the complete step list. Unstructured plan text remains ordinary Markdown.

Reviewing the plan

The compact review card gives you three actions:

• Accept plan — apply the plan and hand the session to an execution mode so the agent can start work.
• Modify plan — pre-fill the composer with a request to change the plan, so you can ask for a different approach before accepting.
• Decline — reject the plan. The agent does not proceed with it.

Click the card itself (or its title) to open the full plan inspector. The inspector is the document: the Approach body (markdown, diagrams, file paths), then the read-only step queue. Unstructured plan text remains ordinary Markdown.

How to enter plan mode

There are two explicit ways to enter plan mode for every user:

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.

For Beginner users, a new project request may also enter the guided plan flow automatically. This is the beginner safety net, not a requirement for experienced users. Intermediate and Advanced users stay in their selected mode when they ask to plan or build; they can enter Plan explicitly from the Mode chip or /mode plan when they want a review before execution (ADR-0271).

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 Auto-Edit for the next execution step.

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.

Specialist team proposals

For a novel objective that needs several distinct roles, the agent can propose a task-specific team of temporary Specialists instead of (or alongside) a plan. The agent designs the roster from your objective and project context; Miton validates the roster, resolves a model route for each Specialist, and shows the proposal in Chat. No Specialist runs until you review and accept the team.

This is a separate approval surface from the plan review card above — see Sub-agents for how Specialist proposals are reviewed, edited, and accepted.

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. The plan panel does not pause or resume execution; switch mode to let the agent act.
• Long-horizon goal tracking is a separate surface. Applying plan steps into Goals is the hand-off point; ongoing progress toward a goal across many turns is tracked in Goals, not in plan mode itself.

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.