Build Prototype

Build a disposable but finished-looking model of the whole surface so the user can settle structure, relationships, and behavior before implementation.

Separate the product layer from the decision layer: prototype.html holds the canonical product screens and flows; a temporary compare.html resolves the user's current question in its specific situation. Scope the comparison by what the decision needs, whether a component, a screen, or a short flow. For a local comparison request, go directly to Compare one decision and limit building and verification to that decision. The whole-surface inventory, review, and preservation gates apply to the prototype, not to this intermediate.

Set the effort

Accept effort=standard or effort=high. Recommend and use standard when the argument is omitted.

Pass one base completion gate at either effort: produce a finished-looking surface, cover every requested screen and relevant state, make intended interactions and reset paths work, exercise every relevant viewport in a browser, correct every reproduced defect found during that inspection, and share an address the user can open. Hold this gate fixed at standard.

• standard uses the base gate as its complete result.
• high passes the same base gate, then adds close visual matching to an inspectable current product or reference through Review and converge. When the host supports subagents, delegate the audit to one fresh reviewer subagent at high model effort and give it the reference and candidate artifact without the builder's findings. Otherwise separate the build and verification passes and report that reviewer independence or model effort was unavailable. If no reference can be inspected, report that visual equivalence is unverified and use the extra pass only to strengthen layout robustness.

Ground the prototype

Use the request and conversation as scope. When present, read GLOSSARY.md, relevant subjects from docs/decisions/README.md, and a work-unit spec only when the request or a prior handoff identifies one. Do not search for a spec.

Inspect the existing product and design system as evidence. Use their canonical terms, interface language, tokens, and components; otherwise use the user's language and the template's finished minimal style. Include the baseline in the review only when the user is choosing between it and the candidate. Surface conflicts instead of resolving them silently.

Hold confirmed relationships fixed. Keep overlays, drawers, and modals attached to their source screen unless the user is reconsidering that relationship.

Build one canonical product surface

Present the screen inventory as a correctable draft and begin building without waiting for approval.

Copy templates/shell.html into one temporary, self-contained HTML file and grow every product screen inside it. Preserve and follow the template's contract comment; it owns the review chrome, product-pixel boundary, screen and state semantics, and viewport behavior. Keep one canonical version of each product screen in this file.

Keep one-click and transient changes as working product interactions, however different they look. Reserve selector presets for important multi-step results, forced data or errors, and structures that are not trivial to reach. Synchronize the selector when interactions enter or leave a declared preset.

Copy project tokens verbatim into :root, or extract the existing design language when no token file exists. When the project ships a dark palette, copy it under .sh-theme-dark so the shell's theme switch appears; a project without one leaves the prototype with no theme control rather than an invented dark mode. Style every screen through those tokens and mark elements with the design system's component names in data-component; use new:Name only when no component exists.

Use realistic dummy content with real-length names, plausible copy, awkward numbers, and only relevant edge conditions. Never use lorem ipsum. Keep out real data, APIs, latency, production routing or state wiring, frameworks, build steps, and network dependencies.

Use a phone frame for native app mockups and start mobile-first prototypes in the template's narrow viewport; its classes own simulated responsive behavior.

Review and converge

Render and inspect the artifact before presenting it. Exercise every screen, declared state, interaction entry and reset path, and relevant viewport in a browser. Run the finished HTML using a method supported by the current harness and share an address the user can open. Explain differences, rationale, and review guidance in the conversation, outside the product pixels. Present the artifact and correctable screen draft, walk through the surface screen by screen, and ask what to change. Do not close an open review with a completion handoff.

For high, audit through two independent lenses. Compare the reference and prototype at matching screen, state, and viewport coordinates for typography, spacing, alignment, wrapping, overflow, and asset treatment. Separately stress layout and interaction recovery with realistic long or awkward content. Give each material mismatch candidate its exact coordinate, observed evidence, and reproduction path. Have the fresh reviewer subagent reproduce candidates when one is available, discard those that do not reproduce, and correct the verified set until no reproduced material mismatches remain. After a correction, re-render its coordinate and the other screens or states that share the changed token, component, or shell behavior. Report the audited coverage and any unverified coordinates or fidelity claims in the conversation.

Compare one decision

For one unresolved visual or interaction decision, copy templates/comparison-shell.html into a temporary compare.html. Name the concrete user situation and render up to three alternatives with just enough context to judge it. A fragment may be sufficient; a flow may need several related views. This scope is independent of the prototype's screen inventory. Build comparisons when a decision arises, not once per product screen, and keep unrelated product work in the prototype.

Preserve the template's styling and contract comment, which owns the comparison controls and keeps product navigation inside its alternative. Hold content, data, surrounding layout, behavior, and confirmed elements fixed except for the governing choice. The reviewer sees one alternative at a time and switches between them, so verify each alternative at the same state and viewport coordinate rather than only the one the comparison opens on. Render and verify only the interactions, states, and sizes needed to judge it, then share the runnable comparison and ask for the choice.

Once the user chooses, apply that result to the affected product UI and flow in the same prototype.html and verify the affected behavior there. Delete the temporary comparison after integration, then resume the prototype review or shaping session. Create a fresh comparison for the next decision; do not collect past comparisons or promote compare.html into the final deliverable. If the prototype has not been built yet, record the choice and discard the comparison without building the whole product just to demonstrate integration.

Preserve the approved result

Keep the working file temporary and write nothing under docs/specs/ while review remains open. Once every screen is approved or explicitly deferred, keep cheap agent-chosen defaults as overridable assumptions. Ask about or explicitly defer consequential behavior not settled by the approved surface, and record its impact as a remaining risk without reopening unrelated screen review.

When every consequential implementation-relevant product decision is settled or explicitly deferred and every cheap agent-chosen default is labeled as an overridable assumption, reuse an identified work-unit folder or derive a kebab-case slug. Record confirmed behavior alongside those explicitly labeled assumptions and deferrals in docs/specs/<slug>/spec.md, creating or updating the same stable product contract used by shaping. Record or preserve its user-visible outcomes, approved scope, observable acceptance criteria, settled constraints and rationale, assumptions, off-limits areas and why, deferrals, and risks. Omit predicted files, functions, code structure, technical layers, and implementation steps. Save and link the approved surface as docs/specs/<slug>/prototype.html. Never infer navigation, order, or behavior from source order or visual proximity.

Promote only user-confirmed, reusable, non-obvious trade-offs from the spec into a project decision contract.

Discard intermediates; the approved prototype is a reference, not production code.