> ## Documentation Index
> Fetch the complete documentation index at: https://www.plungeai.com/guide/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.


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 (`ocean-code/agent/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 TUI's todos pane shows it live. A single edit, one command or a plain question
gets no list: the same rule Claude Code, opencode and Kilo Code use. Each row ticks
through four states:

| Glyph | Meaning |
|---|---|
| `[ ]` | pending |
| `[»]` | in progress |
| `[✓]` | completed |
| `[✕]` | cancelled |

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 TUI, `ctrl+t` toggles the
todos pane (see [19 · Ocean TUI](/oceancode/tui)).

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](/oceancode/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.

| Command | Effect |
|---|---|
| `/plan add <text>` | Add a pending row. |
| `/plan done <n>` | Mark row `n` completed. |
| `/plan cancel <n>` | Mark row `n` cancelled. |
| `/plan edit <n> <text>` | Rewrite row `n`. |
| `/plan remove <n>` | Delete row `n`. |

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](/oceancode/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 TUI, 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 TUI 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](/oceancode/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.

### What approval records

Approving a plan makes it a contract the engine can check. The engine reads what the plan
grants and writes it as a `contract` line of `RECORD.jsonl`, in the session's ledger folder (next
to `SESSION.md`). The model never writes this file. Each approval in the session adds its own
`contract` line; the newest one is the plan the session runs under, and the steps and the
approver start afresh from it.

- **What each to-do may change**: every file or folder the to-do names in backticks.
  `a/{b,c}.rs` counts as two files; a command, code such as `Path::new`, or a placeholder such
  as `<topic>.md` counts as none.
- **How the plan is proven**: the rows of the plan's `## Verification` table (step, check,
  expected result).
- **The areas it touches.** An area is a folder with its own `CLAUDE.md` or `AGENTS.md`, or one
  that `.oceancode/areas.json` adds. The map file can give an area an owner. An owned area is a
  border, and the record lists each border the plan crosses:

  ```json
  {"areas": {"core/core-auth": {"owner": "andreas"}, "tests/live": {}}}
  ```

- **Who approved it and when**: `review` when you answered the review question, `headless`
  when no one could be asked, plus the operating-system user and the time.

The build agent is told which to-dos name no file or folder, so it can add the paths when the
work shows them. When a later turn changes a to-do's paths or the Verification rows, the engine
adds one `plan_changed` line. Edits to prose, checkboxes or the `status:` line add nothing. A
`.oceancode/areas.json` that cannot be read never blocks an approval: the build agent is told,
and the record lists no areas.

### What done means

After approval, a step marked `completed` counts as done only when its check has passed since
its files last changed. The record keeps the evidence, one line per event:

- **`write`**: a file-editing tool (`edit`, `write`, `apply_patch`) changed these files.
  The record does not see changes made through `bash`; a land does: a file it changes that no
  `write` line names is "Not judged" (below).
- **`proof`**: a command the engine recognises as a check ran (a test suite, a type check, a
  build, a script named like `check.sh` or `run_tests.sh`). The line keeps the command, its exit
  code, the steps whose Verification row names that command in backticks, those steps' files,
  and a hash: SHA-256 over each file's path and git blob id, in path order.
- **`step`**: a step marked `completed` whose Verification row names a check command is
  `proven` when a passing `proof` line for it comes after the last `write` to its files, and
  `unproven` otherwise. A line is added only when that state changes.

When a step becomes `unproven`, the model is told once, at its next step, which check to run.
It is told, not stopped. A step whose check is prose ("read it by eye") is not judged, and a
session without an approved plan reads and writes nothing.

A check proves a step only when the command runs it whole, word for word as the Verification
row writes it (redirections such as `2>&1` and a leading `./` aside): for the check `cargo test a`,
`cargo test a --no-run`, `cargo test ab` and `cargo test a -- --list` prove nothing, and a narrower
filter or another script is not the check. A variable the check sets must be set the same way
(`E2E=1 bash check.sh` is not proven by `bash check.sh`, but is by `export E2E=1 && bash check.sh`);
the command's own other variables change nothing. A `cd` before the check is taken as the check
run from there, so write the folder into the Verification row when it matters
(`cd ocean-code/agent && cargo test`).
And only when its exit code counts: run it as its own command, alone or
joined to the commands around it with `&&` (`cd sub && cargo test`). A check piped into another
command (`cargo test 2>&1 | tail -2`) or followed by `;` or `||` (`cargo test; echo done`,
`cargo test || true`) proves nothing, because the exit code is then the last command's, not the
check's. Each `proof` line says so in `counts`. When a plan is approved, the handoff names the
steps whose check the engine cannot judge (a Verification row with no check command, such as
`test -f a.txt`, or no Verification row at all), so you know their "done" will not be checked.

A `write` line also lists the files outside the plan (`outside`: written files that no to-do's
path covers; the plan file itself and files `.oceancode/areas.json` marks `no_plan` never count)
and the owned areas the files lie in (`borders`). Every `write` and `proof` line names the
session that ran the tool (`by`). A helper started with `task` has no record of its own: its
writes and check runs go to its lead's record, under the helper's own session id.

### What a land carries

In an Ocean Git workspace, a `land` by a session with an approved plan sends a receipt of the
record with the commit:

- the session and the plan file, with who approved it and when;
- each step marked done whose Verification row has a check, with the check and whether it is
  `proven` (a step never marked done is not in the list; it is a "Not finished" reason);
- the verdict: `clean`, or `exceptions` with one reason per line (a step not proven or not
  finished, a file written outside the plan, a write into an owned area, a check the engine
  cannot judge, a damaged record);
  - a plan whose to-do paths or Verification rows changed after the approval is not clean; the
    reason names the changed steps. Adding paths to a to-do that was approved without any, as the
    build agent is told to, does not count as such a change;
  - each proven step's files are hashed again at the land and compared with the hash its check
    kept, so a file changed after its check (by a formatter or a command) makes the step not
    proven;
  - a to-do that names no path and has no check is listed as not judged;
  - a file the land changes that no `write` line names (a delete, or a file a command wrote) is
    "Not judged", because the record cannot vouch for it;
- the hash of the land's own changes, which Ocean Git computes again from the request.

The question that asks you to allow the land names the verdict and its reasons. The receipt is
at most 64 KB; a longer one is cut from the end of its lists and says so. Ocean Git keeps it with
the commit: `GET /api/receipts?sha=<commit>` returns it, the change log names its session, plan
and verdict, and the Ocean application shows it on the commit's page as "Plan record".

A session without an approved plan sends no receipt and lands as before. An Ocean Git older than
0.8.8.092 does not know the field: the land is sent again without it and the result warns that it landed without one. A
record that exists and cannot be read is sent as one exception, never as "no record". When
Ocean Git lands the commit but sets its receipt aside (it cannot read it, or cannot keep it), the
result warns "Ocean Git kept no plan record for this commit (…)" with Ocean Git's reason
(0.8.8.111; before, the land read as if the receipt were kept).

Ocean Git can refuse an agent's land on `main` that has no clean receipt (its setting
`LAND_NEEDS_RECEIPT`). It is off. A person's land is never refused for its receipt.

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](/oceancode/session-ledger-and-export) — where the plan and turns are recorded.
