# Planning with the agent How the conversation works, why it researches before it asks, and how to correct a Spec. Planning happens as a conversation. You describe the business requirement, the agent works, and you correct it. There is no form to fill in. ## It researches before it asks [#it-researches-before-it-asks] The agent reads your Context first (the documents attached to this plan, its project and your team, plus any connected repository), and only then asks you questions. That ordering matters. An agent that asks first wastes your time on things it could have looked up, and an agent that never asks invents the answers. You should expect a short pause, then questions that are specific to your business rather than generic. ## Answer the awkward questions [#answer-the-awkward-questions] The questions worth answering carefully are the ones about edge cases: what happens in a different time zone, who gets notified, what the state is after a failure. Those answers become acceptance criteria, and acceptance criteria are what make a Spec buildable. If you do not know an answer yet, say so. "We have not decided" is a real answer and the agent will write the Spec so the decision is visible rather than silently assumed. ## When the agent shows instead of tells [#when-the-agent-shows-instead-of-tells] Some answers are not paragraphs. When the reply compares two or more options, lists three or more rows of the same shape, states a few key numbers, or lays out a sequence of steps, the agent draws it as a card under what it wrote. A card never replaces the answer. The agent still says what it thinks in words, and the card carries the structure: a comparison table with one column marked as the recommendation, a set of options with a button each, a table, a row of numbers, a timeline. Clicking a button in a card sends your choice as your next message, so a decision costs one click instead of a sentence you have to retype. If the agent needs a few short answers it can show a small form instead; half-filled values come back if you leave the page and return. It can also put a picture into a spec: ask it to add a screenshot or mockup from your context, and it places the image where you say. See [Images in documents](/docs/images-in-documents). ## Point at something with @ [#point-at-something-with-] Type `@` in the message box to point the agent at exactly what you mean instead of describing it. Nothing is typed first: `@` opens a short menu of the three places things live, each with a count. | | | | ----------- | --------------------------------------------------- | | **Plan** | your epic, your specs, and any prototypes | | **Context** | the documents on this plan and the ones it inherits | | **Code** | files in the repositories connected to this project | Press `→` to walk into one, `←` to come back out. Or skip the browsing and keep typing: the menu searches all three at once, and it matches loosely, so `authsvc` finds `auth-service.ts`. Whatever you pick is inserted as plain text, and the row that appears under the box shows what the agent will actually read. If something you typed by hand does not appear there, the agent will not find it either. Mentioning a file does not change what else the agent can see. It reads your whole Context as usual; `@` only says which part you are talking about right now. ## Attach files to a message [#attach-files-to-a-message] Paste a screenshot, drop a file on the message box, or click the paperclip. Each file shows as a chip above your text while it uploads, and Send waits until they have all finished. A message can be files alone. Every file you attach is saved to the plan's Context under `attachments`, so the agent can read it this turn and later ones, and you can ask it to put a picture into a spec: "put this in SPEC-3 under Screens". See [Context](/docs/context-sources) and [Images in documents](/docs/images-in-documents). ## Correcting a Spec [#correcting-a-spec] Highlight the part that is wrong and say what you want instead. A small box appears at your selection; type your note and press Enter. The agent receives the passage along with your note, so you never have to describe which part you meant. This works anywhere you read the plan: a spec, your epic, your context sources, and the agent's own answers in the conversation. Quoting an answer back at it is often the fastest correction of all, because it lands on the exact sentence rather than the whole reply. When the change is bigger than one passage, ask in the conversation and name the Spec: ```text SPEC-4 should also cover weekly schedules. Editing a saved report changes what the next send contains, not the schedule itself. ``` Either way the agent rewrites that Spec in place, including its acceptance criteria. You can also edit any Spec directly if you would rather write it yourself. ## Readiness is the signal to watch [#readiness-is-the-signal-to-watch] Each Spec carries a readiness of **Rough**, **Shaping** or **Ready**. It is the agent's judgement about whether someone could pick this up and build it. A plan full of Rough Specs is not a bad plan; it is an early one. Ask the agent what is missing and it will name the specific gaps rather than rewriting everything. Readiness is about the Spec, not about you. A Spec can stay Rough because a business decision has not been made yet, and that is worth seeing rather than papering over. ## When the work is too big [#when-the-work-is-too-big] If the conversation keeps splitting into topics that need different background material, that is the signal to break the plan up. See [Sub-plans and dependencies](/docs/sub-plans-and-dependencies).