Use
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 (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).
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.
| 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). 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
planagent — in Ocean TUI, a bare/planor/plan <description>, or Shift+Tab toPlan(the row-edit verbs above are the only/planforms 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:linereferences; - the chosen approach;
- a Mermaid workflow diagram;
- the to-dos as one
```todoblock, 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
.htmlpage beside it only when you ask for one. The folder lives in your project, so the plan is there to read, edit or commit.- the goal and the research findings, with
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 markedstatus: approved, and the session switches to thebuildagent. 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 planningorAbandon. You can type feedback there too.- approve (
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}.rscounts as two files; a command, code such asPath::new, or a placeholder such as<topic>.mdcounts as none.How the plan is proven: the rows of the plan's
## Verificationtable (step, check, expected result).The areas it touches. An area is a folder with its own
CLAUDE.mdorAGENTS.md, or one that.oceancode/areas.jsonadds. The map file can give an area an owner. An owned area is a border, and the record lists each border the plan crosses:{"areas": {"core/core-auth": {"owner": "andreas"}, "tests/live": {}}}Who approved it and when:
reviewwhen you answered the review question,headlesswhen 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 throughbash; a land does: a file it changes that nowriteline 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 likecheck.shorrun_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 markedcompletedwhose Verification row names a check command isprovenwhen a passingproofline for it comes after the lastwriteto its files, andunprovenotherwise. 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, orexceptionswith 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
writeline 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 — where the plan and turns are recorded.