Plan mode (/plan)

Lifecycle: CURRENT feature reference — this documents the editor /plan workflow. It is not a Funday product roadmap.

What /plan does

/plan swaps the editor for a plan-review surface and routes the next prompt to the plan-role model on a side-channel turn. The planner is held to read-only work: it may create and edit only its plan file (local://<slug>-plan.md), so nothing else touches your code until you approve.

Toggle it from the editor by typing /plan, by pressing Alt+Shift+P, or by passing the initial goal inline:

/plan refactor src/importer.ts to stream rows instead of buffering

The plan-role model

Plan mode runs against a separate role so you can pin a stronger reasoner there without paying for it on every turn. Override per-run with --plan <model-id>, per-shell with PI_PLAN_MODEL, or persistently with modelRoles.plan in config.yml. The registry and the available model ids live on the Models page.

The loop

1. State the goal. A plan-mode banner appears at the top of the editor; the prompt you type next routes to the planner.

2. Iterate. The planner drafts; you reply with corrections like a normal turn. Read-only tools are still available, so it can grep the repo, read PRs, and check assumptions before revising.

3. Approve. When you tell the planner you’re satisfied, it calls resolve with action: "apply" and the approval selector appears.

What happens on exit

The approval screen offers three shapes for handing the plan to the executor. They differ in what the executor sees as “the conversation so far”.

Approve and execute Plan-mode discussion is purged from context; execution starts on a fresh transcript with the plan as the opening message. Use when the plan is long and the back-and-forth doesn’t matter.

Approve and keep context Full planning history stays in the transcript. Use when the iteration informed nuance you want the executor to remember.

Approve and compact context Planning discussion is summarised into a single entry; execution continues in the same session. Middle ground.

Escape on the approval screen cancels: you stay in plan-mode iteration and nothing executes.

Approving a plan auto-names the session from the plan title (separators normalised, capitalised). A session you renamed yourself is left alone.

Chords

The rest of the editor and navigator chords are unchanged in plan mode; see Keybindings.

When to reach for it

Plan mode pays off on changes that touch more than one file, on refactors with non-obvious sequencing, and on designs the planner should justify before implementing. Skip it for one-file edits and trivial changes; the planner round-trip costs tokens you won’t get back.

Pairs naturally with branching: plan on a side branch, throw the branch away. if the design didn’t land, keep iterating on the parent.\n