Write the product vision

Decisions every plan would otherwise ask again

Every planning session runs into the same questions: who this product is for, how alike two screens have to look, what it will never do. They are not gaps in one task. They are decisions nobody wrote down, so every task pays for them again.

/vision writes them down once, in your project's vision.md. /plan-prompt reads it before it asks you anything, so a question the vision answers is no longer asked.

It runs rarely: once to create the document, and again only when you want to complete or revise part of it. It is not a step of any task.

When planning asks for it

When you plan a change that decides something and your project has no vision yet, /plan-prompt stops and tells you to run /vision first, then come back. It does not run it for you.

If you said the task is urgent, planning carries on without it and, when it hands you the plan, tells you that it was made without a vision and that /vision is still worth running. A change that decides nothing is built directly and is never held back for a vision. The difference between the two is in Which route your change takes.

The seven things it asks

Category	What it settles
Audience and goal	Who uses the product, what they are trying to get done, and what it is for.
Consistency principles	How alike two screens that do similar things have to look and behave, and where variation is allowed.
Tone and communication	How the product talks: to whom, how formally, and what it never says.
Cross-cutting business rules	The rules that hold everywhere: what is always true about money, permissions, dates, ownership.
Product non-negotiables	What the product will not do, no matter who asks.
Domain naming	What things are called here, and what they are never called.
Product priorities	What gets traded away first when something has to give: speed, completeness, simplicity, cost.

It drafts, you confirm

You are not asked to write any of this from a blank page. Before asking, /vision reads what your project already says about itself: its README, what it shows the outside world — a landing page, the copy on its entry screens — its developer documentation and the instructions it gives its assistants, and last the names the code uses. It drafts an answer for every category those sources speak to, and each draft names where it came from, so you can correct it in a word.

A category nothing in the project answers arrives as a plain question, said to be one. Every pending category comes in a single message, not one at a time.

A draft is not an answer. What you confirm is written as the answer, what you correct is written as corrected, and what you leave unanswered is written as pending. Silence never turns a draft into a decision, because the next planning session would trust it as one.

Where it lives

vision.md is a document of your project in the toolkit, not a file in your repository. You find it at the top of your project in the Projects section; it has no branch and no status. See Your projects and their documents. When the toolkit is not connected, /vision stops and says so rather than writing the vision anywhere else.

Running it again

A later run reads the existing document first. Every category already answered stays as it is: /vision fills what is still pending and revises only what you ask it to revise, drafted the same way from what the project says now.

What the first run also corrects

The run that creates vision.md does one more thing, once per project. Planning reads your developer documentation before it reads code, which only works if that documentation is true.

Developer documentation. The analyst agent reads the documentation in your project's documentation folder against the code and reports what is no longer true. You see the list before anything changes, and only what you confirm is corrected. Documentation for something nobody documented is not written here: that is /document's work.
Analysis statuses. Each analysis in your project's analysis/ folder is read against the code with one question: is what it describes built? One that is built but not marked so is proposed for Implemented. Paused and rejected stay as a person left them, and one only partly built is left alone and reported. These go into the same confirmation.

The vision and any status it moves live in the toolkit and are never committed. When it corrected developer documentation, which does live in your repository, it makes one commit with only those files. A project with nothing to correct is told so.

Decisions planning proposes for it

Planning keeps an eye on what it asks you. When three earlier plans settled the same question the same way, and the answer belongs in one of the seven categories, it asks whether that answer belongs in the vision. If you say yes, it tells you the category and the answer to record, and you run /vision to write it. From then on that question is no longer asked.

Planning before building — the planning step that reads the vision.
What each command does — /vision beside the other commands.
Your projects and their documents — where vision.md sits.