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.

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

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. It spawns a separate working thread seeded with the plan, so the build starts with fresh context instead of running in the middle of the planning conversation. Build & ship does the same and has that thread open a pull request once the work is complete and verified.

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

Attaching, and building one plan twice

A thread can attach to an existing plan to become the thread building it. Attaching is what links the thread into the plan's references and lets its PR close the plan when it merges.

Several threads can attach to and build the same plan — to compare models, say. Each is its own thread on its own branch with its own PR, so they never collide.

An agent can also file a follow-up plan as a handoff: it mints a new idle thread that owns the plan and waits for someone to build it.

When the premise turns out to be wrong

Builds discover things. If the plan's premise doesn't survive contact with the code, the agent stops and revises the plan for re-approval rather than quietly building something else. The plan stays the record of what you agreed to.

Where plans live

Filed plans appear on the Project Map in their own column, and in Collections alongside every other durable document. A shipped plan is frozen — follow-up work forks rather than reopening it.