Plan Before You Build
Use Plan Mode to turn a fuzzy idea into decisions, boundaries, risks, and a build sequence without changing code.
By the end
An approved implementation plan with named users, workflows, data, states, risks, acceptance checks, and rollback points.
Use Plan Mode as a thinking room
Plan Mode is for questions, brainstorming, architecture, and ordered task design without editing project code or data. Open the mode selector at the lower-left of the Agent chat input and choose Plan. Use it when a request spans several features, introduces a database or integration, affects existing behavior, or contains a decision you do not yet understand. Build mode is appropriate when the scope is already narrow and the acceptance checks are clear.
Read-only does not mean free or passive: Plan Mode interactions use the same effort-based Agent pricing model, and longer or more complex planning can cost more. Ask it to inspect the existing project, identify the current flow, compare approaches, expose missing decisions, and propose a sequence. The highest-value output is a short list of choices you understand and can approve—not a specification whose length hides uncertainty.
Turn ideas into state transitions
Software changes state. A request begins as draft, becomes submitted, gets triaged, is assigned, and eventually closes. An invoice begins pending, is approved or rejected, then is paid. Plan the states, the actions that move between them, who may perform each action, and what evidence the system records.
This is more precise than listing pages. Once the state machine is clear, screens become views and controls over that state. It also reveals edge cases: can a closed request reopen, can two people approve at once, and what happens if an external call succeeds after the local request times out?
Force the data conversation
Ask what records exist, which fields identify them, where each field originates, and which system is authoritative. Separate user-entered facts from derived values. Name data that must persist, data that may be cached, and data that should never be stored. These choices determine the schema and the security boundary.
Plan migrations before data exists in production. Adding a required field to an empty table is easy; adding it after thousands of records requires a default, backfill, staged rollout, or temporary nullable state. A good plan includes both the desired schema and how the current state safely reaches it.
Plan vertical slices
A vertical slice delivers a thin end-to-end journey: interface, server logic, data, error handling, and verification for one capability. Prefer 'create and view one request' before separately building every screen, then every API, then every table. Vertical slices reveal integration problems early and produce checkpoints that are meaningful to users.
Order work by uncertainty and dependency. Confirm an unfamiliar API or permission model with a small probe before designing the whole product around it. Establish authentication before user-owned data. Build observability before a complex background job. Put irreversible or expensive changes behind explicit approval.
Choose main-thread Build or background Tasks
Plan Mode has a main-thread implementation path. Selecting Start building approves the current plan, switches that same main thread to Build mode, and Agent implements there. That path does not produce an isolated Ready task with Apply or Dismiss controls. To implement only one vertical slice in the main thread, revise the plan until the approved plan contains only that slice, then select Start building.
Background Tasks are a separate execution path. Agent proposes Draft tasks on the task board; View plan lets you inspect them, and Accept tasks sends the proposed task set into isolated project copies. Active or queued tasks do not change the main version. When one becomes Ready, review its work log, test results, Preview, and diff, then choose Apply changes to main version or Dismiss. Narrow the proposed task set before Accept tasks when only one slice is authorized.
- Start building: approve the Plan Mode plan and continue implementation in the main thread.
- Accept tasks: send the proposed background Task set into isolated project copies.
- Draft: inspect or revise a background Task before any build begins.
- Active or queued: isolated work; cancel discards it and cannot be restored.
- Ready: evidence is available, but the main version has not changed.
- Apply: merge reviewed work into the main version.
- Dismiss: reject the isolated result without changing the main version.
Approve a plan with gates
Every task should name the expected change, acceptance checks, and safe return point. Add stop conditions: do not delete data, do not publish, do not contact real users, and do not change authentication without approval. Agent can then move quickly inside a clear box.
Before switching to Build mode, ask Agent to restate unresolved questions and assumptions. Approve only what you understand well enough to test. If a tradeoff changes cost, access, data ownership, or user experience, decide it explicitly rather than allowing the implementation to choose silently.
When the happy path breaks
Failure modes
Symptom
The plan is a list of pages and buttons with no explanation of how work changes state.
Likely cause
Planning copied the proposed interface instead of modeling the underlying workflow.
Recovery
Define records, states, transitions, actors, permissions, and history before returning to screens.
Symptom
Agent starts coding while you are still deciding what should happen.
Likely cause
The conversation is in Build mode or a plan was approved before open decisions were resolved.
Recovery
Return to Plan Mode, list unresolved decisions, and approve an implementation task only after its outcome and checks are concrete.
Symptom
One late integration failure invalidates most of the build.
Likely cause
The plan deferred its highest-risk assumption instead of testing it with an early vertical probe.
Recovery
Rank assumptions by uncertainty and blast radius; test risky access, data, or API constraints before dependent features.
Symptom
A finished background Task is applied and breaks the main version.
Likely cause
Ready was mistaken for verified, so its work log, Preview, diff, dependencies, and tests were not reviewed before Apply.
Recovery
Treat every Ready task as a proposed merge: inspect evidence, rerun must-preserve checks, then Apply or Dismiss deliberately.
Hands-on lab
Plan a three-state workflow
Take the intake app from Chapter 2 and plan an authenticated review-and-approval feature without allowing code changes.
- 01Open the mode selector at the lower-left of Agent chat, choose Plan, and ask Agent to explain the current project and data flow using existing evidence.
- 02Define three to five states, allowed transitions, actors, permissions, and the history each transition records.
- 03Ask for two architecture options and compare complexity, cost, reversibility, and security.
- 04Reorder the tasks into thin vertical slices, beginning with the highest-risk assumption.
- 05Use the background Task path for this lab so the merge gate is observable. Add acceptance checks, rollback points, and stop conditions, then revise the proposed Task set until it contains one Draft for the first slice. Preserve later ideas as deferred work.
- 06Select Accept tasks—not Start building—to send that Draft into its isolated copy. When it reaches Ready, inspect View plan, work log, test results, Preview, and diff. Apply changes to main version only if the evidence passes; otherwise Dismiss it or continue in its Task thread.
Deliverable: A reviewed Plan Mode task list and decision table that another builder could implement without inventing policy.
Reusable artifact
Build-plan approval contract
Use this to transform a Plan Mode answer into a safe, testable sequence.
OUTCOME: [observable business result] USERS / ROLES: [who acts and who only views] RECORDS: [entities and authoritative sources] STATES: [state list] TRANSITIONS: [from -> action by role -> to -> history recorded] HIGH-RISK ASSUMPTIONS: [access, API, data, cost, or performance] VERTICAL SLICE 1: [small end-to-end journey] TASK SET TO ACCEPT: [only work authorized to begin now] ACCEPTANCE: [happy, invalid, unauthorized, and recovery checks] ROLLBACK POINT: [known checkpoint and data choice] STOP CONDITIONS: No [publish/delete/contact/change auth] without approval. UNRESOLVED DECISIONS: [must be empty or explicitly deferred]
Before you move on
Receipt checklist
- Plan Mode produced no source or data changes while the design was being decided.
- The plan defines records, states, transitions, roles, and history rather than only pages.
- At least one high-risk assumption is tested before the features that depend on it.
- Accept tasks sends only the authorized first-slice Draft into isolated work, with acceptance checks, a rollback point, and stop conditions.
- A Ready Task is applied only after its work log, test results, Preview, and diff are reviewed against the plan.
Primary sources
