composer

Singular Composer

Use the client with one unique connection name per conversation:

node scripts/composer-agent.js <command> --connection <conversation-connection-name> [options]

Reuse it for paired commands. Local ai-graphics validate|preview reject --connection; omit it. Never reuse another profile or combine it with COMPOSER_AGENT_CREDENTIALS. Use only bundled CLIs. Never expose credentials, replace raw composition JSON, construct script REST calls, or add arbitrary relay execution.

Run node scripts/dependency-preflight.js once per package version, Node major, and lockfile digest; reuse success until one changes. Add --capture for Chrome. Use doctor for installation diagnostics. Always install the latest available Composer skill; never downgrade for protocol compatibility.

Require a passing preflight before new work. Use an existing Node 22.x or 24.x runtime. NODE_VERSION_MISMATCH remains blocking for other majors even when core dependencies are ready; select a supported runtime and rerun as described in installation, without silently replacing the user's global runtime.

After COMPOSER_AGENT_VERSION_MISMATCH, follow installation recovery before choosing Control Node types. Upgrade first, then reread type-specific references from the installed replacement; stale references are not authority for the new protocol.

Route the task first

Read only references needed for the current task and phase.

Recipe algorithms and acceptance scenarios apply only to the requested graphic. They are not skill-maintenance gates. Do not expand a Composer command or documentation task into general widget QA, external-data integration testing or unrequested source edits.

Task	Required reference
Install, upgrade, or verify the skill installation	installation.md before changing any installed file
Pairing, files, and recovery	command-basics.md, resuming-work.md
Graphic creation, design, or reference matching	authoring-quality.md
Isolated property edit	"Isolated property edits" in command-basics.md, then the matching widget guide
Elements, layout, fonts, primitives, or declarative graphics	element-commands.md, graphics.md, or auxiliary-commands.md
Widget selection or configuration	widgets.md, then its routed widget guide
Compositions, app template matches or Integration Resources, revisions, or display variants	composition-structure.md, composition-commands.md, revisions.md, or display-variants.md
Timeline, Update, Behavior, logic layers, or playback	composition-motion.md and motion-commands.md
Control Nodes, containers, values, links, or deletion	control-nodes.md, then its routed creation, editing, or command reference
Native Timer duration control or timerChanged script messages	control-node-timer.md
Widget-owned templates or output links	widget-subcompositions.md or widget-nodes.md
Capture or measurements	capture.md
Composition scripts or Player behavior	composition-scripts.md and its routed scripting references
Reusable construction pattern or supplied motion	recipes.md or video-reference.md
generate improvement handoff	improvement-handoff.md

generate improvement handoff is retrospective. Return its sanitized development prompt without pairing, work, inspection, or mutation.

Authorize and work

Composer AI availability is deployment- and account-gated. If absent or ineligible, report the blocker and stop. For new authorization, request the visible six-character code; never request the token or poll an intent. Run pair --code <code> immediately when supplied. PAIRING_CODE_INVALID is terminal; request a fresh code without retrying. Require paired: true and acknowledged: true. Use check-connection --connection <conversation-connection-name> for a read-only check.

Do not filter pairing stdout/stderr or hide its exit status. Inspect the complete sanitized result; a protocol mismatch before the claim does not consume the code, but expiration still applies. Follow installation recovery before retrying.

For tasks requiring editor commands, run before inspect or mutation:

node scripts/composer-agent.js begin-work --connection <conversation-connection-name>

Continue only for active authorization, connected editor, ready commands, and active lease. begin-work attempts release on readiness failure; check its acknowledged or unknown cleanup outcome in command basics. On OPERATION_CANCELLED, stop until a new instruction. Before yielding, waiting, or ending, run:

node scripts/composer-agent.js finish-work --connection <conversation-connection-name>

Require COMPOSER_WORK_RELEASED. For successful task completion, use finish-work --save instead: it awaits the final composition save when autosave is enabled, or reports save.manualSaveRequired without saving in manual mode. Plain finish-work is a pause/release, not a completion save. Before a blocking question, send status --state waiting-for-user --message "<blocking question>", release without --save, then wait. --message is required. Revisions own the approval exception. Use complete only for explicit revocation. See batched autosave for interruption, save-failure and publication limits.

When an answer arrives, make the answer acknowledgement your first Composer action, before planning, file preparation, readiness checks or inspection where the lease is still active. Do not leave Composer showing the question while preparing the next operation. This feedback does not authorize a mutation or bypass lease/cancellation gates.

Inspect, mutate, verify

For a template-matched composition, the composition contract is inviolable, even on explicit user request. Before structural or contract-dependent behavior changes, read the matched template's Integration Resources (the user's requested status, otherwise published) and check each proposed mutation against the contract. Never delete, rename, move or retype required Control Nodes, rename/move/delete contract-named compositions or paths, or remove required behavior. Decline breaking parts, name the exact contract entries, and offer only contract-preserving alternatives; continue safe parts within the authorized scope. Confirmation, justification or revision approval cannot override this rule. Never clear or change the match to bypass it or offer to proceed after a template switch. Removing or replacing a protecting match is the user's own action in Composer, not an agent workaround. See Contract preservation.

For Control App-driven or template-compatible authoring, follow the Integration Resources completion gate before choosing structure, public controls, or scripts. Track required behavior separately from interface preservation. During structural authoring, discover the root match and preserve its contract for externally addressed content. Unrelated visual edits need no resource fetch.

Before building a new composition, determine the appropriate app template. When template selection calls for Essentials or Studio, use UNO Essentials (template ID 518) unless the user explicitly requests Studio; do not ask the user to choose between Essentials and Studio. This is not a general default for other templates; honor any other explicit template choice. If the user's explicitly requested Control App template appears mismatched, warn them once, then honor their choice and follow that template's Integration Resources contract. Read its contract and assign the template to the composition with set-app-template-match. Follow the completion workflow for other template decisions and uncertainty. An existing matched composition contract remains inviolable.

Composer is the source of truth:

1. Run inspect and read targets narrowly; chat is not current state. See resume safeguards.
2. Read required live schemas and ownership through the routed reference; never infer mutable contracts from memory. For matched compositions, complete the contract-preservation check before every structural or contract-dependent mutation, including isolated node-ID edits, deletions, composition renames, and script changes. Reuse the current task's versioned contract only while its match/status/version remains current.
3. Before the first high-impact mutation in a task, recommend a revision through the AI chat question UI and wait for the user's choice, except for a verified empty starter scene. A default group and empty default sub-composition with no authored content or Control Nodes do not need a backup prompt. Read revision approval for the scene-wide empty-starter check, other exclusions, and consent procedure before proceeding.
4. Make one coherent, bounded change through the highest-level supported operation. For apply, pass the inspected --composition-id as a scope guard.
5. Reinspect the changed scope and verify authoritative readback, links, ownership, and unrelated state.

Use bounded projections and temporary structured inputs. Never decompose failed atomic operations. Follow command-basics.md: after an uncertain outcome, obtain authoritative readback before retry. Report errors directly.

Change only requested content. Preserve unrelated structure, controls, links, scripts, and states. One destination has exactly one write authority; update linked fields through their defining source. The paired editor owns structure, the authenticated helper owns persisted script text, and Player owns runtime behavior. Follow routed revision, template, capture, and scripting safeguards.

Before handoff, confirm scope, readback, ownership, applicable visual/runtime evidence, cleanup, final state, and lease release. Distinguish model verification, captured appearance (including separate Player instances), same-session payload propagation, and Control App testing; follow evidence-specific completion. Report unverified behavior as pending.