Coldstart is in final cutover and has not been released. The commands on this page run in the development build; there is no release you can install today.
/prep runs a planning pass. Its entire output is plan files: what is being built, how it is
structured, how the work divides into sections, what the first session should do, and where a later
session resumes from. It writes no application code, and that restriction is the feature.
[Visual 1.3 — The session ring with the build segment greyed out. The same four-arc ring as 1.1, but the Plan arc is filled in the accent red and the Build arc is drawn in flat grey with a diagonal hatch and the label "no code written here". Running outward from the lit Plan arc, a short horizontal chain of four small document icons: Brief, Architecture, Master plan, Section plan card, each connected by a thin arrow to the next. A fifth icon sits slightly apart at the end of the chain, drawn as the pointer card from 1.1, joined by a dashed arrow labelled "and the address a later session starts from". Caption under the chain: "the pass ends where the first build session begins".]
The problem it solves
When planning and building happen in the same breath, the first implementation choice becomes the architecture. Nobody decided it; it was simply the first thing written, and everything after it was built to fit.
The related failures are familiar. Adjacent features enter the scope without anyone approving them, because they were adjacent and the agent was already there. Later sessions reconstruct the original intent by reading code, which recovers what was built and loses why. A question that genuinely needed your answer gets resolved by a plausible default, and the default is only discovered months later when it turns out to be wrong.
A separate pass with a hard rule against writing code makes those decisions explicit while they are still cheap.
What it produces
The pass declares on disk that this is a planning session, the mirror of what the start verb does for a build session. Then it works through a fixed sequence, asking you the questions it cannot answer for you.
The brief. What is being built and for whom. For a product-shaped brief this includes a specific audience rather than "everyone", where the thing lives (mobile, responsive web, desktop, a local file, a command line tool, a browser extension), the one user journey that has to work end to end in the first version, the top three features, the top three things explicitly excluded from the first version, whether it is single-user or multi-user, and whether it is online or offline-first. Those answers set the stack, so they are asked before any stack question.
The clarifying questions. Only the ones that change the plan. Anything the pass can settle from evidence, it settles.
The architecture file. The structural decisions, recorded where a later session can read them instead of inferring them.
The master plan. The project cut into sections, with their dependencies and their status. A section is the planning unit: one plan file, one or more sessions, one row in the master plan.
The first section's plan card. Only the first. The card carries a one-line goal, the exact list of files a cold session should read, three to seven build steps, the files expected to change, the checks that would establish the result, and a commit-message hint. The pass proposes the file list from the build steps rather than asking you to write it from scratch, and scaffolds the check list from a recognized pattern when one matches. You edit both.
The pointer. The short header a later session resumes from, pointing at the section and session just planned.
Later sections are deliberately not planned here. Detail written weeks before it is executed drifts against the project it describes.
Planning one section later
Once a project exists, /prep <section> plans a single section on its own. It creates that
section's folder and drafts its plan card, skipping the brief, the architecture and the master plan,
which already exist.
There is one detail worth knowing, because it is the difference between a plan that exists and a plan the product can find. Drafting the section's folder and card is not enough on its own: until the section is registered into the master plan by an explicit call, it has a folder and nothing else. No row in the master plan, no state, and invisible to every session that cold-starts. The pass makes that call as part of birthing the section, but if you are assembling a section by hand, that is the step that is easy to omit and hard to notice.
The reverse case is handled too. When a session starts and finds that the next active section has no folder, or a folder with no plan card, it halts and tells you to run the planning pass for that section first rather than proceeding on an empty plan.
The whole-system variant
There is an optional wider mode, requested explicitly, that produces a whole-system design set rather than a single project plan. It is a separate payload that is only read when you ask for it, so the ordinary planning pass stays as small as it is.
When to use it, and when not
Use it before work that spans more than one session, touches more than one surface, or has open questions whose answers change the shape of the result. Use it when a project exists but the next section does not yet have a plan.
Do not use it for a one-line edit or a single-file change. The ceremony costs more than the work, and the product says so rather than pretending otherwise.
Do not use it to build. If you find yourself wanting the code written during the planning session, that is the signal that the plan is finished, not that the rule should bend.
Limits
Open questions are yours. The pass surfaces them; it does not resolve them by picking the most likely answer. A planning session that ends with unanswered questions has done its job, and answering them is your call rather than a gap in the output.
A plan is a hypothesis. It can be complete, internally consistent, and built on an assumption that turns out to be false at the first contact with the code. That is an expected outcome rather than a failure of planning, and there is a separate mechanism for changing course once it happens.
Planning quality is not verified by the pass. Nothing checks that the check list is capable of failing, that the build steps are the right ones, or that the section boundaries are natural. A detailed plan built on stale evidence is still false preparation.
The pass produces files. It does not produce agreement, and it cannot make a decision you have not made.
Next
A session that has been started and worked has to be closed before anything it learned becomes durable: closing a session.
How current this page is
Checked on 10 August 2026 against the product's current planning pass and its recorded release state. It describes what the pass produces, not evidence that planned projects finish faster. To ask whether a claim here still holds, or to report one that does not, write to [email protected].