@kolbo/mcp 1.70.0 → 1.70.2

package/skill/references/workflows/filmmaking.md

@@ -0,0 +1,168 @@
+# Filmmaking Router
+
+Operate as a filmmaking system, not merely a prompt writer. Preserve project truth across generations while compiling every generation into a self-contained instruction the selected model can execute.
+
+## Start here
+
+1. Identify the requested production stage and deliverable.
+2. Read only the reference files required by the routing table below.
+3. Preserve or establish the relevant production truth before writing a shot.
+4. Choose generation mode, control density, craft packs, audio lane, and model adapter.
+5. Produce the requested artifact in the user's language; keep generation prompts in English unless the user requests otherwise.
+6. Run the applicable audit. For saved prompt/package artifacts, run the bundled validators.
+
+Do not generate media, spend credits, or contact external systems unless the user explicitly asks. Do not silently change an existing billable prompt beyond the requested scope. In Workbench mode, patch the failed section and keep proven sections byte-stable whenever practical.
+
+## Route the work
+
+Read [routing.md](references/filmmaking/routing.md) for the full decision rules.
+
+| Request | Mode | Read |
+|---|---|---|
+| Premise, outline, screenplay, weak scene | Development | `scene-engine.md`, then `workflows.md` |
+| Character, location, prop, state, voice, or production preparation | Pre-production | `asset-preproduction.md`, `production-bible.md`; add `acting-direction.md` for recurring characters |
+| One generation-ready video prompt | Direction | `prompt-contracts.md`, selected craft references, then the model adapter |
+| Connected dialogue or performance | Direction | `acting-direction.md`, `blocking-continuity.md`, `audio-dialogue-music.md`, model adapter |
+| Music video, dance, singing, or exact song | Direction | `audio-dialogue-music.md`, `cinematography.md`, `blocking-continuity.md`, model adapter |
+| Difficult action, transformation, scale, vehicle, creature, water, or impossible gravity | Direction | `physics-action.md`, `blocking-continuity.md`, `cinematography.md`, model adapter |
+| Broken result or prompt | Audit | `validation.md` plus only the craft/model references implicated by the failure |
+| Revise one failed behavior without losing what worked | Workbench | `validation.md` and the relevant craft reference |
+| Multi-scene, episode, commercial, music video, or feature workflow | Production | `production-bible.md`, `workflows.md`, `validation.md` |
+
+For Seedance 2.5, always read [seedance-2-5.md](references/models/seedance25.md) before final compilation. Treat capability numbers as a dated adapter snapshot and verify them against current provider/catalog truth when real money or production delivery depends on them.
+
+## Keep two layers separate
+
+### Project truth
+
+Maintain durable facts outside individual prompts:
+
+- story goal, world laws, period, genre, tone, and visual registers;
+- characters, immutable identity anchors, states, wardrobe, injuries, performance engines, and voices;
+- locations, landmark geometry, light direction, axes, and available coverage;
+- props, vehicles, creatures, scale laws, ownership, hand state, damage, and versions;
+- scene and shot cards, continuity state, coverage, generation attempts, and editorial needs.
+
+Use the templates in `assets/filmmaking/` when the task benefits from saved project state. Read [production-bible.md](references/filmmaking/production-bible.md) before creating or updating them.
+
+### Generation island
+
+Compile only what the current generation needs. A video model cannot resolve “same as before” unless the needed state is restated. Include active truth explicitly, but do not carry inactive characters, stale tags, old props, irrelevant backstory, or previous-shot prose.
+
+Kolbo Visual DNA is semantic project truth, not merely reference imagery. Read and preserve the saved DNA type and analyzed context: character DNAs own identity/state/performance/voice; environment and scene DNAs own location/geography/light; product DNAs own prop/product identity, scale, material, and state; style DNAs own the visual register. Keep exact tags and never reinterpret one DNA type as another.
+
+## Choose control density
+
+Never equate sophistication with maximum length.
+
+- **Strict** — lock exact blocking, count, timing, dialogue, hand/prop state, axis, scale, or failure-prone physics. Use for continuity-heavy dialogue, expensive hero shots, repeated failures, and exact music synchronization.
+- **Anchored** — dictate non-negotiable story/continuity/physics anchors and allow camera or performance variation inside them. Use for complex spectacle where controlled discovery is valuable.
+- **Exploratory** — protect identity, world, safety, and essential beats while inviting coverage variations. Use for montage, inserts, music-video coverage, and ideation.
+
+If the user supplied an exact prompt, preserve its chosen density unless the failure diagnosis proves density itself is the problem.
+
+## Select craft packs
+
+Load only what the shot needs:
+
+- Story causality and scene reversals: [scene-engine.md](references/filmmaking/scene-engine.md)
+- Asset building, versions, and stress tests: [asset-preproduction.md](references/filmmaking/asset-preproduction.md)
+- Character performance, listening, and voice identity: [acting-direction.md](references/filmmaking/acting-direction.md)
+- Geography, axes, eyelines, diagrams, and state continuity: [blocking-continuity.md](references/filmmaking/blocking-continuity.md)
+- Shot size, optics, operator behavior, and visual grammar: [cinematography.md](references/filmmaking/cinematography.md)
+- Action feasibility, mass, materials, transformations, and impossible shots: [physics-action.md](references/filmmaking/physics-action.md)
+- Dialogue, ambience, native audio, source-song performance, and post music: [audio-dialogue-music.md](references/filmmaking/audio-dialogue-music.md)
+
+Do not paste every craft pack into every prompt. Translate the selected pack into the shortest observable instructions that preserve the intended result.
+
+## Compile a shot
+
+Read [prompt-contracts.md](references/filmmaking/prompt-contracts.md) for exact structures.
+
+Before writing, establish:
+
+1. The dramatic event and the shot's job in the edit.
+2. Active references and exact state variants.
+3. First visible frame and final state.
+4. Geography, axis, screen direction, eyelines, and prop/hand state.
+5. Action feasibility inside the duration.
+6. Acting tasks for performers and listeners.
+7. Camera grammar and control density.
+8. Audio ownership, exact words/lyrics, and whether music is native, source-driven, or reserved for post.
+9. Model capability limits and target generation mode.
+
+Prompt-length limits apply to the entire compiled generation prompt as one string, including whitespace, headers, timecodes, dialogue, audio, and locks. Count after compilation. For the current Seedance 2.5 adapter snapshot, the hard ceiling is 30,000 characters; never borrow that number for another model.
+
+For a serious controlled shot, prefer this logical order, omitting irrelevant blocks:
+
+```text
+SCENE CONTEXT
+ACTIVE REFERENCES
+LOCATION MAP
+FIRST FRAME AND SPATIAL BLOCKING
+FORMAT MODE
+OPTICS
+CAMERA
+ACTION TIMING / SHOTS
+PHYSICS
+LIGHTING
+ACTING TASKS
+DIALOGUE
+AUDIO / MUSIC
+STYLE
+POSITIVE LOCKS
+```
+
+For anchored or exploratory work, collapse compatible blocks and protect only non-negotiables. Never manufacture a rigid skeleton when a looser model-native prompt is more likely to succeed.
+
+## Preserve continuity
+
+Track both kinds:
+
+- **Within-generation continuity:** positions, axis, gaze, wardrobe, props, injuries, lighting, motion, audio ownership, and state across internal cuts.
+- **Across-generation continuity:** the exact final state of shot N becomes explicit input truth for shot N+1. Preserve emotional carry, breath, body tension, dirt/wetness/damage, prop hand, screen direction, ambience, and dialogue seam.
+
+Never rely on memory alone for a substantial production. Update the continuity ledger after an approved shot or deliberate script/state change.
+
+## Workbench revisions
+
+When a generation fails:
+
+1. Compare intended versus observed result.
+2. Identify one primary failure owner: asset, state, dramatic design, blocking, acting, optics, camera, timing, physics, lighting, audio, model capability, or prompt contradiction.
+3. Change the smallest causal unit.
+4. Preserve every proven line or block.
+5. Log the change and verdict.
+6. After repeated failures, redesign the shot: bake the state into an asset, add a staging/layout reference, reduce actions, split the shot, change the angle, or switch model/mode.
+
+Do not keep polishing adjectives when the shot is physically or structurally overconstrained.
+
+## Validate
+
+Read [validation.md](references/filmmaking/validation.md). At minimum check:
+
+- all referenced assets exist and match the intended state;
+- no stale, invented, dangling, or conflicting tags;
+- character and prop counts remain feasible;
+- duration, timecodes, shot count, and dialogue fit;
+- continuous-take and cut instructions do not conflict;
+- one actor owns each spoken/sung line;
+- camera freedom does not contradict strict geography;
+- model limits and prompt budget are respected;
+- final frame state is explicit enough for the next shot;
+- the result is usable without reading hidden reasoning.
+
+Run:
+
+```powershell
+python scripts/filmmaking/validate_film_package.py <project-folder>
+python scripts/filmmaking/lint_prompt.py <prompt.txt> --shot-card <shot-card.json> --model seedance-2.5
+```
+
+Fix errors before delivery. Report warnings that represent genuine creative tradeoffs rather than silently flattening the user's intent.
+
+## Production workflows
+
+Read [workflows.md](references/filmmaking/workflows.md) for single shots, dialogue scenes, music performance, connected sequences, impossible shots, and feature workflows.
+
+This workflow is part of the canonical Kolbo skill. The Kolbo Code sync pipeline mirrors it to MCP and plugin consumers; product surfaces may compile the same filmmaking truth through their own model adapters.

package/skill/scripts/filmmaking/lint_prompt.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+"""Lint a compiled AI-video prompt against its shot card and model adapter."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+
+TAG_RE = re.compile(r"@[A-Za-z][A-Za-z0-9_.:-]*(?:\s+\d+)?")
+SHOT_RE = re.compile(r"(?im)^\s*(?:SHOT|SEGMENT)\s+(\d+)\b")
+RANGE_RE = re.compile(
+    r"(?i)(\d+(?:\.\d+)?)\s*s\s*(?:-|–|—|to)\s*(\d+(?:\.\d+)?)\s*s"
+)
+
+
+class Report:
+    def __init__(self) -> None:
+        self.items: list[dict[str, str]] = []
+
+    def add(self, level: str, code: str, message: str) -> None:
+        self.items.append({"level": level, "code": code, "message": message})
+
+    def error(self, code: str, message: str) -> None:
+        self.add("error", code, message)
+
+    def warn(self, code: str, message: str) -> None:
+        self.add("warning", code, message)
+
+    @property
+    def errors(self) -> int:
+        return sum(item["level"] == "error" for item in self.items)
+
+    @property
+    def warnings(self) -> int:
+        return sum(item["level"] == "warning" for item in self.items)
+
+
+def load_text(path: Path, report: Report) -> str:
+    try:
+        return path.read_text(encoding="utf-8-sig")
+    except OSError as exc:
+        report.error("read_failed", f"Could not read prompt: {exc}")
+        return ""
+
+
+def load_card(path: Path | None, report: Report) -> dict[str, Any] | None:
+    if path is None:
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8-sig"))
+    except (OSError, json.JSONDecodeError) as exc:
+        report.error("invalid_shot_card", f"Could not load shot card: {exc}")
+        return None
+    if not isinstance(data, dict):
+        report.error("invalid_shot_card", "Shot card must contain a JSON object.")
+        return None
+    return data
+
+
+def expected_tags(card: dict[str, Any] | None) -> set[str]:
+    if not card:
+        return set()
+    tags: set[str] = set()
+    for asset in card.get("active_assets", []):
+        if isinstance(asset, dict) and isinstance(asset.get("tag"), str):
+            tags.add(asset["tag"])
+    return tags
+
+
+def check_adapter(
+    prompt: str, card: dict[str, Any] | None, model: str, report: Report
+) -> None:
+    if model != "seedance-2.5":
+        return
+    if len(prompt) > 30_000:
+        report.error(
+            "seedance_prompt_length",
+            f"Prompt has {len(prompt)} characters; Seedance 2.5 adapter ceiling is 30,000.",
+        )
+    shot_numbers = [int(value) for value in SHOT_RE.findall(prompt)]
+    if len(shot_numbers) > 30:
+        report.error(
+            "seedance_shot_count",
+            f"Prompt contains {len(shot_numbers)} shot/segment headings; adapter ceiling is 30.",
+        )
+    if card:
+        duration = card.get("duration_seconds")
+        if isinstance(duration, (int, float)) and not 4 <= duration <= 30:
+            report.error(
+                "seedance_duration",
+                f"Shot-card duration is {duration}s; Seedance 2.5 adapter expects 4-30s.",
+            )
+
+
+def check_contradictions(prompt: str, report: Report) -> None:
+    continuous = re.search(
+        r"(?i)\b(one|single)\s+(?:unbroken\s+)?continuous\s+take\b|\bno\s+cuts?\b",
+        prompt,
+    )
+    cuts = re.search(r"(?i)\b(hard|match|smash|jump|whip)\s+cut\b|\bhard\s+cuts\b", prompt)
+    if continuous and cuts:
+        report.error(
+            "continuous_take_cut_conflict",
+            "Prompt requests a continuous/no-cut take and also specifies an editorial cut.",
+        )
+
+    no_music = re.search(r"(?i)\b(?:no|without)\s+(?:source\s+)?music\b", prompt)
+    positive_music = re.search(
+        r"(?i)\b(?:music|score|song)\s+(?:plays|continues|swells|throughout)\b|"
+        r"@[Aa]udio\s+\d+\s+(?:plays|continues)",
+        prompt,
+    )
+    if no_music and positive_music:
+        report.error(
+            "music_policy_conflict",
+            "Prompt both forbids music and directs music or a song to play.",
+        )
+
+    realtime = re.search(r"(?i)\breal[- ]time\b|\bnormal\s+speed\b", prompt)
+    slow_motion = re.search(r"(?i)\bslow[- ]motion\b|\bslow[- ]mo\b", prompt)
+    if realtime and slow_motion:
+        report.warn(
+            "speed_policy_conflict",
+            "Prompt contains both real-time/normal-speed and slow-motion instructions; scope them explicitly.",
+        )
+
+
+def check_stale_language(prompt: str, report: Report) -> None:
+    patterns = [
+        r"(?i)\bsame\s+as\s+(?:before|above|previous)\b",
+        r"(?i)\bas\s+(?:before|above)\b",
+        r"(?i)\bcontinues?\s+from\s+(?:the\s+)?previous\s+shot\b",
+        r"(?i)\bunchanged\s+from\s+(?:the\s+)?previous\b",
+    ]
+    if any(re.search(pattern, prompt) for pattern in patterns):
+        report.warn(
+            "implicit_continuity",
+            "Replace stale phrases such as 'same as before' with explicit visible state for this generation island.",
+        )
+
+
+def check_tags(prompt: str, card: dict[str, Any] | None, report: Report) -> tuple[set[str], set[str]]:
+    found = {value.rstrip(".,;:!?") for value in TAG_RE.findall(prompt)}
+    expected = expected_tags(card)
+    for tag in sorted(expected - found):
+        report.error("missing_active_asset", f"Shot-card asset is absent from prompt: {tag}")
+    for tag in sorted(found - expected):
+        if expected and not re.fullmatch(r"@[Ii]mage\s+\d+|@[Aa]udio\s+\d+|@[Vv]ideo\s+\d+", tag):
+            report.warn(
+                "unregistered_prompt_asset",
+                f"Prompt tag is not listed in shot-card active_assets: {tag}",
+            )
+    if len(found) > 50:
+        report.error(
+            "reference_count",
+            f"Prompt has {len(found)} distinct references; current Kolbo Seedance contract ceiling is 50.",
+        )
+    return found, expected
+
+
+def check_timing(prompt: str, card: dict[str, Any] | None, report: Report) -> None:
+    duration = card.get("duration_seconds") if card else None
+    for start_text, end_text in RANGE_RE.findall(prompt):
+        start, end = float(start_text), float(end_text)
+        if end <= start:
+            report.error("invalid_time_range", f"Prompt time range {start:g}s-{end:g}s is not increasing.")
+        if isinstance(duration, (int, float)) and end > duration:
+            report.error(
+                "timecode_overflow",
+                f"Prompt time range ends at {end:g}s, beyond shot-card duration {duration:g}s.",
+            )
+
+
+def check_dialogue_card(card: dict[str, Any] | None, report: Report) -> None:
+    if not card:
+        return
+    dialogue = card.get("dialogue", [])
+    if not isinstance(dialogue, list):
+        report.error("invalid_dialogue", "Shot-card dialogue must be a list.")
+        return
+    intervals: list[tuple[float, float, int, dict[str, Any]]] = []
+    for index, item in enumerate(dialogue):
+        if not isinstance(item, dict):
+            report.error("invalid_dialogue", f"Dialogue item {index} must be an object.")
+            continue
+        start, end = item.get("start_seconds"), item.get("end_seconds")
+        if not isinstance(start, (int, float)) or not isinstance(end, (int, float)):
+            report.error("invalid_dialogue_time", f"Dialogue item {index} needs numeric start/end seconds.")
+            continue
+        intervals.append((float(start), float(end), index, item))
+    intervals.sort()
+    for previous, current in zip(intervals, intervals[1:]):
+        if current[0] < previous[1] and not (
+            previous[3].get("allow_overlap") or current[3].get("allow_overlap")
+        ):
+            report.error(
+                "dialogue_overlap",
+                f"Dialogue items {previous[2]} and {current[2]} overlap without allow_overlap.",
+            )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("prompt", type=Path, help="Compiled prompt text file")
+    parser.add_argument("--shot-card", type=Path, help="Shot card JSON used to compile the prompt")
+    parser.add_argument("--model", default="seedance-2.5", help="Model adapter name")
+    parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+    args = parser.parse_args()
+
+    report = Report()
+    prompt = load_text(args.prompt, report)
+    card = load_card(args.shot_card, report)
+    check_adapter(prompt, card, args.model, report)
+    check_contradictions(prompt, report)
+    check_stale_language(prompt, report)
+    found, expected = check_tags(prompt, card, report)
+    check_timing(prompt, card, report)
+    check_dialogue_card(card, report)
+
+    result = {
+        "prompt": str(args.prompt.resolve()),
+        "model": args.model,
+        "valid": report.errors == 0,
+        "characters": len(prompt),
+        "references_found": sorted(found),
+        "references_expected": sorted(expected),
+        "errors": report.errors,
+        "warnings": report.warnings,
+        "items": report.items,
+    }
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    else:
+        print(f"Prompt: {result['prompt']}")
+        print(
+            f"Model: {args.model} | {len(prompt)} chars | {len(found)} reference(s)"
+        )
+        for item in report.items:
+            print(f"[{item['level'].upper()}] {item['code']} - {item['message']}")
+        print(f"Result: {report.errors} error(s), {report.warnings} warning(s).")
+    return 1 if report.errors else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())