Prototype

Scaffold a design-first prototype for a feature. Everything lands under docs/prototype/<feature>/ — no app code is touched. The format below is the complete spec; do not look for an existing prototype to copy (there may be none).

Two documents, two altitudes:

• PROTOTYPE.md — the prototype itself: HTML mockups, user experience, features, and the data model's field surface in plain language. This is what /prototype <feature> produces.
• PLAN.md — the technical companion: real schema code, SQL, permissions, API surface. Not part of prototyping; write it only after the user has reviewed the prototype and validated it, and asks for the plan (/prototype plan <feature> or "write the plan for X"). Never chain prototype → plan in one go.

Arguments are the feature name and optionally a description. If the first argument is plan, run the Plan workflow for an existing prototype. If no arguments were given, ask for the feature name before doing anything.

Once the prototype is validated, the prototype-app skill can build the feature's frontend vertical inside the real app against an in-memory mock — a separate, also user-initiated step.

Both documents are served by the viewer: bun prototype (from repo root) renders every docs/prototype/*/PROTOTYPE.md at http://localhost:4400/<feature>/, with iframes embedded, mermaid fences drawn, and frontmatter feeding the index page.

The dashboard serves the same docs at /dev/prototype/<feature> while bun dev runs — every .md in the folder as a tab, mockups live in their iframes, diagrams through the app's own renderer.

Prototype workflow

1. Name the directory. Kebab-case the feature name: docs/prototype/<feature>/. If the directory already exists, update its contents in place instead of duplicating.

2. Study the app, not the backend. Find the app's global stylesheet (in this template: apps/dashboard/src/app.css) for design tokens — colors, radius, fonts — and glance at one existing feature's screens so the mockups feel like the real product. Skip schema/API research — that belongs to the plan step.

3. Write PROTOTYPE.md following this skeleton exactly (sections in this order — the doc opens with the visuals):

   ---
   title: Notification Center
   description: One-line summary shown on the prototype index.
   status: draft
   date: 2026-08-11
   ---
   
   # Notification Center
   
   ## Prototypes
   
   ### list-view.html
   
   One paragraph: which screen/flow this mockup shows and what to try clicking.
   
   <iframe
     src="./list-view.html"
     width="100%"
     height="600"
     style="border:1px solid #ccc;border-radius:8px"
   ></iframe>
   
   [Open list-view.html](./list-view.html)
   
   ## Overview
   
   What the feature is and why — a few sentences of product framing. No file paths.
   
   ## Features
   
   **Group per user flow**
   
   - Bulleted capabilities, concrete enough to build the mockup from.
   
   > [!NOTE]
   > Open questions go inline like this, rather than deciding silently.
   
   ## Data model
   
   One line for the shared system columns (id, created/updated/deleted
   timestamps, created_by — whatever every table in the repo carries).
   
   ```mermaid
   erDiagram
     NOTIFICATION }o--|| USER : "for"
   
     NOTIFICATION {
       ref user FK "required - the recipient"
       text title "required"
       text body
       enum kind "mention | assignment | system"
       date read_at "null until read"
     }
   ```
   
   - Bullets only for what the diagram can't show: lifecycle rules,
     read-only fields, derived values.
   
   ## Out of scope
   
   - What this prototype deliberately does not cover.
   

   Rules on top of the skeleton:

   • Frontmatter is plain key: value lines, no nesting. title and description are required; status (draft/review/approved) and date (creation date, absolute) are optional index badges.
   • Prototypes: one subsection per HTML file, iframe embed plus plain-link fallback (not every markdown renderer allows iframes).
   • Features: where a flow has real branching (state machines, multi-step wizards), draw it — a mermaid flowchart/stateDiagram fence or a small ASCII sketch in a plain code fence.
   • Data model: the complete field surface, no implementation detail. Every entity and every field appears in the erDiagram as type name [PK|FK|UK] "comment" attributes — plain types only (text, enum, money, date, list, ref), with required/optional, enum values, and reference targets in the comment string. No ORM code, no SQL, no indexes. Once a plan exists, end the section with Full schema, permissions, and the API surface live in [PLAN.md](./PLAN.md).

4. Build the HTML prototypes. One .html file per distinct screen or flow (list view, detail view, creation flow, etc.), sitting next to PROTOTYPE.md. Rules:

   • Fully self-contained: inline <style> and <script>, zero external requests — no CDNs, no fonts, no images from the network. They must render from file://.
   • Interactive where it matters: mock data as inline JS arrays, working filters/tabs/forms via vanilla JS, so the flow can be clicked through. No frameworks.
   • Match the app's look: reuse its design tokens as CSS variables so the mock feels like the real product. Support light and dark via prefers-color-scheme (the viewer's theme toggle propagates into the iframes).
   • Realistic content, not lorem ipsum — mock data should read like real usage of the feature.

5. Finish. List the created files, summarize any open questions raised in the spec, and point at the viewer (bun prototype → http://localhost:4400/<feature>/) so the user can review. The prototype now waits for their feedback: iterate on it as they react, and only move to PLAN.md once they've validated the prototype and asked for the plan. Do not create app code, migrations, or tests.

Diagrams

Diagram fences are rendered by beautiful-mermaid, which implements a subset of Mermaid. Stick to these six.

Fence header	Use it for
flowchart / graph	Branching flows, wizards, decision points (TD/LR/BT/RL)
stateDiagram-v2	Lifecycles and state machines
sequenceDiagram	Message/call order between actors or services
classDiagram	Type shapes and their relationships
erDiagram	The Data model section — entities and fields
xychart-beta	Bar/line charts for volumes, growth, sizing

linkStyle works in flowcharts and state diagrams for per-edge colour and stroke width.

Not available — do not reach for these, they will not draw: gantt, journey, pie, mindmap, timeline, quadrantChart, gitGraph, sankey-beta, block-beta, kanban, requirementDiagram, C4Context, architecture-beta, packet-beta, radar-beta, treemap-beta. For a roadmap or timeline, use a table; for a journey, a flowchart with one node per step.

The bun prototype viewer still loads full Mermaid from a CDN, so an unsupported fence may draw there while rendering as plain source everywhere else. Do not rely on it — author for the six.

Colours come from the surrounding page's CSS variables, so diagrams follow the light/dark toggle — never hardcode colours in a fence.

Plan workflow (later step, on request)

1. Only on an explicit ask, for a validated prototype. The plan implements what the prototype shows, so the prototype must exist and the user must have reviewed it — if it doesn't exist, say so and offer to prototype first; if it exists but the user hasn't looked at it yet, confirm they're happy with the prototype before planning. Read docs/prototype/<feature>/PROTOTYPE.md in full; unresolved > [!NOTE] questions in it are prompts to ask the user now, not decisions to make silently.

2. Study the codebase so the plan matches how this repo actually builds features — read one existing slice end to end rather than inventing conventions. In this template:

   • Data models: Drizzle tables in packages/core/src/<slice>/<slice>.sql.ts, shared column helpers from packages/core/src/drizzle/types, snake_case column names per CLAUDE.md.
   • Permissions: packages/core/src/permission.ts and how Actor.check is called from core bodies.
   • API: SvelteKit remote functions in apps/dashboard/src/lib/features/<slice>/api/*.remote.ts. Endpoints are remote query/command signatures, not REST routes, unless the feature genuinely needs an HTTP route (webhooks, public API).
   • Slices: core logic in packages/core/src/<slice>/ (<slice>.sql.ts + index.ts); UI in apps/dashboard/src/lib/features/<slice>/. Name where each piece lands.

3. Write PLAN.md next to the prototype, with frontmatter (title, date) and:

   • An opening line linking back to PROTOTYPE.md, plus the slice layout (which files, which packages).
   • Data model — schema definitions in a ts block (the repo's ORM style), the equivalent CREATE TABLE SQL in a sql block, relations, indexes, and a Permissions subsection.
   • API — one subsection per endpoint: signature (name, input schema, return shape), which slice owns it, and auth/actor expectations.
   • Open questions as > [!NOTE] blocks.

4. Finish. Link the plan into PROTOTYPE.md's Data model section if not already, and note the viewer renders it at http://localhost:4400/<feature>/PLAN.md.