Prototyping Sessions
A Prototyping Session is a human-driven Thread for iterating on how a screen looks and behaves before you commit to planning an implementation. You describe the change, an Agent builds a Prototype and serves it live in the Dashboard, and you keep revising it by prompt until it's ready to hand off.
It's a peer choice on the start form, next to the Intake Modes, but it isn't one of them. Small, Medium, and Large (Wayfinder) rank how much of a design's decisions the Agent settles for you in a grilling conversation; a Prototyping Session skips the grilling and builds first. See Choose an Intake Mode if your idea needs a design conversation instead of a build-and-revise loop.
When to Prototype
Start a Prototyping Session when a screen's layout or behavior is easier to judge by looking at it than by describing it in words. Use it before an Intake Session when you want to settle a screen's shape first, then let the Intake Session's conversation turn that agreed shape into an Issue Plan.
A Prototyping Session never writes to your Project's real branches while it runs. It builds inside your Project's own Workspace so it can borrow the real screen's markup and styles, but nothing is durable until you choose Handoff.
Start a Prototyping Session
The start card asks for:
- Project and Credential: the same selection every session kind uses.
- What should change: a required prose description of the change you want to see.
- Screen (optional): a route or file path named in prose, such as
/pricingorsrc/views/PricingView.tsx, so the Agent knows where to look first. - Image (optional): an attached screenshot or mock, sanitized the same way an Intake Session's image Attachment is.
Starting the session opens a write-capable Thread with a live preview. The Agent builds the first Prototype without asking anything on its first turn unless your description leaves it nothing it can build. The Prototype card appears on the start form when your tenant's Prototyping switch is on, which is the default.
How Revisions Work
Each prompt you send is one Revision: one Run that changes the live Prototype in response to your instruction. The preview stays on screen between Revisions; only its status updates while a Revision is in progress. When a Revision produces more than one option, a variant switcher lets you choose which one stays live. Variants are facets of the one Prototype, never separate Prototypes.
A Prototyping Session never Steers a running Revision, so wait for the current Run to finish before sending the next prompt. Discard ends the session without a Handoff, freezing the Thread and releasing its Workspace the same way discarding any other session does.
Fidelity: In-App or Standalone
A Prototype has one of two Prototype Fidelity levels, and the preview panel labels which one you are looking at.
- In-App: the Project's own app, running from the session's Workspace with the change applied. The markup is real code, so what you see is what an implementation would look like in place.
- Standalone: a page the Agent wrote that borrows the app's styles, with sample data and no backend. The markup is a visual reference, not implementation code.
The Agent chooses by one bounded attempt: it tries the app's own dev server only when a dev script exists and its dependencies are already installed, gives it one start, and switches to Standalone if the app does not come up or the screen needs a backend or data the Workspace cannot supply. It never repairs the build or installs anything, because a Workspace has no network access and the Prototype is the deliverable. Ask for a switch in a Revision if you want the other level.
The Agent also reports a Preview Path, the route beneath the Prototype where the changed screen lives, and the preview opens there rather than at the app's root. Before the Agent reports one, the preview opens at the screen you named on the start form when it is a route. A screen that does not exist yet is reached the same way, at the throwaway route or page the Agent created for it. The preview reloads on its own when a Revision finishes.
Handoff: What It Carries
When the Prototype looks right, choose Plan the implementation to start Handoff. Handoff:
- Summarizes the session's Revisions into a digest (what changed and why), retryable if it fails to parse.
- Asks you to choose Small or Medium for the Intake Session it's about to start, plus a Grilling Style for Medium. Handoff never starts a Large (Wayfinder) Intake Session.
- Starts that Intake Session on a fresh Thread carrying your original brief, its Attachments, the final Prototype, the Revision digest, and a pointer to the Prototype's source.
Handoff is one-way and happens once per Prototyping Session. After it completes, the session accepts no further Revisions, and there's no path back from the new Intake Session to the Prototyping Session it came from. Start a new Prototyping Session if you want to keep prototyping.
Handoff freezes the session for good
Once you confirm Handoff, the Prototyping Session stops accepting Revisions and its Workspace is released. Finish revising before you hand off; there's no way back into the same session afterward.
Where the Prototype's Source Ends Up
At Handoff, the Dispatcher (never the Agent) commits the Prototype's files and pushes them to a namespaced throwaway branch, prototyping/<threadId> using this Prototyping Session's own Thread id, in your Project's own repository. The new Intake Session's Workspace checks out that branch instead of your default branch, so its read-only conversation can discuss the exact files the Prototype left behind. The Intake Session names the Prototyping Session it came from and that branch so you can trace either one back to the other.
When that Intake Session's Issue Plan is Published, the resulting tracer Issue carries a Prototype section linking back to the branch and the Prototyping Session. The branch itself is left for you to prune once you no longer need it.
Related
- Choose an Intake Mode: compare Small, Medium, and Large for a design that needs a conversation instead of a live build.
- The Core Loop: see how the Intake Session a Handoff starts turns into published Issues and a Pull Request.
- Core Concepts: review the Thread and Run vocabulary a Prototyping Session shares with every other session kind.