.claude/skills/video-beats-orchestrate/SKILL.md

---
name: video-beats-orchestrate
description: Run the video beat pipeline for several beats in parallel (B2 to B13 of Moser Baer in batches of four). Launches Haiku sub-agents for the long mechanical stages and Sonnet sub-agents for the stages that need judgment, enforces file ownership and the two-builds-at-a-time limit, and integrates the results. Use when the user asks to produce more beats of the video "in parallel" or "in a batch".
---

# Orchestrate the video beats

The user explicitly asked for parallel sub-agents for this work (CLAUDE.md otherwise says not to spawn subagents unless asked). Use them only for this pipeline.

## The stages and the model each one runs on

All four stages run on **Haiku** (the user's decision on 2026-11-01: the first batch ran storyboarding and review on Sonnet and cost far too many tokens). What makes Haiku good enough is the constraint, not the model: a fixed recipe per stage, a compact plan format that a tool compiles (`compose-beat.js`), a short reading list, and gates that catch mistakes.

| Stage | Skill / agent | Model | What keeps it reliable |
|---|---|---|---|
| 1 prepare: align, brief, scaffold | `video-beat-prepare` | **Haiku** | three fixed commands (the aligner retries itself) |
| 2 storyboard: plan, compose, assets | `video-beat-storyboard` | **Haiku** | writes a short plan with "@word" cues; `compose-beat.js` derives indexes, text lists and sounds; the lint gates it; about 15 tool calls |
| 3 build: lint, render, check | `video-beat-build` | **Haiku** | fixed procedure, mechanical fixes only |
| 4 review (OFF by default) | `video-beat-review` | **Haiku** | the user dropped the review round on 2026-11-01 ("go with the first pass, I am fine with some mistakes"); run it only when the user asks for it for a beat |

Launch each stage as `Agent(subagent_type: "video-beat-<stage>", model: "haiku", description: "...", prompt: "<Stage> beat B#. Follow .claude/skills/video-beat-<stage>/SKILL.md.")`. Always pass `model: "haiku"` explicitly as well as the subagent type. **Escalation rule (the only exception):** if a stage has failed twice on one beat and the failure is a judgment problem (not a tool error), re-run that one stage for that one beat once on `model: "sonnet"`, tell the user it was escalated and why. Never run a stage on a bigger model by default.

**Pipeline now: prepare, storyboard, build. No review round.** (Reviews cost a lot of tokens for little gain; the hard-gate checks stay, but their failures are reported, not chased agent by agent.)

## Run a batch (for example B2, B3, B4, B5)

1. **Check the shared pieces first** (once per batch, by you): `node .claude/skills/video-visual-production/render/selftest-scenes.js` prints `all N scene types draw`; the scene types the batch needs exist (read each beat's plan section in `research/video-production/05-moser-baer-plan.md`; if a needed type is missing, build it in a new `render/scenes-*.js` file with an example in `EXAMPLES`, register it in `scenes.js`, regenerate the cheat sheet with `node render/make-plan-format.js`, and only then launch, because agents may not edit code).
2. **Stage 1, parallel, Haiku:** one agent per beat, all launched in a single message. They call Groq (rate limits are not confirmed: if one fails with a rate error, rerun it alone). Wait for all four. Read each report: a beat with under 85% matched words stops here and goes to the user.
3. **Stage 2, parallel, Haiku:** one agent per beat, single message. They read the brief, write the sheet, ledger and assets, and get the lint to zero. Read each report, `needs-B#.md` files and waivers. Decide what to do about gaps (usually accept the fallback and tell the user).
4. **Stage 3, parallel, Haiku:** one agent per beat, single message. The builds queue for two slots, so four launched together finish in about two rounds (about 10 minutes for four beats). Do not launch more than four builders at once.
5. **Stage 4 is skipped** unless the user asks. A beat whose check fails is delivered as built, with the failing rows listed; the orchestrator fixes defects that come from a scene type once in the scene code and rebuilds the affected beats itself (a plain `build-beat.js` run, cached), without an agent.
6. **Integrate (you):** read all reports; verify with your own eyes at least each beat's `contact-sheet.png` and the `Verdict` line in each `STATUS-video-B#.md`; run `git status` to confirm only beat files changed; add the finished beats to the memory note `project_video-production-phase` and `docs` if the user asked; list for the user: per beat the path of the MP4 and `REVIEW-B#.md`, hard-gate state, waivers, typeset fallbacks, gaps, interpolated cues, and what only they can judge. Do not call a video good.

Run beats in background-capable order: launch with `run_in_background: true` where the next step does not depend on the result, and you are notified when each completes. Never poll.

## File ownership (why parallel agents do not collide)

Each beat owns: `research/the-fall-of-moser-baer/video/{beat-sheet,ledger,timeline,lint,STATUS-video,REVIEW,brief,needs,credits,assets,edits}-B#.*`, `video/timing/words-B#.json`, `video/history/B#-*`, and `C:/video-build/moser-baer-v7-hinglish/B#/`. Nobody but you touches `render/*.js`, `scripts/*.js`, skills, `tools.md`, `history.md`, `CLAUDE.md`, memory or docs. Shared read-only: `reference-words.json`, `SCRIPT-v7*.md`, the audio.

## Limits on this machine

6 GB RAM with about 800 MB free: at most **two builds at once** (`VIDEO_BUILD_SLOTS`, enforced by `build-beat.js` with lock folders under `C:/video-build/.slots`; a crashed build's slot expires after 30 minutes, or delete the folder only if no build is running), at most four agents at once. Chrome capture runs inside the build slot or in the storyboarder's `assets.js` call (one at a time is fine; they use random ports).

## If an agent fails

Read its last message. Re-launch only that stage for only that beat, with the same model and the failure message in the prompt. After two failures on one beat, stop and tell the user. Never "fix" a gate by editing a rule.

## After the batch

Update `.claude/skills/video-script-production/references/tools.md` and `history.md` if tools changed (this is yours to do, not the agents'), the memory note, and the `needs-*.md` list. No commit unless asked. Then offer the next batch (B6 to B9, B10 to B13) and say which scene types they need that do not exist yet.