Remotion Orchestrator

remotion-orchestrator — Remotion Skills Package entry point

/remotion-video one-shot command

/remotion-video is the one-shot command lane for Remotion marketing videos. It turns a rough brief into one governed production packet, one render path, and one final evidence report.

Hard rules for this command path:

• single voice only; no multi-voice casts and no per-scene voice switching.
• use existing Synthex ElevenLabs credentials and voice configuration only.
• no new vendors, no new accounts, no connector platforms.
• start with dry-run unless the operator explicitly asks for production render.
• write .harness/remotion/<jobId>/production-packet.json, script.md, preflight-report.md, and render-command.sh.
• never commit generated MP4s.

The command routes through remotion-script, remotion-production, remotion-direction, remotion-editing, remotion-integrations, and remotion-professionalism, while preserving the existing Remotion Skills Package workflow below.

Single entry point for the Remotion Skills Package — a set of 10 sibling skills (remotion-orchestrator, remotion-brand-research, remotion-brand-codify, remotion-designer, remotion-colour-family, remotion-motion-language, remotion-screen-storyteller, remotion-marketing-strategist, remotion-composition-builder, remotion-render-pipeline) installed globally at ~/.claude/skills/remotion-* (symlinked to ~/Pi-Dev-Ops/skills/remotion-*). Available in every project, not just Pi-Dev-Ops.

Discovery brief gate (turn 1, mandatory)

Adopted from nexu-io/open-design (Apache-2.0). Before any wave plan is emitted, lock the brief. Refuse to proceed until every required field is filled — vague briefs produce overlong wave plans and off-brand renders.

Required fields

Optional: school (visual-school override for the colour generator), voiceoverScript (skip storyteller if pre-written), referenceComposition (existing job to remix).

Hard stop conditions

• topic reads as a category ("our product", "the launch") rather than a specific claim → block.
• composition ≠ Explainer in v1 without explicit fallback acknowledgement → block.
• Multiple brands named in one brief → split into N parallel jobs (one per brand); never blend.

The gate runs before the wave plan is computed. A blocked brief never reaches the dispatcher.

Invocation

The user can invoke the package by:

• Saying any of: "use the Remotion Skills Package", "remotion package", "use remotion".
• Naming any individual skill (e.g. "use remotion-designer to QA this layout").
• Submitting a brief that classifies as intent: "video" via app/server/brief.py.

Translates a free-text brief into a structured render job and a wave plan that the Pi-Dev-Ops orchestrator (app/server/orchestrator.py) dispatches via P3-B fan-out.

The Remotion project

All compositions, brand configs, motion / colour helpers, and the render entry live at:

../../remotion-studio/

When working from any other project, sub-skills cd into that path before reading or editing brand / composition files. The render entry is npx tsx render/render.ts ... from inside remotion-studio.

Triggers

Brief contains any of: video, explainer, promo, ad, reel, intro, outro, cta, social cut, 60s/30s/15s, render, marketing video, training video, release video, feature video, paired with one of the brand identifiers dr / disaster recovery / nrpg / ra / restoreassist / carsi / ccw / carpet cleaners warehouse.

Inputs

The Pi-Dev-Ops planner (Opus 4.7) calls this skill with:

• brief — original free-text request
• repo_url — usually local:Pi-Dev-Ops/remotion-studio
• linear_team_id, linear_project_id — pre-resolved from config/harness/projects.json

Output

A wave plan JSON written to remotion-studio/.research/wave-plans/{job_id}.json with this shape:

{
  "jobId": "ra-nir-explainer-2026-04-28T15-30-00",
  "brand": "ra",
  "composition": "Explainer",
  "channel": "linkedin",
  "durationSec": 60,
  "topic": "RestoreAssist NIR Phase 1 standardisation",
  "linear": { "teamId": "...", "projectId": "..." },
  "outputPath": "output/ra-nir-explainer-2026-04-28T15-30-00.mp4",
  "waves": [
    { "id": 1, "parallel": [ {"skill":"remotion-brand-research","if":"brands/ra.ts missing or stale"}, {"skill":"remotion-marketing-strategist"} ] },
    { "id": 2, "parallel": [ {"skill":"remotion-screen-storyteller"}, {"skill":"remotion-colour-family","if":"palette incomplete"}, {"skill":"remotion-motion-language","if":"motion missing"} ] },
    { "id": 3, "parallel": [ {"skill":"remotion-brand-codify","if":"any new brand artifacts"}, {"skill":"remotion-designer"} ] },
    { "id": 4, "serial":   [ {"skill":"remotion-composition-builder"}, {"skill":"remotion-render-pipeline"} ] }
  ]
}

Wave-count discipline

• ≤3 waves for output <30s
• ≤5 waves for output ≤120s
• ≤8 waves for output >120s

Over-decomposition is the failure mode this guards against.

Composition routing (brief → composition id)

v1 supports Explainer only. Other composition ids return: "{Composition} ships in v1.1 — falling back to Explainer with channel-specific framing".

Brand resolution

Match keywords → BrandSlug:

• disaster recovery, dr → dr
• nrpg → nrpg
• restoreassist, ra, nir → ra
• carsi → carsi
• ccw, carpet cleaners warehouse → ccw

If brief names multiple brands, ask the planner to split into N parallel jobs (one per brand) and emit N wave plans. Never blend brands into one composition.

Linear routing

After the render skill writes the MP4, this skill (or the render skill) opens a Linear ticket in the project mapped from config/harness/projects.json:

Thumbnail & still image generation (Canva-first — do NOT credential-hunt)

For a video thumbnail, poster, or any marketing still, the reliable path is the connected Canva MCP, not a raw image-gen API key:

1. generate-design (design_type: your_story for 9:16, youtube_thumbnail for 16:9) with a detailed brand-aligned query — pass the palette/headline in the query; Canva renders headline text reliably.
2. Download the candidate previews and pick the best; create-design-from-candidate → export-design (PNG at target WxH, export_quality: pro).

Hard rules (learned the hard way, 2026-07-01):

• Never credential-hunt for image-gen keys. Do not scan .env files or vercel env pull across projects/environments looking for GEMINI_API_KEY / OPENAI_API_KEY / AI_GATEWAY_API_KEY. The auto-mode classifier blocks it as credential exploration, and it wastes the whole session.
• Vercel "Sensitive" env vars are write-only — vercel env pull returns them EMPTY. Do not try to pull one; get the value from its original source or use Canva.
• If no image tool is connected and no key is reachable in ONE directed check, stop and ask the founder once — offer Canva up front.
• A frame-grab from the rendered MP4 (bundled ffmpeg at node_modules/@remotion/compositor-*/ffmpeg) is the offline fallback. Note: on macOS, symlink the sibling *.dylib files into the cwd so the bundled ffprobe/ffmpeg resolve (SIP strips DYLD_*).

What this skill does NOT do

• Does not author compositions — that's remotion-composition-builder.
• Does not run npx remotion render — that's remotion-render-pipeline.
• Does not edit BrandConfig files — that's remotion-brand-codify.

It only plans + delegates.

Per-project usage model

The package is shared infrastructure; each calling project supplies its own runtime config and API keys.

Adding a new brand for your project

If your project (e.g. Synthex) needs to render for a brand that isn't yet in src/brands/:

1. Run remotion-brand-research against the brand's public sources.
2. Run remotion-brand-codify to produce Synthex/packages/brand-config/src/brands/{slug}.ts.
3. Extend the BrandSlug union in Synthex/packages/brand-config/src/types.ts.
4. Register in Synthex/packages/brand-config/src/brands/index.ts.
5. Run npm run typecheck from Synthex/packages/brand-config/ (then npm run build to regenerate dist/).

Currently registered brands: dr, nrpg, ra, carsi, ccw, synthex, unite.