Prototypes

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

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

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

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

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

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

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

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

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.

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

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.

Write this under Settings → Skills. Copy it and change the parts in your own words.

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.

[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

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

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 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.