freedak/OpenMontage
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial release — OpenMontage: the first open-source agentic video production system

Browse Source 
11 production pipelines, 47 tools, 124 agent skills.
Supports cloud APIs (fal.ai, OpenAI, ElevenLabs, Suno, HeyGen, Runway) and
free local providers (diffusers, Piper TTS, WAN 2.1, Hunyuan, CogVideo).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
calesthio
2026-03-29 08:25:17 -07:00
commit a3e735cc7a
1147 changed files with 240221 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/meta/checkpoint-protocol.md
+128
View File
@@ -0,0 +1,128 @@
# Checkpoint Protocol — Meta Skill
## When to Use
After completing a stage's work AND passing review. This skill teaches you when and how to checkpoint, and when to ask the human for approval. It replaces the Python `checkpoint_policy.py` with an instruction-driven protocol.
Checkpoints are the save points of a pipeline. They enable resume-from-failure, human oversight, and audit trails.
## Protocol
### Step 1: Check Manifest Policy
Read the current stage's configuration from the pipeline manifest:
```yaml
- name: idea
checkpoint_required: true # Must we checkpoint?
human_approval_default: true # Must we ask the human?
```
| `checkpoint_required` | `human_approval_default` | Action |
|----------------------|------------------------|--------|
| true | true | Checkpoint + present to human for approval |
| true | false | Checkpoint + proceed automatically |
| false | * | Skip checkpoint entirely (rare) |
### Step 2: Prepare Checkpoint Data
Gather everything needed for the checkpoint:
1. **Stage name** — which stage just completed
2. **Status** — `"completed"` (or `"awaiting_human"` if approval needed)
3. **Artifacts** — the canonical artifact(s) produced by this stage
4. **Metadata** — review findings, cost snapshot, timing info
### Step 3: Write Checkpoint
Call the checkpoint utility:
```python
write_checkpoint(
pipeline_dir, # Project working directory
project_name, # Project identifier
stage_name, # e.g., "idea"
status, # "completed" or "awaiting_human"
artifacts, # {"brief": {...}} — the stage's output
)
```
The checkpoint utility will:
- Validate the artifact against its schema
- Write the checkpoint JSON to disk
- Include timestamp and stage metadata
### Step 4: Human Approval (If Required)
When `human_approval_default: true`:
1. **Present a summary** to the human:
```
## Stage Complete: [stage_name]
### Artifact Summary
[Key details from the artifact — title, duration, key decisions]
### Review Findings
[Summary from reviewer: N critical (all fixed), N suggestions]
### Cost So Far
[Budget spent / total, breakdown by tool]
### Action Required
Please review and approve to continue, or provide feedback for revision.
```
2. **Wait for human response:**
- **Approved** → update checkpoint status to `"completed"`, proceed to next stage
- **Revision requested** → go back to the stage director skill with the human's feedback, produce revised artifacts, re-review, re-checkpoint
- **Abort** → stop the pipeline
3. **Approval stages** (which stages typically need human approval):
- `idea` — Always. The creative direction defines everything downstream.
- `script` — Always. The words are the foundation.
- `scene_plan` — Usually. Visual choices are subjective.
- `assets` — Rarely. Automated quality checks are sufficient.
- `edit` — Rarely. Technical assembly, not creative.
- `compose` — Rarely. But human may want to preview.
- `publish` — Always. Human must approve before anything goes public.
### Step 5: Determine Next Stage
After checkpoint is written and approved (if needed):
```python
next_stage = get_next_stage(pipeline_dir, project_name)
```
This reads all existing checkpoints and returns the next stage that needs to run, or `None` if the pipeline is complete.
### Step 6: Resume Protocol
At the START of any pipeline run (not just after a stage), always check for existing progress:
```python
next_stage = get_next_stage(pipeline_dir, project_name)
```
If `next_stage` is not the first stage:
1. Inform the human: "Found existing progress. Resuming from stage: [next_stage]"
2. Load prior artifacts from checkpoints for context
3. Continue from that stage
If a checkpoint exists with status `"awaiting_human"`:
1. Inform the human: "Stage [name] is awaiting your approval"
2. Present the checkpoint data for review
3. Wait for approval before proceeding
## Key Principles
1. **Always checkpoint completed work.** Even if `checkpoint_required: false`, consider checkpointing anyway if the stage took significant time or cost. Losing work is worse than an extra file on disk.
2. **Never skip human approval on creative stages.** `idea` and `script` shape everything. Rushing past them to save time produces videos nobody wants.
3. **Include cost snapshots.** The human should know how much has been spent and how much remains before approving expensive downstream stages (assets, compose).
4. **Checkpoints enable resume.** If the pipeline crashes at `compose`, the human can restart and it picks up from `compose` — not from `idea`. This is the whole point.
5. **Be transparent in approval requests.** Don't just show the artifact — show the review findings, the cost, and any concerns. Help the human make an informed decision.
skills/meta/reviewer.md
+116
View File
@@ -0,0 +1,116 @@
# Reviewer — Meta Skill
## When to Use
After completing any pipeline stage's work — before checkpointing. You are the quality gate between "work done" and "work accepted." This skill replaces the Python reviewer class with an instruction-driven self-review protocol.
Every stage gets reviewed. No exceptions. The review quality determines whether the final video is worth watching.
## Protocol
### Step 1: Load Review Context
Before reviewing, gather:
1. **Review focus items** from the pipeline manifest for this stage (`review_focus` field)
2. **Success criteria** from the manifest for this stage (`success_criteria` field)
3. **Active playbook** quality rules
4. **The artifact** produced by the stage
### Step 2: Schema Validation
First, the non-negotiable check:
- Validate the artifact against its JSON schema (`schemas/artifacts/<name>.schema.json`)
- If schema validation fails, this is a **critical** finding — fix immediately, do not proceed
### Step 3: Review Against Focus Items
For each `review_focus` item from the manifest:
1. Evaluate the artifact against this specific criterion
2. Assign a severity:
- **critical** — Must fix before proceeding. The artifact is broken, incomplete, or dangerously wrong.
- **suggestion** — Should fix. Improves quality significantly but doesn't block progress.
- **nitpick** — Could fix. Minor polish that's nice-to-have.
3. Write a specific, actionable finding (not vague)
**Good finding:** "Section 3 narration is 180 words for a 10-second window — that's 1080 wpm, impossible to speak. Cut to 25 words."
**Bad finding:** "Script might be too long."
### Step 4: Cross-Check Against Playbook
If a style playbook is active, verify:
- [ ] Color references match playbook palette
- [ ] Transition types are in the playbook's allowed set
- [ ] Pacing rules are respected (min/max durations)
- [ ] Asset descriptions include playbook style cues
- [ ] Quality rules are not violated
Each violation is a **suggestion** severity finding.
### Step 5: Evaluate Success Criteria
For each `success_criteria` item from the manifest:
- Is the criterion met? (yes/no/partial)
- If not met, create a **critical** finding
### Step 6: Make a Decision
Count findings by severity:
| Scenario | Action |
|----------|--------|
| 0 critical, any suggestions/nitpicks | **Pass** — proceed to checkpoint. Note suggestions for the record. |
| 1+ critical findings | **Revise** — fix all critical findings, then re-review (max 2 rounds). |
| After 2 revision rounds, still critical | **Pass with warnings** — proceed anyway, note unresolved issues. Never block indefinitely. |
### Step 7: Record Review
Structure your review as:
```
## Review: [stage_name] — Round [N]
**Decision:** PASS / REVISE / PASS_WITH_WARNINGS
### Findings
1. [CRITICAL] Title of finding
- Description: What's wrong
- Action: What to fix
- Status: pending / fixed / accepted / deferred
2. [SUGGESTION] Title of finding
- Description: What could be better
- Action: How to improve
- Status: pending / accepted / deferred
### Summary
- Critical: N (N fixed)
- Suggestions: N
- Nitpicks: N
- Playbook violations: N
- Success criteria met: N/M
```
## Key Principles
1. **Be specific, not vague.** "The hook is weak" is useless. "The hook asks a question but doesn't create urgency — try leading with the surprising stat from key_point #2" is actionable.
2. **Critical means critical.** Don't inflate severity. A missing schema field is critical. A slightly wordy paragraph is a suggestion. A comma splice is a nitpick.
3. **Two rounds max.** The goal is shipping, not perfection. After two revision rounds, pass with warnings and move on. Perfectionism kills pipelines.
4. **Review the artifact, not the process.** You're checking the output, not how it was produced. If the brief is compelling, it doesn't matter if the agent used an unusual approach.
5. **Playbook is law.** If the playbook says "no more than 3 colors on screen," that's not a suggestion — it's a constraint. Violations are always flagged.
## Stage-Specific Review Guidance
| Stage | What matters most |
|-------|-----------------|
| idea | Hook uniqueness, research depth, angle diversity |
| script | Timing accuracy, narrative arc, enhancement cue density |
| scene_plan | Full coverage, visual variety, asset feasibility |
| assets | File existence, style consistency, budget adherence |
| edit | Timeline coverage, audio sync, subtitle presence |
| compose | Playability, duration accuracy, audio quality |
| publish | SEO quality, metadata completeness, export packaging |
skills/meta/skill-creator.md
+112
View File
@@ -0,0 +1,112 @@
# Skill Creator — Meta Skill
## When to Use
When you encounter a situation where no existing skill covers what you need to do, and the gap is reusable — not a one-off task. This skill teaches you to create new skills dynamically during a pipeline run.
Examples of when to create a new skill:
- A scene requires a visualization technique not covered by existing skills (e.g., "interactive map animation")
- A new tool is available but has no usage skill (e.g., a new TTS provider)
- A recurring pattern emerges across multiple stages that could be codified
Do NOT create a skill for:
- One-off tasks that won't recur
- Things already covered by an existing skill
- Pure tool configuration (that belongs in tool code)
## Protocol
### Step 1: Identify the Gap
Clearly articulate:
1. **What you need to do** that no existing skill covers
2. **Why it's reusable** — will future pipelines benefit?
3. **Where it fits** — which layer and directory?
### Step 2: Research Best Practices
Before writing the skill, research:
1. **Web search** for established approaches to this task
2. **Existing skills** in the repo for structural patterns
3. **Tool documentation** for any tools the skill will reference
### Step 3: Choose the Skill Type
| Type | Directory | Purpose |
|------|-----------|---------|
| Stage director | `skills/pipelines/<pipeline>/` | How to execute a specific pipeline stage |
| Meta skill | `skills/meta/` | Cross-cutting protocol (review, checkpoint, etc.) |
| Tool skill | `.agents/skills/` | How to use a specific API or tool effectively |
| Style skill | `styles/` | Visual/audio style definition (YAML playbook) |
### Step 4: Write the Skill
Follow this structure (adapt to skill type):
```markdown
# [Skill Name] — [Context]
## When to Use
[1-2 sentences: what situation triggers this skill]
## Prerequisites
[Table of required resources: schemas, prior artifacts, tools, other skills]
## Process
### Step 1: [First action]
[Clear instructions with examples]
### Step 2: [Second action]
[Clear instructions with examples]
...
### Step N: Self-Evaluate
[Quality rubric: scoring table with 1-5 scale]
### Step N+1: Submit
[How to persist the output]
## Common Pitfalls
[Bullet list of mistakes to avoid]
```
### Key Principles for Good Skills
1. **Teach thinking, not just doing.** A skill that says "generate an image" is useless. A skill that says "consider the emotional beat of this scene, research how top creators visualize this concept, then craft a prompt that includes the playbook's style anchors" is valuable.
2. **Include examples.** Show what good output looks like. Show what bad output looks like. The contrast teaches more than instructions alone.
3. **Reference concrete resources.** Don't say "check the schema." Say "validate against `schemas/artifacts/brief.schema.json`." Don't say "use a tool." Say "use `image_selector` with the playbook's `image_prompt_prefix`."
4. **Include a self-evaluation rubric.** Every skill should end with a scoring table. This forces the agent to check its own work before proceeding.
5. **Document pitfalls.** What goes wrong when this skill is executed poorly? Warn explicitly.
6. **Be opinionated.** A skill that says "you could do A or B" is less useful than one that says "do A because [reason], but fall back to B when [condition]."
### Step 5: Register the Skill
After writing the skill file:
1. Add an entry to `skills/INDEX.md`
2. If it's a pipeline stage skill, ensure the pipeline manifest references it in the stage's `skill` field
3. If it's a tool skill, place it in `.agents/skills/<tool-name>/`
### Step 6: Validate
Quick checks:
- [ ] File is well-formed markdown with clear headers
- [ ] All referenced schemas, tools, and resources exist
- [ ] Process steps are numbered and actionable
- [ ] Self-evaluation rubric is present
- [ ] Common pitfalls section is present
- [ ] No orphan references (everything mentioned exists in the repo)
## Common Pitfalls
- **Creating skills for one-off tasks**: If you'll never do this again, just do it inline. Skills are for patterns.
- **Vague instructions**: "Make it good" is not a skill. Specificity is what makes a skill useful.
- **No self-evaluation**: Without a rubric, the agent has no way to know if it followed the skill correctly.
- **Missing prerequisites**: A skill that references `image_selector` but doesn't list it in prerequisites will confuse future agents.
- **Over-engineering**: A 500-line skill for a simple task is worse than a 50-line one. Match complexity to the task.