hadi-got-motion

Hadi Got Motion

A motion studio in a skill: 12 motion styles, each with its own way of moving, and one taste bar. Every frame is built from real material: archive prints and photos, real typefaces, real data, real recordings. Code cuts, hinges, times and lights it; code never draws the art. The bar is Mr Pemberton's Mistake, a talking cut-out farce from Victorian engravings (references/case-pemberton.md).

Everything runs through one command, hgm (scripts/hgm here; after hgm install it's on the PATH). Every hgm command prints a short summary and writes details to files, so tokens go to taste, not plumbing. Read the Token budget section below before you start; it is part of the craft, not an afterthought.

Order of work: Tools check → Brief picker → Estimate → Setup → Direction → Voice → Assets → Animate → Review → Deliver. Never start construction before the brief and setup are done.

Resuming a film? Read the project's HANDOFF.md and run hgm state inside the project. Don't re-read the skill's references, old films or the whole film file.

0–1 · Tools check and brief picker (one exchange)

• Don't ask and don't explain. Run bash <this skill's folder>/scripts/hgm picker, adding --title "…" --duration 45 --concept "…" for anything already said. Call visualize read_me once with ["elicitation"], then show_widget with the printed loader exactly as printed.
• The answer line comes back as Motion graphic details — Tools: … · Title: … · Duration seconds: … · Pacing: 1–5 · Concept: … · Motion style: … · …. Only the concept is required: no title, name it; no duration, 30 s; no pacing, 3; no map look, no map.
• If anything was missing and they didn't pick "Not now", start hgm install in the background.
• Empty widget, no widget tool, an uploaded script, or a skipped form: see references/setup.md.

2 · Time estimate (straight after the answers)

hgm estimate --answers "<the answer line, verbatim>". Give its first two lines in one or two sentences, then start. Don't wait for an OK.

"Let Claude decide": end to end, no questions

When the style is "Let Claude decide" (or "you decide", "surprise me", or the form was skipped):

• Ask nothing more. Decide everything as a director: the style that serves the concept, the pace (3 unless the concept clearly wants calm or frenzy), a map only if the story travels through real places, a walk only in cut-out farce or paper theatre, the cast and voices, the script, and images from the archives (ChatGPT only if already connected).
• Re-run hgm estimate --style <id> --duration <s> --pace <1-5> --script write|have|none and tell them in two lines what you picked, why, and how long it will take.
• The one stop you can't skip is the ElevenLabs sign-in, if a voice is needed and nothing is connected yet. If it can't happen, make a type-and-music film.

3 · Setup (finish before any construction)

hgm install if needed, then hgm new <slug> --style <id> --pace <1-5> (ids: cutout-farce, kinetic-editorial, kinetic-swiss, editorial-collage, period-print, paper-theatre, real-maps, stat-hits, footage-led, silent-film, title-sequence, object-diorama), then hgm doctor. ElevenLabs sign-in (hgm connect-voice) and ChatGPT images (hgm connect-images) have exact wording in references/setup.md; follow it word for word and never handle a key. All green → say "Setup done" in one line.

4 · Direction

• hgm ref <style-id> prints everything this style needs in one go: its section of styles.md, its motion language, the rules under all styles, and taste.md (the bar and the anti-AI-look checklist). Don't open whole reference files.
• Facts need research, never guesswork. If the film states facts (history, science, people, numbers, "what would happen if"), a subagent researches it into FACTS.md before any script is written: hgm ref research. Script only from confirmed facts; drama comes from the true specifics.
• No script given: pitch 3 concepts in one message (a character in a situation, a 1.5 s hook, an escalation to a payoff) and kill the safest one yourself. Under "Let Claude decide", don't pitch: pick the strongest and go. Words per 30 s come from the pace (pacing.json words30: 50 at pace 1, 66 at 3, 82 at 5). End on the payoff line.
• Plan the scenery. Write a scene plan in BRIEF.md: one line per scene with its time range, place and how it changes. The world changes every scenery seconds of the pace unless the story needs one place. A new prop on the same backdrop is not a change (taste.md, "Scenery").
• Lock the world in BRIEF.md with five rules: palette (2–3 colours plus one accent per beat), print or line, texture (one grain), light, lettering (one family).

5 · Voice: the voice is the clock (skip for "no voiceover")

• hgm voices --list → cast in audio/cast.json → audio/script.json (text carries the acting in [audio tags], caption is the clean on-screen text, gap_after leaves room for action).
• hgm voice-all prints one summary line plus any ✗ lines (full log: review/voice.log). Fix ✗ lines with skip_start, the caption, or hgm voices <id>. Details: hgm ref elevenlabs.

6 · Assets: online first, then ChatGPT

• Delegate the mechanical part to a subagent (Agent tool, model: "sonnet"): give it the list of visuals, the BRIEF world rules and the commands hgm assets <key> "query" … (images) and hgm assets --audio <key> "query" (sounds). It returns, per key, its top 3 candidates in one combined sheet and a short text list. You view that one sheet small and choose; then hgm pick <key>:<n>:<name> (you or the subagent) downloads and logs the credit. Sources: hgm ref sources.
• Only what the archives can't give goes to ChatGPT (hgm img inbox/<name>.png "<prompt>", or a prompt pack): hgm ref imagegen.
• Maps: hgm map-data … then hgm map-reel: hgm ref maps. Never draw or guess geography.
• Cut and rig in assets/build_assets.py (hgm grid, hgm zoom, hgm cut, hgm explode; recipe: hgm ref cutout-farce-recipe). A subagent can do the coordinate reading and cutting; you check the single explode sheet.

7 · Animate

• Build in <slug>.mjs (the scaffold). hgm api lists every helper with its signature: use it instead of reading the scaffold or old films. Keep the timeline helpers; replace the DEMO block.
• One state object with at(sec, {key: [from, to]}, dur, ease). Every action gets an SFX cue; captions are keyed to words. at() scales every duration by the pace (PC.k); cut and change scenery on PC.shot and PC.scenery. hgm voice-all applies the pace's narrator tempo and gaps.
• Move the way the style moves (its frame rate, what steps on twos or threes, its easing, camera, transitions). The scaffold already applies the profile. Never give every style the same smooth ease-in-out: that sameness is the AI tell.
• Walks belong to cut-out farce (and paper theatre's hop and glide): walk(style, t, {facing}), hgm ref walks, hgm walks for the reel.
• Write the film file once, then change it with small Edits. Never rewrite the whole file to change a scene.
• Traps to avoid: hgm ref traps before the first build.

8 · Review: look like a designer (this is where tokens are worth spending)

• hgm stills 0,1,3,6,10,... (12–18 times, including mid-action) writes review/contact.jpg. View it once and judge it against the taste checklist: hook at 0, 1, 3 and 10 s; one hero per beat; nothing covering a face; nothing just "present"; does the scenery change on the plan, or do frames in a row share one backdrop?; would anyone guess AI made it?
• Fix all you found in one pass, then hgm stills only the changed moments. Zoom (hgm zoom) only into the one thing you're judging.

9 · Build and deliver

• hgm build (render, mix, mux; run it in the background), then hgm frames 0.2,<mid>,<end> and look at the frames from the final MP4. hgm cover <t> makes a plain, no-type cover.
• Send the MP4 and cover (SendUserFile). Say the length, any changes from the brief, and what you couldn't verify (Claude can't listen: the mix was checked by levels and timings).
• Keep CREDITS.md complete. Notes come back surgical: apply exactly those, re-check those frames, rebuild.

Token budget

Measured on the first three films (Pemberton 338 turns, Hyderabad 116, Wright brothers 72): every turn re-reads the whole conversation, so cost is turns × context size. The chat starts at about 90K tokens before anything happens. A screenshot, a sheet or a cat stays in context and is paid again on every later turn. So:

• Fewer turns. Batch independent commands into one tool call (hgm stills … && hgm frames …). Plan a fix list, then apply it in one pass.
• Small outputs. Use hgm commands, not cat, ls or sed on references, old films or logs. hgm ref, hgm api and hgm state print only what's needed. Never print JSON, the full voice list twice, or the film file. Redirect long tool output to a file and tail -3 it.
• Small images, few of them. One contact sheet per review round; 220 px frames are enough to judge. Never Read raw stills, raw downloads or full-size frames; zoom into a crop instead.
• Subagents for mechanical work (model: "sonnet"): asset search and download, cutting and rigging checks, renders, credits. They return a short list and one sheet. Keep the main model for the concept, script, style, picks and the designer's review.
• Hand over before the context gets heavy. At about 200K tokens of context (or 40% of the window, whichever comes first; roughly 50 tool calls in), finish the current step, run hgm handoff, fill in its "Next" lines, and tell the user: "Continue in a new chat: continue <slug>." A fresh chat resumes from HANDOFF.md and hgm state for about 5K tokens.

Phase	Main-chat turns	Context it may add
Picker + estimate	≤ 4	≤ 8K (the visualize guide is most of it)
Setup	≤ 3	≤ 2K
Research (subagent writes FACTS.md)	≤ 2	≤ 3K (you read FACTS.md, never the search results)
Direction (+ hgm ref)	≤ 6	≤ 12K
Voice	≤ 4	≤ 4K
Assets (subagent does the search)	≤ 6	≤ 10K (one combined sheet + one explode sheet)
Animate (film written once)	≤ 8	≤ 25K (the film file you write)
Review (≤ 4 contact sheets)	≤ 12	≤ 12K
Build + deliver	≤ 4	≤ 4K
Whole film	≤ 50	ends under ~180K

Spend freely on the concept, the style choice and the designer's review. They make the film; the budget comes out of plumbing, never out of looking.

Non-negotiables

• Voices: ElevenLabs only.
• Images: archives first; ChatGPT images when needed. Never Higgsfield. No AI video. Never draw characters, illustrations or emblems in code.
• Engine: canvas + anime.js + FFmpeg. three.js only for true 3D; Blender only if physical light is the idea.
• Credits and keys: credit every source. Never put the user's email or personal details in requests. Never print keys.