Plan mode and todos

Two separate things share the word "plan": the step list the model keeps as it works, and plan mode, an agent that researches and writes a plan file before anything is changed.

For the full design and the code paths, see PLAN-MODE.md (apps/ocean-coding-agent-rust/docs/PLAN-MODE.md in the repository); this page is the operator's summary.

The step list (todos)

For work with three or more distinct steps the model keeps a todo list — one item per step — and Ocean pager's todos pane shows it live. A single edit, one command or a plain question gets no list: the same rule Claude Code, opencode, Kilo Code and Grok Build use. Each row ticks through four states:

The model writes the list as a fenced ```todo block in its reply (or through its todo tool); the newest complete block replaces the whole list, so the pane always reflects the latest one. In the pager, ctrl+t toggles the todos pane (see 19 · Ocean pager).

If the model skips the list and then does real multi-step work anyway (twelve or more tool calls with no plan), the next step carries a reminder to write it; a plain answer is never reminded. A settled turn that still has open items is worked off (see 08 · Bounding a long run). OC_PLAN=off turns the directive, the reminder and the work-off off for a run; the todos pane and /plan keep working.

The always-plan floor

If the model has not planned yet, oceancode shows one synthesized row — your prompt text — so the list is never empty. The moment the model writes a real plan, that floor steps aside and does not come back for the session.

Editing the plan yourself — /plan

You can edit the list while a step runs; the model merges your changes with its own on the next step.

A row you add is open work: the run keeps going until it is done or a bound trips (see 08 · Bounding a long run). If you add a to-do while the agent has already finished, it counts as progress — the run picks the work back up for one more turn instead of stopping.

Plan mode

Plan mode is a distinct agent, not a key. In it the model researches and writes a plan, and may change nothing else: it may read and search, run read-only commands and send out explore agents, and its one writable place is the plan folder, .oceancode/plans/ (.md and .html files only).

• Enter it by selecting the plan agent — in Ocean pager, a bare /plan or /plan <description>, or Shift+Tab to Plan (the row-edit verbs above are the only /plan forms that do not switch mode).

• The plan file. Every plan-mode session writes one file, .oceancode/plans/<date>-<topic>-<tag>.md, where <tag> comes from the session id. It holds:

  • the goal and the research findings, with file:line references;
  • the chosen approach;
  • a Mermaid workflow diagram;
  • the to-dos as one ```todo block, with sub-steps indented;
  • a verification check per to-do, and any open questions.

  The model updates the same file as the plan changes. It writes an .html page beside it only when you ask for one. The folder lives in your project, so the plan is there to read, edit or commit.

• Review and leave it. When the plan is ready the model calls plan_exit. That refuses until the plan file exists with its to-do block, then asks you to review it. In Ocean pager the plan opens in the plan viewer, where you can comment on lines and then:

  • approve (a): the plan's to-dos become the session's to-do list, the file is marked status: approved, and the session switches to the build agent. Build first checks the plan's findings against the code, splits large to-dos into sub-to-dos, and then implements them one by one, keeping the file's status current. The run keeps going until every to-do is done (see 08 · Bounding a long run);
  • send it back (s, type your notes, Enter): the model stays in plan mode, revises the file with your notes and line comments, and asks again;
  • abandon it (q): plan mode ends and nothing is built.

  Other editors (Xcode) show the same choice as a question: Build, Keep planning or Abandon. You can type feedback there too.

The step list keeps working throughout: plan mode changes what the model may do, not how progress is tracked.

See also

• 06 · Session ledger and export — where the plan and turns are recorded.