Storybook Pipeline

Storybook Pipeline (Orchestrator)

The runbook for turning one English story into a finished, self-contained HTML storybook. It does no creative work itself — it dispatches the 4 component skills in order, with the right artifact paths, and locks the filename convention so every output pairs cleanly by scene index.

It exists so that in a fresh session, "make a storybook from this story" has a single entry point — no need to remember the 4 skills, their order, or the filename conventions.

When this skill applies

The user has an English story (typically in stories/) and wants the full output: scenes + images + audio + a single HTML storybook. Common phrasings:

• "run the pipeline on stories/the-little-cloud.md"
• "make a storybook from this story"
• "turn this into an illustrated storybook"
• "build the storybook end to end"

Does NOT apply to:

• Single-step requests — if they only want images, invoke story-illustrator; only audio, story-narrator. The orchestrator is for the full chain.
• Re-running after partial completion — if some artifacts exist, detect them and resume from the next missing step; don't blindly overwrite. Ask if unsure.

Pipeline order (LOCKED)

input:  stories/{slug}.md
1. scene-splitter         → {slug}_scenes.json
2. story-illustrator      → {slug}_bible.md, {slug}_shotlist.md, {slug}_images.json
3. story-narrator         → {slug}_audio/{slug}_part_NN.mp3 (+ manifest.json, optional title.mp3)
4. story-html-publisher   → {slug}_story.json + {slug}.html   ← the deliverable

Steps 2 and 3 both read {slug}_scenes.json and are independent — but in an interactive session run them in order so the user reviews each at its own gate.

Slug + filename convention (LOCKED)

The slug is derived from the story title or filename: lowercased, hyphenated, ASCII-safe (^[a-z0-9-]+$, max 60 chars). Every artifact shares it. All artifacts live in stories/{slug}/; the raw .md stays at stories/ (it's the trigger, not an artifact). See CLAUDE.md for the full filename table.

Workflow — five dispatch stages

Stage 0: Intake

1. Identify the story file (explicit argument → the single new *.md in stories/ → ask).
2. Determine the slug. Read line 1 (the # Title) + the filename; propose a slug. One-line confirm: "Slug: the-little-cloud. OK?" — proceed on go. (HARD GATE — locks the slug into every artifact.)
3. Create the working dir stories/{slug}/. All sub-skills output there.
4. Detect completed stages. Glob for stories/{slug}/{slug}_scenes.json, _images.json, etc. If any exist, list them and ask: skip those stages or redo? Default = skip completed.
5. Check for the QA flag. If the user said "with QA" / "--qa", note qa_enabled = true for the illustrator. Default OFF.
6. Ask the image aspect ratio AND model up front — HARD GATES. Don't wait until Stage 2; settle both now so the long stages run uninterrupted:

   "What aspect ratio? 4:5 portrait (storybook / phone — the default), 1:1 square, 3:4 book page, or 16:9 widescreen." "Which image model? nano-banana-2 (fast & cheap, ~$0.08/img), nano-banana-pro (best for multi-character, ~$0.15/img), Smart mix (pro only for multi-character beats — suggested), or seedream-4 (cheapest, ~$0.03/img). See image-models.json." Lock them as aspect_ratio and the model choice and pass both to the illustrator at Stage 2. Ask — do not infer. Aspect ratio locks into every image; both gates spend money. They pause even under an auto-mode reminder.

7. Pre-flight checks: stories/ is writable; FAL_KEY is resolvable (python .claude/skills/story-illustrator/assets/fal_image.py --check — re-checked at Stage 2); the ElevenLabs MCP is connected (re-checked at Stage 3); and the user has (or will provide) an ElevenLabs voice_id for the narrator.

Stage 1: Dispatch scene-splitter

Invoke scene-splitter with the story path, the slug, and output dir stories/{slug}/. The user approves the scene plan at its hard gate. Output: {slug}_scenes.json — the spine for stages 2 + 3.

Stage 2: Dispatch story-illustrator

Invoke story-illustrator with:

• stories/{slug}/{slug}_scenes.json and the slug
• A style hint from the story's tone (e.g. "warm soft watercolor children's-book illustration" for a gentle beginner story)
• Pre-locked aspect ratio + model from Stage 0: "Aspect ratio: {aspect_ratio} (already chosen, do not re-ask). Image model: {model choice} (already chosen, do not re-ask)."
• If qa_enabled, add "with QA"
• A note: "Generate one image per scene, indexed to match scenes.json. Save {slug}_bible.md, {slug}_shotlist.md, {slug}_images.json to stories/{slug}/."

The illustrator's own aspect-ratio and model prompts are skipped because the orchestrator pre-supplied both. The user approves the bible (Stage 2 gate — remind them to verify child-safe character designs before approving, since fixing after generation costs a regen per image), the references, and the shot list / images. Each image costs money (Fal) — these are hard gates.

Stage 3: Dispatch story-narrator

Invoke story-narrator with:

• stories/{slug}/{slug}_scenes.json and the slug
• A note: "One MP3 per scene, saved as {slug}_part_NN.mp3 in stories/{slug}/{slug}_audio/. Detect scenes.json and skip your own splitting."
• The ElevenLabs voice_id if known (else the narrator asks once)

The user approves the narration script at the narrator's hard gate (each TTS call is billed). Output: {slug}_audio/ with N MP3s + manifest.

Stage 4: Dispatch story-html-publisher

Invoke story-html-publisher with the slug. It discovers the artifacts automatically, runs the build script, and writes {slug}_story.json + {slug}.html. The user reviews the finished storybook at its hard gate and replies done.

Stage 5: Final summary

One-screen summary:

• Artifacts produced (with paths) — ending with the headline: stories/{slug}/{slug}.html
• Total cost: Fal images (~$X, from the per-scene models) + ElevenLabs narration
• "Open stories/{slug}/{slug}.html in your browser to read the finished storybook."

Gates — preserved, not bypassed

This orchestrator does NOT auto-approve gates. Gates pause regardless of any auto-mode / "work without stopping" reminder — that reminder applies to read-only work, not to gates that spend money or commit a creative choice.

If the user wants to fully automate (skip gates), that's their call to make explicitly — the orchestrator never decides it.

Failure modes

• Story file not found → stop at Stage 0, list stories/, ask which file.
• Slug already has artifacts → list them, ask skip/replace, default skip (resume).
• A sub-skill returns redo → re-invoke that skill with the corrective input; don't re-run upstream stages.
• FAL_KEY missing (Stage 2) or ElevenLabs MCP unavailable (Stage 3) → surface the error, suggest setup (README). The publisher can build a partial storybook if only one medium is missing — but ask first.

What this skill does NOT do

• Does NOT bypass any sub-skill's hard gate.
• Does NOT generate content itself — it only dispatches.
• Does NOT write a story for the user — input is a finished English .md (this pipeline illustrates + narrates + exports; it doesn't author).
• Does NOT support multi-story batch runs in one call.

Reference files

• scene-splitter/SKILL.md
• story-illustrator/SKILL.md
• story-narrator/SKILL.md
• story-html-publisher/SKILL.md