From 4e7ab6fc0b80a4087c1563a48add2bcb451a75ec Mon Sep 17 00:00:00 2001
From: calesthio <celesthioailabs@gmail.com>
Date: Sun, 29 Mar 2026 12:55:41 -0700
Subject: [PATCH] Add mandatory music plan gatekeeping to pipeline planning

- Add cross-pipeline Music Plan requirement to AGENT_GUIDE User-Facing Planning Protocol
- Add Step 5: Music Plan to cinematic idea-director with library/API/BYO options
- Add music plan resolution to cinematic quality gate
- Ensures agent surfaces music situation before production starts, not at asset stage
---
 AGENT_GUIDE.md                              | 25 +++++++++++++++--
 skills/pipelines/cinematic/idea-director.md | 30 ++++++++++++++++++++-
 2 files changed, 52 insertions(+), 3 deletions(-)

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