Plans & the Build button

Not every request needs a plan. The lead agent sizes up each turn, and when work is complex, risky, or ambiguous it writes a plan document into your project's Plans collection instead of typing code.

A plan is a card, not a chat message

Proposing a plan ends the agent's turn — it stops and waits for you. The plan renders as a dedicated card in the chat with full Markdown, tables and mermaid diagrams included, and it's a real versioned document you can also read in Collections. The card leads with a plain summary; engineering details fold away behind a toggle.

What a good plan contains

A plan shows the system before and after, in the same shape:

• The problem, and the current state that causes it
• The future state — the same picture, after the change
• The approach, and the key files it touches
• Risks, and the open questions you need to answer

Plans are short by default, sized to the change. A two-file fix doesn't get ten sections.

Revision happens in place

Before Build is dispatched, send feedback and the agent revises the plan in place rather than posting a second one. The card re-renders with the added and removed lines shown inside it, and the agent narrates what changed and why. A revision can retitle the plan when the scope moves.

One thread owns one plan for its whole life. If you want a genuinely different plan, that's a new thread or a fork — a fork inherits the conversation but not plan ownership, so it's free to propose its own.

Build

Build is one click. Its chevron opens build options, such as the model the coders that type the change run on. While the work runs, the card reads Building — this thread is on it; afterwards it shows Built — not shipped yet, then Shipped once the work lands through a pull request. A plan waiting for you also leaves a Ready to build card at the end of the transcript, with the same Build button and a View plan ↑ link.

If main moves after a plan is written, the card warns May be out of date — N behind main and offers Update plan to re-verify it against the current code; updating the thread from main reviews its unbuilt plan too.

You don't have to use the button — you can simply tell the agent in chat to proceed in-conversation.

Follow-ups as briefs

A thread creates and builds its own plan; attaching several threads to one existing plan is not available.

When you request follow-up work or approve a deferral, the agent can file a follow-up brief. If this thread has unmerged code, the brief waits for its PR to merge. Otherwise the new thread starts immediately. That thread reads the current code, writes its own plan, and stops for you to review and Build.

When the premise turns out to be wrong

Builds discover things. Once Build is dispatched, the approved plan is frozen. If the agent needs to deviate from it, it explains the difference in chat and asks for approval rather than revising the card or quietly building something else. The final report and PR description record what was actually built.

Where plans live

Filed plans appear in the Knowledgebase's Plans section, under the area they concern, alongside every other durable document. A shipped plan is frozen — follow-up work forks rather than reopening it.