Coldstart is in final cutover and has not been released. The behavior on this page runs in the development build; there is no release you can install today.
The planning pass is one session that decides the shape of the work and builds none of it. It settles what is being made and for whom, what structure has to stay coherent while it is made, what order the pieces come in, and what the first piece's sessions are. Its entire output is plan files.
It is a separate session on purpose. Planning and building want different attention, and mixing them is how the first implementation choice becomes the architecture by accident.
[Visual 2.1 — The work-loop chain from the section opener with the Plan block enlarged and the other three dropped to thin outline. Inside the enlarged block, four boxes stacked top to bottom with a downward arrow between each: "Brief — what we are agreeing to attempt", "Architecture — what must stay coherent", "Master plan — what must exist before what", "Section plan — the next piece, as sessions". A tag on the block's left edge reads "no code this session, enforced"; a small note beside the bottom box reads "only the first section is detailed".]
The problem it solves
An idea that is too large for one sitting has to be divided before it can be worked on, and someone has to divide it. If nobody does, the division happens anyway, one implementation choice at a time, and nobody can see it happening.
The visible symptoms are familiar. Adjacent features enter scope without anyone deciding to admit them. A structural choice made in the first hour turns out to be load-bearing in the fifth session. A later session has to reconstruct the original intent from a conversation that is no longer in front of it.
A planning pass makes the division an explicit, inspectable act. It costs a session, and it is the only part of this method that asks for one up front.
What it does during a real session
It declares on disk that this is a planning session, before it announces it. That declaration is a field in the project's pointer, and a boundary check reads it: while a planning session is declared, writes outside the section being planned are refused, and so is any command that is not provably read-only. This matters because "plan files only, no code" as a promise in prose is a promise the agent can forget. As a field on disk it is a condition other parts of the product enforce.
It settles the product's shape before asking anything about tools. Who it is for, where it runs, the one journey that has to work, the top three features, the top three explicit non-goals, single or multi user, online or offline. That set is capped deliberately: it exists to establish shape, not to plan detail that will age before it is used.
It asks only the questions that change the plan. Section count, section ordering, structural choices, hard external dependencies, what "done" means for the project as a whole. Anything that does not move one of those is deferred to the session that will actually need it.
It writes four durable answers. The brief records the intended user, the outcome, the scope, the non-goals and the constraints. The architecture records the important structure and boundaries. The master plan orders the major areas and makes their dependencies visible. The first section's plan turns that area, and only that area, into sessions.
It details the first section only. Later areas keep their place in the order and stay undetailed until their turn, because the sessions that run before them produce better evidence than anything available today.
It ends by minting the pointer. The last act writes the small resume file the next session will read, naming the first session's action and the files it should read.
How a session entry is composed
Each session in the first section's plan is written in a fixed order, because the later fields are inferred from the earlier ones: the one-line goal, the exact files to read, three to seven build steps, the files expected to change, the checks that would establish the result, and the intended output.
Two of those are proposed rather than requested from scratch. The file list is inferred from the build steps and offered for you to correct, named in your project's actual idiom rather than as a generic placeholder. The check list is scaffolded from a recognized pattern when one matches, so that a session about a webhook gets signature, tampering, duplicate-event and logging checks rather than "test it works". When no pattern matches, the pass asks for two to four concrete checks instead of inventing vague ones.
A session entry that grows past a set length is treated as a sizing signal and split, on the same reasoning as the one-sentence goal test: length is usually two jobs wearing one name.
When to use it, and when not
Use it for a new project, for a major capability expected to span several sessions, and for work whose ordering, dependencies, human decisions or verification boundaries need to be settled before anyone starts.
Skip it for a small, obvious change that fits one session and carries little adjacent risk. A short statement of outcome, scope, non-goals and checks is enough there, and the planning ceremony would cost more than it saves. That judgment is yours: the product cannot infer it from the size of the repository.
Do not use it to build. If the shape is already settled and you want work done, the planning pass is the wrong door and it will refuse to write code through it.
Limits
A plan is not proof. It names the checks that would establish the result; naming them passes none of them. The session that does the work still has to run them and report what it could not establish.
A detailed plan built on stale evidence is confidently wrong. Planning makes intent inspectable before work begins; it does not make the underlying facts current.
The architecture can meet a constraint nobody knew about, and the check list can test the wrong condition. When new evidence breaks a load-bearing premise, the plan is what should change first, before the work that depends on it continues.
Nothing here establishes that a generated plan is accurate, complete, or better than one you would have written yourself. What it establishes is that the plan exists in files, in a form a session that was not present for the discussion can read.
Next
With the shape settled, the next unit is one piece of it: the bounded session.
How current this page is
Checked on 10 August 2026 against the product's current planning procedure and its recorded release state. It describes what the planning pass does, not evidence that planned work turns out better. To ask whether a claim here still holds, or to report one that does not, write to [email protected].