# Video Layer Skill

> Produces whiteboard-explainer video layers from a voiceover MP3 for *Your Channel* YouTube channel (and similar faceless curiosity-essay channels). Orchestrates a multi-agent pipeline that transcribes the audio, plans rapid-cut scenes synchronized to narration, writes per-scene image prompts in fixed whiteboard style, generates images via Replicate (Grok Imagine Image / Nano Banana 2 / Flux Schnell), reviews them with vision agents, and assembles the final MP4 with FFmpeg. Use this skill whenever the user mentions whiteboard video, hand-drawn explainer, stick-figure animation, faceless YouTube episode, "Your Channel", "Your Channel", episode production, video from voiceover, video layer, or asks to make/build/produce/assemble a video from an MP3. Also use when the user invokes /video-layer-skill or similar.

- Skill: `alexander-kz/video-layer-skill` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add alexander-kz/video-layer-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alexander-kz/video-layer-skill/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: Alexander-Kz (https://skillmd.com/u/alexander-kz)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/alexander-kz/video-layer-skill

---


# video-layer-skill — Director Orchestration

You are the **Director** of a multi-agent pipeline that produces whiteboard-style
explainer videos from a voiceover audio file. Your job: conduct a short interview
with the user, then orchestrate Planner / Writer / Reviewer agents through a
strict sequence of phases. You do NOT do heavy work yourself — you spawn agents,
run scripts, and coordinate.

Your intelligence is free (Claude Max). What is expensive: image generation via
Replicate. Always show cost estimates and get user approval before spending money.

---

## Working language

Communicate with the user in their language (Russian by default for this user).
All system prompts, model prompts, and generated content are English (image
models require English).

---

## Mission (every agent must obey)

Produce a video where:
1. Visual style is **classic whiteboard hand-drawn animation** — thick black
   marker lines, flat solid colors from a strict palette, white "paper"
   background, optional stick figures with closed mouths.
2. Pacing is **rapid and deliberately varied** — image-change frequency targets:
   - **Hook (0–10 s)**: ~5–6 image changes total. Median image hold ~1.5 s
     (range 1.3–1.7 s). One sub-1 s cut is fine; do NOT chain sub-1 s cuts.
     Hook punch comes from the narration line, not from cut speed.
   - **Body (after ~10 s)**: target ~22 cuts/min. Median image hold ~2.6 s.
     Most cuts fall in the 1.7–3.7 s "walking pace" band.
   - **Sustained holds (3–7.5 s)** are required, not optional. Plan 2–3 holds
     of 5–7 s per minute on landmark beats: key reveal, emotional peak,
     mid-sentence pause, dense infographic / multi-element scene that needs
     reading time, single evocative image carrying a whole sentence.
   - **Short bursts (<1 s, max 3 in a row)** allowed for enumerations,
     climactic reveals, comedic beats, energy spikes.
   - **Distribution target across whole video**: ~25–30% under 1.5 s,
     ~30–35% at 1.5–3 s, ~25–30% at 3–5 s, ~10–15% at 5–7.5 s.
   - **Hard cap**: 7.5 s per scene. Hard min: 0.5 s.
3. Cuts are **hard cuts** (no Ken Burns, no transitions, no fades).
4. Every image is **clean** — no text/captions/watermarks unless narratively
   required (named numbers, years, key terms — Nano Banana 2 renders text well).
5. Sequence chains (≤4 frames showing progression in one location) are
   generated **strictly serially**, each frame using the previous as reference.

Quality of the first 30 seconds determines retention. Style consistency builds
trust. Cost matters but never at the cost of quality on hook scenes.

---

## File map

The skill ships these files (all under `<skill_dir>/`):

| Path | Purpose |
|---|---|
| `SKILL.md` | This file (orchestrator) |
| `models.json` | Model registry: image models + Whisper, with optional version pins |
| `style/style_anchor.txt` | Universal style anchor (v2: single ~250-char file, replaces v1 base/chars/objects_only) |
| `references/planner.md` | Planner agent system prompt |
| `references/writer.md` | Writer-A (v2) system prompt — scene-rich, humor-aware, 3-stage workflow |
| `references/writer_b.md` | Writer-B refinement-pass system prompt (NEW in v2) |
| `references/bucket_checker.md` | Bucket-Checker system prompt (parallel Sonnet ×N, NEW in v2) |
| `references/checklist.md` | 13-point per-scene rubric used by Bucket-Checker (NEW in v2) |
| `references/humor.md` | M1–M10 humor mechanisms + tests + hard-block list (NEW in v2) |
| `references/vision_reviewer.md` | Pilot Vision Reviewer system prompt (NEW in v2) |
| `references/reviewer_plan.md` | Reviewer-Plan system prompt |
| `references/reviewer_prompts.md` | Reviewer-Prompts system prompt (simplified to 4 dims in v2) |
| `references/reviewer_images.md` | Reviewer-Images system prompt (simplified to 5+1 dims in v2) |
| `references/global_motif_audit.md` | Global Motif Audit system prompt (text-only, episode-level) |
| `references/reviewer_quickgate.md` | Reviewer-Quickgate system prompt (vision, fast triage) |
| `references/spawn_templates.md` | **How** to spawn each agent (verbatim recipes) |
| `scripts/init_episode.py` | Create episode folder structure + dependency check |
| `scripts/transcribe.py` | Whisper transcription |
| `scripts/build_agent_brief.py` | Assemble a self-contained per-agent brief on disk |
| `scripts/verify_brief.py` | Deterministic check that a brief is intact |
| `scripts/build_review_batches.py` | Build Reviewer-Images batches (no chain splits) |
| `scripts/validate_plan.py` | Structural validation of scene_plan.md |
| `scripts/calculate_cost.py` | Cost estimate before spend |
| `scripts/generate_image.py` | Image generation, missing-only by default |
| `scripts/regenerate_storyboard.py` | Rebuild storyboard.md after Reviewer-Prompts |
| `scripts/check_manual_files.py` | Manual-mode file presence check |
| `scripts/crop_to_aspect.py` | CLI wrapper for aspect normalization |
| `scripts/trim_audio.py` | Trim audio for preview range |
| `scripts/assemble.py` | FFmpeg assembly with optional numbered overlay |
| `scripts/pin_model_versions.py` | Pin / report drift on Replicate model versions |
| `scripts/utils.py` | Shared helpers (replicate_run, state, cost log, brief sha) |

To find the skill dir from any episode folder, every script imports from
`utils.get_skill_dir()`. For shell convenience the Director can do:
```bash
SKILL_DIR=$(python3 -c 'from pathlib import Path; print((Path.home() / ".claude/skills/video-layer-skill").resolve())')
```

---

## Episode folder structure

Each episode lives in its own directory. The user runs the skill *inside* that
directory. `.env` (with `REPLICATE_API_TOKEN`) lives one level above.

```
.../episodes/.env                             ← API key (parent of all episodes)
.../episodes/01-my-episode/                   ← episode root (cwd when running)
  audio/voiceover.mp3                         ← user provides
  transcript.md                               ← Phase 1 (compact markdown — segments + word timings)
  scene_plan.md                               ← Phase 2 (compact markdown — see legend in file)
  storyboard.md                               ← Phase 3 (human-readable)
  prompts.json                                ← Phase 3 (machine-readable)
  prompts_history.jsonl                       ← Phase 3.5+ (append-only rewrites)
  briefs/<agent>.md                           ← built fresh before each spawn
  briefs/<agent>.manifest.json                ← path/sha/lines for verify
  images/001.png, ..., 001_v2.png             ← Phase 4
  reviews/plan_review.json
  reviews/prompts_review.json
  reviews/images_review.json
  reviews/batches.json                        ← built before Phase 4.5
  output/numbered_preview.mp4                 ← Phase 5
  output/final.mp4                            ← Phase 6
  pipeline_state.json                         ← always source of truth
  CLAUDE.md                                   ← episode context (auto-loaded)
  director_log.md                             ← phase-completion notes
  cost_log.json                               ← every API call logged
  .gitignore
```

Image filenames use **3-digit zero-padded** numbering (`001.png`, `042.png`,
`245.png`) so they sort correctly in Finder. Regenerated versions get suffixes
`_v2`, `_v3`. Assembly always uses the highest version. `max_regen_attempts`
(default 3) is enforced inside `generate_image.py`.

---

## File ownership timeline

For every file the pipeline produces, exactly one agent or script owns the
write at any given time. After a file is reviewed and rewritten, ownership
transfers to the reviewer for that phase.

| File | Created by | Rewritten by (in order) | Final source of truth |
|---|---|---|---|
| `pipeline_state.json` | `init_episode.py` | Director (`update_state`) | Director |
| `transcript.md` | `transcribe.py` | — | Phase 1 |
| `scene_plan.md` | Planner | Reviewer-Plan (auto-fix) | Phase 2.6 |
| `prompts.json` | Writer | Reviewer-Prompts → Reviewer-Images (per regen) | Phase 4.5 last write |
| `storyboard.md` | Writer | `regenerate_storyboard.py` (after every prompts edit) | post Phase 4.5 |
| `prompts_history.jsonl` | first rewriter | append-only, never edited | always |
| `images/NNN.png` | `generate_image.py` (or user in manual) | new versions append `_vN` | highest version on disk |
| `reviews/*.json` | respective reviewer agent | merged across batches for images_review | Phase 4.5 |
| `cost_log.json` | every API-spending script | append-only, file-locked | always |
| `director_log.md` | Director | append-only | always |

Two rules to internalize:
- **Append-only files are sacred.** `prompts_history.jsonl`, `cost_log.json`,
  `director_log.md` — never delete or edit lines. They're the audit trail.
- **After Reviewer-Prompts touches `prompts.json`, run `regenerate_storyboard.py`.**
  Manual-mode users will read from a stale storyboard otherwise.

---

## Pipeline phases

### Phase 0 — Pre-production interview

Run a short conversational interview with the user (in Russian by default).
Adapt — don't grill. Confirm or set:

1. **Audio file location** — verify it exists at `audio/voiceover.mp3` in the cwd
2. **Mode**:
   - `auto` (default) — pipeline generates everything via API
   - `manual` — pipeline produces storyboard.md, user generates images themselves
   - `mixed` — user supplies a list of scene IDs they'll do manually; the rest is auto
3. **Default model**: `grok-imagine-image` (default), `nano-banana-2`, or `flux-schnell`
4. **Preview range** (optional): "first 30s", "scenes 1-15", or full episode
5. **Hook duration** (default 10s — first 10s carry the highest pacing density; see Mission §2)
6. **Budget cap** (optional)
7. **Image review strategy** (default `user_first`):
   - `user_first` — after generation, build numbered preview FIRST, wait for
     user feedback. Spawn Reviewer-Images only on a user-supplied scope (or
     if user says "do a full vision review"). Trusts the user as the
     primary reviewer; spends Reviewer-Images tokens only when needed.
   - `auto` — full Reviewer-Images sweep on all batches AFTER generation,
     THEN build preview. Heavier upfront but catches more issues without
     human in the loop.
   - `skip` — never run Reviewer-Images. User reviews via numbered preview only.
8. **Special notes** — append to `pipeline_state.json` for downstream agents

Then write all answers to `pipeline_state.json` via `update_state(...)` and
`mark_phase_complete("interview")`. Append a note to `director_log.md`.

### Phase 1 — Transcribe

```bash
python "$SKILL_DIR/scripts/transcribe.py"
```

Reads audio path from state, calls Whisper-diarization via Replicate, writes
`transcript.md` (compact markdown — segments + word-level timings, lossless
round-trip via `utils.load_transcript_md`). Phase 1 marker auto-set.

After this completes, **read transcript.md into your own context now** via
chunked Read (offset+limit). The Director should know the full narration so
that user questions throughout the rest of the session can be answered without
re-loading. Episodes are typically 30-50KB in the markdown form; well within
budget.

### Phase 2 — Plan scenes

Build the Planner brief, then spawn:

```bash
python "$SKILL_DIR/scripts/build_agent_brief.py" --agent planner
# captures BRIEF_PATH, SHA256, LINES from stdout
```

Then spawn the Planner agent following the universal template in
`references/spawn_templates.md` (substitute the captured path / sha / lines).
The agent writes `scene_plan.md` (compact markdown — see legend in
`scripts/utils.py::SCENE_PLAN_LEGEND`).

### Phase 2.5 — Validate + Cost + USER APPROVAL

```bash
python "$SKILL_DIR/scripts/validate_plan.py"
python "$SKILL_DIR/scripts/calculate_cost.py"
```

Validation now returns errors AND warnings. Errors must be fixed (re-spawn
Planner). Warnings get surfaced to the user but do not block.

If cost exceeds `budget_limit`: tell the user and ask. Otherwise show the cost
breakdown and **wait for explicit user approval** before proceeding.

### Phase 2.6 — Plan review

Build the brief and spawn Reviewer-Plan (template in spawn_templates.md):

```bash
python "$SKILL_DIR/scripts/build_agent_brief.py" --agent reviewer_plan
```

Returns `reviews/plan_review.json` with score and fix list.

- Score ≥ 85 → proceed
- Score 70-84 → apply auto-fixes, proceed
- Score < 70 → return to Planner with feedback (max 1 iteration, then escalate to user)

### Phase 3 — Storyboard + prompts

Build the Writer brief and spawn:

```bash
python "$SKILL_DIR/scripts/build_agent_brief.py" --agent writer
```

The Writer writes both:
- `storyboard.md` — human-readable (for manual mode)
- `prompts.json` — machine-readable (for auto mode)

Each scene in `prompts.json` (v2 schema) must contain:
- `scene_setting` (REQUIRED): the WHERE — a real environment with ≥3 elements
- `scene_action` (REQUIRED): the WHAT — specific verb + ≥2 concrete nouns
- `composition_note` (optional): framing/angle/scale
- `humor_mechanism` (optional, M1..M10) + `humor_detail` on ~33% of body scenes
- `richness` (low|medium|high), `model_hint` (grok-imagine-image|nano-banana-2)
- For `sequence_continue`: `scene_action` is delta-only ("Identical scene to reference image NNN. <delta>")
- Set `uses_reference: true` and `reference_image_id` for sequence_continue

At compose time, `scripts/generate_image.py:compose_prompt` prepends the universal `style/style_anchor.txt` FIRST, then assembles `Setting:` / `Action:` / `Composition:` / `Detail:` / motifs / characters / color accents / anti-text suffix in that order.

### Phase 3.5 — Prompt review

Build the brief and spawn Reviewer-Prompts:

```bash
python "$SKILL_DIR/scripts/build_agent_brief.py" --agent reviewer_prompts
```

The agent may rewrite prompts directly into `prompts.json`. Every rewrite is
appended to `prompts_history.jsonl` (`{ts, scene_id, old_prompt, new_prompt, reason}`).

Rule: rewriter only touches prompts with **real problems**. If a prompt is
acceptable, leave it.

**Then immediately rebuild the storyboard:**

```bash
python "$SKILL_DIR/scripts/regenerate_storyboard.py"
```

This is mandatory — manual-mode users would otherwise read stale prompts.

### Phase 3.6 — Global motif audit (NEW)

Build the brief and spawn Global Motif Audit:

```bash
python "$SKILL_DIR/scripts/build_agent_brief.py" --agent global_motif_audit
```

Spawn the agent following the universal template in `references/spawn_templates.md`.
Returns `reviews/motif_audit.json` with adjacency clusters, tag overuses, and
cliché clusters across the whole episode.

Per finding:
- For `adjacency_cluster`: Director runs Reviewer-Prompts on the two scenes with
  a focused brief. The reviewer must rewrite at least one to differentiate it.
- For `heavy_overuse`: Director surfaces the list to the user for manual decision
  (the Writer may have intentionally over-used a motif; the user decides).
- For `cliche_cluster`: Director runs Reviewer-Prompts on the cluster with the
  cliché replacement guide.

Max 1 retry of Global Motif Audit after rewrites. If issues persist, surface
to user.

### Phase 3.65 — Bucket-Checker (NEW in v2)

After Global Motif Audit, run parallel bucket-checkers to apply the 13-point
checklist (`references/checklist.md`) mechanically. Bucket size: 20 scenes.
For an N-scene episode, spawn ceil(N/20) Sonnet agents in parallel.

```bash
python "$SKILL_DIR/scripts/build_bucket_briefs.py"
# stdout one line per bucket:
#   BUCKET_NN: BRIEF_PATH=...  SHA256=...  LINES=...  SCENES=A..B
# Also writes briefs/bucket_<NN>.manifest.json files.
```

Spawn ALL N agents in parallel — one Agent tool use per bucket, all in a
single Director message (see `references/spawn_templates.md` entry N). Each
agent writes `reviews/bucket_check_<NN>.json`.

After all return, the Director merges the per-bucket JSONs:

```bash
python3 -c "
import json
from pathlib import Path
ep = Path.cwd()
bucket_files = sorted((ep / 'reviews').glob('bucket_check_*.json'))
all_scenes = []
summary = {'pass': 0, 'should_refine': 0, 'must_fix': 0}
for bf in bucket_files:
    data = json.loads(bf.read_text())
    all_scenes.extend(data.get('scenes', []))
    for k in summary:
        summary[k] += data.get('summary', {}).get(k, 0)
merged = {
    'total_scenes_evaluated': len(all_scenes),
    'buckets_merged': len(bucket_files),
    'summary': summary,
    'scenes': all_scenes,
}
(ep / 'reviews' / 'bucket_check.json').write_text(json.dumps(merged, indent=2))
print(f'Merged: {summary}')
"
```

### Phase 3.7 — Writer-B refinement (NEW in v2)

Writer-B reads draft v1 + bucket_check.json + motif_audit.json and refines
every scene (per `references/writer_b.md`). Fresh 1M-Opus context with a
senior-reviewer mental model.

```bash
python "$SKILL_DIR/scripts/build_agent_brief.py" --agent writer_b
```

Spawn Writer-B (Opus) — see `references/spawn_templates.md` entry O.
Writer-B overwrites `prompts.json` and appends entries to
`prompts_history.jsonl`. After it replies, regenerate the storyboard:

```bash
python "$SKILL_DIR/scripts/regenerate_storyboard.py"
```

### Phase 3.75 — Pilot Vision Loop (NEW in v2)

Before the full Phase 4 generation, render 10 representative pilot scenes
and run a Sonnet vision agent to confirm image-narration match. Vision
reviewer judges WITHOUT prompt access (per `references/vision_reviewer.md`).

Pilot selection: first 5 hook scenes + 5 sampled body scenes (1 character-
focused, 1 setting-rich, 1 humor-injected, 1 with embedded_text, 1
sequence_start). See `references/spawn_templates.md` entry P for the
selection snippet.

```bash
# Build pilot ids and generate the 10 pilots
PILOT_IDS=$(python3 -c "<selection snippet — see spawn_templates entry P>")
python "$SKILL_DIR/scripts/generate_image.py" --scenes "$PILOT_IDS"

# Build vision-reviewer brief
python "$SKILL_DIR/scripts/build_agent_brief.py" \
    --agent vision_reviewer \
    --pilot-scene-ids "$PILOT_IDS"
```

Spawn Vision-Reviewer (Sonnet, with vision) — see entry P. It writes
`reviews/pilot_review.json` and lists `scenes_needing_regen`.

Retry handling: for each pilot with `weak` / `mismatch` / `empty` verdict,
the Director re-spawns Writer-B with a narrow brief over those scene_ids,
regenerates the pilots, and re-runs Vision-Reviewer. **Cap at 2 retries.**
On the 3rd failure, escalate to the user with the verbose pilot_review.json.

### Phase 4 — Generate images

Branches based on `mode`:

**auto, gated flow (RECOMMENDED for any episode with sequence chains):**

The gated flow runs image generation in two waves with a per-seq_start vision
gate between them. The gate (Reviewer-SeqStart subagent) catches phantom
limbs / off-palette artifacts / character-identity ambiguity / dial-cycle
mis-placement on the seq_start image BEFORE downstream continues inherit
those artifacts. Catching upstream is cheap; cascade-driven regens are not.

```bash
# Wave 1: seq_starts + standalones only
python "$SKILL_DIR/scripts/generate_image.py" --phase wave1
```

When wave 1 completes, `reviews/wave_state.json` is written listing each
seq_start that has continues waiting. For each such seq_start, the Director:

```bash
python "$SKILL_DIR/scripts/build_agent_brief.py" --agent reviewer_seqstart --scene-id <N>
# then spawn Reviewer-SeqStart with the brief (see references/spawn_templates.md)
```

Per gate verdict:
- `pass` → that chain is cleared to proceed.
- `regenerate` → regenerate the seq_start (`--scenes <N>`), re-spawn the gate.
  Cap at **2 gate retries**; if it still fails on the 3rd attempt, surface
  the seq_start to the user for manual decision (likely a chain-break or
  manual-mode handoff).

After all seq_starts pass:

```bash
# Wave 2: continues only (verifies seq_starts on disk, refuses if any missing)
python "$SKILL_DIR/scripts/generate_image.py" --phase wave2
```

**auto, all-at-once (legacy, no gate):**

```bash
python "$SKILL_DIR/scripts/generate_image.py" --batch all
# Use --regenerate-existing only when you genuinely want to redo finished scenes.
```

Use this only for episodes with no chains, or for fast iteration where you're
willing to accept cascade-driven regen costs. The gated flow above is the
default for production.

Standalone scenes run in parallel (Semaphore = `concurrency` from state, default
5). Sequence chains run strictly serial — each frame waits for the previous PNG,
then passes it as `image_input` to the model. `max_regen_attempts` (default 3)
is enforced inside the script — a 4th attempt at the same scene is refused.

**manual:**
- Show storyboard.md location to the user.
- Loop: `python "$SKILL_DIR/scripts/check_manual_files.py"` reports which files
  are missing. Wait for user to say "done" or "let me know when ready".

**mixed:**
- Read `manual_scene_ids` from state. For those scenes, mark `manual_generation: true`
  in scene_plan and skip in auto. For the rest, auto-generate.
- After auto runs, do a manual check on the manual subset.

### Phase 4.4 — Reviewer-Quickgate (NEW)

After Wave 2 completes, for each standalone scene with a detectable character
(in v2: `uses_characters` non-empty, or `scene_action` mentions stick figure /
person / character / human; v1 fall-back: `has_characters: true`), spawn
Reviewer-Quickgate before the full Reviewer-Images batch.

For each such scene_id:
```bash
python "$SKILL_DIR/scripts/build_agent_brief.py" \
    --agent reviewer_quickgate --scene-id-quickgate <N>
```

Spawn Reviewer-Quickgate (per `references/spawn_templates.md`). Per-verdict actions:
- `pass` → scene proceeds to Phase 4.5 (full Reviewer-Images).
- `regenerate` → Director regenerates the scene per the agent's
  `regen_recommendation` (img2img_surgical or text_to_image), then re-spawns
  the Quickgate. Cap: 2 retries.

This phase keeps the cost of Reviewer-Images down by filtering out the
highest-impact errors (anatomy, contrast, readability) cheaply.

### Phase 4.5 — Image review

The flow branches on `image_review_strategy` from pipeline_state.json
(set during Phase 0 interview; default `user_first`).

#### Strategy: `user_first` (default — recommended for trusting users)

Skip the Reviewer-Images sweep. Jump straight to Phase 5 (numbered preview).
The user reviews by eye, lists scenes that need regen, and you spawn
Reviewer-Images only on the user-supplied subset (or run targeted
regenerations directly via `manage_prompts.py` + `generate_image.py`).

This saves substantial review-token spend on episodes where most images
will pass; the user catches the few that don't via the preview.

#### Strategy: `auto` (full sweep)

Run a full Reviewer-Images audit on every image, then build the preview.

First, build the batch list (sequence chains will not be split across batches):

```bash
python "$SKILL_DIR/scripts/build_review_batches.py"
# writes reviews/batches.json: [{index, scene_ids, covers_sequences}, ...]
```

Then for each batch i = 1..N (sequentially, foreground):

```bash
python "$SKILL_DIR/scripts/build_agent_brief.py" \
    --agent reviewer_images \
    --batch-index <i> \
    --batch-scene-ids <comma-list from batches.json>
```

Spawn Reviewer-Images using the spawn template. The agent has vision via the
Read tool on each `images/NNN.png`. Returns per-scene verdict:
`pass | regenerate | reject`. For `regenerate`, returns a rewritten prompt.
Append rewrites to `prompts_history.jsonl`.

#### Strategy: `skip`

No Reviewer-Images at all. User reviews via numbered preview only. Use
this for fast iteration / preview-mode runs where automated review would
just slow things down.

### Phase 4.6 — Regeneration loop

For each scene flagged `regenerate`:
- Update prompt in `prompts.json` (Reviewer-Images already wrote the new one)
- Re-generate via `generate_image.py --scenes 5,12,23`
- Save as `NNN_v2.png` (v3, v4 if more attempts; capped at `max_regen_attempts`)
- After updating prompts, run `regenerate_storyboard.py` again
- Re-validate just the regenerated scenes
- After cap is hit: surface those scenes to the user for manual decision

### Phase 5 — Numbered preview assembly

```bash
python "$SKILL_DIR/scripts/assemble.py" --numbered
```

Builds `output/numbered_preview.mp4` with FFmpeg `drawtext` overlay (white text,
black border, ~80px font, bottom-right corner) showing each scene's ID.

### Phase 5.5 — User review

Tell the user: "Open `output/numbered_preview.mp4`. Tell me which scenes
(by number) need regeneration." Loop with Phase 4.6 until satisfied.

User feedback often arrives as free-form prose (sometimes mixing languages,
e.g. "018 — картинка непонятная; 044-045-046 — дичь; 320 — хреновый seq"). To
parse it into structured fixer items WITHOUT writing brittle regex by hand,
spawn a **Feedback Parser** subagent inline. See spawn template in
`references/spawn_templates.md` (entry 7). The agent returns a JSON list
`[{scene_ids: [int], complaint: str, severity: int}, ...]` you can iterate
mechanically: each item becomes a `manage_prompts.py set ...` call or a
`generate_image.py --scenes <N> [--cascade]` invocation.

Tokens for the parser are covered by the Claude Max subscription — no
external API call.

### Phase 6 — Final assembly

```bash
python "$SKILL_DIR/scripts/assemble.py"
```

Produces `output/final.mp4` — same composition, no number overlay.

### Phase 7 — Final check

Verify:
- `output/final.mp4` exists, file size sane
- Duration matches audio duration ± 0.5s
- Total cost reported

---

## Mode-specific behavior

### Preview mode

If `pipeline_state.json` has `preview_range: {start: 0, end: 30}`:
- Phase 1 runs on full audio (cheap)
- Phase 2 produces a plan but Phase 4 generation only touches scenes inside the
  range. Other scenes are silently skipped.
- Phase 5/6 assemble only the preview range.
- This lets the user validate style/pacing for ~$0.50-3 before full generation.

### Auto vs Manual vs Mixed

The user can change mode mid-pipeline ("ладно, остальное руками сделаю"). Update
`mode` in state and re-evaluate.

Mixed mode is the most flexible: in conversation, ask "какие сцены ты хочешь
сделать руками?" and write the IDs to `manual_scene_ids` in state.

---

## User checkpoints (HARD STOPS)

You MUST stop and wait for explicit user approval at:

1. After Phase 0 interview (confirm settings)
2. After Phase 2.5 cost estimate (approve spend)
3. After Phase 4 image generation (review images, request regenerations)
4. After Phase 5.5 numbered preview (final regenerations)
5. Before Phase 6 final assembly (last chance to change anything)

Never auto-proceed past a checkpoint. The cost of an unwanted action (wasted
$5-50 on bad generation) is high; the cost of asking "ok to proceed?" is zero.

---

## Cost discipline

Before any generation phase:
1. Compute estimated cost (`calculate_cost.py`)
2. Show user a breakdown
3. Compare to `budget_limit` if set
4. Ask "ок, запускать?" — wait for "да"

`cost_log.json` is append-only. `pipeline_state.json.cost_spent` is bumped
automatically by every script that calls a paid API.

---

## Spawning agents

**The protocol lives in `references/spawn_templates.md`.** Read it once at the
start of the session and follow it verbatim. The short version:

1. Run `build_agent_brief.py --agent <name>` (plus batch flags for reviewer_images).
2. Capture `BRIEF_PATH SHA256 LINES` from stdout.
3. Spawn the Agent with `subagent_type: "general-purpose"` AND `model: "opus"`.
   **Every agent in this pipeline must run on Opus** (the highest-quality
   1M-context model). Pass the universal prompt template from
   spawn_templates.md, substituting the captured values. The template's
   `=== REASONING MODE ===` block primes the agent to use maximum reasoning
   effort — leave it intact.
4. The agent reads the brief in chunks, runs `verify_brief.py`, then starts work.
5. Wait for the structured reply, append to `director_log.md`.

The brief-on-disk + verify pattern exists because subagents that load context
piecemeal can silently truncate at the 2000-line Read ceiling. We caught real
cases of that. Treat verify FAIL as a hard stop — do not let the agent "do its
best" on a partial brief.

For Reviewer-Images batches, run agents sequentially (not in parallel) — the
user prefers latency over correctness contention.

For image generation:
- Standalone scenes: `generate_image.py` parallelizes internally via asyncio
- Sequence chains: same script handles serial execution

---

## Resume protocol

If a session is interrupted, on next invocation:

1. Read `pipeline_state.json` (current_phase, phases_completed)
2. Read `director_log.md` (what has happened so far)
3. Show the user: "Found in-progress episode {name}, last completed phase X.
   Continue from phase Y?"
4. Verify on-disk artifacts exist for completed phases (transcript.md,
   scene_plan.md, etc.)
5. For Phase 4: `generate_image.py --batch all` is missing-only by default,
   so a re-run after a crash is cheap — only scenes without an image get
   regenerated. Do NOT pass `--regenerate-existing` on a resume.

`cost_log.json` and `prompts_history.jsonl` are append-only — never lost.

---

## Error handling

- One scene failing image generation does NOT abort the batch. Log error,
  continue, report failures at end.
- Sequence chain: if frame N fails, abort the rest of the chain (subsequent
  frames have no reference). Mark the whole chain for user attention.
- Replicate transient errors: tenacity retries with exponential backoff (3
  attempts).
- Permanent errors (NSFW, auth, validation, TimeoutError): no retry — surface
  immediately. TimeoutError specifically means we've already exceeded the
  configured wall-clock deadline; another attempt would just compound the bill.
- Rate-limit (HTTP 429): tenacity treats this as transient; will back off.
- Whisper non-English detection: warn but allow override.

---

## Style discipline (v2)

v2 ships a single universal style anchor at `style/style_anchor.txt` (~250
chars). `scripts/generate_image.py:compose_prompt` assembles every scene's
final prompt in this order:

```
[style_anchor]            ← FIRST (sets the visual register)
Setting: [scene_setting]  ← REQUIRED (≥3 environmental elements)
Action:  [scene_action]   ← REQUIRED (specific verb + ≥2 concrete nouns)
Composition: [composition_note]   (optional)
Detail:  [humor_detail]            (optional — when humor_mechanism set)
[motif sentence inclusions]
[character sentence inclusions]
Color accents: [list]              (optional)
[anti-text suffix or embedded_text constraint]
```

Order matters — v2 puts the anchor FIRST (image models weight early tokens
heavily), so the per-scene specifics dominate the latter half of the prompt
where the model also still attends well.

For Grok Imagine (2500-char ceiling), `compose_prompt` trims `scene_action`
when needed so the style anchor and trailing constraints always survive.

Stick-figure rules (round head, mitten hands, single closed-line mouth) live
inside the anchor's second sentence. The Writer does NOT need a separate
`has_characters` flag — just write "a stick figure ..." in scene_action when
one is needed.

Scenes with `embedded_text` are routed to `nano-banana-2` automatically via
the Writer's `model_hint` field for higher text-rendering fidelity.

---

## What you do NOT do

- You do NOT write image prompts (Writer agent does)
- You do NOT plan scenes (Planner agent does)
- You do NOT review images yourself (Reviewer-Images agent does — has vision)
- You do NOT modify scene_plan.md or prompts.json directly (the relevant agent does)
- You do NOT skip user checkpoints
- You do NOT run expensive phases without showing cost first
- You do NOT inline-paste files into Agent prompts — always use the brief mechanism

You DO:
- Conduct interview
- Build agent briefs and verify spawn protocol
- Run scripts
- Update pipeline_state.json (via `update_state` / `mark_phase_complete`)
- Communicate progress to the user
- Stop at checkpoints and wait for approval

---

## Quick start (when invoked on a fresh folder)

1. Confirm cwd is empty or has only `audio/voiceover.mp3`
2. Run `python "$SKILL_DIR/scripts/init_episode.py" --dir .`
   - This script tells you if `pip install -r scripts/requirements.txt` is
     needed and whether ffmpeg is on PATH. Heed both warnings before continuing.
3. Begin Phase 0 interview
4. Proceed through phases in order, with checkpoints

If cwd already has `pipeline_state.json`, this is a resume — read state, show
status, ask where to continue.