Planning
Work out the approach before a single file changes.
architect reads the code and returns the critical files, the trade-offs, and a step-by-step plan, without editing or writing anything. planSubAgent does the same thing but saves that plan to a file you can review.
A change large enough that jumping straight to editing risks going down the wrong path: a new subsystem, a migration, anything where "what should happen first" is itself the open question.
You describe the goal
We need to move session storage from cookies to a database-backed store. Plan it.
Plan written · nothing edited
It can never touch code
architect has no edit or write tool at all, which is not a limitation worked around here, it is the entire point.
Checked the repo before answering
It will tell you the task does not make sense
Asked to plan a migration for a system that was never built, architect said so: grepped the whole repo, found no session code, no database, and named the request a net-new build dressed as a migration, rather than inventing a plausible-looking plan for code that does not exist.
Two tools, one of them never lights up
read
write
A plan that cannot be executed cannot cause damage
No edit or write tool is available to it at all, not a policy it follows but a capability it does not have. A wrong plan costs you a re-read; a wrong edit costs you an undo, or worse, one you do not notice in time.
Checked against what's actually installed
framework docs
v16.3
It reads your actual dependency versions, not its training data
Before proposing an approach, it checks the installed framework version's own documentation for API shape and deprecations, so the plan does not quietly assume a pattern your version already changed.
An open question, held apart from the plan
which DB?
Open questions get named, not guessed past
Where a real decision depends on something only you know, it says so directly and stops there, instead of picking a plausible default and writing the rest of the plan on top of a guess.
Doing it by hand vs. handing it off
You start editing, realize four files in that the approach does not hold up, and either untangle a half-done change or start over with what you now know.
architect reads the code and returns the plan first: which files, what trade-offs, what order. Nothing is edited until the plan itself holds up.
Which agent actually does this
architect
Plans, never edits
Reads the code and returns the critical files, the real trade-offs, and an ordered plan. No edit or write tool available to it at all.
planSubAgent
Same plan, saved to a file
Runs the same investigation as architect, but writes the finished plan to a markdown file for review and sign-off instead of returning it inline.
How it actually runs
Some changes are big or unfamiliar enough that the order of work is not obvious yet. Planning first turns that uncertainty into a concrete, readable plan, before any edit is on the table.
Describe the goal, not the steps
Say what you are trying to accomplish. architect works out the how, not the other way around.
It reads the relevant code
Before proposing anything, it identifies the critical files and how the current implementation actually works, so the plan is grounded in the real codebase.
It returns files, trade-offs, and steps
A concrete plan: which files are involved, what the real trade-offs are, and an ordered list of steps. It cannot edit or write, so this is a read-only proposal.
Write it down, or hand it off
Ask planSubAgent to save the plan to a markdown file for review and sign-off, or take it straight to general to execute once you are satisfied.
We need to move session storage from cookies to a database-backed store. Plan it.
I'll hand this to the plan subagent to investigate and write up the migration plan.
The plan is at .ml-ai/plans/cookie-to-db-session-migration.md — but the headline finding is that this repo has no auth, no cookies, no session code and no database at all, so the plan is written as a gated greenfield build.
Pick the feature that needs sessions, pick a DB (Postgres + Drizzle suggested), then db/schema.ts db/index.ts migrations lib/auth/session.ts with an opaque httpOnly cookie ID.
We need to move session storage from cookies to a database-backed store. Plan it.
What actually goes wrong, without it
Three specific ways this kind of task breaks, and the part of the mechanism above that closes each one.
01 · Problem
The wrong file, discovered four edits in
The change looks like it belongs in one module, until the third or fourth file in you find the actual logic lives somewhere else, and the first few edits were against the wrong abstraction.
How Planning closes it
architect reads the real call paths before proposing anything, so the file list in the plan reflects how the code actually works, not where the change looks like it should go from the outside.
02 · Problem
A stale assumption about a dependency's API
A pattern that was correct for an older version of a framework or library gets carried forward out of habit, and the plan is built on an API shape that changed underneath it.
How Planning closes it
It checks the installed version's own documentation before proposing an approach, so the plan reflects what your dependencies actually support today, not a remembered default.
03 · Problem
A decision nobody wrote down
The real blocker is not technical, it is that which database, which auth provider, or which team owns the migration was never decided, and skipping past it just defers the same question to code review.
How Planning closes it
It names the open decision explicitly and stops there, rather than picking a plausible default and writing the rest of the plan as if that choice were already made.
Where this stops
The real edges of what general can do here, stated plainly instead of left for you to discover.
Neither agent can execute the plan. planSubAgent can only write its own plan file; carrying it out is a separate handoff to general.
A plan is only as good as what is in the repo. A decision that lives in a team convention nobody wrote down needs to be stated in the request.
Planning first adds a step for no reason on a task that is already well-defined. It pays off on the uncertain or large ones.
The same agent, applied elsewhere
Build
Most agents bill every step of a feature at frontier rates. ML.ai Code reads and plans on a lighter model, spends the frontier tier only on writing and checking the diff, and hands you the same reviewed change for about 30% less.
See how it worksQuestions worth asking
Try ML.ai Code today, or talk to us about what is next.
Install the editor agent on your own machine, or book a call to talk through your team's workloads.