stage-compose

# stage-compose

Author an Orkas HTML composition and turn it into video. In Orkas, lint,
inspect, snapshot, draft, and export run through built-in `video_studio`.

Apply `frontend-design` before writing `manifest.art_direction`. When the user
provides a reference image/video, DESIGN.md, brand guide, screenshot, design
notes, or named style, apply `design-system-importer` to create intent-bound
media constraints and compact tokens. After snapshot, apply
`composition-design-review` yourself as an advisory frame checklist; it never
replaces native QA or creates a gate.

All COMPOSE stops and authorization transitions belong to `gate-control`. This
Skill supplies the manifest, contact sheet, draft, QA evidence, and readiness;
pass those facts to `gate-control` rather than restating approval policy.

## No-runtime advisory package

When production tools cannot run, follow `gate-control`'s complete unexecuted-
package protocol and read
[no-runtime-package.md](references/no-runtime-package.md). Read it only on that
branch; ordinary runtime work never needs it.

## QA response kernel

Every QA failure or recovery handoff carries the current reviewable artifact
package, not only a reason: returned `current_candidate`, contact sheet or
sampled frames, failed draft when present, and `findings_path`/inline findings.
Label it current but unapproved, state the bounded repair and next cheap check,
and omit fields not returned. If `review_package.presentation_required:true`,
show `primary_artifact`, summarize `conclusion`, and keep other paths as evidence.
With no media, show the returned manifest or authored HTML.

Ask only for a real creative/cost choice, with concrete options derived from the
artifact. Do not expose native error ids, Gate labels, repair budgets,
signatures, or schema jargon. Translate a result into: what needs work, what
remains safe, and the concrete repair/next check. In Chinese, say `生成旁白音频`,
`将旁白音频加入视频`, or `旁白音频生成失败`, never `旁白物化`.

Top-level continuation fields outrank prose errors:

- `next_step_owner:agent` plus `execution.continue_in_current_turn:true` means
  mutate the named file, retry, and continue in this turn.
- `next_step_owner:user` requires the artifact and concrete choices now.
- `next_step_owner:external` stops safely at the preserved artifact without
  claiming automatic recovery.

Fatal inspect blocks snapshot/draft/preview until repaired. A successful inspect
with visual review allowed goes to snapshot before editing, so repairs have frame
evidence. Before showing a passing snapshot, inspect the complete returned frame
set economically, batch visible blockers, repair affected scenes, then rerun
inspect + snapshot. A semantic failure stays visible but unapproved and must not
retry unchanged input. An exhausted visual-QA cycle shows evidence and native
options, then waits; no recovery operation exists.

A narration retime moves all scene windows. When materialization returns
`scaffold_retimed:true`, adjust each shifted scene's tweens from its new window
before inspect/snapshot; do not drop a silent designed beat.

A passing snapshot ends the turn until go-ahead for its visual identity. Show
the complete frame set and stop; do not draft in that turn. Visible changes make
a new identity and require one changed complete preview. Narration/audio-only
work inherits prior preview when scene windows and pixels are unchanged.

For detailed failure classification, repair causes, and bounded retry behavior,
read [qa-and-repair.md](references/qa-and-repair.md) only after inspect,
snapshot, or draft actually reports a failure/recovery branch.

## Post-gate revisions

On every gate submission or post-gate edit, use `gate-control` and its resolver
before production calls. Styling-only HTML/CSS/SVG/layout/motion/palette/assets
is `visual_only`. Signed delivery, approved copy, narration, timing, language,
source mappings, roles, or narration intent is `gate_b_payload`.

After a draft/final `visual_only` edit, recapture and show the changed complete
frame set, wait for go-ahead, then draft the complete composition as one mp4.
Approved export re-encodes the same whole composition at delivery quality. The
new draft reopens final-video confirmation; do not imply only one scene can be
encoded or skip whole-composition QA.

In other words, `composition.draft` re-encodes the complete composition as one mp4;
export is not a scene-only shortcut.

## Fast COMPOSE runbook

1. Read this installed root once per conversation; re-read only when runtime
   reports an updated installation. Read an existing canonical manifest. Apply
   `frontend-design`; apply `design-system-importer` only for a concrete style
   source; apply `composition-design-review` only after snapshot.
2. Stop for direction before writing any manifest, narration, or art direction.
3. The plan is only
   `project/composition/composition-manifest.json`: duration, language, audio
   ownership, scenes, approved copy, narration, and art direction. No shotlist,
   script, or second structural contract. Before authoring it, read
   [manifest-and-authoring.md](references/manifest-and-authoring.md), which owns
   schema, scaffold, language, art direction, and offline authoring rules.
4. For standalone narration, call `speech.capabilities`, select a returned
   locale-compatible `route_ref` + `voice_ref`, write exact intent, then run the
   free `composition.check_narration_fit`. Open the plan stop only when
   `gate_b_ready:true`.
5. On every new/resumed production turn, call `composition.status`. Reconcile
   file/state disagreement through `gate-control`. Plan identity is normalized
   approved intent, not raw manifest hash; implementation-only art direction,
   formatting, HTML/CSS/SVG/motion makes a new candidate without reopening plan.
   Once current, call `composition.doctor` once that turn, fix missing required
   capabilities, then call `composition.prepare`.
6. For standalone speech after prepare, read
   [narration.md](