For AI agents: an index of this guide is available at https://www.plungeai.com/guide/llms.txt. Append .md to any page URL, or send Accept: text/markdown, to get markdown. The developer documentation is at https://www.plungeai.com/docs/llms.txt.

Documentation Index: fetch the complete documentation index at /llms.txt. Use this file to discover all available pages before exploring further.
Feedback

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:

GlyphMeaning
[ ]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.

CommandEffect
/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 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);
    • 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:

    {"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