Studio UX Element protocol

Operator-visible chat for the split Studio UX workcells (ux_improver_worker + implementation_worker).

Updated

Room and identity

Item Value
Room !XpWhlVkoxnjDQHvYlX:matrix.forgedc.net (alias #studio-ux:matrix.forgedc.net may not resolve)
Human operator @forgeadmin:matrix.forgedc.net
Allowlist (optional) MATRIX_OPERATOR_SENDERS=@forgeadmin:matrix.forgedc.net
Bot posts MATRIX_ACCESS_TOKEN account (typically not forgeadmin)

When MATRIX_OPERATOR_SENDERS is unset, any non-bot sender may reply (legacy behavior).

Layering

Layer Use
Element Human-visible status, HITL, product briefings
Disk Canonical machine contract (implement-job.json, implement-result.json, PDCA plans)
NATS Future agent bus — not used for Studio UX v1 handoff

Do not treat operator small-talk as job commands. Parsers require typed prefixes or explicit approval grammar.

Operator mode (split campaigns)

Env Default Effect
STUDIO_UX_ELEMENT_OPERATOR_MODE 1 when FM_STUDIO_UX_SPLIT_MODE=1 Product-oriented copy; no per-rank IMPLEMENT? spam
STUDIO_UX_ELEMENT_INCLUDE_JOB_JSON unset (0) When 1, include JSON fence in technical IMPLEMENT? cards

In operator mode (auto split):

  • One ASSESSMENT BRIEF per page replaces per-rank IMPLEMENT? Matrix posts (jobs still written to disk).
  • IMPLEMENT START / IMPLEMENT DONE show scope title and scores, not job_id / model.
  • JSON job contracts remain on disk only unless STUDIO_UX_ELEMENT_INCLUDE_JOB_JSON=1.

Interactive campaigns (FM_STUDIO_UX_MODE=interactive) keep APPROVE? and per-rank IMPLEMENT? cards.

Screenshot lifecycle

When Image
Analysis cycle-start Before panel (baseline)
Each implement rank after capture Before / After composite · rank N/M with red tint on changed pixels (before) and green tint (after)
Monolithic cycle-complete Same composite with change highlights when after.png exists

Workcell personas (visible bus)

Messages prefix the acting workcell before the consumer id (one Matrix bot, multiple personas):

Persona Workcell Typical messages
ux_improver ux_improver_worker START, ASSESSMENT BRIEF, ANALYSIS DONE, HANDOFF
implementation_worker implementation_worker ACK HANDOFF, IMPLEMENT START, IMPLEMENT DONE
studio_ux_orchestrator split orchestrator CAMPAIGN START, IMPLEMENT PHASE START, CAMPAIGN DONE

Format: **[ux_improver · forge-market] ASSESSMENT BRIEF** · \tickers``

Disable with STUDIO_UX_ELEMENT_WORKCELL_PERSONA=0.

Disk handoff refs appear in HANDOFF / ACK HANDOFF lines with absolute paths (open in editor):

Files:
- job-r01: `/home/.../pages/tickers/iter-001/implement-job-r01.json`
- plan-r01: `/home/.../forge-market/.cursor/plans/studio-ux-pdca/tickers-01-....plan.md`
- pdca-r01: `/home/.../pages/tickers/iter-001/pdca-prompts/01-....md`

IMPLEMENT DONE lists result, before_screenshot, after_screenshot, and compare_image paths under Artifacts:.

Message kinds (analysis workcell)

Prefix Purpose
CAMPAIGN START Full campaign opened; page roster + expected job count
CAMPAIGN ANALYSIS DONE Analysis phase complete (split campaigns); suggestions queued rollup
CAMPAIGN DONE Final rollup after implement phase
ASSESSMENT BRIEF Product summary: user job, score, findings, work queue (operator mode)
ANALYSIS DONE Per-page milestone — slim line in operator mode
IMPLEMENT PHASE START Implement phase banner (split orchestrator)
START Page cycle opened
LIVE In-place status edit (m.replace)
PICKUP? Reuse prior suggestions vs fresh assess
APPROVE? Interactive approval before jobs
IMPLEMENT? Handoff to implement workcell (technical / interactive only)
HANDOFF ux_improver → implementation_worker disk ref
ACK HANDOFF implementation_worker picked up job

ASSESSMENT BRIEF body

  • Page title, route, purpose (manifest)
  • User job from assessment.json functionality_summary.intended_job
  • Platinum band from platinum-overall.json (Excellent / Good / Fair / Poor / Critical) — not legacy GPT overall
  • Top score drivers from platinum-overall.json topDamageContributors
  • Top findings (severity + axis + evidence summary)
  • Numbered work queue from prioritized_suggestions
  • Before screenshot caption

IMPLEMENT? body (technical mode)

  • Header: **[{consumer_id}] IMPLEMENT?** · \` · suggestion {rank}/{total}`
  • Fields: job_id, model, Ref:, Plan: (omitted in operator mode)
  • Split mode copy: Queued for implementation phase
  • JSON fence only when STUDIO_UX_ELEMENT_INCLUDE_JOB_JSON=1

Message kinds (implement workcell)

Prefix Purpose
IMPLEMENT START Cursor about to run (scope title in operator mode)
LIVE Build / score / gate progress
IMPLEMENT DONE PASS or FAIL with scores (scope title in operator mode)

IMPLEMENT DONE and the before/after compare image caption include a human-readable Improvement block (**Improvement:**, **What changed:**, **In the image:**) sourced from the ranked PDCA prompt Do section. Written to {cycle_dir}/implement-essence-rNN.md on disk.

Delivery: IMPLEMENT DONE is posted as one Matrix image message (m.image) whose caption is the full IMPLEMENT DONE body plus a one-line before/after legend. A separate text-only IMPLEMENT DONE is sent only when compare build/upload fails (Pillow missing, Matrix error, etc.). Mid-cycle compare updates still replace the cycle-start panel; the final rank posts a new image message (force_new) so operators always see text and image together.

IMPLEMENT DONE is not parsed as a new IMPLEMENT? job.

HITL reply grammar

Analysis phase (unchanged)

Reply Effect
approve all / all All ranks
approve 1,3 Selected ranks
reorder 3,1,2 then approve all Reorder then approve
skip / reject / none No jobs posted
fresh Discard assessment
pickup / fresh Prior-run pickup gate

Implement handoff

Reply Effect
implement Acknowledge auto-posted job (interactive)
hold Pause; implement worker must not start
retry Re-run failed implement job
abort Cancel job; write implement-result status aborted

Timeout default: 900s → analysis treats as hold and @mentions forgeadmin.

Paper mode

When MATRIX_ACCESS_TOKEN is unset or mode: paper:

  • Write element-notify.json under {cycle_dir}/ with the same message bodies
  • Tests inject operator replies via element-approval-reply.txt or env presets

Prerequisites (live Matrix)

Dependency Where Why
Pillow>=10 NOTIFY_PYTHON venv (forge-cursor-bridge/.venv by default) Build matrix-compare-rNN.png before/after composites with red/green change highlights
Compare resolution STUDIO_UX_MATRIX_PANEL_WIDTH (default 960), STUDIO_UX_MATRIX_PANEL_HEIGHT (default 1080) Max pixels per before/after panel in the Element composite
Compare crop STUDIO_UX_MATRIX_COMPARE_SOURCE (default viewport) viewport = first-screen PNG (sharper); full = scroll capture; auto = viewport when present
Compare focus STUDIO_UX_COMPARE_CROP_TO_CHANGES (default 1), STUDIO_UX_COMPARE_MIN_CROP_HEIGHT (default 400), STUDIO_UX_COMPARE_MAX_HIGHLIGHT_RATIO (default 0.30) Crop to the densest change band (not full-width shallow strips); enforce minimum readable height; when pixel drift exceeds 30% of the panel, limit red/green highlights to the focus region only

If Pillow is missing, IMPLEMENT DONE still posts but compare_image is omitted and Element may show only the baseline before panel.

Schemas

Schema Path
forge.studio_ux_implement_job.v1 schemas/studio_ux_implement_job.v1.schema.json
forge.studio_ux_implement_result.v1 schemas/studio_ux_implement_result.v1.schema.json
forge.studio_ux_approval.v1 Written as approval-manifest.json in cycle dir