Skip to content

World's first open-source, agentic video production system. 12 production pipelines, 100+ tools, 700+ agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.

Add mandatory music plan gatekeeping to pipeline planning

calesthio4e7ab6fc0b80
diff --git a/AGENT_GUIDE.md b/AGENT_GUIDE.md
index 30159173..a4180382 100644
--- a/AGENT_GUIDE.md
+++ b/AGENT_GUIDE.md
@@ -330,11 +330,32 @@ Before committing to execution, present:
3. Recommended tool path.
4. Alternative tool paths that are actually available.
5. Cost estimate and quality tradeoffs.
-6. Production plan by stage.
-7. Approval gate before asset generation.
+6. **Music plan** — mandatory for every pipeline that has audio. See below.
+7. Production plan by stage.
+8. Approval gate before asset generation.
If a user prefers a specific vendor and that tool is available, surface it directly. Do not hide provider choice.
+### Music Plan (Mandatory)
+
+Music is a critical part of any video. **Surface the music situation to the user at proposal/idea time** — do not silently defer it to the asset stage where a failure becomes expensive.
+
+Check music availability in this order and present the options:
+
+1. **User music library (`music_library/`):** Check if this folder exists and contains tracks. If so, list available tracks with durations and let the user pick one.
+2. **Music generation APIs:** Check which music tools are available via the registry (`registry.get_by_capability("music_generation")`). Report their status honestly — include quota status if known.
+3. **Royalty-free sources:** Note if the user can provide their own track (e.g., from YouTube Audio Library, Jamendo, or other free sources). Offer the `music_library/` drop path.
+
+**Always present the user with explicit choices:**
+- Use a track from their library (which one?)
+- Provide a different track (drop it in `music_library/`)
+- Generate one via API (if available — name the provider and cost)
+- Proceed without music
+
+**If no music source is available:** Tell the user explicitly. Do NOT let this surface as a surprise at the asset stage.
+
+Record the music decision in the proposal/brief artifact so the asset director knows what to do.
+
## Pipeline Asset Expectations
Each pipeline manifest's `tools_available` field declares what tools a stage can use. Use selectors for multi-provider capabilities — the selector handles routing to whatever is available. Read the pipeline manifest for the authoritative list per stage.
diff --git a/skills/pipelines/cinematic/idea-director.md b/skills/pipelines/cinematic/idea-director.md
index b2f99c86..abbb7e2f 100644
--- a/skills/pipelines/cinematic/idea-director.md
+++ b/skills/pipelines/cinematic/idea-director.md
@@ -65,11 +65,39 @@ Recommended metadata keys:
If the user has weak source media and no generation path, say so. A cinematic result still needs enough visual or audio material to carry mood.
-### 5. Quality Gate
+### 5. Music Plan (Mandatory)
+
+Cinematic videos live and die by their audio. **Surface the music situation before the user approves the brief.**
+
+Check availability in this order:
+
+1. **User music library (`music_library/`):** Check if this folder exists and contains tracks. List available tracks with durations and moods. Let the user choose.
+2. **Music generation APIs:** Check `registry.get_by_capability("music_generation")`. Report status, quota, and cost per track.
+3. **Royalty-free sources:** Note that the user can provide a track from YouTube Audio Library, Jamendo, or other free sources by dropping it in `music_library/`.
+
+Present explicit options:
+
+```
+MUSIC PLAN
+├── Your music library: [N tracks / empty]
+├── AI generation: [provider] — [AVAILABLE/UNAVAILABLE] [cost]
+└── Bring your own: Drop a track in music_library/ before asset stage
+
+Options:
+ (a) Use a library track (which one?)
+ (b) Provide your own track
+ (c) Generate via API (if available)
+ (d) Proceed without music (not recommended for cinematic)
+```
+
+Record the decision in `brief.metadata.music_strategy` with the chosen source and path/prompt.
+
+### 6. Quality Gate
- the source truth is explicit,
- the emotional arc is specific,
- the output shape fits the available assets,
+- the music plan is resolved (source chosen or explicitly deferred),
- the treatment is cinematic for a reason, not by label only.
## Common Pitfalls