ai-video-pipeline

name	ai-video-pipeline
description	Create, run, resume, or test StoryTeller AI video pipelines.

AI Video Pipeline

Workflow

Stage	Execute	Done when
director	create subagent: $ai-video-director	Director validator passes.
concept_requests	create one subagent per pending concept: $ai-video-concept-art	Concept-art validator passes; status.py sees no pending concept requests.
concept_images	create one subagent per pending concept image request: $imagegen	Each request's output_path exists.
shot_requests	create one subagent per pending shot: $ai-video-shot-producer	Shot-producer validator passes; status.py sees no pending shot requests.
keyframe_images	create one subagent per pending keyframe image request: $imagegen	Each request's output_path exists.
video_generation	run python: scripts/generate_video.py for each pending shot	clip.mp4 and clip_metadata.yaml exist for each shot.
rough_edit	run python: scripts/assemble_video.py	final/final_v001.mp4 exists.

Run loop:

1. If creating a project, run python scripts/init_project.py with explicit --id, --title, --target-duration-sec, --language, and brief input.
2. Run python scripts/status.py --project <project> --json.
3. If current_stage is complete, stop. If blocked is true, report the blocker.
4. Execute every pending item for current_stage using the stage table.
5. After each item, run python scripts/validate_stage.py --project <project> --stage <current_stage>; add --concept-id <concept_id> or --shot-id <shot_id> when validating one item. Then rerun status.py --json.
6. Repeat from step 3 until complete or blocked.

Pipeline owns project-level flow and artifact reconciliation. Stage skills own only their scoped outputs.

Resources

Bundled Python scripts:

Script	Use
scripts/init_project.py	Create a project scaffold.
scripts/status.py	Read authoritative pipeline state and pending items.
scripts/validate_stage.py	Run the validator for the current stage.
scripts/generate_video.py	Generate one shot clip through ComfyUI.
scripts/start_comfyui.py	Explicitly start ComfyUI from the repo config when requested.
scripts/assemble_video.py	Assemble generated clips into the rough final.

Prompt templates:

• assets/templates/worker_prompts.md: Use the matching template when creating a subagent for a pending director, concept, shot, or image item.

Header

Before every major action, print one line:

[StoryTeller] project=<project_id> stage=<stage> item=<item-or-> action=<action> status=<running|ok|blocked|done>

Use headers only for human-readable progress. Use scripts/status.py --json and validators as the state authority.

Subagent Policy

Create a subagent for every stage whose executor is create subagent: $skill. Use spawn mode with agent_type="worker", fork_context=false, model="gpt-5.5", and reasoning_effort="medium". Pass only the target project path, target item id, write scope, validator command, and expected output files. Do not fork the full pipeline context into workers.

For concept_requests, concept_images, shot_requests, and keyframe_images, create a fresh subagent for each pending item. If subagents are unavailable, stop and report the blocker. Do not fall back to codex exec or inline skill execution.

Use subagents only for skill stages:

• director
• concept requests
• image generation
• shot requests
• keyframe image generation

Do not use subagents for status.py, validators, or stages whose executor is run python:.

Each worker task must have one target object and an explicit write scope. Treat files and validators as authoritative, not the worker's final message.

Concept requests and shot requests may run sequentially or in low concurrency when each worker writes only its own target directory.

Blockers

Stop and report the blocker when:

• status.py --json reports blocked: true.
• validate_stage.py exits nonzero.
• A worker returns without the expected files.
• $imagegen does not create output_path.
• ComfyUI is unavailable at the repo-configured URL.
• generate_video.py or assemble_video.py fails.
• The final video is missing after rough edit.