npm - takomi - Versions diffs - 2.5.1 → 2.5.4 - Mend

takomi 2.5.1 → 2.5.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (661) hide show

package/assets/.agent/skills/hyperframes-core/references/sub-compositions.md CHANGED Viewed

@@ -1,237 +1,237 @@
-# Sub-Compositions
-A sub-composition is a separate HTML file embedded in a host composition. HyperFrames loads it, seeks it independently, and composites the result into the host at `data-start`.
-## Host Wiring
-In the host composition, the sub-composition appears as a clip with `data-composition-src`:
-```html
-<div
-  id="chart"
-  data-composition-id="data-chart"
-  data-composition-src="compositions/data-chart.html"
-  data-start="2"
-  data-duration="8"
-  data-track-index="2"
-  data-width="1920"
-  data-height="1080"
-></div>
-```
-- `data-composition-id` on the host must match the internal `data-composition-id` of the file at `data-composition-src`.
-- The host clip needs its own `data-start`, `data-duration`, `data-track-index`, `data-width`, `data-height`.
-## Sub-Composition File Structure
-### Mental model — what the runtime actually does
-When a host loads a sub-composition via `data-composition-src`, the runtime:
-1. `fetch`es the HTML file.
-2. Parses it with `DOMParser`.
-3. **Finds the `<template>` element and clones ONLY its contents into the host slot.**
-4. Everything **outside** the `<template>` (including the entire `<head>`) is **discarded**.
-So `<template>` is not just a wrapper — it is the **transport container**. If a node needs to exist in the live render, it must be inside `<template>`. Full stop.
-### File shape
-```html
-<!doctype html>
-<html>
-  <head>
-    <meta charset="UTF-8" />
-    <!-- head is metadata for the source file only; the runtime ignores it -->
-  </head>
-  <body>
-    <template>
-      <!-- EVERYTHING the runtime needs goes here: styles, markup, scripts -->
-      <style>
-        /* Root: style by #root, never a class. (At render the CSS is scoped to
-           data-composition-id, so a class on the root stops matching — see Pitfall 3.) */
-        #root {
-          position: absolute;
-          inset: 0;
-          color: #fff;
-        }
-        /* .label, #bar, … — descendants, plain selectors */
-      </style>
-      <div id="root" data-composition-id="data-chart" data-width="1920" data-height="1080">
-        <!-- sub-composition markup -->
-      </div>
-      <script>
-        window.__timelines = window.__timelines || {};
-        const tl = gsap.timeline({ paused: true });
-        // ... build timeline ...
-        window.__timelines["data-chart"] = tl;
-      </script>
-    </template>
-  </body>
-</html>
-```
-Contrast with **standalone** compositions, which put the root directly in `<body>` with no `<template>` wrapper.
-## Common pitfalls that pass static checks but break at render
-`lint`, `validate`, and `inspect` evaluate each file in isolation. These two failures live in the **cross-file mount contract** and cannot be caught until the runtime actually tries to mount the sub-composition. Watch for them at author time and verify with the pre-render checklist below.
-### Pitfall 1 — `<style>` in `<head>` instead of inside `<template>`
-```html
-<!-- ❌ WRONG — looks normal, ships catastrophically broken -->
-<head>
-  <style>
-    #root { font-size: 88px; ... }
-  </style>
-</head>
-<body>
-  <template>
-    <div id="root" data-composition-id="data-chart" ...>...</div>
-  </template>
-</body>
-<!-- ✅ RIGHT — styles are inside the template, root styled by #root (see Pitfall 3) -->
-<head></head>
-<body>
-  <template>
-    <style>
-      #root { font-size: 88px; ... }
-    </style>
-    <div id="root" data-composition-id="data-chart" ...>...</div>
-  </template>
-</body>
-```
-**Why this happens:** standard HTML conventions tell you to put `<style>` in `<head>`. In a standalone HTML file that's correct. In a HyperFrames sub-composition it is **not** — the runtime only clones `<template>` contents, so `<head><style>` is dropped on the floor.
-**Symptom:** the composition lints / validates / inspects clean, the render completes, but every text element shows up as tiny unstyled default text in the top-left and SVGs blow up to canvas-size because none of the CSS reached the live DOM. The same trap applies to `<script>` blocks, `<link rel="stylesheet">`, custom-element registrations — anything that needs to execute or apply in the render must be inside `<template>`.
-### Pitfall 2 — Host `data-composition-id` ≠ inner template `data-composition-id`
-```html
-<!-- ❌ WRONG — host renames the slot; runtime can't find the timeline -->
-<!-- host file (e.g. index.html) -->
-<div data-composition-id="chart-mount" data-composition-src="compositions/chart.html" ...></div>
-<!-- chart.html -->
-<template>
-  <div data-composition-id="data-chart" ...>...</div>
-  <script>
-    window.__timelines["data-chart"] = tl;
-  </script>
-</template>
-<!-- ✅ RIGHT — both ids match, and the timeline key matches them too -->
-<div data-composition-id="data-chart" data-composition-src="compositions/chart.html" ...></div>
-<!-- chart.html template root: data-composition-id="data-chart" -->
-<!-- timeline: window.__timelines["data-chart"] = tl; -->
-```
-**Why this happens:** it feels natural to give the host slot a different name like `chart-mount` ("the mount point") vs `data-chart` ("the actual chart"). HyperFrames does not work that way — **the host's `data-composition-id` is the lookup key the framework uses to find the registered timeline**. Lint passes because each file's ids are individually valid; the cross-file mismatch only blows up at render.
-**Symptom:** the render logs `Sub-composition timelines not registered after 45000ms: <host-id>` for every mismatched slot, waits 45s per scene, then captures static initial-state frames (so the video is full-length but no animation plays).
-### Pitfall 3 — Styling the root by a class instead of `#root`
-```html
-<!-- ❌ WRONG — class on the root, stylesheet keyed off it -->
-<template>
-  <style>
-    .frame {
-      position: absolute;
-      inset: 0;
-      background: #faf9f5;
-    }
-    .frame .title {
-      font-size: 120px;
-    }
-  </style>
-  <div id="root" class="frame" data-composition-id="03-scene" ...>
-    <div class="title">…</div>
-  </div>
-</template>
-<!-- ✅ RIGHT — root styled by #root, descendants by plain selectors -->
-<template>
-  <style>
-    #root {
-      position: absolute;
-      inset: 0;
-      background: #faf9f5;
-    }
-    .title {
-      font-size: 120px;
-    }
-  </style>
-  <div id="root" data-composition-id="03-scene" ...>
-    <div class="title">…</div>
-  </div>
-</template>
-```
-**Why this happens:** when sub-compositions are inlined into one composited render, the compiler **scopes each file's CSS to its own `data-composition-id`** so scenes can't leak styles into each other — every rule `S` becomes `[data-composition-id="<id>"] S` (a _descendant_ selector). A rule whose leftmost selector is the **root's own class** (`.frame`) therefore becomes `[data-composition-id="<id>"] .frame`, which cannot match the root (the root _is_ the scoped element, not a descendant of it), so **every `.frame…` rule silently drops**. `#root` is special-cased by the scoper and keeps matching the root; plain descendant selectors (`.title`) match normally. The per-scene class namespace is also just redundant — the `data-composition-id` scope already isolates each scene's styles.
-**Symptom:** _identical_ to Pitfall 1 — tiny unstyled text in the top-left, images at natural size, inline styles (e.g. a card background) the only thing surviving. The trap: this passes `lint`/`validate`/`inspect` (they evaluate the file in isolation, unscoped) **and looks perfect in `preview`** (Studio mounts each scene in its own iframe, also unscoped) — it only breaks in the composited MP4 render. Lint rule `subcomposition_root_styled_by_class` flags it; the registry blocks (e.g. `apple-money-count`) model the `#root` pattern.
-### Verification checklist before render
-```bash
-# For every sub-composition file in compositions/:
-#   1) <style> + <script> + main markup all live INSIDE <template>
-grep -n "<style\|<script\|<template" compositions/<scene>.html
-#      → first <style>/<script>/<div data-composition-id> should be AFTER <template>, before </template>
-#   2) host data-composition-id == internal data-composition-id == window.__timelines key
-grep "data-composition-id" index.html
-grep "data-composition-id\|__timelines\[" compositions/<scene>.html
-#      → all three strings must match exactly per scene
-#   3) the root is styled by #root, not by a class on the data-composition-id element
-grep -n 'data-composition-id=' compositions/<scene>.html
-#      → that element should NOT also carry a class="…" that the <style> keys off
-#        (e.g. `.frame { … }`); scoping drops it. Style the root via #root. See Pitfall 3.
-```
-For the runtime end-to-end check (a fast `snapshot` pass + per-scene frame eyeball), see the **Visual smoke test** step in `hyperframes-cli`'s Minimum Completion Gate — that is the only gate that catches these three pitfalls.
-## What HyperFrames Does With the Sub-Composition
-- Loads the file and registers its timeline under its internal `data-composition-id`.
-- Seeks the sub-composition's timeline independently from the host's playhead.
-- Plays the sub-composition's content from `data-start` of the host clip, for `data-duration` seconds.
-**Do not** manually `master.add(child)` a sub-composition timeline into the host timeline. HyperFrames already drives them independently — nesting them in GSAP causes double-seeks.
-### The host clip's `data-duration` is the slot's visible window
-`data-duration` on the host clip defines **how long the slot is visible**, and it takes precedence over the sub-composition's internal GSAP timeline length. Two consequences follow:
-- **Internal timeline shorter than the slot → the slot holds.** If the sub-composition's GSAP timeline finishes before `data-duration` elapses, the slot keeps showing its final frame for the rest of the window. You do **not** need to pad the timeline with empty tweens.
-- **`data-duration` shorter than the host composition → the slot ends (and goes blank) when its own `data-duration` elapses.** This is intended: the clip is a fixed-length window on the timeline, not "fill until the composition ends." To keep a sub-composition visible for the whole composition, set its `data-duration` to span the host window (or add another clip to cover the remaining time). Leaving a single full-bleed sub-composition shorter than the composition is almost always a mistake — the linter flags it as `subcomposition_blanks_before_host`.
-## Animations Inside Sub-Compositions
-Prefer `gsap.fromTo()` over `gsap.from()` for entrance tweens. The host re-seeks the sub-composition every time its clip becomes visible; `gsap.from()` records the starting state at registration and can desync on seek-back, while `gsap.fromTo()` declares both endpoints explicitly and replays cleanly.
-## Per-Instance Variables
-If the sub-composition declares variables on its `<html>` element (`data-composition-variables`), the host can override values per instance:
-```html
-<div
-  data-composition-id="data-chart"
-  data-composition-src="compositions/data-chart.html"
-  data-variable-values='{"title":"Q4 Revenue","accent":"#66d9ef"}'
-  data-start="2"
-  data-duration="8"
-  data-track-index="2"
-  data-width="1920"
-  data-height="1080"
-></div>
-```
-The host can render the same sub-composition multiple times with different `data-variable-values` to produce per-instance variations. See `variables-and-media.md` for variable declaration syntax.
+# Sub-Compositions
+A sub-composition is a separate HTML file embedded in a host composition. HyperFrames loads it, seeks it independently, and composites the result into the host at `data-start`.
+## Host Wiring
+In the host composition, the sub-composition appears as a clip with `data-composition-src`:
+```html
+<div
+  id="chart"
+  data-composition-id="data-chart"
+  data-composition-src="compositions/data-chart.html"
+  data-start="2"
+  data-duration="8"
+  data-track-index="2"
+  data-width="1920"
+  data-height="1080"
+></div>
+```
+- `data-composition-id` on the host must match the internal `data-composition-id` of the file at `data-composition-src`.
+- The host clip needs its own `data-start`, `data-duration`, `data-track-index`, `data-width`, `data-height`.
+## Sub-Composition File Structure
+### Mental model — what the runtime actually does
+When a host loads a sub-composition via `data-composition-src`, the runtime:
+1. `fetch`es the HTML file.
+2. Parses it with `DOMParser`.
+3. **Finds the `<template>` element and clones ONLY its contents into the host slot.**
+4. Everything **outside** the `<template>` (including the entire `<head>`) is **discarded**.
+So `<template>` is not just a wrapper — it is the **transport container**. If a node needs to exist in the live render, it must be inside `<template>`. Full stop.
+### File shape
+```html
+<!doctype html>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <!-- head is metadata for the source file only; the runtime ignores it -->
+  </head>
+  <body>
+    <template>
+      <!-- EVERYTHING the runtime needs goes here: styles, markup, scripts -->
+      <style>
+        /* Root: style by #root, never a class. (At render the CSS is scoped to
+           data-composition-id, so a class on the root stops matching — see Pitfall 3.) */
+        #root {
+          position: absolute;
+          inset: 0;
+          color: #fff;
+        }
+        /* .label, #bar, … — descendants, plain selectors */
+      </style>
+      <div id="root" data-composition-id="data-chart" data-width="1920" data-height="1080">
+        <!-- sub-composition markup -->
+      </div>
+      <script>
+        window.__timelines = window.__timelines || {};
+        const tl = gsap.timeline({ paused: true });
+        // ... build timeline ...
+        window.__timelines["data-chart"] = tl;
+      </script>
+    </template>
+  </body>
+</html>
+```
+Contrast with **standalone** compositions, which put the root directly in `<body>` with no `<template>` wrapper.
+## Common pitfalls that pass static checks but break at render
+`lint`, `validate`, and `inspect` evaluate each file in isolation. These two failures live in the **cross-file mount contract** and cannot be caught until the runtime actually tries to mount the sub-composition. Watch for them at author time and verify with the pre-render checklist below.
+### Pitfall 1 — `<style>` in `<head>` instead of inside `<template>`
+```html
+<!-- ❌ WRONG — looks normal, ships catastrophically broken -->
+<head>
+  <style>
+    #root { font-size: 88px; ... }
+  </style>
+</head>
+<body>
+  <template>
+    <div id="root" data-composition-id="data-chart" ...>...</div>
+  </template>
+</body>
+<!-- ✅ RIGHT — styles are inside the template, root styled by #root (see Pitfall 3) -->
+<head></head>
+<body>
+  <template>
+    <style>
+      #root { font-size: 88px; ... }
+    </style>
+    <div id="root" data-composition-id="data-chart" ...>...</div>
+  </template>
+</body>
+```
+**Why this happens:** standard HTML conventions tell you to put `<style>` in `<head>`. In a standalone HTML file that's correct. In a HyperFrames sub-composition it is **not** — the runtime only clones `<template>` contents, so `<head><style>` is dropped on the floor.
+**Symptom:** the composition lints / validates / inspects clean, the render completes, but every text element shows up as tiny unstyled default text in the top-left and SVGs blow up to canvas-size because none of the CSS reached the live DOM. The same trap applies to `<script>` blocks, `<link rel="stylesheet">`, custom-element registrations — anything that needs to execute or apply in the render must be inside `<template>`.
+### Pitfall 2 — Host `data-composition-id` ≠ inner template `data-composition-id`
+```html
+<!-- ❌ WRONG — host renames the slot; runtime can't find the timeline -->
+<!-- host file (e.g. index.html) -->
+<div data-composition-id="chart-mount" data-composition-src="compositions/chart.html" ...></div>
+<!-- chart.html -->
+<template>
+  <div data-composition-id="data-chart" ...>...</div>
+  <script>
+    window.__timelines["data-chart"] = tl;
+  </script>
+</template>
+<!-- ✅ RIGHT — both ids match, and the timeline key matches them too -->
+<div data-composition-id="data-chart" data-composition-src="compositions/chart.html" ...></div>
+<!-- chart.html template root: data-composition-id="data-chart" -->
+<!-- timeline: window.__timelines["data-chart"] = tl; -->
+```
+**Why this happens:** it feels natural to give the host slot a different name like `chart-mount` ("the mount point") vs `data-chart` ("the actual chart"). HyperFrames does not work that way — **the host's `data-composition-id` is the lookup key the framework uses to find the registered timeline**. Lint passes because each file's ids are individually valid; the cross-file mismatch only blows up at render.
+**Symptom:** the render logs `Sub-composition timelines not registered after 45000ms: <host-id>` for every mismatched slot, waits 45s per scene, then captures static initial-state frames (so the video is full-length but no animation plays).
+### Pitfall 3 — Styling the root by a class instead of `#root`
+```html
+<!-- ❌ WRONG — class on the root, stylesheet keyed off it -->
+<template>
+  <style>
+    .frame {
+      position: absolute;
+      inset: 0;
+      background: #faf9f5;
+    }
+    .frame .title {
+      font-size: 120px;
+    }
+  </style>
+  <div id="root" class="frame" data-composition-id="03-scene" ...>
+    <div class="title">…</div>
+  </div>
+</template>
+<!-- ✅ RIGHT — root styled by #root, descendants by plain selectors -->
+<template>
+  <style>
+    #root {
+      position: absolute;
+      inset: 0;
+      background: #faf9f5;
+    }
+    .title {
+      font-size: 120px;
+    }
+  </style>
+  <div id="root" data-composition-id="03-scene" ...>
+    <div class="title">…</div>
+  </div>
+</template>
+```
+**Why this happens:** when sub-compositions are inlined into one composited render, the compiler **scopes each file's CSS to its own `data-composition-id`** so scenes can't leak styles into each other — every rule `S` becomes `[data-composition-id="<id>"] S` (a _descendant_ selector). A rule whose leftmost selector is the **root's own class** (`.frame`) therefore becomes `[data-composition-id="<id>"] .frame`, which cannot match the root (the root _is_ the scoped element, not a descendant of it), so **every `.frame…` rule silently drops**. `#root` is special-cased by the scoper and keeps matching the root; plain descendant selectors (`.title`) match normally. The per-scene class namespace is also just redundant — the `data-composition-id` scope already isolates each scene's styles.
+**Symptom:** _identical_ to Pitfall 1 — tiny unstyled text in the top-left, images at natural size, inline styles (e.g. a card background) the only thing surviving. The trap: this passes `lint`/`validate`/`inspect` (they evaluate the file in isolation, unscoped) **and looks perfect in `preview`** (Studio mounts each scene in its own iframe, also unscoped) — it only breaks in the composited MP4 render. Lint rule `subcomposition_root_styled_by_class` flags it; the registry blocks (e.g. `apple-money-count`) model the `#root` pattern.
+### Verification checklist before render
+```bash
+# For every sub-composition file in compositions/:
+#   1) <style> + <script> + main markup all live INSIDE <template>
+grep -n "<style\|<script\|<template" compositions/<scene>.html
+#      → first <style>/<script>/<div data-composition-id> should be AFTER <template>, before </template>
+#   2) host data-composition-id == internal data-composition-id == window.__timelines key
+grep "data-composition-id" index.html
+grep "data-composition-id\|__timelines\[" compositions/<scene>.html
+#      → all three strings must match exactly per scene
+#   3) the root is styled by #root, not by a class on the data-composition-id element
+grep -n 'data-composition-id=' compositions/<scene>.html
+#      → that element should NOT also carry a class="…" that the <style> keys off
+#        (e.g. `.frame { … }`); scoping drops it. Style the root via #root. See Pitfall 3.
+```
+For the runtime end-to-end check (a fast `snapshot` pass + per-scene frame eyeball), see the **Visual smoke test** step in `hyperframes-cli`'s Minimum Completion Gate — that is the only gate that catches these three pitfalls.
+## What HyperFrames Does With the Sub-Composition
+- Loads the file and registers its timeline under its internal `data-composition-id`.
+- Seeks the sub-composition's timeline independently from the host's playhead.
+- Plays the sub-composition's content from `data-start` of the host clip, for `data-duration` seconds.
+**Do not** manually `master.add(child)` a sub-composition timeline into the host timeline. HyperFrames already drives them independently — nesting them in GSAP causes double-seeks.
+### The host clip's `data-duration` is the slot's visible window
+`data-duration` on the host clip defines **how long the slot is visible**, and it takes precedence over the sub-composition's internal GSAP timeline length. Two consequences follow:
+- **Internal timeline shorter than the slot → the slot holds.** If the sub-composition's GSAP timeline finishes before `data-duration` elapses, the slot keeps showing its final frame for the rest of the window. You do **not** need to pad the timeline with empty tweens.
+- **`data-duration` shorter than the host composition → the slot ends (and goes blank) when its own `data-duration` elapses.** This is intended: the clip is a fixed-length window on the timeline, not "fill until the composition ends." To keep a sub-composition visible for the whole composition, set its `data-duration` to span the host window (or add another clip to cover the remaining time). Leaving a single full-bleed sub-composition shorter than the composition is almost always a mistake — the linter flags it as `subcomposition_blanks_before_host`.
+## Animations Inside Sub-Compositions
+Prefer `gsap.fromTo()` over `gsap.from()` for entrance tweens. The host re-seeks the sub-composition every time its clip becomes visible; `gsap.from()` records the starting state at registration and can desync on seek-back, while `gsap.fromTo()` declares both endpoints explicitly and replays cleanly.
+## Per-Instance Variables
+If the sub-composition declares variables on its `<html>` element (`data-composition-variables`), the host can override values per instance:
+```html
+<div
+  data-composition-id="data-chart"
+  data-composition-src="compositions/data-chart.html"
+  data-variable-values='{"title":"Q4 Revenue","accent":"#66d9ef"}'
+  data-start="2"
+  data-duration="8"
+  data-track-index="2"
+  data-width="1920"
+  data-height="1080"
+></div>
+```
+The host can render the same sub-composition multiple times with different `data-variable-values` to produce per-instance variations. See `variables-and-media.md` for variable declaration syntax.

package/assets/.agent/skills/hyperframes-core/references/subagent-dispatch.md CHANGED Viewed

@@ -1,41 +1,41 @@
-# Subagent dispatch — harness adapter
-The video workflows (`product-launch-video` / `faceless-explainer` / `pr-to-video` / `motion-graphics` / `general-video`) describe subagent dispatch in harness-neutral verbs. This file maps those verbs to the primitives of whatever agent harness you are running on. Read it once per run, before the first dispatch; everything else in the workflows (dispatch packets, file artifacts, exit-code gates, Resume tables) is harness-independent and needs no translation.
-## The contract (identical on every harness)
-- **DISPATCH(role_file, dispatch_context)** — start one child agent whose prompt is the **full contents of the named `agents/<role>.md` file** followed by the `## Dispatch context` block from the workflow, copied **verbatim** (never digested or paraphrased). Every harness below accepts arbitrary task text, so this works everywhere; never rely on the child seeing your conversation, memory, or skills — the prompt and the files on disk are its entire world.
-- **Parallel fan-out** — when a step says "start N workers in parallel", the workers are mutually independent (no ordering, no shared state beyond the filesystem). Run as many concurrently as your harness allows.
-- **WAIT** — a step's completion criterion is always **the expected artifact existing on disk** (e.g. `compositions/<scene-id>.html`), never the harness's completion notification (some harnesses deliver results best-effort). After waiting, verify the artifacts; a missing artifact means that child failed — re-dispatch it once with the same prompt before surfacing an error.
-## Concurrency cap → batching rule (cap never changes scope)
-A harness concurrency limit **reduces parallelism, not work**: every scene still gets built, one scene per dispatch, with the available slots chewing through the full list.
-- Harness queues excess children internally (Claude Code; Hermes `delegate_task` beyond `max_concurrent_children`) → submit **all N at once** and let the queue drain.
-- Harness hard-caps active children (e.g. OpenClaw `maxChildrenPerAgent`) → dispatch in **waves of the cap size**: start `cap` workers, wait for their artifacts, start the next wave, until all N scenes exist. Example: 9 scenes on a cap-3 harness = 3 waves of 3 — never drop scenes, never merge scenes into one worker to fit the cap.
-## Primitive map
-| Verb in the workflows            | Claude Code                                                         | Codex CLI                                                                                   | OpenClaw                                                                               | Hermes Agent                                                                                                   |
-| -------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| DISPATCH                         | `Agent` tool, `subagent_type: "general-purpose"`                    | `spawn_agent` (built-in `worker` role; prompt carries the role file)                        | `sessions_spawn` (role file rides in `task`; child only auto-loads AGENTS.md/TOOLS.md) | `delegate_task` — put role file + context into each task's `context` (child system prompt is not customizable) |
-| parallel fan-out                 | multiple Agent calls in one message, each `run_in_background: true` | multiple `spawn_agent` calls (async by design) or `spawn_agents_on_csv` for uniform batches | repeated `sessions_spawn` (always non-blocking)                                        | one `delegate_task(tasks=[...])` batch call                                                                    |
-| WAIT                             | background-task completion notifications arrive automatically       | `wait_agent` with all child IDs                                                             | `sessions_yield` (never poll session lists)                                            | `delegate_task` returns when all tasks finish (blocking the turn is normal)                                    |
-| default concurrency              | min(16, cores − 2), excess queues                                   | 6 (`agents.max_threads`)                                                                    | 5 active per session, 8 global                                                         | 3 (`delegation.max_concurrent_children`)                                                                       |
-| re-dispatch after a gate failure | new Agent call, same prompt + the error/`## Repair context`         | new `spawn_agent`, same prompt + the error                                                  | new `sessions_spawn`, same `task` + the error                                          | new `delegate_task`, same `context` + the error                                                                |
-Harness-specific notes:
-- **Codex**: children inherit the parent cwd and cannot change it — exactly what these pipelines need (shared `PROJECT_DIR`). Prefer prompt-carried roles over `.codex/agents/*.toml` registration; the workflows already deliver roles in the prompt. **Codex policy-gates spawning on the user explicitly requesting delegation — a skill instruction alone does not satisfy it, and you will be tempted to skip the tool without even trying.** Do not silently degrade: on Codex, if the user has not granted delegation this session, **ask one line** — "OK to run this workflow's workers as parallel subagents?" — **folded into the workflow's first existing user pause** (e.g. the API-key question) so the run pauses only once; at the latest, before the first dispatch step. An affirmative — or a standing grant in the workspace `AGENTS.md` or the kickoff prompt — unlocks native dispatch for the whole session. Only without a grant: prefer ladder rung 1 below (headless `codex exec` children) for the scene fan-out; inline serial is the last resort.
-- **OpenClaw**: result announcement is best-effort (lost on gateway restart) — the artifact-on-disk WAIT rule above is the source of truth, not the announce message.
-- **Hermes**: children get a fresh conversation and only see what you put in `context`, and only the final summary returns — both already match the workflows' design (dispatch packets carry everything; results land on disk). Requires a **local execution backend** (the pipelines exchange data through `PROJECT_DIR` and packet files on the shared filesystem; Docker/remote backends break that).
-- **Any other harness**, or subagents unavailable/disabled — degrade down this ladder:
-  1. Headless CLI children: write each child prompt to a file, start the CLI per worker as a background shell process (redirect stdin from /dev/null, output to a log), then collect artifacts from disk.
-  2. Inline serial execution: do each role yourself, one at a time — read the role file, follow it with the dispatch context as if you were the child, finish, then return to the runbook. Load only one role's resources at a time (a scene's role file + its packet), and still run every per-role self-check before moving on.
-## Vocabulary mapping (older phrasing you may meet in agent prompts)
-- "in the same message" / `run_in_background: true` — Claude Code idioms for "concurrently / as a background child"; apply your harness's equivalent from the table.
-- "Skill `X`" / "loaded with the Skill tool" — load skill X; on harnesses without a skill-loading tool, read `<skills-root>/X/SKILL.md` directly (the skills root is the directory containing this skill family; derive it from `SKILL_DIR` in your dispatch context).
-- `Read` / `Write` / `Edit` / `Bash` — capability names (read file / write file / edit in place / run shell); map to your harness's tools.
+# Subagent dispatch — harness adapter
+The video workflows (`product-launch-video` / `faceless-explainer` / `pr-to-video` / `motion-graphics` / `general-video`) describe subagent dispatch in harness-neutral verbs. This file maps those verbs to the primitives of whatever agent harness you are running on. Read it once per run, before the first dispatch; everything else in the workflows (dispatch packets, file artifacts, exit-code gates, Resume tables) is harness-independent and needs no translation.
+## The contract (identical on every harness)
+- **DISPATCH(role_file, dispatch_context)** — start one child agent whose prompt is the **full contents of the named `agents/<role>.md` file** followed by the `## Dispatch context` block from the workflow, copied **verbatim** (never digested or paraphrased). Every harness below accepts arbitrary task text, so this works everywhere; never rely on the child seeing your conversation, memory, or skills — the prompt and the files on disk are its entire world.
+- **Parallel fan-out** — when a step says "start N workers in parallel", the workers are mutually independent (no ordering, no shared state beyond the filesystem). Run as many concurrently as your harness allows.
+- **WAIT** — a step's completion criterion is always **the expected artifact existing on disk** (e.g. `compositions/<scene-id>.html`), never the harness's completion notification (some harnesses deliver results best-effort). After waiting, verify the artifacts; a missing artifact means that child failed — re-dispatch it once with the same prompt before surfacing an error.
+## Concurrency cap → batching rule (cap never changes scope)
+A harness concurrency limit **reduces parallelism, not work**: every scene still gets built, one scene per dispatch, with the available slots chewing through the full list.
+- Harness queues excess children internally (Claude Code; Hermes `delegate_task` beyond `max_concurrent_children`) → submit **all N at once** and let the queue drain.
+- Harness hard-caps active children (e.g. OpenClaw `maxChildrenPerAgent`) → dispatch in **waves of the cap size**: start `cap` workers, wait for their artifacts, start the next wave, until all N scenes exist. Example: 9 scenes on a cap-3 harness = 3 waves of 3 — never drop scenes, never merge scenes into one worker to fit the cap.
+## Primitive map
+| Verb in the workflows            | Claude Code                                                         | Codex CLI                                                                                   | OpenClaw                                                                               | Hermes Agent                                                                                                   |
+| -------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| DISPATCH                         | `Agent` tool, `subagent_type: "general-purpose"`                    | `spawn_agent` (built-in `worker` role; prompt carries the role file)                        | `sessions_spawn` (role file rides in `task`; child only auto-loads AGENTS.md/TOOLS.md) | `delegate_task` — put role file + context into each task's `context` (child system prompt is not customizable) |
+| parallel fan-out                 | multiple Agent calls in one message, each `run_in_background: true` | multiple `spawn_agent` calls (async by design) or `spawn_agents_on_csv` for uniform batches | repeated `sessions_spawn` (always non-blocking)                                        | one `delegate_task(tasks=[...])` batch call                                                                    |
+| WAIT                             | background-task completion notifications arrive automatically       | `wait_agent` with all child IDs                                                             | `sessions_yield` (never poll session lists)                                            | `delegate_task` returns when all tasks finish (blocking the turn is normal)                                    |
+| default concurrency              | min(16, cores − 2), excess queues                                   | 6 (`agents.max_threads`)                                                                    | 5 active per session, 8 global                                                         | 3 (`delegation.max_concurrent_children`)                                                                       |
+| re-dispatch after a gate failure | new Agent call, same prompt + the error/`## Repair context`         | new `spawn_agent`, same prompt + the error                                                  | new `sessions_spawn`, same `task` + the error                                          | new `delegate_task`, same `context` + the error                                                                |
+Harness-specific notes:
+- **Codex**: children inherit the parent cwd and cannot change it — exactly what these pipelines need (shared `PROJECT_DIR`). Prefer prompt-carried roles over `.codex/agents/*.toml` registration; the workflows already deliver roles in the prompt. **Codex policy-gates spawning on the user explicitly requesting delegation — a skill instruction alone does not satisfy it, and you will be tempted to skip the tool without even trying.** Do not silently degrade: on Codex, if the user has not granted delegation this session, **ask one line** — "OK to run this workflow's workers as parallel subagents?" — **folded into the workflow's first existing user pause** (e.g. the API-key question) so the run pauses only once; at the latest, before the first dispatch step. An affirmative — or a standing grant in the workspace `AGENTS.md` or the kickoff prompt — unlocks native dispatch for the whole session. Only without a grant: prefer ladder rung 1 below (headless `codex exec` children) for the scene fan-out; inline serial is the last resort.
+- **OpenClaw**: result announcement is best-effort (lost on gateway restart) — the artifact-on-disk WAIT rule above is the source of truth, not the announce message.
+- **Hermes**: children get a fresh conversation and only see what you put in `context`, and only the final summary returns — both already match the workflows' design (dispatch packets carry everything; results land on disk). Requires a **local execution backend** (the pipelines exchange data through `PROJECT_DIR` and packet files on the shared filesystem; Docker/remote backends break that).
+- **Any other harness**, or subagents unavailable/disabled — degrade down this ladder:
+  1. Headless CLI children: write each child prompt to a file, start the CLI per worker as a background shell process (redirect stdin from /dev/null, output to a log), then collect artifacts from disk.
+  2. Inline serial execution: do each role yourself, one at a time — read the role file, follow it with the dispatch context as if you were the child, finish, then return to the runbook. Load only one role's resources at a time (a scene's role file + its packet), and still run every per-role self-check before moving on.
+## Vocabulary mapping (older phrasing you may meet in agent prompts)
+- "in the same message" / `run_in_background: true` — Claude Code idioms for "concurrently / as a background child"; apply your harness's equivalent from the table.
+- "Skill `X`" / "loaded with the Skill tool" — load skill X; on harnesses without a skill-loading tool, read `<skills-root>/X/SKILL.md` directly (the skills root is the directory containing this skill family; derive it from `SKILL_DIR` in your dispatch context).
+- `Read` / `Write` / `Edit` / `Bash` — capability names (read file / write file / edit in place / run shell); map to your harness's tools.