Apply prototype review comments
A reviewer pinned a comment to something rendered in the proto gallery. The comment records where
it was clicked in the source, plus the exact state, theme, role, viewport and commit they saw.
Your job is to change the code that ships, prove the reviewed state now looks right, and answer
the thread. The proto skill installed beside this one owns the concepts and hard rules: read
its SKILL.md when prototypes, drafts, flows or guards are unfamiliar, references/cli.md for a
command's flags or JSON, and references/troubleshooting.md when a command fails. Project rules
in AGENTS.md or CLAUDE.md take precedence for code conventions.
Rules
- Fix the owning view, not the prototype. A component prototype only composes a view with
fixtures, so the reviewed pixels come from the view, and that is what ships. Edit a draft
directly, a flow in its
.flow.ts, and fixture data only when the comment is about the data.
- Agents never approve. Do not run
review approve, review reopen or review unlock, and
delete a comment only when a person asks. Resolving a thread is not approval.
- The
proto hard rules still apply: never edit proto/review/** by hand (write through
proto comments ... or MCP), never weaken a guard, and never copy view markup into a
.proto.tsx to satisfy a comment.
Loop
Add --app <dir> to every command in a monorepo. When the review lives on the deployed gallery,
add --remote to the comments and review status commands only. check, flow show and
screenshot always run locally and exit 2 with --remote. The MCP tools (proto_comments_list,
proto_comments_show, ...) take the same fields and return the same JSON.
- Find the threads. For a given id, run
proto comments show <id> --json. Otherwise run
proto comments list --json (open by default; filter with --slug <key>, --spec,
--state). Threads whose last message is from an agent are waiting on a person
(--waiting); leave them alone unless something changed.
- Read everything. Read every message in the thread, not just the first, because later
replies often change the request. Download the images with
proto comments attachments <id> --json (into .tmp/proto/<id>/) and look at them.
- Locate the source.
target.source is the app-relative path:line:column of the JSX nearest to the clicked
element. target.sourceChain walks outward from it to the composing prototype. The first
entry outside the .proto.tsx is usually the owner. If that entry is a shared component
and the request is about this screen only, the fix belongs at the call site further out in
the chain. When only the .proto.tsx appears, the comment is about fixtures or state
selection.
target.text, selector and testId confirm the element. A region target lists what
was drawn inside the dragged area.
- Lines refer to
context.commit. If the file changed since, find the element by its text or
with git diff <commit> -- <path>.
- An empty chain means the element came from outside the app's sources (for example a
design-system package). The owner is the app view that renders that component.
- Flow comments have
target.kind: "node". node is the flow node id, or null for the whole
flow. proto flow show <id> --json, where <id> is the comment key without its flow-
prefix, maps the node to its prototype and state.
- Reproduce. With
proto dev running, open the gallery URL from
proto url <slug> --state <context.state> --theme <theme> --role <role> --width <viewport.width>, leaving out the flags whose context value is null. The gallery applies
the width; a --bare render document takes the window's width instead. For a flow comment,
use the node's prototype and state.
- Fix the owner. When the request needs a state the prototype lacks, add it to the view's
props and to the prototype's
meta.states.
- Verify.
proto check --json must exit 0, with no problems and no error. Run the
view's own checks (typecheck, stories, tests). Look at the reviewed state at the reviewed
theme, role and width, for example with
proto screenshot <slug> --state <id> --theme <theme> --width <w> [--role <role>]. If the view
appears in other prototypes or states, check those too.
- Answer.
- Done and verified:
proto comments resolve <id> --note "<what changed, where, how you verified it>". You can then proto comments attach <id> <png>, which attaches the image to
that note.
- Ambiguous, needs a product decision, or out of scope:
proto comments reply <id> --note "<question or reason>" and leave the thread open.
- A resolved thread that still needs work:
proto comments reopen <id> --note "...". That
reopens the comment; reopening the review is a person's call.
- Fix your own wording with
proto comments edit <id> --note "..." [--message <n>].
The work is done when every thread you took is either resolved with a verified note or open with
a reply that says what is needed. Approval stays with the reviewer.
Pitfalls
resolve on a thread that is already resolved changes nothing, and its --note is dropped.
Use reply instead.
edit, attach and detach only work on your own messages (message_not_owned).
--author defaults to agent. Never post as reviewer.
comments add on a prototype key needs --selector (selector is required); flow keys do
not. Agents add comments only when a person asks for one.
Component story comments
A story--<component slug> key addresses a CSF file; context.state is its story id.
Use proto stories list --filter '<component slug>--*' --json to find that file and
proto stories url <context.state> to reopen the story. Apply theme and viewport from the
comment in the gallery. Fix the owning component or its fixtures as appropriate, preserving
CSF and preview setup. Verify with proto stories run --filter '<story-id>' --json plus the
project's checks and a visual review in proto dev; prototype screenshot/evidence commands
are not story capture commands. Reply/resolve with the ordinary comment commands.
Read threads with proto comments list --slug story--<slug> --json. Adding a component comment
requires --state <story-id> belonging to the component (invalid_input if absent/invalid),
with the normal --note and --selector. Existing story-* prototype slugs remain prototypes.
Story review is local; do not pass --remote. Agents never approve component reviews.
1---2name: proto-apply-comments3description: Apply @compozy/proto gallery review comments to the code that renders them, verify the reviewed state and answer each thread. Use for a comment id such as `login-form-7` or `flow-checkout-2` or `story--ui-button-3`, a gallery link with `comment=`, or a request to address open prototype review comments. For authoring prototypes or setting up proto, use the proto skill.4metadata:5 source: https://skillmd.com/skills/compozy/proto-apply-comments6---78# Apply prototype review comments910A reviewer pinned a comment to something rendered in the proto gallery. The comment records where11it was clicked in the source, plus the exact state, theme, role, viewport and commit they saw.12Your job is to change the code that ships, prove the reviewed state now looks right, and answer13the thread. The `proto` skill installed beside this one owns the concepts and hard rules: read14its `SKILL.md` when prototypes, drafts, flows or guards are unfamiliar, `references/cli.md` for a15command's flags or JSON, and `references/troubleshooting.md` when a command fails. Project rules16in `AGENTS.md` or `CLAUDE.md` take precedence for code conventions.1718## Rules1920- **Fix the owning view, not the prototype.** A component prototype only composes a view with21 fixtures, so the reviewed pixels come from the view, and that is what ships. Edit a draft22 directly, a flow in its `.flow.ts`, and fixture data only when the comment is about the data.23- **Agents never approve.** Do not run `review approve`, `review reopen` or `review unlock`, and24 delete a comment only when a person asks. Resolving a thread is not approval.25- The `proto` hard rules still apply: never edit `proto/review/**` by hand (write through26 `proto comments ...` or MCP), never weaken a guard, and never copy view markup into a27 `.proto.tsx` to satisfy a comment.2829## Loop3031Add `--app <dir>` to every command in a monorepo. When the review lives on the deployed gallery,32add `--remote` to the `comments` and `review status` commands only. `check`, `flow show` and33`screenshot` always run locally and exit 2 with `--remote`. The MCP tools (`proto_comments_list`,34`proto_comments_show`, ...) take the same fields and return the same JSON.35361. **Find the threads.** For a given id, run `proto comments show <id> --json`. Otherwise run37 `proto comments list --json` (open by default; filter with `--slug <key>`, `--spec`,38 `--state`). Threads whose last message is from an agent are waiting on a person39 (`--waiting`); leave them alone unless something changed.402. **Read everything.** Read every message in the thread, not just the first, because later41 replies often change the request. Download the images with42 `proto comments attachments <id> --json` (into `.tmp/proto/<id>/`) and look at them.433. **Locate the source.**44 - `target.source` is the app-relative `path:line:column` of the JSX nearest to the clicked45 element. `target.sourceChain` walks outward from it to the composing prototype. The first46 entry outside the `.proto.tsx` is usually the owner. If that entry is a shared component47 and the request is about this screen only, the fix belongs at the call site further out in48 the chain. When only the `.proto.tsx` appears, the comment is about fixtures or state49 selection.50 - `target.text`, `selector` and `testId` confirm the element. A `region` target lists what51 was drawn inside the dragged area.52 - Lines refer to `context.commit`. If the file changed since, find the element by its text or53 with `git diff <commit> -- <path>`.54 - An empty chain means the element came from outside the app's sources (for example a55 design-system package). The owner is the app view that renders that component.56 - Flow comments have `target.kind: "node"`. `node` is the flow node id, or `null` for the whole57 flow. `proto flow show <id> --json`, where `<id>` is the comment key without its `flow-`58 prefix, maps the node to its prototype and state.594. **Reproduce.** With `proto dev` running, open the gallery URL from60 `proto url <slug> --state <context.state> --theme <theme> --role <role> --width61 <viewport.width>`, leaving out the flags whose context value is `null`. The gallery applies62 the width; a `--bare` render document takes the window's width instead. For a flow comment,63 use the node's prototype and state.645. **Fix** the owner. When the request needs a state the prototype lacks, add it to the view's65 props and to the prototype's `meta.states`.666. **Verify.** `proto check --json` must exit 0, with no `problems` and no `error`. Run the67 view's own checks (typecheck, stories, tests). Look at the reviewed state at the reviewed68 theme, role and width, for example with69 `proto screenshot <slug> --state <id> --theme <theme> --width <w> [--role <role>]`. If the view70 appears in other prototypes or states, check those too.717. **Answer.**72 - Done and verified: `proto comments resolve <id> --note "<what changed, where, how you73 verified it>"`. You can then `proto comments attach <id> <png>`, which attaches the image to74 that note.75 - Ambiguous, needs a product decision, or out of scope: `proto comments reply <id> --note76 "<question or reason>"` and leave the thread open.77 - A resolved thread that still needs work: `proto comments reopen <id> --note "..."`. That78 reopens the comment; reopening the review is a person's call.79 - Fix your own wording with `proto comments edit <id> --note "..." [--message <n>]`.8081The work is done when every thread you took is either resolved with a verified note or open with82a reply that says what is needed. Approval stays with the reviewer.8384## Pitfalls8586- `resolve` on a thread that is already resolved changes nothing, and its `--note` is dropped.87 Use `reply` instead.88- `edit`, `attach` and `detach` only work on your own messages (`message_not_owned`).89- `--author` defaults to `agent`. Never post as `reviewer`.90- `comments add` on a prototype key needs `--selector` (`selector is required`); flow keys do91 not. Agents add comments only when a person asks for one.9293## Component story comments9495A `story--<component slug>` key addresses a CSF file; `context.state` is its story id.96Use `proto stories list --filter '<component slug>--*' --json` to find that file and97`proto stories url <context.state>` to reopen the story. Apply theme and viewport from the98comment in the gallery. Fix the owning component or its fixtures as appropriate, preserving99CSF and preview setup. Verify with `proto stories run --filter '<story-id>' --json` plus the100project's checks and a visual review in `proto dev`; prototype screenshot/evidence commands101are not story capture commands. Reply/resolve with the ordinary comment commands.102103Read threads with `proto comments list --slug story--<slug> --json`. Adding a component comment104requires `--state <story-id>` belonging to the component (`invalid_input` if absent/invalid),105with the normal `--note` and `--selector`. Existing `story-*` prototype slugs remain prototypes.106Story review is local; do not pass `--remote`. Agents never approve component reviews.