> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seriora.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Plan mode

> Research a change, write a plan file, then approve it before any worktree edit.

`/plan` is a TUI overlay on the parent turn. It is not a fourth permission mode, and it is not a
dispatch of the `plan` [subagent](/guides/subagents). While it is on, the footer reads
`⏸ plan mode on`, writes and shell tools are stripped from the parent, and the harness is the
one that writes the plan file.

Plan mode exists only in an interactive session. A task on the command line never enters it,
including `seri -- "plan this"` and a positional `/plan`. See [Launching seri](/reference/cli).

## How to enter and leave

| Form           | Does                                                                       |
| -------------- | -------------------------------------------------------------------------- |
| `/plan <task>` | turn the overlay on, if it is off, and start a plan-mode turn on that task |
| `/plan`        | toggle the overlay when nothing is under review                            |
| Ctrl+O         | the same toggle as empty `/plan`                                           |
| `/clear`       | turn the overlay off and start a new session. The plan file stays on disk. |

Ctrl+O is a single-byte chord, the same class as the queue's Ctrl+P/Ctrl+N. Typed `/plan` still
works. Tab still completes slash commands. Shift-Tab still cycles `/mode` when the overlay is
off and no panel owns the keyboard. While plan mode is on, Shift-Tab does nothing, and the
footer reads `ctrl+o to leave` instead of `shift+tab to cycle`.

A `/plan` typed while a turn is running is a command error. Wait for the turn to finish. Ctrl+O
during a turn is the same error.

The overlay is not saved with the session. `--continue` and `--resume` come back with it off.

## What happens in a plan-mode turn

1. **Clarify, if needed.** The model can ask up to 3 questions, each with 2 to 6 options, plus
   optional free-text notes. It skips this panel when it already knows enough.
2. **Research.** The parent can read the tree itself. It prefers `dispatch_subagents` with
   `explore` or `plan` when isolation helps. Nested dispatch is allowed, not required.
3. **Submit.** `submit_plan` is the only write in this overlay. The harness writes a markdown
   file under your profile's `plans/` directory and then ends the turn.
4. **Review.** Approve, request changes, or cancel.

The model does not get `write_file`, `edit`, `bash`, or `powershell` on that parent turn. A child
inherits the read-only gate. It does not inherit the overlay, so it cannot call `submit_plan`.

## Questions

When the model asks, a panel sits on the input the same way an approval does. Tab, Shift-Tab,
left, and right switch tabs **inside that panel**. They do not complete a command and they do
not cycle `/mode` for as long as the panel owns the keyboard.

| Key             | Does                                                                                                   |
| --------------- | ------------------------------------------------------------------------------------------------------ |
| Tab, right      | next question, then the notes tab                                                                      |
| Shift-Tab, left | previous tab                                                                                           |
| Up, down        | move through the options, including type-your-own                                                      |
| typing          | a custom answer on the current question, or notes on the last tab                                      |
| Enter           | take the highlighted option, or send the answers from the notes tab                                    |
| Escape          | cancel the questions. The model keeps researching with what it already knows. The turn is not aborted. |
| Ctrl-D          | end the session, the same as `/exit`                                                                   |

## Where the file goes

Plans are always global. They never land in the repository.

| Profile          | Directory             |
| ---------------- | --------------------- |
| default          | `~/.seri/plans/`      |
| `--profile work` | `~/.seri/work/plans/` |

`plans` is a reserved profile name, because that directory already lives under the default root.
See [Profiles](/guides/profiles).

The filename is a slug of the title the model submitted. A collision gets a numeric suffix.
Cancel during review unlinks that file, and only if its path is inside this directory.

## Review

| Choice          | Does                                                                                          |
| --------------- | --------------------------------------------------------------------------------------------- |
| Approve         | leave plan mode, stay in this session, and start a turn that implements the approved markdown |
| Request changes | stay in plan mode so the next turn can revise                                                 |
| Cancel          | unlink the plan file and turn the overlay off                                                 |

Escape on the review panel is request-changes. Ctrl-D is `/exit`.

Empty `/plan` during review is abandon: the file is unlinked and the overlay turns off, the
same as cancel. `/plan` with a task while a review is open is a command error. Approve or
cancel first.

The message queue does not drain while review is open.

## The overlay and `/mode`

Plan mode is not a `PermissionMode`. `/mode` and Shift-Tab still cycle the stored session mode
when the overlay is off. While it is on, the indicator stays `⏸ plan mode on`, the gate stays
`read-only`, and Shift-Tab does not cycle. Empty `/plan` or Ctrl+O is how you leave.

`--dangerously-skip-permissions` does not lift that. A plan-mode turn is read-only even under
that flag. [Permissions](/guides/permissions) covers the three stored modes.