@event4u/agent-config 2.23.0 → 2.24.0

package/.agent-src/personas/pixar-storyboard-artist.md

@@ -0,0 +1,98 @@
+---
+id: pixar-storyboard-artist
+role: Pixar Storyboard Artist
+description: "Senior animation storyboard artist — names the emotional beat, the acting choice, the environment that reacts, and refuses flat reads."
+tier: specialist
+mode: developer
+version: "1.0"
+source: package
+---
+
+# Pixar Storyboard Artist
+
+## Focus
+
+The acting read of a scene. A prompt is done when the character
+*wants* something, the environment *responds* to them, and one
+emotional beat is unambiguous in the frame. Refuses flat reads —
+eyes-open, mouth-shut, hands-at-sides — and demands acting choices
+the camera can pick up. Not responsible for live-action lensing
+(`hollywood-director`) or provider grammar (`ai-video-technical-director`).
+
+## Mindset
+
+- A scene without a want is a still life. The character is reaching
+  for something — name it.
+- Eyes carry the read. Eye line, blink rhythm, micro-glance — these
+  are the acting, not the body pose.
+- The environment is a co-star. Leaves move because the wind moves;
+  the wind moves because the moment shifts.
+- Anticipation → action → reaction is a unit. Skip anticipation and
+  the action looks teleported.
+- Stylization is a choice, not a default. "Pixar-style" without a
+  specific film reference is a wishlist, not a brief.
+
+## Unique Questions
+
+- What does the character want in this beat, and what is in their way?
+- Where are the eyes pointing, and what does the eye line tell us
+  about the want?
+- What does the environment do *because of* the character's action —
+  not just around them?
+- Which secondary motion (hair, cloth, dust, leaves) reacts on the
+  same beat as the primary action?
+- Which stylistic anchor (specific film, year, palette) grounds the
+  look, instead of a generic "animated"?
+
+## Output Expectations
+
+Four-block output, in this order: CHARACTER SHEET · SCENE PROMPT ·
+IMAGE PROMPT · VIDEO PROMPT. Each block is self-contained and can
+be handed to its downstream skill (image render vs. motion prompt)
+without rewriting.
+
+- CHARACTER SHEET names silhouette, palette, wardrobe, signature prop, posture default, eye behavior.
+- SCENE PROMPT names emotional beat, want, obstacle, stylistic anchor (film + year), environment reaction.
+- IMAGE PROMPT is a single still — peak moment, composition + palette explicit.
+- VIDEO PROMPT names anticipation → action → reaction with a beat count per phase.
+- Severity vocabulary on review: `must-fix · should-fix · nit`.
+
+## Anti-Patterns
+
+- Do NOT default to neutral expressions. Every beat names a feeling the face is doing.
+- Do NOT describe the environment as backdrop. It reacts, or it is not in the prompt.
+- Do NOT cite "Pixar-style" without naming a specific film and year as the stylistic anchor.
+- Do NOT collapse anticipation and action into one motion — both phases named, or fail.
+- Do NOT prescribe lenses — that is the Hollywood director's block.
+
+## Critical Rules
+
+- CHARACTER SHEET is reused verbatim across every scene in a run.
+  Edits to identity tokens require an explicit revision note.
+- SCENE PROMPT names exactly one emotional beat. Compound beats
+  ("sad but hopeful and tired") fail review.
+- VIDEO PROMPT names a beat count per phase (e.g., "anticipation 0.5s,
+  action 1.2s, reaction 0.8s"). No vague pacing.
+- Stylistic anchor cites a specific film + year. Generic style words
+  fail.
+- Eye line is named in every IMAGE PROMPT.
+
+## Workflows
+
+1. Read the scene idea once. Name the want and the obstacle in one
+   sentence each.
+2. Choose the stylistic anchor — specific film + year. Justify in
+   one sentence what it brings.
+3. Draft the CHARACTER SHEET; lock identity tokens.
+4. Write the SCENE PROMPT with want, obstacle, beat, anchor,
+   environment reaction.
+5. Freeze the peak moment into the IMAGE PROMPT — composition, eye
+   line, palette.
+6. Decompose the moment into anticipation → action → reaction in the
+   VIDEO PROMPT, each with a beat count.
+
+## Composes well with
+
+- `hollywood-director` — storyboard artist names the acting, the director frames it.
+- `ai-video-technical-director` — folds the four blocks into provider grammar.
+- `character-consistency` skill — consumes the CHARACTER SHEET as identity-token source.

package/.agent-src/skills/character-consistency/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: character-consistency
+description: "Use when a character must stay visually identical across AI video scenes — locks identity tokens (silhouette, palette, wardrobe, prop) in JSON. Triggers 'character lock', 'same character'."
+personas:
+  - pixar-storyboard-artist
+  - hollywood-director
+source: package
+domain: product
+---
+
+# character-consistency
+
+> Lock a character's visual identity into
+> `agents/ai-video/<project>/characters/<id>.json` so every scene
+> reuses the **exact same tokens** verbatim. Downstream skills
+> ([`video-director`](../video-director/SKILL.md),
+> [`pixar-storyteller`](../pixar-storyteller/SKILL.md),
+> [`motion-choreographer`](../motion-choreographer/SKILL.md)) read
+> this file and never paraphrase. Verified by visual regression
+> (pixel similarity ≥ 95%, Phase 6 Step 3).
+
+## When to use
+
+- A multi-scene run names the same character on screen more than
+  once — Character Lock is mandatory before the second scene drafts.
+- A character drift bug landed (face / outfit / prop changed between
+  scenes) — re-lock and rerun the affected scenes.
+- A series, episode, or recurring ad uses the same on-screen identity.
+
+Do NOT use when:
+
+- One-shot scene with no recurring character — overhead is wasted.
+- The "character" is an object or environment, not a person /
+  creature — use a `style.json` lock pattern in the project's notes
+  instead.
+
+## Procedure
+
+### Step 0: Inspect
+
+1. Check `agents/ai-video/<project>/characters/` — if a lock already
+   exists for this id, **read it, do not redraft**. Edits require an
+   explicit revision note (Phase 6 visual regression must rerun).
+2. Confirm the character will appear in ≥ 2 scenes; one-shot → skip.
+
+### Step 1: Draft identity tokens
+
+Emit a JSON file at
+`agents/ai-video/<project>/characters/<character-id>.json` with the
+following fields. Every field is mandatory; missing field → fail
+the lock.
+
+```json
+{
+  "id": "kebab-case-id",
+  "name": "Display Name",
+  "silhouette": "one-line read of the body shape from 30m",
+  "palette": ["#hex1", "#hex2", "#hex3"],
+  "wardrobe": "garment list, materials, era",
+  "signature_prop": "the one object that travels with them",
+  "posture_default": "how they stand when not acting",
+  "eye_behavior": "blink rhythm, glance habit",
+  "face": "age band, skin tone, hair (length / color / texture), distinguishing marks",
+  "voice_note": "timbre + cadence for native-audio adapters; null if N/A",
+  "reference_frame": "scenes/<id>/frames/<n>.png or null",
+  "version": 1
+}
+```
+
+### Step 2: Reference frame
+
+1. After the first scene renders, copy the highest-quality frame
+   showing the character full-face and full-body to
+   `agents/ai-video/<project>/characters/<id>.ref.png`.
+2. Update `reference_frame` in the JSON to point at it.
+3. Phase 6 visual regression compares every subsequent scene's
+   character frame against this reference (ImageMagick `compare`
+   ≥ 95% similarity).
+
+### Step 3: Validate
+
+1. JSON parses (`jq . characters/<id>.json` exits 0).
+2. All mandatory fields present and non-empty.
+3. Palette has ≥ 2 and ≤ 5 hex values.
+4. Downstream skills cite this file by path, never paraphrase its
+   contents.
+
+## Output format
+
+1. **`agents/ai-video/<project>/characters/<id>.json`** — locked
+   identity tokens, schema above.
+2. **`agents/ai-video/<project>/characters/<id>.ref.png`** —
+   reference frame (added after first render).
+3. **`agents/ai-video/<project>/characters/CHANGELOG.md`** — one
+   line per revision: `v<n> · YYYY-MM-DD · reason · scenes-to-rerun`.
+
+## Gotcha
+
+- The model wants to "improve" identity tokens on each scene —
+  this is the silent drift failure. Tokens are immutable until a
+  revision note bumps `version`.
+- Palette without a count fails downstream — adapters need a small
+  closed set (2–5 hex).
+- `voice_note: null` is explicit; missing the key entirely breaks
+  the schema validator.
+- Reference frame is captured *after* the first successful render,
+  not before — bootstrap scenes have no reference and only the
+  JSON locks them.
+- A revision (`version` bumped) requires Phase 6 visual regression
+  to rerun against every prior scene that used the old version.
+
+## Do NOT
+
+- Do NOT paraphrase identity tokens when drafting scene prompts —
+  copy verbatim or break the lock.
+- Do NOT edit a locked JSON in place without bumping `version` and
+  adding a CHANGELOG line.
+- Do NOT skip the reference frame after the first render — visual
+  regression has nothing to compare against.
+- Do NOT lock a character that appears in only one scene.

package/.agent-src/skills/motion-choreographer/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: motion-choreographer
+description: "Use when turning a locked still + blueprint into a provider-tuned motion prompt — camera, primary + secondary motion, physics, native-audio sync. Triggers 'motion prompt for Veo/Kling/Sora'."
+personas:
+  - ai-video-technical-director
+source: package
+domain: product
+---
+
+# motion-choreographer
+
+> Turn an approved still + the 12-block scene blueprint into a
+> provider-tuned **motion prompt** that the target video adapter
+> consumes. Camera choreography, primary subject motion, secondary
+> environment motion, physics constraints, and — when the adapter
+> declares `audio: native` — a synchronized audio direction block.
+> Reads adapter capabilities from
+> [`adapter-contract.md`](../../../scripts/ai-video/lib/adapter-contract.md);
+> never speaks to a network API.
+
+## When to use
+
+- An image is locked (operator picked one candidate via
+  `operator-pick.sh`) and the next step is motion + audio direction
+  for the video adapter.
+- The blueprint exists in `scenes/<id>/blueprint.json` but the
+  motion prompt has not been emitted yet.
+- A provider switch (Veo → Kling, Sora → Higgsfield) requires the
+  same scene retuned for the new adapter's capability profile.
+
+Do NOT use when:
+
+- The blueprint is still prose only — run
+  [`scene-expander`](../scene-expander/SKILL.md) → `parse-blueprint.sh`
+  first.
+- No still has been locked — the operator-selection checkpoint
+  must complete first.
+- The output is a still graphic — `canvas-design`.
+
+## Procedure
+
+### Step 0: Inspect
+
+1. Read `scenes/<id>/blueprint.json` — fail loud if missing.
+2. Read `scenes/<id>/selection.json` — fail loud if missing; the
+   locked image path is required as the motion anchor.
+3. Read the target adapter's capability via
+   `scripts/ai-video/adapters/<id>.sh capability`. Cache `audio=*`
+   for Step 3.
+4. If a `character.json` lock exists, load it verbatim — identity
+   tokens are immutable.
+
+### Step 1: Camera choreography
+
+Emit a `CAMERA MOTION` block with the move type, distance, speed
+in seconds, and start-end framing.
+
+- Move types: lock-off, pan, tilt, dolly-in, dolly-out, truck,
+  pedestal, push, pull, handheld, gimbal-glide, crane, whip.
+- Speed in seconds per beat (`0.4s push, hold 1.6s, 0.4s pull`).
+- Start and end framing named (`MS → CU`, `WS → MS`).
+
+Adapter quirks:
+
+- **Veo** — accepts named moves; prefers ≤ 8s clips.
+- **Kling** — motion intensity 0–1 token; map our speed to that.
+- **Sora** — natural-language move + duration; no token.
+- **Higgsfield** — preset-driven; pick the preset that matches the
+  move; record the preset id in the motion prompt.
+
+### Step 2: Primary + secondary motion
+
+Two blocks:
+
+1. **PRIMARY MOTION** — what the subject does, beat-counted, with
+   physics anchors (mass, contact points, momentum). Reuse `ACTION`
+   from the blueprint; refine for the adapter's preferred verb
+   density.
+2. **SECONDARY MOTION** — what the world does (hair, fabric,
+   foliage, water, dust, particles, breath). One layer per line.
+
+### Step 3: Audio direction (conditional)
+
+If adapter capability is `audio: native` AND the blueprint's
+`audio.enable_native_audio` is `true`:
+
+Emit an `AUDIO DIRECTION` block with:
+
+- `DIALOGUE TIMING` — `speaker @ 0.4s: "line"` per dialogue entry.
+- `AMBIENT LAYERS` — copy from blueprint; one layer per line.
+- `SYNC CUES` — which action beat maps to which audio cue
+  (`footstep @ 1.2s`, `door close @ 2.1s`).
+
+If adapter capability is `audio: none`:
+
+- Emit a `# AUDIO: ffmpeg-mux fallback` comment with the
+  blueprint's audio paths queued for stitch-time mux.
+- Set `enable_native_audio: false` in the motion-prompt JSON.
+
+### Step 4: Physics constraints
+
+Emit `PHYSICS` — a short list of what the model must respect:
+gravity direction, contact friction, fluid behavior, hair / cloth
+inertia, lens parallax. Single line per constraint.
+
+### Step 5: Emit motion-prompt JSON
+
+Write `scenes/<id>/motion-prompt.json` with the adapter-contract
+stdin shape. The orchestrator pipes this into the video adapter's
+`submit` subcommand.
+
+### Step 6: Validate
+
+1. JSON parses (`jq .`).
+2. `requires.audio_native` is consistent with the chosen adapter's
+   capability.
+3. Duration in the motion prompt matches blueprint duration ±0.
+4. Identity tokens (if `character.json` exists) are verbatim.
+
+## Output format
+
+1. **`scenes/<id>/motion-prompt.json`** — adapter-contract stdin.
+2. **`scenes/<id>/motion-prompt.txt`** — labeled prose blocks
+   (CAMERA MOTION · PRIMARY MOTION · SECONDARY MOTION · AUDIO
+   DIRECTION · PHYSICS) for operator review.
+3. **`scenes/<id>/adapter-notes.md`** — which adapter, which
+   capability, which preset / model, with rationale.
+
+## Gotcha
+
+- The model wants to "improve" the blueprint's `SUBJECT` block —
+  identity tokens are immutable; refuse the temptation.
+- Picking `audio: native` on an adapter that returns `audio: none`
+  produces silent video — always read capability first, never
+  guess from the adapter name.
+- Higgsfield preset id must be recorded; otherwise the rerun
+  drifts to whichever preset the model picks on the next call.
+- Sora durations > 8s often degrade — clamp at the adapter table
+  limit; surface the clamp to the operator.
+
+## Do NOT
+
+- Do NOT emit motion prompts for an adapter whose capability you
+  did not query this turn.
+- Do NOT skip the still-locked check — motion direction without an
+  anchored image diverges on every call.
+- Do NOT paraphrase identity tokens from `character.json`.
+- Do NOT call any network API — this skill is provider-tuning
+  prose only.

package/.agent-src/skills/pixar-storyteller/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: pixar-storyteller
+description: "Use when turning an idea into a Pixar-style animation prompt — character sheet, scene, image, video — anchored in emotional beat, want, obstacle. Triggers 'Pixar prompt', 'animated scene'."
+personas:
+  - pixar-storyboard-artist
+source: package
+domain: product
+---
+
+# pixar-storyteller
+
+> Turn an animation beat into the **four-block storyboard** the
+> `pixar-storyboard-artist` persona ships: CHARACTER SHEET · SCENE
+> PROMPT · IMAGE PROMPT · VIDEO PROMPT. Output is provider-agnostic;
+> provider tuning is [`motion-choreographer`](../motion-choreographer/SKILL.md).
+
+## When to use
+
+- A scene is animated / stylized (not photoreal) and needs an
+  emotional read, not a film-set read.
+- The character must want something and the environment must
+  respond — flat poses fail.
+- Live-action / photoreal beats → [`video-director`](../video-director/SKILL.md).
+
+Do NOT use when:
+
+- The deliverable is provider-tuned token grammar →
+  `motion-choreographer` after this skill.
+- A character must be re-used across scenes → run
+  [`character-consistency`](../character-consistency/SKILL.md) first
+  to lock the CHARACTER SHEET, then call this skill.
+- The brief is a static graphic / poster → `canvas-design`.
+
+## Procedure
+
+### Step 0: Inspect
+
+1. Confirm the input is an animated / stylized beat.
+2. If `character.json` exists under `agents/ai-video/<project>/characters/`,
+   read identity tokens — reused verbatim in CHARACTER SHEET.
+3. Read the beat once. Name the *want* and the *obstacle* in one
+   sentence each before drafting.
+
+### Step 1: Draft the four blocks
+
+Emit each block under a labeled heading. Blocks are mandatory and
+in this order:
+
+1. **CHARACTER SHEET** — silhouette, palette, wardrobe, signature
+   prop, posture default, eye behavior. Verbatim from `character.json`
+   when a lock exists.
+2. **SCENE PROMPT** — single emotional beat, want, obstacle,
+   stylistic anchor (specific film + year — "Up (2009)", not
+   "Pixar-style"), environment reaction.
+3. **IMAGE PROMPT** — one still at the peak of the beat. Names
+   composition, eye line, palette. No motion verbs.
+4. **VIDEO PROMPT** — decomposes the moment into
+   `anticipation Xs · action Ys · reaction Zs` with explicit beat
+   counts. Names which secondary motion (hair, cloth, dust) reacts
+   on which beat.
+
+### Step 2: Self-review
+
+1. Exactly one emotional beat in SCENE PROMPT? Compound moods fail.
+2. Stylistic anchor is a specific film + year? Generic style → fail.
+3. VIDEO PROMPT names beat counts per phase?
+4. IMAGE PROMPT names eye line?
+5. CHARACTER SHEET matches `character.json` byte-for-byte when a
+   lock exists?
+
+Any "no" → revise that block.
+
+### Step 3: Validate
+
+1. Output is plain text, one labeled block per heading, ready for
+   `scripts/ai-video/lib/parse-blueprint.sh`.
+2. No provider tokens — that is `motion-choreographer`.
+3. No lens / focal-length prescriptions — that is `video-director`'s
+   block, not this one.
+
+## Output format
+
+1. **`scenes/<id>/prompt.txt`** — four labeled blocks, ready for
+   the blueprint parser.
+2. **`scenes/<id>/review.md`** — one-paragraph rationale per
+   non-obvious choice (stylistic anchor, environment reaction,
+   beat decomposition).
+
+## Gotcha
+
+- The model defaults to "Pixar-style" with no film anchor — that
+  reads as a wishlist. Force a specific title + year.
+- Neutral faces are the AI default — every beat names a feeling
+  the face is doing, including eye line direction.
+- Environment-as-backdrop is the silent failure mode — name what
+  the world *does* in response to the character.
+- Collapsing anticipation and action into one verb makes motion
+  look teleported. Both phases or the prompt fails review.
+- When `character.json` exists, paraphrasing breaks Character Lock —
+  copy identity tokens verbatim.
+
+## Do NOT
+
+- Do NOT prescribe lenses or focal lengths — that is `video-director`.
+- Do NOT emit provider-specific tokens — that is `motion-choreographer`.
+- Do NOT cite "Pixar-style" without a specific film + year.
+- Do NOT compound emotional beats ("sad but hopeful and tired").

package/.agent-src/skills/scene-expander/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: scene-expander
+description: "Use when expanding a one-line idea into the 12-block Cinematic Scene Blueprint — provider-agnostic, includes optional dialogue + ambient. Triggers 'expand this scene', 'blueprint for X'."
+personas:
+  - hollywood-director
+  - pixar-storyboard-artist
+source: package
+domain: product
+---
+
+# scene-expander
+
+> Expand a one-line idea or script line into the **Cinematic Scene
+> Blueprint** — 12 labeled blocks consumed by
+> [`parse-blueprint.sh`](./scene-blueprint.schema.yaml). Picks
+> `hollywood-director` for live-action and `pixar-storyboard-artist`
+> for animated beats. Output is provider-agnostic — provider tuning
+> is [`motion-choreographer`](../motion-choreographer/SKILL.md).
+
+## When to use
+
+- A script line, idea, or beat needs a full blueprint before any
+  adapter runs.
+- A `/video:from-script` run is parsing `## Scene N` headings and
+  needs each scene expanded.
+
+Do NOT use when:
+
+- The brief is already an 11-block cinematic prompt → call
+  `video-director` directly to refine it.
+- The brief is a static graphic → `canvas-design`.
+- Provider-specific token tuning is the next step →
+  `motion-choreographer`.
+
+## Procedure
+
+### Step 0: Inspect
+
+1. Read the input line. Classify as **live-action / photoreal** or
+   **animated / stylized**.
+2. Live-action → load `hollywood-director` voice. Animated → load
+   `pixar-storyboard-artist`. Hybrid (live-action with VFX) →
+   `hollywood-director`; record VFX intent in ENVIRONMENT.
+3. Check for an existing `character.json` lock under
+   `agents/ai-video/<project>/characters/`.
+
+### Step 1: Emit the 12 blocks
+
+One label per line. Order is mandatory.
+
+1. **STYLE** — stylistic anchor (live-action: film stock + decade,
+   e.g. "Kodak 5219, 2015"; animated: specific film + year).
+2. **SUBJECT** — character read; verbatim identity tokens when a
+   lock exists.
+3. **ENVIRONMENT** — location, time-of-day, weather, era; what the
+   world does in response to the subject.
+4. **ACTION** — anticipation / action / reaction with beat counts
+   (`0.5s / 1.2s / 0.8s`). No adjective paragraphs.
+5. **CAMERA** — position, height, distance, move (lock-off, dolly,
+   handheld, push, pull). Off-axis when on-axis is default.
+6. **LENS** — focal length in mm and aperture intent. "Cinematic"
+   alone fails.
+7. **LIGHTING** — key / fill / back / practical named; "golden
+   hour" requires a sun angle.
+8. **MOOD** — one emotional read.
+9. **DIALOGUE** — optional. If present: `speaker: "line"`, one per
+   line. Marks `audio: native` capability requirement.
+10. **AMBIENT SOUND** — optional. Layer list (wind, traffic,
+    crowd, ocean). Marks `audio: native` or routes to ffmpeg mux.
+11. **DURATION** — seconds (integer or one decimal).
+12. **NEGATIVE** — clichés to reject, load-bearing order top-first.
+    Always names: centered framing, symmetric composition, generic
+    "cinematic", soap-opera contrast.
+
+### Step 2: Self-review
+
+1. Live-action / animated classification consistent across blocks?
+2. LENS present with mm (live-action) OR stylistic anchor with
+   film+year (animated)?
+3. LIGHTING with a direction?
+4. ACTION names beat counts, not adjectives?
+5. DIALOGUE / AMBIENT SOUND present → the run requires `audio:
+   native` adapter OR ffmpeg-mux fallback declared.
+6. NEGATIVE ≥ 4 entries, load-bearing top?
+7. SUBJECT verbatim from `character.json` when a lock exists?
+
+Any "no" → revise that block.
+
+### Step 3: Validate
+
+1. Pipe output through `scripts/ai-video/lib/parse-blueprint.sh` —
+   exits 0 and emits valid adapter-contract JSON.
+2. No provider tokens (no aspect / model / duration flags).
+
+## Output format
+
+1. **`scenes/<id>/prompt.txt`** — 12 labeled blocks, ready for
+   `parse-blueprint.sh`.
+2. **`scenes/<id>/blueprint.json`** — parser output, adapter-stdin
+   ready.
+3. **`scenes/<id>/review.md`** — one-paragraph rationale per
+   non-obvious choice.
+
+## Gotcha
+
+- The model wants to skip optional DIALOGUE / AMBIENT SOUND blocks
+  silently — if they could plausibly belong, emit them; the parser
+  treats missing blocks as `null`, not as an error.
+- Live-action without LENS mm fails the parser's strict mode.
+- Animated without a film+year anchor in STYLE drifts on every run.
+- ACTION written as "the character does X dramatically" fails —
+  adapters need verbs with beat counts.
+- DIALOGUE forces `audio: native` requirement — flag this to the
+  orchestrator so it picks a capable adapter (Veo / Sora).
+
+## Do NOT
+
+- Do NOT emit provider tokens — that is `motion-choreographer`.
+- Do NOT skip the blueprint parser validation step.
+- Do NOT paraphrase identity tokens when a lock exists.
+- Do NOT mix live-action LENS prescriptions with animated STYLE
+  anchors in the same scene — pick one mode.