# 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. ## 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. ## 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).