motion-graphics Checked

| Phase | Execution | Primary artifact | Detailed flow |

| -------- | --------------------------------------------------------------------- | ---------------------------------------------------------------- | ----------------------------- |

| init | Bash | hyperframes.json | Step 0 |

| plan | subagent — **decide search?** + classify + asset strategy | shot-plan.json (draft: category, asset_needs queries, brief) | agents/director.md (Part 1) |

| source ◇ | Bash — media-use resolve (**skip if asset_needs is empty**) | assets/ + assets/index.md | phases/source/guide.md |

| design | subagent — shot design around resolved assets | shot-plan.json (final: block(s) + layout + motion + positions) | agents/director.md (Part 2) |

| build | subagent — reuse-first composition | compositions/index.html | agents/builder.md |

| render | Bash — hyperframes render (MP4, or --format webm/mov for overlay) | renders/video.mp4 | Step 5 |

| verify | Bash — lint / inspect -> repair subagent on failure | (fixes in place) | agents/finalize.md |

◇ source runs only when the chosen category declares assets. Pure code/text categories (e.g. kinetic-type, most charts/stat) have asset_needs: [] and skip straight from plan to design.

Categories — split by the search decision

plan's **first decision is: does this need a search?** That fork splits the categories into two groups; then the specific category is picked — for search-driven, **by the type of content the search returns**. Each category is one categories/<id>/module.md (its planning + build rules); the shared motion vocabulary lives in references/motion-vocabulary.md (→ hyperframes-animation rules/blueprints + registry blocks).

**Form categories — no search; the user supplies the content:**

| Category | Intent | Leans on |

| -------------- | ---------------------------------------------- | --------------------------------------------------------------------------- |

| kinetic-type | punchy line / quote / title, motion-first text | caption-* blocks + animation rules |

| stat | single hero number / count-up + ring | apple-money-count / rules/{counting-dynamic-scale, stat-bars-and-fills} |

| charts | bar / line / pie / race / % from data | data-chart block |

| logo-reveal | logo sting / brand lockup (user logo) | logo-outro / rules/svg-path-draw |

| lower-thirds | name / title bars, callouts, social overlays | caption-* + registry overlay blocks |

**Search-driven categories — search first, then animate by content type** (the RWA path):

| Returned content | Category | Animation |

| ---------------- | -------------- | -------------------------------------------------------------- |

| webpage / link | webpage | webpage / UI animation (scroll, reveal, cursor, callouts) |

| news article | news | headline reveal + source card + key-fact callouts |

| tweet | tweet | animated tweet card |

| image / entity | asset-fusion | the asset's geometry _becomes_ the chart (RWA diegetic fusion) |

Build order: one at a time, coverage-first (rough is fine). kinetic-type ported from the prototype; the rest follow.

Prerequisites

macOS Apple Silicon or Linux x64. System tools: brew install node ffmpeg. npx hyperframes doctor once. macOS GPU render: export PRODUCER_BROWSER_GPU_MODE=hardware.

Optional keys (local fallbacks if unset) — only needed by categories that source/generate assets via media-use:

| Key | Used for | Fallback |

| ----------------------------------- | ----------------------------------------------------------- | ------------------------------- |

| GEMINI_API_KEY / GOOGLE_API_KEY | image generation (media-use resolve) | skip generate / search-only |

| (asset_scout / search providers) | webpage/news/tweet + asset-fusion real-asset search | category degrades to asset-free |

Flow

### Step 0 — Initialize

cwd is the agent workspace root; write all artifacts under PROJECT_DIR = videos/<project-name>/. <project-name>: use the dir the user gave, else a short kebab-case name from the intent (<subject>-motion). Not the workspace basename or a timestamp.

Only when $PROJECT_DIR/hyperframes.json is absent:

PROJECT_DIR="${MOTION_GRAPHICS_DIR:-videos/<project-name>}"
mkdir -p "$(dirname "$PROJECT_DIR")"
npx hyperframes init "$PROJECT_DIR" --non-interactive --example=blank

init checks the installed skills against the latest on GitHub and updates the global set if any are out of date.

**Constraints:** never hyperframes init in the workspace root; never nest another hyperframes/ inside PROJECT_DIR; every Bash command (master + subagents) is a (cd "$PROJECT_DIR" && ...) subshell — never bare cd.

### Step 1 — Plan (subagent: Director Part 1)

Dispatch one subagent. prompt = full agents/director.md + ## Dispatch context (SKILL_DIR / PROJECT_DIR / the user's request / Schema: <SKILL_DIR>/references/shot-plan-ir.md). It must:

1. **Decide: does this need a search?** (the first fork)

• **No** → pick a **form category** (kinetic-type / stat / charts / logo-reveal / lower-thirds); content is user-supplied; asset_needs: [].
• **Yes** → emit a **search plan** into asset_needs[] (news / web / tweet / image; two-pole queries). The specific **search-driven category** (webpage / news / tweet / asset-fusion) is confirmed by the content type returned in Step 2, and finalized in Step 3.

2. Write a draft shot-plan.json (envelope + chosen form category _or_ search intent + asset_needs + a one-paragraph shot brief). Schema: references/shot-plan-ir.md.

Validation: [ -s "$PROJECT_DIR/shot-plan.json" ] && echo ok || echo missing.

### Step 2 — Source ◇ (Bash: media-use, conditional)

If shot-plan.json.asset_needs is non-empty, resolve assets (search / generate /