stage-compose

stage-compose

How to author an Orkas/OVS HTML composition and turn it into a video. composition-manifest.json v2 is the canonical timeline/audio/design artifact. In this open-source build, ovs draft is the VideoStudio-style production gate: it runs manifest/source/narration/local-asset checks, HyperFrames check/render, media QA, sampled-frame video QA, and writes one report. HyperFrames remains the render backend; do not bypass the draft gate for user-facing drafts.

For visual direction, apply frontend-design before writing manifest art_direction. If the user provides a reference image/video, DESIGN.md, brand guide, screenshot, design notes, existing app UI, or named style, apply design-system-importer to convert it into intent-bound reference constraints and compact tokens. composition-design-review is a bounded full-frame review before a visual preview is shown, with a post-draft fallback when preview is skipped.

Gate authorization belongs to gate-control. This skill supplies the canonical manifest, contact sheet, draft, and QA evidence; after any Gate B/Preview/Gate D decision or resumed approval, run ovs gate transition rather than inventing a second confirmation or recovery loop.

When the production runtime is unavailable, return a clearly unexecuted candidate package instead of fabricating a render: locked assumptions, final-form script/narration, timed storyboard, exact visible copy/captions, visual/audio and rights-safe asset plan, target export settings, and checkable preview/final QA.

Fast COMPOSE Runbook

After Gate B approves the canonical composition manifest, keep the production turn narrow:

1. Read the approved project/composition/composition-manifest.json and this skill if not already loaded for the current turn. Also read frontend-design; read design-system-importer only when a concrete style source or explicit named reference exists. Read composition-design-review after snapshot evidence exists, or after the draft when preview was intentionally skipped and the fallback trigger applies.
2. If standalone narration is needed, capture the exact ovs speech-capabilities profile in the approved plan and run ovs narration fit before synthesis. Visual authoring, ovs check, and ovs snapshot may proceed while narration is pending so the visual candidate remains reviewable. Required narration blocks only complete ovs draft/final delivery. Before drafting, run ovs speak once to project/composition/assets/narration.mp3, declare the composition-owned track, probe its duration, rerun measured fit, and reconcile. Reuse an existing matching narration file; do not synthesize again just because a visual preview changed. For an AUTO segment, use audio.owner: "assembler" and render silent.
3. Keep the approved project/composition/composition-manifest.json with schema_version: 2, including approved timeline/copy/source mappings, audio ownership, and art_direction. Confirm its dedicated cover, any references/reference_fidelity, and VisualDirectionV1; then prepare and author static resolved/hero frames before deterministic motion. The exact 0s cover must already be readable. Reconcile after manifest timing/audio changes without replacing authored DOM/CSS/SVG/motion.
4. Decide whether to open the optional HTML Preview Gate before rendering mp4. Use the preview gate when expected render rework is expensive: target duration >= 20s, scene count >= 3, render cost is likely slow, or the composition has dense text, complex SVG/GSAP, many branded/supplied assets, tight narration timing, or a prior draft failure. Skip it for short/simple work: target duration < 20s, scene count <= 2, no narration/timing complexity, and no obvious visual-risk signal. The subject category alone never forces the preview gate.
5. If visual preview is needed, run ovs check and ovs snapshot. Review the complete contact-sheet index and open the cover, QA-named frames and risky cells at full size; compare declared references. Collect all blockers, apply one localized repair, then rerun check/snapshot and review the complete new revision. The contact sheet is only an index. The author checklist is advisory and adds no scored approval gate; present current passing snapshot evidence after addressing concrete visible blockers.
6. Run the draft command: ovs draft project/composition --out project/render/draft.mp4 --quality draft --report project/render/draft-report.json --findings project/composition/qa/check.json. Before rendering, this gate validates manifest/HTML consistency, prepares declared local vendor assets, blocks remote runtime resources, verifies local assets, checks shotlist/source alignment, and checks narration mapping. Then it runs HyperFrames check/render, media QA, sampled-frame QA, and writes one report.
7. If draft fails, repair the highest canonical source, reconcile when needed, and retry only after the authored signature changes. Do not delete QA state or repeat an unchanged strategy. After two non-converging passes, preserve the current artifact and show the visible unresolved issue with concrete options through gate-control; await a real user direction before another cycle.
8. If the draft command returns ok: true, the composition is frozen for final-video confirmation. Do not edit index.html, composition-manifest.json, assets, or narration again in the same turn unless the report contains a real blocker (check/source/audio/video QA failure), or the user explicitly asks for a revision. Visual/readability warnings and design-review fix/polish notes are advisories, not permission to self-repair.
9. If preview was skipped and the fallback trigger applies, run composition-design-review against representative draft frames. Open final-video confirmation only after the draft command returns ok: true and any triggered review has no concrete blockers.