Skip to content

Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.

README: name the contract-derivation pattern SPEC (#98)

Shogo Kajiyama57f3f61f3afe
diff --git a/README.md b/README.md
index ec6db29..a50a110 100644
--- a/README.md
+++ b/README.md
@@ -216,6 +216,34 @@ Picture tools (`fit`, `caption`, `overlay`, `graphics`, `color`, `export`, `scen
## Built for agents
+### What is SPEC?
+
+This project's author, [kajisho5](https://github.com/kajisho5), coined **SPEC** (Self-Producing
+Execution Contract) for the pattern this skill's tool layer is built on: each tool's `input_schema`
+— the part of its contract that has to track the CLI exactly, flag for flag — is never
+hand-authored side by side with the code. It is derived, at run time, from the one thing that
+actually has to be correct for the CLI to work at all: the script's own `argparse` parser.
+
+Concretely, `scripts/_contract.py`'s `_capture_parser()` imports every tool script and
+intercepts its `parse_args()` call to get the live, fully-built parser object — flags, types,
+choices, defaults, required/positional, mutually exclusive groups, all of it. `input_schema` is
+built straight from that object. (The rest of a `ToolSpec` — `role`, `capabilities`, `inputs`,
+`outputs`, `output_schema` — comes from a hand-authored table, `TOOL_META`, since those facts
+aren't things a parser can express; only `input_schema` is parser-derived.)
+
+- **The contract**'s `input_schema` for every tool is generated from the live parser directly.
+- **The MCP server** (`mcp/server.py`) carries no schema of its own; `tools/list` is translated
+ straight from the contract, `input_schema` included.
+- **The docs** (`docs/contract.md`'s field reference, this README's tool table) describe the same
+ shape. `tests/test_contract.py` runs on every CI run and fails the build if any of them drift
+ out of sync with what the code actually does — it catches drift, it doesn't fix it for you.
+
+The result: add a flag to a script's `argparse` block, and `input_schema` and the MCP tool
+definition follow with no second edit; if a docs page or a `TOOL_META` entry falls behind, CI
+catches it rather than letting it drift silently. There is no separate `input_schema` file to
+forget to update, and no version of "what CLI flags does this tool accept" that can quietly go
+stale.
+
### Machine-readable contract
```bash