feat: Multimodal Studio — unified image/video/character generation layer (#12)

Adds ACOS's unified generation layer (image + video + consistent characters) via the Higgsfield MCP connector, model-agnostic and brand-locked. Includes the multimodal-studio skill, multimodal-director agent, /studio and /generate-video commands, and docs. Also fixes long-standing CI build debt (commits package-lock.json, pins TypeScript 5.6.3, fixes website-mcp template + creator/evaluator type errors) so the build job is green.

Author: frankxai

.claude-plugin/plugin.json

@@ -22,7 +22,11 @@
     "content-creation",
     "agentic-ai",
     "mcp",
-    "anthropic"
+    "anthropic",
+    "multimodal",
+    "image-generation",
+    "video-generation",
+    "higgsfield"
   ],
   "categories": [
     "creator-tools",

.claude/agents/multimodal-director.md

@@ -0,0 +1,57 @@
+---
+name: Multimodal Director
+description: Creative director who orchestrates image, video, and character generation into coherent, brand-locked asset sets. Routes models, engineers visual prompts, and runs the async generation pipeline end to end via the multimodal connector.
+capabilities:
+  - model-routing
+  - visual-prompt-engineering
+  - character-consistency
+  - video-generation
+  - async-job-orchestration
+  - brand-locked-output
+priority: medium
+mcpServers:
+  - higgsfield
+model: sonnet
+---
+
+# 🎬 Multimodal Director
+*Creative Director — Image · Video · Character*
+
+## Agent Mission
+
+You are the **Multimodal Director**. You take a creative brief and return finished visual assets — stills, video, and consistent characters — that look like one campaign and obey the brand. You don't describe images; you generate them. You own the whole pipeline: brief → model routing → prompt craft → async generation → assembled delivery.
+
+## Frank DNA
+
+Cool, premium, high-intellect, fun. Direct and technical. Lead with the asset, not the claim. Every output should make someone think "that's a system I want to build," not "that's a stock image." No AI slop ever ships.
+
+## Core Identity
+
+- **Role:** Creative Director for generative visual production
+- **Primary tool:** the `multimodal-studio` skill + Higgsfield MCP (image, video, character)
+- **Output:** production-ready, brand-locked visual asset sets with reproducible logs
+
+## Operating Loop
+
+1. **Load the skill.** Always work through the `multimodal-studio` skill — it holds the model matrix, prompt structure, and async lifecycle. Read `resources/model-matrix.md` for routing.
+2. **Lock the brief.** Goal, placement, aspect ratio (derive from placement), style, character?, modality. Ask only for what you can't infer.
+3. **Check the connector.** Confirm the higgsfield tools are available. If not, surface the `claude mcp add --transport http --scope user higgsfield https://mcp.higgsfield.ai/mcp` command — never fake a result.
+4. **Route + state it.** Pick the model and say which and why in one line.
+5. **Craft.** Subject + Action + Setting + Composition + Lighting + Style + Technical. Inject brand tokens if a brand skill is active. For video, describe motion explicitly.
+6. **Generate async + in parallel.** Submit independent assets together, poll `get_generation_status`, download to canonical paths.
+7. **Hold consistency.** For recurring subjects, `create_character` once and reference its ID across the whole set.
+8. **Inspect.** Run the AI-slop checklist. Regenerate anything that fails. Produce required crops/derivatives.
+9. **Log.** Model + prompt + seed/job ID per keeper, so it's reproducible and auditable.
+
+## Boundaries
+
+- Read-only on code; this agent generates assets, it doesn't refactor the repo.
+- Cost-aware: drafts cheap, finals at 4K, image→video before text→video.
+- Brand-locked when a brand skill is loaded; never override brand tokens without an explicit operator call.
+
+## Composes With
+
+- `frankx-brand` / `brand-guidelines` — brand tokens
+- `video-script` / `content-strategy` — incoming briefs
+- `suno-ai-mastery` — scoring the video output
+- Commands: `/studio`, `/generate-video`, `/generate-images`, `/infogenius`

.claude/commands/generate-video.md

@@ -0,0 +1,48 @@
+---
+name: generate-video
+description: Generate short-form / cinematic video from a still or a text prompt via the Multimodal Studio (Higgsfield MCP) — Kling, Hailuo, Veo, Sora-class, DoP.
+---
+
+# 🎥 /generate-video — Video Generation
+
+**Turn a still or a prompt into motion. Image→video first (cheaper, keeps your composition); text→video for hero scenes.**
+
+Activates the `multimodal-studio` skill and the **Multimodal Director**. Read the skill's `resources/model-matrix.md` for routing and the async lifecycle.
+
+## Step 0 — Connector check
+Confirm higgsfield tools are available. If not:
+```bash
+claude mcp add --transport http --scope user higgsfield https://mcp.higgsfield.ai/mcp
+```
+
+## Step 1 — Source & intent
+- **Source:** existing still (preferred — image→video) or text-only (text→video)
+- **Placement & ratio:** Reels/Shorts/TikTok → 9:16; YouTube/landing → 16:9
+- **Length:** default short (≤10s); state the target
+- **Character?:** reference an existing character ID for consistency
+
+## Step 2 — Route the model
+- Image→video, cinematic motion/physics → **Kling**
+- Image→video, expressive character action → **Hailuo**
+- Text→video, complex scene → **Veo / Sora-class**
+- Fast still→motion (~5s) → **DoP**
+State the choice in one line.
+
+## Step 3 — Craft the motion prompt
+Describe **camera move + subject motion + pacing** explicitly — models default to near-static otherwise. Include lighting and mood. Example:
+> "Slow push-in on the subject, hair drifting in a gentle breeze, volumetric backlight, cinematic teal-and-amber grade, 24fps filmic motion, 9:16."
+
+## Step 4 — Generate (async)
+Submit, capture the job ID, poll `get_generation_status`. Video takes longer than stills — poll, don't assume. Download to the canonical asset path. Inspect for motion artifacts; regenerate once if needed.
+
+## Step 5 — Deliver
+- Provide the clip + a poster frame (still export).
+- Note model, prompt, seed/job ID.
+- Offer to score it with `/create-music`.
+
+## Usage
+```text
+/generate-video animate this hero still into a 5s cinematic loop, 16:9
+/generate-video 9:16 teaser: neon city flythrough, fast cuts, 8s
+/generate-video lesson intro featuring character <id>, slow push-in, warm light
+```

.claude/commands/studio.md

@@ -0,0 +1,77 @@
+---
+name: studio
+description: End-to-end multimodal production — turn a brief into a coherent set of images, video, and consistent characters via the Multimodal Studio (Higgsfield MCP).
+---
+
+# /studio — Multimodal Production Pipeline
+
+**One brief in, a finished brand-locked asset set out. Images + video + consistent characters across 30+ models.**
+
+```text
+╔══════════════════════════════════════════════════════════════════════╗
+║                      MULTIMODAL STUDIO PIPELINE                        ║
+║         "One connector. Stills, motion, and a character that stays."   ║
+╠══════════════════════════════════════════════════════════════════════╣
+║  BRIEF  →  ROUTE  →  CRAFT  →  GENERATE (async, parallel)  →  ASSEMBLE  ║
+╚══════════════════════════════════════════════════════════════════════╝
+```
+
+This command activates the `multimodal-studio` skill and the **Multimodal Director** agent. Read the skill before generating; it holds the model matrix, prompt structure, and async lifecycle.
+
+## Step 0 — Connector check
+
+Confirm the higgsfield MCP tools are available (`generate_image`, `generate_video`, `create_character`, `list_characters`, `get_generation_status`). If they're missing, stop and tell the operator:
+```bash
+claude mcp add --transport http --scope user higgsfield https://mcp.higgsfield.ai/mcp
+```
+Never fabricate an image or a URL.
+
+## Step 1 — BRIEF
+
+Gather (infer from project context; ask only for gaps):
+- **Goal & placement** — blog hero / OG card / IG reel / YouTube thumbnail / campaign set
+- **Aspect ratio** — derive from placement (see skill matrix); don't ask for pixels
+- **Style** — photoreal / 3D / illustration / minimalist / cinematic; inherit brand tokens if a brand skill is active
+- **Character?** — recurring subject that must stay consistent across assets
+- **Modality** — stills, video, or both
+
+## Step 2 — ROUTE
+
+Pick models deliberately and state the choice in one line each:
+- Photoreal people/products → **Soul** (4K)
+- Stylized / illustration / in-image text → **Flux / Seedream**
+- Motion from a still → **image→video** (Kling / Hailuo / DoP)
+- Text→video, complex scenes → **Veo / Sora-class**
+
+## Step 3 — CRAFT
+
+Build each prompt as **Subject + Action + Setting + Composition + Lighting + Style + Technical**. For video, describe camera move + subject motion + pacing explicitly. Inject brand palette/mood.
+
+## Step 4 — GENERATE (async + parallel)
+
+- For a recurring subject: `create_character` once → reuse its ID in every call.
+- Submit independent assets in parallel, capture job IDs, poll `get_generation_status`.
+- Download finished assets to the project's canonical asset path.
+- On policy/failure: report, adjust, retry once.
+
+## Step 5 — ASSEMBLE
+
+- Verify the set reads as one campaign (same character ID, palette, lighting).
+- Produce derivatives (hero → OG 1200×630, square 1080×1080, vertical 1080×1920).
+- Run the AI-slop checklist; regenerate anything that fails.
+- Log model + prompt + seed/job ID per keeper.
+
+## Usage
+
+```text
+/studio hero image + 3 social cards + 5s teaser for the "Agentic Creator OS" launch post
+/studio a consistent course-instructor character, then 4 lesson thumbnails featuring her
+/studio animate this product still into a 5s cinematic loop
+```
+
+## Related
+
+- `/generate-video` — video-first entry point
+- `/generate-images` — single-image / article-asset flow
+- `/infogenius` — research-grounded image prompts
+- `/create-music` — score the videos this produces

.claude/skill-rules.json

@@ -5,6 +5,15 @@
   "_updated": "2026-01-25",
 
   "activation_rules": [
+    {
+      "skill": "multimodal-studio",
+      "triggers": {
+        "keywords": ["generate image", "generate video", "create character", "multimodal", "higgsfield", "image generation", "video generation", "b-roll", "cinematic", "thumbnail", "hero image", "character reference", "visual asset"],
+        "file_patterns": ["*.png", "*.jpg", "*.jpeg", "*.mp4", "*.mov", "public/images/**", "assets/**"],
+        "commands": ["/studio", "/generate-video", "/generate-images", "/infogenius"]
+      },
+      "priority": "high"
+    },
     {
       "skill": "suno-ai-mastery",
       "triggers": {

.gitignore

@@ -38,8 +38,8 @@ tmp/
 temp/
 *.tmp
 
-# Package lock (use npm ci)
-package-lock.json
+# Package lock — committed so `npm ci` works (reproducible, integrity-checked installs)
+# package-lock.json
 
 # Claude Flow runtime state
 .claude-flow/

.mcp.json

@@ -15,6 +15,11 @@
         "CLAUDE_FLOW_MEMORY_BACKEND": "hybrid"
       },
       "autoStart": false
+    },
+    "higgsfield": {
+      "type": "http",
+      "url": "https://mcp.higgsfield.ai/mcp",
+      "_comment": "Unified multimodal connector for the multimodal-studio skill — image, video, and character generation across 30+ models (Soul, Flux, Seedream, Kling, Hailuo, Veo, Sora). OAuth via Higgsfield account; no API keys. Add interactively: claude mcp add --transport http --scope user higgsfield https://mcp.higgsfield.ai/mcp"
     }
   }
 }

CLAUDE.md

@@ -80,9 +80,12 @@ On non-Claude platforms, just describe what you want. Skills activate from conte
 
 ## Available Commands (35+)
 
-### Creation (10)
+### Creation (12)
+
 | Command | Description |
 |---------|-------------|
+| `/studio` | **Multimodal Studio** — end-to-end image + video + character production (Higgsfield MCP) |
+| `/generate-video` | Video generation: still→video or text→video (Kling/Hailuo/Veo/Sora/DoP) |
 | `/article-creator` | Guided blog article creation |
 | `/create-music` | Suno music production pipeline |
 | `/infogenius` | Research-grounded image generation |
@@ -139,6 +142,22 @@ User: "write a blog post about AI agents"
   → Routes to: /article-creator
 ```
 
+## Multimodal Studio (v11)
+
+ACOS's unified generation layer: **image + video + consistent characters** across 30+ frontier models through a single connector.
+
+- **Skill:** `multimodal-studio` — model routing, visual prompt engineering, character consistency, async lifecycle, brand-locked output
+- **Agent:** Multimodal Director (`.claude/agents/multimodal-director.md`)
+- **Commands:** `/studio` (e2e pipeline), `/generate-video`, `/generate-images`, `/infogenius`
+- **Connector:** Higgsfield MCP (default) — one OAuth, models incl. Soul, Flux, Seedream, Kling, Hailuo, Veo, Sora
+
+```bash
+# Connect the multimodal connector (one-time)
+claude mcp add --transport http --scope user higgsfield https://mcp.higgsfield.ai/mcp
+```
+
+Stays **vendor-agnostic** (any MCP filling `~~image generation` / `~~video generation` works — see `CONNECTORS.md`) and **brand-locked** (assets inherit Frank DNA + active brand tokens). The differentiator vs. single-vendor agent platforms: character consistency across an entire asset set via `create_character` → reuse the character ID everywhere. See `docs/multimodal-studio.md`.
+
 ## v10 Safety Systems
 
 ### Circuit Breaker

CONNECTORS.md

@@ -22,11 +22,18 @@ ACOS is **tool-agnostic at the skill level** — workflows describe what needs t
 
 | Category | Placeholder | Default (ACOS) | Alternatives |
 |----------|-------------|----------------|--------------|
-| Image generation | `~~image generation` | nano-banana (Gemini 2.5 Flash Image) | Midjourney, Stability AI, Flux |
+| Image generation | `~~image generation` | **Higgsfield MCP** (Soul/Flux/Seedream, 4K) | nano-banana (Gemini 2.5 Flash Image), Midjourney, Stability AI |
+| Video generation | `~~video generation` | **Higgsfield MCP** (Kling/Hailuo/Veo/Sora/DoP) | Veo 3 (direct API), RunwayML |
+| Character consistency | `~~character` | **Higgsfield MCP** (Soul character training) | manual reference images |
 | Music generation | `~~music generation` | Suno AI (direct API) | Udio |
-| Video generation | `~~video generation` | Veo 3 (direct API) | RunwayML, Kling |
 | Design | `~~design` | Figma MCP | Canva |
 
+> **Multimodal Studio:** image, video, and character generation are unified under one connector
+> (Higgsfield MCP — one OAuth, 30+ models). The `multimodal-studio` skill and `/studio` command
+> drive it. Connect with:
+> `claude mcp add --transport http --scope user higgsfield https://mcp.higgsfield.ai/mcp`
+> Skills stay vendor-agnostic — any MCP filling these categories works.
+
 ### Communication & publishing
 
 | Category | Placeholder | Default (ACOS) | Alternatives |