Handbook
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 BRIEFper page replaces per-rankIMPLEMENT?Matrix posts (jobs still written to disk). IMPLEMENT START/IMPLEMENT DONEshow scope title and scores, notjob_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.jsonfunctionality_summary.intended_job - Platinum band from
platinum-overall.json(Excellent / Good / Fair / Poor / Critical) — not legacy GPT overall - Top score drivers from
platinum-overall.jsontopDamageContributors - 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.jsonunder{cycle_dir}/with the same message bodies - Tests inject operator replies via
element-approval-reply.txtor 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 |