kinocut AGENTS.md

Kinocut - Project Rules

Public Agent Skill

• skills/kinocut/SKILL.md is the canonical public skill for this repo.
• Invoke $kinocut in compatible agent hosts for guarded video inspection, editing, Hyperframes, repurposing, release checkpoints, and human-review workflows.
• skills/mcp-video/SKILL.md is a compatibility entry point only. Keep it thin and direct new work to $kinocut.
• Keep the skill aligned with docs/CLI_REFERENCE.md, docs/TOOLS.md, the Python client, and public MCP tool names when those surfaces change.

Before Writing Any Code

1. Check if it already exists. Search ffmpeg_helpers.py, validation.py, limits.py, and defaults.py before writing any utility function. Import, don't duplicate.
2. Check the public API. Functions registered as MCP tools in server.py are the public surface. Internal functions are prefixed with _. Don't break tool signatures.

FFmpeg Security

1. ALL user-controlled values in FFmpeg filter strings MUST be escaped with _escape_ffmpeg_filter_value() from ffmpeg_helpers.py. This includes: colors, fonts, text, paths, and any string that goes into a -vf or -filter_complex argument.
2. Gold standard pattern (from effects_engine.py:text_animated):

   safe_text = _escape_ffmpeg_filter_value(text)
   safe_font = _escape_ffmpeg_filter_value(font) if font is not None else font
   safe_color = _escape_ffmpeg_filter_value(color) if color is not None else color
   

3. Never use f-string interpolation of user values directly into filter strings without escaping.

Error Handling

1. Always raise custom types from errors.py, never raw ValueError, RuntimeError, or FileNotFoundError.
   • Input file issues → InputFileError
   • FFmpeg processing failures → ProcessingError (auto-truncates stderr to 500 chars)
   • Bad parameters → MCPVideoError with error_type="validation_error"
2. Never embed result.stderr directly in error messages. Route through ProcessingError which truncates to 500 chars.
3. Never use bare except Exception: without logging. Always except Exception as e: logger.warning(...).