proto
@compozy/proto is a prototype gallery and review loop for React + Vite apps. A prototype renders
the app's real, shipped views with fixture props, one state at a time. People open the gallery,
pin comments to rendered elements, and each comment records the JSX source chain of what they
clicked. Agents fix that source and answer through the CLI or MCP. People approve; agents never
do. The point is that the reviewed screen is the code that ships, so there is nothing to
translate from a mockup afterwards.
This skill is the shipped contract and is replaced by proto init --skills on upgrade. Put
project rules (which views exist, where fixtures live, which specs to use) in the project's
AGENTS.md or CLAUDE.md, not in this file.
Mental model
- Component prototype:
<view>.proto.tsx beside the view it composes. It imports the view
and picks props per state. It contains no markup of its own: any lowercase JSX tag (<div>)
is a markup problem. Layout belongs in the view.
- Draft:
src/drafts/<slug>/index.proto.tsx, an exploration that may use free markup. Drafts
never get the production Frame.
- Flow:
flows/<id>.flow.ts, a journey across prototype states and external pages.
meta is data, never code. export const meta = definePrototype({...}) (and
export const flow = defineFlow({...})) is read from the syntax tree and never executed. Only
string, boolean, array and object literals are allowed: no variables, numbers, spreads,
template strings or computed values.
- Base origins. The shell (gallery and review API) runs on
127.0.0.1:<dev.port> (4400 by
default). It is prebuilt and never imports app code. Prototypes render on the render origin,
port + 1, compiled by the app's own vite.config.ts in the proto-render mode, one state
per iframe document. The two talk only through a validated postMessage protocol. App CSS
loads on the render origin only.
- Canvas and Frame.
proto.canvas.tsx exports Canvas (providers around every state; it
receives theme and role) and an optional Frame (production chrome around component
prototypes that are not standalone).
- Temporary sharing.
proto share sends a scoped built snapshot through Cloudflare Access.
Use CLI-only share connect, share <slug> --approver <email> (or --flow / --all),
share status, share refresh, share stop, and share disconnect; all accept --json.
Start runs until stopped, and approvers require a clean committed tree. Agents never approve.
See references/cli.md for invitations and output.
- Review store.
proto/review/<key>.json per prototype (key = slug) or flow
(key = flow-<id>), committed with the code. Comment ids are <key>-<n>. Each key is
in_review or approved; approval records the commit and is a human act. A new comment on an
approved prototype puts it back in review.
- Guards. The production boundary (
proto() in vite.config.ts) fails the app build when
prototype-only code reaches it. The network guard fails proto check, proto build and
Storybook/Vitest with protoPresentation() when a prototype, draft or story reaches a module
listed in guards.forbidRuntimeImports; it cannot see a global fetch or an unlisted client.
Matching rules: references/setup.md, section Guards.
Proto or Storybook
- Proto: screens and journeys that people review and approve: states of a real view inside
the app chrome, flows across states, comments anchored to source, evidence for a spec.
- Storybook: the component catalog, args and controls, per-component interaction and a11y
tests. Proto can host its existing CSF stories for browsing and review; addon panels and
addon-vitest stay in Storybook. Root guards are explicitly configured per story root.
- Neither: a UI change with no prototype to update. Edit the view and run its own checks.
Hard rules
- Never weaken a guard to make something render. Do not remove
forbidRuntimeImports
entries, set guards.productionBoundary: false, drop proto() or protoPresentation(), or
move a file out of a guarded path. A guard failure means a view reaches data access. Move
that access to the route and pass props instead.
- Prototypes compose views with fixtures. When a state needs something the view cannot show,
add a prop to the view. Never copy the view's JSX into the
.proto.tsx.
- Import the view's own module. Do not import a barrel that also re-exports routes, hooks or
API clients. It drags the data layer into the graph, and the network guard fails it as
network_import once those modules are listed.
- Agents never approve or reopen reviews, never run
review unlock, and delete comments only
when a person asks. Resolving a comment is not approval.
- Never edit
proto/review/** by hand. Use the CLI, MCP or the gallery.
Working loop
- Orient:
proto list --json, proto flow list --json, and proto check --json for the
current problems. Add --app <dir> in a monorepo.
- Scaffold:
proto new --in src/<path>/<view>.tsx (component prototype),
proto new <slug> --draft (draft), or proto flow new <id> (flow).
- Edit, then run
proto check --json until it exits 0, with an empty problems and no error.
Warnings never fail. The compile step, and with it network_import, only runs once the
registry problems are gone.
- Look at every state you touched: with
proto dev running, open
proto url <slug> --state <id> --bare, or capture proto screenshot <slug> --state <id>
(--theme dark, --width <px>), which starts a temporary server when none is running.
- Run the project's typecheck and the view's own stories or tests:
check does not type-check.
The work is done when check passes and the touched states render as intended. Approval stays
with people.
Invoke the binary the way the project does: bunx proto, npx proto, or a package script such as
bun run proto <command> --app app.
References
Read only the one you need:
references/authoring.md: before writing or editing a prototype, draft, flow or canvas
(meta fields, states, fixtures, URL state, flow nodes and edges).
references/setup.md: when installing proto, editing proto.config.ts, or wiring Vite,
Storybook or Vitest (config keys and defaults, guards, the render origin, skills install).
references/cli.md: when you need a command's flags, JSON output, exit codes, error codes or
the MCP tools.
references/troubleshooting.md: when check, build, dev, Storybook or a capture fails,
or the gallery renders something unexpected.
For gallery review comments (a comment id like login-form-7), use the proto-apply-comments
skill.
Existing Storybook stories
Add stories.roots to proto.config.ts: each root requires id, stories globs, preview
and vite; optional dir defaults to ., title to id, themeGlobal to theme, static
and guards.forbidRuntimeImports to empty. Paths are relative to dir. The root Vite config
installs React, CSS and aliases without proto(); .storybook/main.ts is never executed.
Install storybook and @storybook/react-vite at ~10.6.0 in each root. Never rewrite CSF.
The two base origins are joined by one origin per root at port + 2 + index; clear old MSW
workers/site data after reordering roots. Stories use their preview, not proto.canvas.tsx.
sb.mock is inert (story_mock_unsupported); do not claim module mocking works.
proto stories list --root <id> --filter '<story-id-glob>' --json returns roots and files.
No config returns empty arrays (human: No stories configured.), exit 0.
proto stories run --root <id> --filter '<glob>' --theme dark --json runs selected roots only.
Options: --concurrency (6), --timeout ms (30000, clamped 1000–120000), --port.
JSON: summary and stories rows (id, root, stage, status, hasPlay, durationMs,
error). Registry problems do not prevent selected stories running, but exit 1.
Exit 0 all pass, 1 failure/empty filter, 3 missing Playwright. Existing servers must match
projectId; interrupt closes only owned resources without a partial report.
proto stories url <id> links /?c=<component>&story=<id>.
- MCP:
proto_stories_list, proto_stories_run (requires root or filter), proto_stories_url.
check validates story config/index only. Guards run in the story server/runner, without
inheriting the app prototype guard. Local builds include lazy story roots under
__stories/<root>/, including local story-- review snapshots when requested; story problems
and missing/unsupported peers fail them. MSW needs a base-aware worker URL and scope confined
to that root (see the package README). Remote builds omit stories with stories_not_built;
story problems/missing peers do not fail remote builds.
Reference static mounts and publicDir assets base-relative (e.g. via import.meta.env.BASE_URL) so they work in local static builds.
- Component comments use
story--<slug>; comments add requires --state <story-id> from that
component plus --note and --selector. Remote review does not accept story keys.
Errors: invalid_input exit 2 (unknown root, missing/invalid state); story_not_found exit 1;
project_mismatch exit 1 (pass another --port); storybook_missing / storybook_unsupported
exit 3 (install supported peers); playwright_missing exit 3 (install Chromium).
1---2name: proto3description: Author, set up and debug @compozy/proto prototypes, drafts, flows, existing Storybook stories and the canvas. Use when editing `*.proto.tsx`, `src/drafts/`, `*.flow.ts`, `proto.canvas.tsx` or `proto.config.ts` and its Vite, Storybook or Vitest guards, when running the `proto` CLI or MCP tools, or when `proto check`, `proto dev` or a capture fails. Not for UI edits that touch no prototype, nor for gallery review comments (proto-apply-comments).4metadata:5 source: https://skillmd.com/skills/compozy/proto6---78# proto910`@compozy/proto` is a prototype gallery and review loop for React + Vite apps. A prototype renders11the app's **real, shipped views** with fixture props, one state at a time. People open the gallery,12pin comments to rendered elements, and each comment records the JSX source chain of what they13clicked. Agents fix that source and answer through the CLI or MCP. **People approve; agents never14do.** The point is that the reviewed screen _is_ the code that ships, so there is nothing to15translate from a mockup afterwards.1617This skill is the shipped contract and is replaced by `proto init --skills` on upgrade. Put18project rules (which views exist, where fixtures live, which specs to use) in the project's19`AGENTS.md` or `CLAUDE.md`, not in this file.2021## Mental model2223- **Component prototype**: `<view>.proto.tsx` beside the view it composes. It imports the view24 and picks props per state. It contains no markup of its own: any lowercase JSX tag (`<div>`)25 is a `markup` problem. Layout belongs in the view.26- **Draft**: `src/drafts/<slug>/index.proto.tsx`, an exploration that may use free markup. Drafts27 never get the production `Frame`.28- **Flow**: `flows/<id>.flow.ts`, a journey across prototype states and external pages.29- **`meta` is data, never code.** `export const meta = definePrototype({...})` (and30 `export const flow = defineFlow({...})`) is read from the syntax tree and never executed. Only31 string, boolean, array and object literals are allowed: no variables, numbers, spreads,32 template strings or computed values.33- **Base origins.** The shell (gallery and review API) runs on `127.0.0.1:<dev.port>` (4400 by34 default). It is prebuilt and never imports app code. Prototypes render on the render origin,35 `port + 1`, compiled by the app's own `vite.config.ts` in the `proto-render` mode, one state36 per iframe document. The two talk only through a validated `postMessage` protocol. App CSS37 loads on the render origin only.38- **Canvas and Frame.** `proto.canvas.tsx` exports `Canvas` (providers around every state; it39 receives `theme` and `role`) and an optional `Frame` (production chrome around component40 prototypes that are not `standalone`).41- **Temporary sharing.** `proto share` sends a scoped built snapshot through Cloudflare Access.42 Use CLI-only `share connect`, `share <slug> --approver <email>` (or `--flow` / `--all`),43 `share status`, `share refresh`, `share stop`, and `share disconnect`; all accept `--json`.44 Start runs until stopped, and approvers require a clean committed tree. Agents never approve.45 See `references/cli.md` for invitations and output.46- **Review store.** `proto/review/<key>.json` per prototype (key = slug) or flow47 (key = `flow-<id>`), committed with the code. Comment ids are `<key>-<n>`. Each key is48 `in_review` or `approved`; approval records the commit and is a human act. A new comment on an49 approved prototype puts it back in review.50- **Guards.** The production boundary (`proto()` in `vite.config.ts`) fails the app build when51 prototype-only code reaches it. The network guard fails `proto check`, `proto build` and52 Storybook/Vitest with `protoPresentation()` when a prototype, draft or story reaches a module53 listed in `guards.forbidRuntimeImports`; it cannot see a global `fetch` or an unlisted client.54 Matching rules: `references/setup.md`, section Guards.5556## Proto or Storybook5758- **Proto**: screens and journeys that people review and approve: states of a real view inside59 the app chrome, flows across states, comments anchored to source, evidence for a spec.60- **Storybook**: the component catalog, args and controls, per-component interaction and a11y61 tests. Proto can host its existing CSF stories for browsing and review; addon panels and62 addon-vitest stay in Storybook. Root guards are explicitly configured per story root.63- **Neither**: a UI change with no prototype to update. Edit the view and run its own checks.6465## Hard rules66671. **Never weaken a guard to make something render.** Do not remove `forbidRuntimeImports`68 entries, set `guards.productionBoundary: false`, drop `proto()` or `protoPresentation()`, or69 move a file out of a guarded path. A guard failure means a view reaches data access. Move70 that access to the route and pass props instead.712. **Prototypes compose views with fixtures.** When a state needs something the view cannot show,72 add a prop to the view. Never copy the view's JSX into the `.proto.tsx`.733. **Import the view's own module.** Do not import a barrel that also re-exports routes, hooks or74 API clients. It drags the data layer into the graph, and the network guard fails it as75 `network_import` once those modules are listed.764. **Agents never approve or reopen reviews**, never run `review unlock`, and delete comments only77 when a person asks. Resolving a comment is not approval.785. **Never edit `proto/review/**` by hand.** Use the CLI, MCP or the gallery.7980## Working loop81821. Orient: `proto list --json`, `proto flow list --json`, and `proto check --json` for the83 current problems. Add `--app <dir>` in a monorepo.842. Scaffold: `proto new --in src/<path>/<view>.tsx` (component prototype),85 `proto new <slug> --draft` (draft), or `proto flow new <id>` (flow).863. Edit, then run `proto check --json` until it exits 0, with an empty `problems` and no `error`.87 Warnings never fail. The compile step, and with it `network_import`, only runs once the88 registry problems are gone.894. Look at every state you touched: with `proto dev` running, open90 `proto url <slug> --state <id> --bare`, or capture `proto screenshot <slug> --state <id>`91 (`--theme dark`, `--width <px>`), which starts a temporary server when none is running.925. Run the project's typecheck and the view's own stories or tests: `check` does not type-check.9394The work is done when `check` passes and the touched states render as intended. Approval stays95with people.9697Invoke the binary the way the project does: `bunx proto`, `npx proto`, or a package script such as98`bun run proto <command> --app app`.99100## References101102Read only the one you need:103104- `references/authoring.md`: before writing or editing a prototype, draft, flow or canvas105 (meta fields, states, fixtures, URL state, flow nodes and edges).106- `references/setup.md`: when installing proto, editing `proto.config.ts`, or wiring Vite,107 Storybook or Vitest (config keys and defaults, guards, the render origin, skills install).108- `references/cli.md`: when you need a command's flags, JSON output, exit codes, error codes or109 the MCP tools.110- `references/troubleshooting.md`: when `check`, `build`, `dev`, Storybook or a capture fails,111 or the gallery renders something unexpected.112113For gallery review comments (a comment id like `login-form-7`), use the `proto-apply-comments`114skill.115116## Existing Storybook stories117118Add `stories.roots` to `proto.config.ts`: each root requires `id`, `stories` globs, `preview`119and `vite`; optional `dir` defaults to `.`, `title` to id, `themeGlobal` to `theme`, `static`120and `guards.forbidRuntimeImports` to empty. Paths are relative to `dir`. The root Vite config121installs React, CSS and aliases without `proto()`; `.storybook/main.ts` is never executed.122Install `storybook` and `@storybook/react-vite` at `~10.6.0` in each root. Never rewrite CSF.123The two base origins are joined by one origin per root at `port + 2 + index`; clear old MSW124workers/site data after reordering roots. Stories use their preview, not `proto.canvas.tsx`.125`sb.mock` is inert (`story_mock_unsupported`); do not claim module mocking works.126127- `proto stories list --root <id> --filter '<story-id-glob>' --json` returns roots and files.128 No config returns empty arrays (human: `No stories configured.`), exit 0.129- `proto stories run --root <id> --filter '<glob>' --theme dark --json` runs selected roots only.130 Options: `--concurrency` (6), `--timeout` ms (30000, clamped 1000–120000), `--port`.131 JSON: `summary` and `stories` rows (`id`, `root`, `stage`, `status`, `hasPlay`, `durationMs`,132 `error`). Registry problems do not prevent selected stories running, but exit 1.133 Exit 0 all pass, 1 failure/empty filter, 3 missing Playwright. Existing servers must match134 `projectId`; interrupt closes only owned resources without a partial report.135- `proto stories url <id>` links `/?c=<component>&story=<id>`.136- MCP: `proto_stories_list`, `proto_stories_run` (requires root or filter), `proto_stories_url`.137- `check` validates story config/index only. Guards run in the story server/runner, without138 inheriting the app prototype guard. Local builds include lazy story roots under139 `__stories/<root>/`, including local `story--` review snapshots when requested; story problems140 and missing/unsupported peers fail them. MSW needs a base-aware worker URL and scope confined141 to that root (see the package README). Remote builds omit stories with `stories_not_built`;142 story problems/missing peers do not fail remote builds.143 Reference `static` mounts and `publicDir` assets base-relative (e.g. via `import.meta.env.BASE_URL`) so they work in local static builds.144- Component comments use `story--<slug>`; `comments add` requires `--state <story-id>` from that145 component plus `--note` and `--selector`. Remote review does not accept story keys.146147Errors: `invalid_input` exit 2 (unknown root, missing/invalid state); `story_not_found` exit 1;148`project_mismatch` exit 1 (pass another `--port`); `storybook_missing` / `storybook_unsupported`149exit 3 (install supported peers); `playwright_missing` exit 3 (install Chromium).