cowork-ux

name	cowork-ux
description	Cowork/Code MCP UX — plain language, menus, progress loops
agent_rule	Never paste raw JSON. Echo human_summary. Loop subscribe_progress for async jobs.
task	["narrate"]
domain	["story"]
persona	["agent-only"]
scope	episode
category	onboarding
triggers	["cowork","auto mode","don't ask every time","human friendly","just go","/cowork-ux"]

Cowork / Code UX — human-friendly Storyboard MCP

Use this skill whenever the user works through Claude Cowork, Claude Desktop, Claude Code, or Cursor with the Storyboard MCP. The server already returns human_summary, permission_hint, next_actions, and inline images — your job is to speak like a creative collaborator, not a JSON debugger.

Session start: when the user mentions Cowork, auto mode, or "don't ask every time", call attach_skill({ ref: "skill:cowork-ux" }) (idempotent if already attached).

Golden rules

1. Never paste raw tool JSON to the user — not args, not structuredContent, not {action:"generate",…}. Summarize in plain language.
2. Echo human_summary from the tool response before the client's native permission card appears (when you have a preview/dry-run) or right as you fire the real call.
3. Echo permission_hint once when the action is billable and the user hasn't seen it this session — one line, no legalese.
4. Render next_actions as a numbered menu after multi-slot results. The user replies with a number; you dispatch the matching tool + args unchanged.
5. After async submit, loop subscribe_progress({ job_id }) until terminal: true or should_resubscribe: false. Narrate progress; never say "polling get_create_media".
6. Images land inline — sync create_media image results include {type:"image"} blocks. Don't ask the user to open URLs for stills.
7. Keep the 5-intent model from storyboard-intro.md — don't enumerate 40 tools on first turn.

Tool → human verb mapping

MCP tool	Say this (not the tool name)
create_media	Generate / animate / restyle / upscale {kind}
generate_project	Render an N-scene storyboard
moodboard_spread	Generate N moodboard images
place_subject	Place your product in N scenes
create_variations	Make N variations of this image
submit_creative_job	Start async video job (N scenes) — I'll stream progress
submit_plan	Run N-step plan — approve once
director_export	Stitch + soundtrack + brand finishing
subscribe_progress	(read-only — prefer over get_creative_job; see Permission cards)
get_creative_job / get_create_media	(read-only fallback poll — use only if subscribe_progress unavailable)
list_capabilities / get_pricing	(read-only — auto-approve)
spend_cap	Set daily spend cap
publora_publish_post	Publish to social (always confirm)

Permission cards (Claude Desktop / Cowork)

The native MCP permission dialog is client-owned — Storyboard cannot replace its "Request { … }" JSON block. What we control:

Layer	What the user sees
Server title	Card headline, e.g. "Check on a multi-scene project that's still rendering" (live on all 122 tools)
Server readOnlyHint	Marks polling tools as read-only — Desktop may tier them separately from billable submits
Agent chat	Plain-language line before the card: "Rendering scene 3 of 6… (~2 min left)"
User setting	Always allow on subscribe_progress (and read-only getters) after the first approval

Rules for agents:

1. Prefer subscribe_progress({ job_id }) over repeated get_creative_job / get_create_media — one 25s hold + inline notifications beats N separate permission prompts.
2. Never paste the permission card JSON into chat — narrate progress from structuredContent.message / scene counts instead.
3. On the first async job in a session, tell the user once: "I'll stream render progress — click Always allow on the progress tool so you aren't prompted every few seconds."
4. Polling tools are free reads — they do not bill. Billable work already happened at submit_creative_job / create_media submit time.
5. human_summary on responses applies to submit tools only (create_media, generate_project, moodboard_spread, submit_plan) — it does not appear on pre-call permission cards for { job_id } polls.

If the chat shows "response stalled mid stream" (recovery — never re-run)

That message is emitted by the client (claude.ai / Desktop / Code), not Storyboard, when the response stream idles too long — which happens while a long async render (video / audio / 3D) runs. It does not mean the job failed. The render is still going on the server and the asset almost always lands.

When the user says any of these — "it stalled", "is it done?", "did it finish?", "where's my video?", "check it", "the response cut off", "try again", "retry" — treat it as a status check, not a new request:

1. Recover, don't re-create. Call subscribe_progress({ job_id }) (or get_create_media({ job_id })) for the job from the submit response. If you lost the job_id, call get_recent_assets — the finished asset is there.
2. Never re-issue create_media for the same thing after a stall. It's already rendering; a resubmit renders and charges it twice. (The server also auto-dedupes an identical re-submit within ~10 min as a safety net, but don't rely on it — check the existing job.)
3. Prevent it next time: always loop subscribe_progress({ job_id }) right after an async submit — it streams progress and keeps the stream warm, so the stall message doesn't appear.

Cost confirmation before fan-out

Before any multi-slot fan-out costing > $0.20, run a dry-run first:

• moodboard_spread({ …, confirm: false })
• place_subject({ …, confirm: false })
• create_variations({ …, confirm: false })
• generate_project({ …, confirm: false })

Echo the estimate in one line: "I'll generate 12 brand moodboard images (~$0.34 total, ~60–90s). Say go when ready." Then fire without confirm: false when the user approves.

For single create_media calls under $0.20, dry-run is optional — echo human_summary and proceed unless the user asked for a preview.

Auto mode

Trigger phrases: "auto mode", "just go", "don't ask every time", "skip confirmations", "cap at $N today".

When triggered:

1. Call spend_cap({ action: "set", cap_usd: N }) — default $25/day if the user didn't specify.
2. Confirm back: "I'll skip per-image confirmations under $N/day (currently $X spent). I'll still ask before publishing to social."
3. Under the cap: skip redundant confirm: false re-prompts for spreads the user already approved this session.
4. Never auto-approve: publora_publish_post, spend_cap increases, forget_assets with confirm: true.
5. Still dry-run once per session for spreads > $0.50 — show total, then auto-fire the rest of the session under cap.

Do not add or call a set_auto_mode tool — skill + spend_cap + client "Always allow" is enough.

Progress narration

Async jobs (mjob_*, cjob_*, ltj_*)

submit → job_id
loop subscribe_progress({ job_id }) until terminal

Narration template:

• Use structuredContent.message when present.
• Use eta_seconds / eta_p95_seconds from the submit response: "Rendering… (~45s)"
• Use quality_tier: "Fast preview · pixverse-i2v"
• On scene completion: "Scene 3 of 8 ready — opening preview…"
• On checkpoint_ready: mirror webapp copy — offer review_checkpoint + resume_from_checkpoint.

Never say: "polling get_create_media", "calling get_creative_job every 8–15s", or paste job IDs unless the user asks.

Sync path

Images: show inline preview + one-line summary from human_summary.

Video / audio / 3D: share the URL + ETA context; no inline render today.

next_actions menu format

After moodboards, projects, variations, or spreads:

Here are your results. Next:
1. Animate slot-3 into a video
2. Make 4 variations of slot-3
3. Open the live viewer

User says "2" → call the tool and args from next_actions[1] exactly.

submit_plan — single approval for multi-step flows

For complex chains (brief → moodboard → spread → animate → export), prefer:

1. submit_plan({ goal, steps: [...] }) → shows total cost + step list
2. User approves once via submit_plan({ plan_id, confirm: true })
3. Poll get_plan or subscribe_progress on the plan's job id

Echo: "Run 4-step plan: launch moodboard · total ~$0.52 — approve once"

Permission copy templates

When human_summary is absent, fall back to these shapes:

Tool	Template
create_media	Generate {kind} — {prompt_short} · ~{cost} · {eta}
generate_project	Render {n}-scene storyboard · ~{cost} · {eta} · viewer when done
moodboard_spread	Generate {count} moodboard images · ~{cost} · live viewer link
place_subject	Place your product in {count} scenes · ~{cost}
create_variations	Make {count} variations of this image · ~{cost}
submit_creative_job	Start async video job ({n} scenes) · ~{cost} · I'll stream progress
submit_plan	Run {n}-step plan: {goal} · total ~{cost} — approve once
director_export	Stitch + soundtrack + brand finishing · ~{cost}

What NOT to do

• Don't paste tool args or raw JSON responses.
• Don't ask the user to pick a model unless they asked.
• Don't fire 12-slot spreads without a cost preview when > $0.20.
• Don't build custom permission UI — Cowork owns the gate.
• Don't remove confirm: false dry-runs in auto mode without spend_cap set.

See also

• get-started-mcp.md — install ritual + health-check (start here for new users)
• storyboard-intro.md — five user intents + canonical paths
• finishing-quality.md — post-generation finishing pass
• recover-pasted-image.md — pasted image → public URL in Claude Code
• Desktop large uploads: https://storyboard.daydream.monster/upload-handoff — drag-drop → copy URL for create_media