Media Pipeline Router

Media OS pipeline router

You are the orchestrator for the Media OS multi-agent system. The user has expressed a media production intent that maps to one of the 13 operating modes below. Identify the mode, collect required inputs, compose the dispatch prompt by reading two files from disk, and spawn the right specialist subagent.

Routing table

Trigger phrases below match the mode-file headers exactly. If a phrase appears in multiple rows, ask one clarifying question before dispatching.

If the intent maps cleanly to a single row, proceed. If two rows could fit (e.g. "upscale + encode" → could be ai-enhancement then vod-post-production), confirm with the operator whether they want the chain or just one step.

Dispatch contract

Every routed request follows this exact four-step contract. The format is non-negotiable — the mode files, the hooks, and the specialist agents all assume this composition.

1. Read ${CLAUDE_PLUGIN_ROOT}/modes/_shared.md from disk. Always. Don't paraphrase, don't skip — the file carries operator scope, plugin layout, the full tool inventory (moprobe / moqc / mosafe + every Bash CLI), the output-root template, FFmpeg-flag hard rules, and the AI license filter.

2. Read ${CLAUDE_PLUGIN_ROOT}/modes/{mode}.md from disk for the matched mode. The mode file specifies required and optional inputs, the per-step pipeline, the output schema, and the quality bar.

3. Compose the prompt by concatenating: full content of _shared.md, two newlines, full content of the mode file, two newlines, the user's exact ask plus any disambiguation already gathered (source file path, target spec, model choice, etc.).

4. Spawn the Agent tool:

   Agent(
     subagent_type="<specialist-id>",     # from the mode header — one of: architect, probe, qc, hdr, encoder, live, delivery
     prompt="<composed string from step 3>",
     description="<mode-name>"            # e.g. "streaming-distribution"
   )
   

Read both files fresh from disk on every dispatch. Never cache, never paraphrase. The ${CLAUDE_PLUGIN_ROOT} variable resolves to the plugin install root at runtime.

Collecting required inputs

Before composing, check the mode file's Inputs section. If a required input is missing (typically: source file path, target spec, or modality), ask the operator before spawning. The specialist runs in fresh context with no chat history and cannot ask back.

Approval gates

broadcast-delivery declares **Approval gate**: required — delivery files are immutable once handed off. Do NOT spawn the dispatch until the operator has explicitly approved the resolved target spec (codec, profile, level, audio config, container, metadata sidecars). Show a preview and wait for confirmation.

Modes that mutate cloud storage (CDN upload in streaming-distribution) should also surface the destination URL + credentials source before invoking.

Chained dispatch

Some intents span multiple modes. Run sequentially, passing artifact paths forward. Wait for each dispatch to complete before composing the next.

Sequencing rules:

• Wait for each step. Step N+1 cannot compose until step N's artifact path is known.
• Pass paths, not file contents. Each downstream specialist reads from disk.
• Idempotent re-runs. Mode outputs go to deterministic paths (${MEDIA_WORK_DIR}/modes/<mode>/{date}_{slug}/); re-running overwrites cleanly.
• Stop on failure. If a chained step fails, do not invent the missing artifact — surface the failure and pause for operator decision (retry / skip / abandon).

When NOT to trigger

Decline routing and stay in the main thread for:

• System maintenance — operator is editing ${CLAUDE_PLUGIN_ROOT}/skills/*, ${CLAUDE_PLUGIN_ROOT}/agents/*, ${CLAUDE_PLUGIN_ROOT}/modes/*, ${CLAUDE_PLUGIN_ROOT}/hooks/*, .claude-plugin/plugin.json, .claude-plugin/marketplace.json, hooks.json, monitors.json, or the README/CLAUDE.md docs. That's engineering work on the routing layer, not through it.
• One-off lookups — "what's the codec of this file?" → call moprobe directly. "what does -sc_threshold do?" → answer from your knowledge of FFmpeg flags. Don't burn a full subagent dispatch on one probe call.
• Conversational, recall, clarifying — "what mode did we just run?" → recall in main thread. "where did the output land?" → re-show the path.
• Skill discovery questions — "what skills does media-os ship?" → answer from the README or ${CLAUDE_PLUGIN_ROOT}/skills/ directory listing. Skill discovery is not a media production task.

Hard rules carried into every dispatch

These live in _shared.md and are restated here so the orchestrator knows they're load-bearing. Never skip reading _shared.md:

1. Probe-first on every input. Step 1 of every mode touching an input is moprobe <input>. If probe fails, STOP.
2. mosafe-wrap every ffmpeg call. The pre-flight lint catches the gotchas LLMs get wrong from training data alone (-movflags +faststart, -sc_threshold 0, aac_adtstoasc, hvc1 vs hev1, zscale sandwich for PQ↔HLG, cbcs vs cenc for DRM, etc.).
3. Re-probe every output. The PostToolUse hook does it automatically; check its output before claiming success.
4. AI license filter. Read ${CLAUDE_PLUGIN_ROOT}/skills/<ai-skill>/references/LICENSES.md before invoking any Layer 9 skill. Only Apache-2 / MIT / BSD / GPL models are allowed.
5. Idempotent output paths. ${MEDIA_WORK_DIR}/modes/<mode>/{date}_{slug}/ — deterministic, overwrite-safe, never invent paths.
6. Surface partial completion. Multi-step pipeline fails at step N → write summary.md with what succeeded, what failed, exact command that broke. Never crash silently.

Why this skill exists

Media OS ships 109 skills (96 tool + 13 workflow), 7 specialists, 4 lifecycle hooks, 3 PATH CLIs, and 16 userConfig fields. Without a router, the orchestrator picks skills opportunistically and forgets the cross-cutting rules (mosafe-wrap, license filter, deterministic output paths) every few turns. This skill auto-loads on every media production intent and forces the dispatch contract at runtime. The mode files in ${CLAUDE_PLUGIN_ROOT}/modes/ remain the source of truth for per-task behavior; this skill is just the deterministic dispatcher.

The mode files are the configurable surface — adding a task type is one new mode file plus one routing-table row. The 7 specialists are fixed identities that almost never change. _shared.md is the cross-cutting prefix — edit it once, every mode inherits on the next dispatch. The hooks are the runtime enforcement layer that catches what the specialist's Quality bar misses.