CLAUDE.md · diff
git:20260405.fd18fe6 to git:20260507.8f4de28
16 added, 44 removed. Audit A to A.
- # mcp-video — Project Rules
-
- ## 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
-
- 3. **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.
- 4. **Gold standard pattern** (from `effects_engine.py:text_animated`):
- ```python
- 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
- ```
- 5. **Never use f-string interpolation of user values directly into filter strings** without escaping.
-
- ## Error Handling
-
- 6. **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"`
- 7. **Never embed `result.stderr` directly in error messages.** Route through `ProcessingError` which truncates to 500 chars.
- 8. **Never use bare `except Exception:` without logging.** Always `except Exception as e: logger.warning(...)`.
+ # CLAUDE.md instructions for KyaniteLabs/mcp-video
- ## Subprocess Calls
+ <!-- EMPOWER_ORCHESTRATOR:START -->
+ ## Empower the Orchestrator
- 9. **ALL `subprocess.run()` and `subprocess.Popen()` calls MUST have a `timeout` parameter.** Use `DEFAULT_FFMPEG_TIMEOUT` from `defaults.py`.
- 10. **Catch `subprocess.TimeoutExpired`** and raise `ProcessingError` with a clear timeout message.
- 11. **Validate input paths** with `_validate_input_path()` from `ffmpeg_helpers.py` before passing to subprocess.
+ This repository is governed by the Empower Orchestrator law. Every top-level/orchestrator Claude Code session is an audition to improve the system, not only finish the current task.
- ## Configuration
+ When you notice a repeatable task done 3+ times or a recurring agent failure mode, consider shipping the smallest durable artifact that prevents the repetition: a tool, skill, slash command, hook, guardrail, memory entry, test, verifier, or doctrine doc.
- 12. **All default values MUST be defined in `defaults.py`.** Reference by name, never hardcode magic numbers like `crf=23`, `timeout=600`, `fps=30`.
- 13. **Validation constants** go in `validation.py`. Resource limits go in `limits.py`. Runtime defaults go in `defaults.py`.
+ This applies to top-level/orchestrator sessions. Background workers execute their assigned slice and do not independently widen scope.
- ## Size Limits
+ Before dispatching automation or creating a durable system change, state the four-question blast-radius check in chat:
- 14. **No module may exceed 800 LOC.** If it does, split into a subpackage.
- 15. **No function may exceed 80 lines.** If it does, extract helpers.
- 16. **No dead code.** If a function/method/constant has zero callers outside its definition, remove it.
+ 1. Scale: one file/workspace/all sessions?
+ 2. Severity: minor friction/broken workflow/data loss or leaked content?
+ 3. Reversibility: single revert/manual cleanup/surgery?
+ 4. Predictability: bounded failure mode/guessing/unknown?
- ## Architecture
+ All green permits auto mode. Any yellow requires inline human approval. Any red means do not dispatch; do the work inline or escalate.
- 17. **`ffmpeg_helpers.py` is the single source of truth** for: `_run_ffmpeg()`, `_validate_input_path()`, `_escape_ffmpeg_filter_value()`, `_get_video_duration()`, `_run_ffprobe()`, `_seconds_to_srt_time()`. Never duplicate these.
- 18. **`server.py` is the tool registration layer.** Business logic goes in engine modules, not in server tool handlers.
- 19. **Lazy imports in `server.py`** keep startup fast. Follow the existing pattern: import inside the tool handler function.
+ Worker discipline: isolated worktree/sandbox, one artifact equals one commit/change unit, verify before commit, register through the target tool's native discovery surface, and never write outside the assigned scope.
- ## Testing
+ Success line: “I noticed X, found a better way. The system just got an upgrade.”
- 20. **Every fix must pass `python3 -m pytest tests/ -x -q --tb=short`** before committing.
- 21. **Run `python3 -c "import mcp_video"`** to verify no broken imports after changes.
+ Full recipe: `docs/agent-law/empower-orchestrator.md`.
+ <!-- EMPOWER_ORCHESTRATOR:END -->