Video Craft Playbook

What does Video Craft Playbook do?

This is a video craft handbook for coding agents, helping you see before you start: for making a high-quality video, what visual capabilities are available to call upon; for each capability, what kind of expression it works for, where it fails, and what it costs; how previous cases combined them and what pitfalls they encountered.

This handbook does not prescribe which tool to use. There are no default tools and no fixed recipes: the same visual style, same type of video, under different constraints (budget, footage, duration, need for real physics, need for real people, number of revisions) will require completely different combinations. Tool selection is for you to make a purposeful plan based on the current task; this handbook only provides the basis for judgment.

How to Use

1. Before Starting: Check Writeback Backlog

python3 ~/.agents/skills/video-craft-playbook/scripts/playbook.py status

status lists case cards not yet distilled (cases/inbox/), capability cards past their review period, and the count of entries in the backlog layer (references/lessons-backlog.md). When the consolidation threshold is reached, it prompts you to run consolidate. The inbox only contains cards that were judged worth distilling in the last run but haven't been distilled yet. If there is a backlog, spend a few minutes distilling it into the handbook (see step 4) before starting a new project; if time is tight, at least tell the user how many items are pending writeback.

2. Planning: Decompose Expression Requirements First, Then Match Capabilities

Don't start with "what tool to use". Start with "what makes each element of this video work":

1. Decompose the finished video into elements: subject, environment, motion, camera, text & graphics, texture, sound, rhythm.
2. For each element, answer the questions in references/task-lenses.md: where does its "truth" come from, does it need frame-by-frame precision, how many revisions will it go through, can it be paid for, how fast does it need to be delivered.
3. For each element, find at least two viable capabilities in references/capability-atlas.md: first scan the top-level overview table to pick candidates, then read the corresponding cards. After comparison, write down your selection and the rejected alternatives. The candidates should include "real footage that can be found" (atlas group H: local material index, open material library), not just compare generation and code. The source ladder and the "copy → shot description → search → license check → compositing" pipeline are detailed in task-lenses question 11 and craft-lessons L60.
4. When combining multiple capabilities, define the interfaces first: time authority, framerate, coordinates & camera, alpha, color, audio bus (task-lenses section 3).
5. Before starting, write out a "capability division of labor table" (template in task-lenses section 4), show it to the user in the first reply, then execute. No need to wait for confirmation.

For editing-type tasks (footage already provided, mainly editing and post-processing), see task-lenses section 6: techniques decomposed into common components and the "signal → technique" rules in references/editing-grammar.md; the signals and fields to be output at the comprehension layer are in references/edit-signals.md. Both are currently inferences—use them as starting points, and decide at the end whether they can be upgraded.

For camera-level motion grammar (openings, transitions, title cards, UI entrances, closings), after selecting Remotion, refer to the external recipe library index references/shot-vocabulary.md: search by functional slot and energy to find cards, then go to the repo to read the full card and demo source; it comes from the product trailer context and is not locally verified.

references/composition-patterns.md records how historical cases were actually combined, useful for inspiration and estimating costs. They are solutions for those specific tasks, not templates: before copying, confirm that your task constraints are the same as theirs.

3. Execution: Craft & Pitfalls

• Cross-tool practices (acceptance-first, single authority for time, frame as pure function of t, layered review, paid three-piece set, audio conventions, etc.) are in references/craft-lessons.md.
• Known pitfalls grouped by tool are in references/pitfalls.md. Before using a tool, scan its group.
• The invocation method for specific tools is governed by the corresponding Skill (each atlas card lists the entry point); this handbook does not repeat their command details.

4. Wrap-up: First Judge Whether It's Worth Distilling, Then Decide on Writeback

The handbook grows through cases, but not every case needs to be written back: details that only repeat existing entries or are only applicable to this specific piece will only dilute the handbook. When delivering the video (or aborting the task), follow references/writeback.md section 1 to list candidates, pass through the three gates (reusability, non-deducibility, cost), and only count those that pass with evidence. If they can be merged into existing entries, don't create new ones.

• If one or more count: Write back per writeback section 2: new-case to create a case card → distill into the corresponding file (if the permanent layer is full, write into references/lessons-backlog.md) → check → close. If there's no time to distill, leave the card in inbox; the next status will remind you.
• If none count: Skip writeback, do not create a case card, do not register in the ledger. Also skip if the user says not to write back.

In the final delivery note, include one line titled Playbook Writeback, stating the conclusion: which files were modified, or that the case card is pending distillation, or "Skipped: ".

Neutrality Principles (Must Be Followed When Writing and Using the Handbook)

• Capability cards only state facts: what it's good at, what it's not good at, costs, certainty, verification source. Do not write ordering words like "default", "preferred", "recommended", "use first". playbook.py check will intercept such words.
• Card order follows media category, not ranking.
• If a tool was used well in a case, note it as "under what constraints, because of what reason it worked", not as "use it for this type of video".
• Capabilities not verified in local cases should still be included, marked as "installed but not verified" or "inferred". Do not omit because you haven't used it, and do not exaggerate because you have.
• Length also indicates bias: card fields have fixed length, feature lists and implementation details do not go into cards; tools used more frequently do not get more space because of it.
• If a record is found to introduce bias (e.g., a workspace note says "default to X"), rewrite it as a conditional sentence: under what constraints it is suitable.