Running Pipelines#

OpenMontage pipelines have no central Python orchestrator. Your AI coding assistant (Claude Code, Cursor, etc.) reads the YAML manifest, follows the corresponding stage-director skill for each step, calls tools from the registry, writes checkpoints, and respects human approval gates.

Starting a Production#

After setup, open the project in your coding assistant and issue a request:

Start a new production using the animated-explainer pipeline for the topic: "How neural networks learn".

The agent selects the pipeline (or defaults to one declared in the manifest), derives a kebab-case project_id (e.g. how-neural-networks-learn), creates the workspace under projects/<project-id>/, and begins the standard stage progression:

research → proposal → script → scene_plan → assets → edit → compose → publish

See the full list and categories in Available Pipelines.

Loading Manifests#

The agent loads the manifest from pipeline_defs/<name>.yaml and validates it against the pipeline schema. You can inspect available pipelines and a manifest directly:

python -c "
from lib.pipeline_loader import list_pipelines, load_pipeline
print(list_pipelines())
manifest = load_pipeline('animated-explainer')
print(manifest['name'], manifest['orchestration']['budget_default_usd'])
"

Use get_stage_order(manifest) to retrieve the exact sequence the agent will follow.

Stage-Director Skills and Tool Governance#

Before working on any stage the agent must read the director skill listed in the manifest (e.g. skills/pipelines/explainer/research-director.md). The skill contains the exact workflow, artifact contracts, review criteria, and quality rubrics for that stage.

Each stage declares tools_available. The agent may call only those tools (plus any preferred_tools or fallback_tools). Selectors (tts_selector, image_selector, video_selector) are the normal entry point for multi-provider capabilities. Tools outside the list for the current stage are blocked.

Sub-Stages and Conditional Work#

Manifests can define sub_stages inside a stage. These appear as stage.sub_name when you request get_stage_order(manifest, include_sub_stages=True). Sub-stages activate based on context (for example, a short preview sample when a video_analysis_brief is present). They do not create separate checkpoints unless the manifest marks them as such.

Reference Input Support#

Pipelines that declare reference_input.supported: true (see cinematic and documentary-montage) accept a reference video or local file. When present, the agent first runs the analysis tools listed under analysis_tools (typically video_analyzer, scene_detect, frame_sampler, transcriber) to produce a video_analysis_brief. This brief grounds later stages. See Analysis and Corpus for details.

Checkpoint Flow#

After completing a stage the agent calls write_checkpoint, which:

Validates the canonical artifact for the stage (e.g. script for the script stage)
Merges any decision_log entries
Records cost_snapshot, review, human_approved, and the locked render_runtime
Writes pipeline/<project-id>/checkpoint_<stage>.json

Status values are pending, in_progress, awaiting_human, completed, or failed.

To resume an interrupted run, the agent calls get_latest_checkpoint and get_next_stage and continues from the last completed stage. Human approval gates are set by the manifest's human_approval_default combined with the checkpoint_policy (guided, manual_all, or auto_noncreative).

You can inspect state at any time:

ls pipeline/<project-id>/
cat pipeline/<project-id>/checkpoint_script.json

All artifacts are also materialized as standalone JSON files under projects/<project-id>/artifacts/.

Human Approval and Budget Gates#

Creative stages usually default to human_approval_default: true. The agent pauses and asks for explicit approval before writing the checkpoint. Budget controls (single_action_approval_usd, cap mode) can also force a pause. See Budget Governance and Cost Tracking.

Follow the stage-director skill exactly and let the agent surface any blockers (missing runtime, budget overrun, delivery-promise violation) before proceeding.