0016 — Plan mode
- Status: accepted · Raised by: the project owner, 2026-11-01
- Specs: IF-0.5, IF-6, IF-7; a sibling of ADR 0013 (step-debug mode) and ADR 0014 (reliability monitoring)
The idea
The harness gets a plan mode. It is the classic plan mode of agent harnesses:
- the agent studies the task and the code and writes a plan before it changes anything;
- the user approves the plan;
- only then does work begin.
Here the accent is on the harness's memory tools:
- the journal:
- every decision, finding, assumption and open question of the planning goes into the journal as it is made;
- the work items of the plan are journal todos, each with its test protocol (what to test, regressions included, how, under which conditions, what evidence proves it);
- the rules the work must follow are specifications and constraints;
- mind maps — the map of what is known about the task: decisions, questions, constraints, invariants, alternatives considered and rejected;
- flowcharts — the flows the plan changes or adds, drawn before they are built.
The mode sets the agent's rules. While the mode is on, the context carries the instructions for these tools:
- what to journal and how;
- when to open a mind map and what goes into it;
- when a flow deserves a flowchart.
They go when the mode ends, which hook context could not do. Entering also fires the hook point PlanEnter (IF-6) for a project's own hooks. Leaving the mode is the user's approval of the plan.
Decided by the owner (2026-11-01)
-
What plan mode allows. The engine enforces it and the rules tell the agent. Only these are available now:
- the harness's tools (journal, mind maps, flowcharts);
- read operations (reading, searching, read-only commands);
- web search.
No edits to the project, no commits, nothing with side effects. It also sets the mindset: concentrate on planning, do not get distracted by anything else.
-
The plan is the journal. The approved plan is not only text in the conversation: it is the set of journal todos, specifications and decisions the planning wrote, plus its mind map and flowcharts, so the next session and other agents find it.
-
A framework, not instructions. Where plan mode elsewhere is a prompt, here it is a framework: documented tools, attention to keeping the documentation current, spec-first (P-4, P-10).
-
Switching (answers Q-25). Both ways, as in other harnesses: the user switches the mode on, or asks the agent to plan something and the agent enters plan mode itself. Leaving it takes the user's approval of the plan.
-
The plan is mirrored into the documentation (answers Q-26; replaces the earlier "plan file is optional"). Writing documentation to files is mandatory: the plan's decisions, specifications and questions go into their files and its work items into the roadmap, consistent with the journal and maps (ADR 0017, CON-43).
Open
(none)