# Prototypes
Turn a plan into a clickable mockup you can share, comment on, and send back to the agent.
A plan can render as a **prototype**: a clickable mockup of what it describes, generated from the
specs themselves.
It exists to make a plan reviewable by people who will not read a spec tree. A stakeholder who
shrugs at "SPEC-4: schedule a report" will tell you within seconds that the screen never says which
time zone the send happens in.
## Generating one [#generating-one]
Ask for it in the plan conversation. The agent builds the prototype from the plan as it currently
stands, so generate it after the specs are roughly right rather than at the first draft.
Regenerating it later picks up whatever has changed.
## How the agent builds one [#how-the-agent-builds-one]
It follows the same pass every time. It looks at your linked repository first, so the prototype
matches what you already ship. It walks every spec that has a screen, covers the empty and error
states as well as the working one, checks its work against a fixed list, and only then saves.
That check is why the first version you open is usually complete, instead of arriving with gaps you
have to point out.
The agent does not write the whole document. It writes the plan's prototype sources, one small file
per screen plus a theme and a manifest, under the plan's `specs/prototype/` folder, and Plansmith
assembles them into one prototype in the template. A prototype with many screens saves as reliably
as a small one, and changing one screen rewrites one file: the other screens, and the comments on
them, stay exactly where they were.
## Matching your app [#matching-your-app]
Link a repository and the prototype uses your real colours, type and components. The agent tells you
which repository it matched against, so you can check it picked the right one.
When a flow crosses two of your apps, for example it starts in your customer portal and finishes in
your back office, you still get one prototype. Each screen matches the app it belongs to and names
that app above the frame, and the step strip gives each app its own row, so you can see where the
flow crosses over. One screen never mixes two apps' designs. In an older browser, those screens show
without their app's styling. That means Chrome or Edge before 118, Safari before 17.4, or Firefox
before 146, the versions that added CSS `@scope`.
If it cannot match, it says which of three things happened, because they need different answers from
you:
* **No repository is linked.** Link one and the next prototype will match your app.
* **Your linked repositories hold no user interface.** Nothing to match. This is a fact about your
code, not a problem to fix.
* **A repository could not be read.** Its connection needs reconnecting. Your app is there, we could
not see it.
## Revising keeps your comments in place [#revising-keeps-your-comments-in-place]
When the agent revises a prototype, it carries your comment anchors across, so feedback left on an
earlier version still lands where it belongs. Restyling or moving something does not break its
comments.
The agent tells you when an anchor is lost: if a part is removed altogether, the comments anchored
to it lose their place.
## What the agent checks before you see it [#what-the-agent-checks-before-you-see-it]
The agent works through a fixed list before it saves, and the save reports anything it missed back
to it. These are the things on that list:
* Every screen shows the real address it stands for.
* Every screen says whether this plan adds it, changes it, or leaves it alone. When we cannot tell,
it says so rather than guessing.
* Notes from the agent sit outside the mockup, never inside it, so commentary is never mistaken for
the product.
* The flow list dims what is not built yet instead of hiding it.
## Point at something and say what to change [#point-at-something-and-say-what-to-change]
Open the prototype and press the element-select button in its toolbar. The pointer becomes a
crosshair and whatever you hover is outlined, so you can see what you are about to pick. Click the
button, card or heading you mean, type one instruction, and press Enter.
Your instruction lands in the chat box with the element, the screen it sits on and the prototype it
belongs to already named, added after anything you were part-way through writing. Read it, change it
if you want, and press send. Nothing reaches the agent until you do.
It works the same way on the plan's own prototype and on any prototype file in the drawer; on a file
the instruction names that file, so the agent edits the right one.
When you send a change with the prototype open (or just after closing it), the agent knows which
screen you were looking at. It changes that one screen and leaves the rest as they were, so most
changes land in under a minute.
## Edit a screen directly [#edit-a-screen-directly]
For a small fix, you do not need to write a message. Press **Edit** in the prototype's toolbar and
click any text: a label, button, heading or value. Type, then press Enter to save or Esc to cancel.
Most text saves at once, and an **Undo** appears until your next edit.
* Text the screen's code draws (a live total, a sentence split around bold words, the flow rail) is
changed by the agent in about a minute. The bar under it says "send to the agent" instead of
"save".
* The small bar under the text you are editing has **Ask the agent**, and **Remove** for text that
saves at once, which takes the element out of the screen.
* Edit is off while the agent is working on the plan, and for people who can view the plan but not
edit it. Its tooltip says which.
Your edits change the prototype only. They collect beside the toolbar as "changes not in the specs".
Press **Update specs** and the agent carries all of them into the specs in one turn.
If an edit disagrees with a spec (you typed a $1.50 fee on a screen whose spec says transfers are
free), the agent does not pick a side. It shows both, your edit and the spec's words, and asks which
one is right. Until you answer, neither the spec nor that screen changes. **The spec is right** puts
the screen back as it was (if you changed that screen again since, the agent changes it to match the
spec instead); **The screen is right** has the agent update the spec.
## Sharing it [#sharing-it]
A prototype has its own share link. Anyone holding that URL can open it, signed in or not, which is
what makes it useful for showing a customer or an exec.
**A prototype share link sits outside your plan's permissions.** It is a public URL for whoever has
it. Making the plan private later does **not** kill an existing link. Revoke the link itself, and see
[Sharing a plan](/docs/sharing-a-plan).
## Comments come back to the agent [#comments-come-back-to-the-agent]
Reviewers can leave comments anchored to a specific part of the prototype, and you can resolve them
as you work through.
A comment can be sent to the planning agent, which reads it as feedback on the plan and updates
the affected specs. That closes the loop from "this screen is wrong" to a changed
acceptance criterion without anyone transcribing anything.
## Wrapping the prototype builder [#wrapping-the-prototype-builder]
Your team can add its own rules to every prototype without rewriting how prototypes are built. A
wrapper is a company or project skill that **extends** the built-in one; it names the builder's
hooks, so it keeps working when we reword a step.
| Hook | What it adds |
| --------------- | -------------------------------------------------------------------------------------------- |
| `extra-craft` | Your typefaces, spacing and brand rules |
| `extra-screens` | Screens you want in every prototype |
| `extra-notes` | Extra kinds of note beside the two we ship: what did not change, and what happens underneath |
| `extra-checks` | More things to check before saving |
| `save-bar` | Raise the bar the agent holds itself to before saving |
Write this under **Settings → Skills**. Copy it and change the parts in your own words.
**Paste the body only.** The settings form writes the header for you. Pasting a whole file that
carries its own header gives you two, and the inner one quietly becomes body text.
Set **Extends** to `Prototype builder` on the form, then paste this as the body. The pass, the way
a prototype is saved and the checks it must pass are unchanged.
```text
[HOOK: extra-craft]
Our house style, on every prototype:
- Display face is Söhne, body is Söhne. Never a substitute, never a system font.
- Brand green is a foreground only. It is never a background fill.
[HOOK: extra-screens]
Always include, even when the plan does not mention them:
- The printed dispatch note. It is a document, not a screen, so it is drawn as a
sheet with no browser chrome.
[HOOK: extra-notes]
Add one register beside the two we ship:
- "Warehouse impact": what changes for a picker on the floor.
[HOOK: extra-checks]
Also check before saving:
- Every price is shown with its currency. A bare number has been misread twice.
- Every date is unambiguous (12 Mar 2026, never 03/12/26).
[HOOK: save-bar]
Saving additionally requires that every screen showing stock
also shows its as-of time. This RAISES the bar. It never lowers it.
```
### What a wrapper cannot do [#what-a-wrapper-cannot-do]
A wrapper adds rules and raises the bar. It cannot lower one. It cannot:
* **Change how a prototype is saved.** Saving has one door, and it has to be one door: it stores the
file, records the prototype, and stamps which specs it was built from, all together. Save any
other way and the file exists with nothing pointing at it, so the Prototypes panel opens an empty
tab and you cannot tell what the agent did.
* **Widen where a prototype may load things from, or unpin the icon version.** Both keep a saved
prototype rendering the same way months later.
* **Make a prototype call a server or load real data.** It runs entirely in your browser, on made-up
data. That is what makes it safe to share with anyone holding the link.
* **Remove a check, or lower the accessibility floor.**
If a wrapper asks for any of those, the agent follows the built-in skill and tells you it did.
## Linking to a prototype [#linking-to-a-prototype]
Opening a prototype in the plan console puts it in the URL (`?prototype=specs/prototype.html`),
the same way an open document or spec is addressed. Reload and it is still open. Copy the link
from the viewer header and a teammate lands on the same prototype. The expand control switches
the viewer to a full-page frame (`&view=full`), and the copied link carries that too.
## The template around the screens [#the-template-around-the-screens]
The agent writes the screens; Plansmith assembles them into a **prototype template**, the frame with
the flow index, the step strip and the notes. A company or a project can replace that template with its
own, and an existing prototype can be rebuilt in whatever template is in force from the Preview tab.
See [Prototype template](/docs/prototype-template).
Who can see a plan, and how prototype links differ.
How to ask for changes once the feedback is in.
The other skill you can wrap, and its own worked example.