calvyn-code 0.14.0

package/optional-skills/creative/kanban-video-orchestrator/references/role-archetypes.md

@@ -0,0 +1,298 @@
+# Role Archetypes
+
+The library of role archetypes for video production. **Compose a team from this
+list, don't clone a fixed roster.** Most videos need 4-7 profiles. The director
+is always present; everything else is conditional on the brief.
+
+Each role's profile name is by convention `kebab-case` (e.g. `creative-director`,
+`image-generator`). Multiple instances of the same role get descriptive suffixes
+when they need different focus (e.g., `renderer-ascii`, `renderer-3d`).
+
+For toolset + skill mapping per role, see [tool-matrix.md](tool-matrix.md).
+
+## Always present
+
+### director
+
+The vision-holder. Reads the brief and brand guide, decomposes into a task
+graph, comments to steer creative direction, approves the final cut.
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** `kanban-orchestrator`. The kanban plugin auto-injects baseline
+  orchestration guidance for free; `kanban-orchestrator` is the deeper
+  decomposition playbook. Add `creative-ideation` if the brief is wide-open
+  and needs framing help.
+- **Personality:** Tied to the brand voice — see `assets/soul.md.tmpl`
+
+The director has the same toolset as everyone else, but its `SOUL.md` rules
+**forbid** execution. The "decompose, don't execute" discipline is enforced
+by personality + the kanban-orchestrator skill, not by missing tools.
+
+## Pre-production roles
+
+Pick based on what the brief needs.
+
+### writer / screenwriter
+
+Writes scripts, dialogue, voiceover copy, narration. Use for any video with
+spoken or written words beyond a tagline.
+
+- **Toolsets:** kanban, file
+- **Skills:** `kanban-worker`, `humanizer` (post-process to strip AI-tells)
+- **Outputs:** `script.md`, `narration.md`, `dialogue/scene-NN.md`
+
+### copywriter
+
+Like `writer` but specifically for marketing copy: taglines, CTAs, voiceover
+scripts for product videos.
+
+- **Toolsets:** kanban, file
+- **Skills:** `kanban-worker`, `humanizer`
+- **Outputs:** `copy.md`
+
+### concept-artist / visual-designer
+
+Develops the visual identity: mood board, style frames, color palette
+rationale, typography choices. Produces a `visual-spec.md` that all generators
+follow. Often produces still reference frames using image-generation APIs or
+local skills.
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** `kanban-worker` plus any project-specific design skill —
+  `claude-design` (UI/web), `sketch` (quick mockup variants),
+  `popular-web-designs` (matching known web aesthetic), `pixel-art` (retro),
+  `ascii-art` (terminal/retro), `excalidraw` (hand-drawn frames),
+  `design-md` (text-based design docs)
+- **Outputs:** `visual-spec.md`, `taste/style-frames/*.png`
+
+### storyboarder
+
+Maps the brief to a beat-by-beat shot list with timing. Critical for narrative
+film and music video. Often pairs with a diagramming tool.
+
+- **Toolsets:** kanban, file
+- **Skills:** `kanban-worker` plus a diagram skill — `excalidraw` (sketch),
+  `architecture-diagram` (technical/system), `concept-diagrams` (educational/
+  scientific)
+- **Outputs:** `storyboard.md` with one row per scene/shot, optional
+  storyboard sketches
+
+### cinematographer / dp
+
+Designs the visual language: framing, color, motion, transitions. Reviews
+generator output for visual consistency. Hands off per-scene `VISUAL_SPEC.md`.
+
+- **Toolsets:** kanban, terminal, file, video, vision
+- **Skills:** `kanban-worker` plus the visual skill that matches the project
+  (e.g., `ascii-video` for ASCII work, `manim-video` for explainers,
+  `touchdesigner-mcp` for real-time visuals, etc.)
+- **Outputs:** `scenes/scene-NN/VISUAL_SPEC.md`, review comments on renderer
+  tasks
+- **Reviews via:** `video_analyze` (sends full clip to multimodal LLM for
+  native review), `vision_analyze` for spot-checking frames, ffprobe summaries
+
+## Production roles
+
+### renderer (generic)
+
+A worker that produces visual content for one or more scenes. Loaded with
+whichever creative skill fits the scene's style. Multiple renderers can run in
+parallel, each pinned to a different skill via `always_load` in their profile
+or `--skill` on the task.
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** one creative skill (see specialized variants below)
+- **Outputs:** `scenes/scene-NN/clip.mp4`
+
+### Specialized renderer variants
+
+When scenes need very different tools, create specialized renderer profiles
+instead of overloading one. Each loads a different creative skill.
+
+| Variant | Skill | Best for |
+|---------|-------|----------|
+| `renderer-ascii` | `ascii-video` | Terminal aesthetic, retro pixel, audio-reactive grid, video-to-ASCII conversion |
+| `renderer-manim` | `manim-video` | Math, algorithms, 3Blue1Brown-style explainers, equation derivations |
+| `renderer-p5js` | `p5js` | Generative art, particles, shaders, organic motion, web-canvas content |
+| `renderer-comfyui` | `comfyui` | AI-generated stills + video using local ComfyUI workflows (img-to-img, img-to-video, etc.) |
+| `renderer-touchdesigner` | `touchdesigner-mcp` | Real-time, audio-reactive, installation art, VJ-style content |
+| `renderer-3d` | `blender-mcp` *(optional)* | 3D modeling, animation, photoreal environments, character animation |
+| `renderer-pixel` | `pixel-art` | Retro game aesthetic with era-correct palettes |
+| `renderer-comic` | `baoyu-comic` | Knowledge-comic style narrative scenes |
+| `renderer-meme` | `meme-generation` *(optional)* | Meme-style stills for satirical/social content |
+| `renderer-procedural` | (none — Python with PIL + ffmpeg directly) | Custom procedural content where no skill fits |
+| `renderer-video` | (external image-to-video API: Runway / Kling / Luma) | Animating still images in narrative film |
+| `renderer-motion-graphics` | (external — Remotion CLI) | Motion graphics, kinetic typography, UI animations |
+
+For external-API renderers, the profile holds the API client logic; only
+`kanban-worker` is loaded, plus the terminal toolset and the API key.
+
+### image-generator
+
+Specifically for text-to-image generation. Often produces stills that go to
+`renderer-video` for animation.
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** `kanban-worker`, optionally `comfyui` (drives a local
+  ComfyUI install for image generation)
+- **External APIs (alternative to local ComfyUI):** FAL, Replicate, OpenAI
+  Images, Midjourney
+- **Outputs:** `scenes/scene-NN/stills/*.png`
+
+### image-to-video-generator
+
+Takes still images and animates them via Runway/Kling/Luma APIs, or via
+ComfyUI's image-to-video workflows locally. Almost always follows
+`image-generator` in narrative film pipelines.
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** `kanban-worker`, optionally `comfyui` (for local image-to-video
+  workflows like AnimateDiff or WAN)
+- **External APIs:** Runway, Kling, Luma, Pika
+- **Outputs:** `scenes/scene-NN/clip.mp4`
+
+### music-supervisor
+
+Sources, analyzes, and prepares the music track. For music videos, also
+produces a beat/BPM map and key-moment timestamps. Uses `songsee` for
+spectrograms when the editor or renderer needs a visual reference of the
+audio's energy.
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** `kanban-worker`, `songsee` (audio visualization), plus one of:
+  - `songwriting-and-ai-music` — when commissioning lyrics + Suno prompts
+  - `heartmula` — when generating music with the open-source local model
+  - `spotify` — when sourcing existing tracks
+- **Outputs:** `audio/track.mp3`, `audio/beats.json`, optional
+  `audio/track-spectrogram.png`
+
+### voice-talent / narrator
+
+Generates voiceover audio. Calls a TTS API directly; no Hermes skill required
+beyond `kanban-worker`. The user can also supply pre-recorded VO instead of
+generation.
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** `kanban-worker`
+- **External APIs:** ElevenLabs, OpenAI TTS, etc.
+- **Outputs:** `audio/voiceover/line-NN.mp3`, `audio/voiceover/timeline.mp3`
+
+### foley / sfx-designer
+
+Sound effects and ambient design. Often optional unless the brief calls for
+sound design specifically.
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** `kanban-worker`, `songsee` for audio-feature visualization when
+  designing to a track
+- **Outputs:** `audio/sfx/*.mp3`
+
+## Post-production roles
+
+### editor
+
+Assembles the final cut from clips. Uses ffmpeg for stitching, fades,
+transitions. Reviews each clip for pacing and quality before assembly.
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** `kanban-worker`
+- **External tools:** ffmpeg, ffprobe
+- **Outputs:** `output/final.mp4`, `output/final-noaudio.mp4`
+
+### colorist
+
+Color grading. Usually optional — if the renderers already produce
+brand-consistent output and the editor just stitches, the colorist is overkill.
+Worth including for narrative film with hero shots.
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** `kanban-worker`
+- **Outputs:** `output/final-graded.mp4`
+
+### audio-mixer
+
+Mixes voiceover + music + SFX into a final audio track. Sets levels, ducks
+music under VO, normalizes loudness (LUFS).
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** `kanban-worker`
+- **External tools:** ffmpeg with `loudnorm` filter, optional `sox`
+- **Outputs:** `audio/final-mix.mp3`
+
+### captioner
+
+Burns subtitles into the video, generates SRT, handles accessibility. Can also
+generate captions from audio via Whisper.
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** `kanban-worker`
+- **External tools:** Whisper (CLI or API), ffmpeg subtitle filters
+- **Outputs:** `output/captions.srt`, `output/final-captioned.mp4`
+
+### masterer
+
+Final encode + format variants. Produces deliverables for each platform target
+(square for IG, vertical for TikTok, full HD for YouTube, etc.).
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** `kanban-worker`
+- **Outputs:** `output/final-1080.mp4`, `output/final-9x16.mp4`, etc.
+
+## QA roles
+
+### reviewer
+
+A neutral quality gate. Reads the brief, watches the cut, comments
+specifically on what's off (pacing, sync, brand alignment, technical
+quality). Distinct from the cinematographer (who reviews visuals during
+production) and the editor (who reviews for assembly).
+
+- **Toolsets:** kanban, terminal, file, video, vision
+- **Skills:** `kanban-worker`
+- **Review tools:** `video_analyze` (native clip review via multimodal LLM),
+  `vision_analyze` (frame/thumbnail review), ffprobe
+- **Outputs:** `review-notes.md`, comments on tasks
+
+### brand-cop
+
+Reviews specifically for brand compliance — colors, typography, voice. Use
+when the brand guidelines are detailed and a generic reviewer might miss
+violations.
+
+- **Toolsets:** kanban, file
+- **Skills:** `kanban-worker`
+- **Outputs:** comments + `brand-review.md`
+
+## Composing teams — heuristics
+
+- **Always:** director + at least one renderer + editor.
+- **Add writer** if scripted dialogue / narration / on-screen text exceeds a
+  tagline.
+- **Add storyboarder** if the brief has more than 5 distinct beats and the
+  director hasn't already laid out a beat list.
+- **Add cinematographer** if multiple renderer instances need consistent
+  visual language. (For a single-tool video, the renderer's own skill spec
+  is enough.)
+- **Add image-generator + image-to-video-generator pair** for narrative film
+  with photorealistic visuals.
+- **Add music-supervisor** when music is provided and rhythm matters
+  (music videos always; explainers sometimes).
+- **Add voice-talent** for any voiceover / narrative dialogue.
+- **Add audio-mixer** when there are 2+ audio sources (VO + music, music + SFX).
+- **Add captioner** for accessibility-priority projects (explainer, tutorial,
+  any platform that defaults to muted playback).
+- **Add reviewer** for high-stakes projects. Skip for quick experimental loops.
+- **Add masterer** when multiple platform deliverables are needed.
+
+## Anti-patterns
+
+- **One renderer doing everything.** If scenes use very different tools
+  (ASCII + 3D + motion graphics), use specialized renderer variants. The
+  renderer loads ONE creative skill at a time; mixing styles in a single
+  renderer causes thrashing.
+- **A separate profile per scene.** No. Profiles are per-role, not per-scene.
+  Eight scenes use one or two renderer profiles, not eight.
+- **A "general" profile that does everything.** Worse than no specialization.
+  The kanban routing breaks down if every task fits every profile.
+- **No reviewer for important deliverables.** Saves an hour of pipeline time
+  but ships flaws.

package/optional-skills/creative/kanban-video-orchestrator/references/tool-matrix.md

@@ -0,0 +1,317 @@
+# Tool Matrix — Skills + Toolsets per Role
+
+Maps each role archetype to the Hermes skills it should `always_load` and the
+toolsets it needs. Only references skills that ship in the public hermes-agent
+repository (under `skills/` or `optional-skills/`). External APIs and CLIs are
+called from the terminal toolset; they don't appear in `always_load`.
+
+## Hermes skills relevant to video production
+
+### Visual / rendering skills (`hermes-agent/skills/creative/`)
+
+| Skill | What it does | Best fit for |
+|-------|--------------|--------------|
+| `ascii-video` | Production pipeline for ASCII art video — generative, audio-reactive, video-to-ASCII | Renderer for ASCII / terminal / retro pixel content; cinematographer for ASCII projects |
+| `ascii-art` | Static ASCII art generation | Concept artist for ASCII style frames; secondary tool for ASCII renderer |
+| `manim-video` | Manim CE animations — math, algorithms, 3Blue1Brown-style explainers | Renderer for math, algorithm walkthroughs, technical concept explainers |
+| `p5js` | p5.js sketches — generative art, shaders, interactive, 3D | Renderer for generative art, particle systems, organic motion, web-canvas content |
+| `comfyui` | Generate images, video, audio with ComfyUI workflows (image-to-image, image-to-video, etc.) | image-generator, image-to-video-generator, or general renderer for AI-generated content |
+| `touchdesigner-mcp` | Control a running TouchDesigner instance — real-time visuals, audio-reactive installation art, VJ | Renderer for real-time/audio-reactive content; installation art; live performance |
+| `blender-mcp` *(optional)* | Control Blender 4.3+ via MCP — 3D modeling, animation, rendering | Renderer for 3D scenes, photoreal environments, character animation |
+| `pixel-art` | Pixel art with era palettes (NES, Game Boy, PICO-8) | Renderer for retro game aesthetic; concept artist for pixel-style frames |
+| `baoyu-comic` | Knowledge-comic generation (educational, biography, tutorial) | Renderer for comic-style narrative; explainer in panel form |
+| `baoyu-infographic` | Infographic generation | Renderer for data-driven explainer scenes |
+| `meme-generation` *(optional)* | Generate meme images by overlaying text on templates | Generator for satirical/social content; meme-style stills |
+
+### Design / pre-production skills (`hermes-agent/skills/creative/`)
+
+| Skill | What it does | Best fit for |
+|-------|--------------|--------------|
+| `claude-design` | Design one-off HTML artifacts (landing, deck, prototype) | Concept artist for product video style frames; storyboarder for UI-heavy content |
+| `design-md` | Design markdown docs | Concept artist documenting visual specs |
+| `popular-web-designs` | Reference patterns for popular web designs | Concept artist; cinematographer when matching a known UI aesthetic |
+| `sketch` | Throwaway HTML mockups (2-3 design variants to compare) | Concept artist exploring directions; storyboarder for UI flows |
+| `excalidraw` | Excalidraw-style hand-drawn diagrams | Storyboarder; concept artist for sketch-style frames |
+| `architecture-diagram` | Software architecture diagrams | Storyboarder for technical content; explainer scenes about systems |
+| `concept-diagrams` *(optional)* | Flat, minimal SVG diagrams (educational visual language; physics, chemistry, math, anatomy, etc.) | Renderer / storyboarder for explainer scenes with clean educational diagrams |
+| `pretext` | Mathematical/scientific content authoring | Writer / cinematographer for technical-explainer pretexts |
+| `creative-ideation` | Constraint-driven project ideation | Director / cinematographer when the brief is wide-open and needs framing |
+| `humanizer` | Strip AI-isms from text, add real voice | Writer / copywriter post-process to avoid AI-tells in scripts and VO copy |
+
+### Audio / media skills (`hermes-agent/skills/creative/` + `skills/media/`)
+
+| Skill | What it does | Best fit for |
+|-------|--------------|--------------|
+| `songwriting-and-ai-music` | Songwriting craft + Suno prompt patterns | Music supervisor when commissioning a track via Suno |
+| `heartmula` | Open-source music generation (Apache-2.0, Suno-like) | Music supervisor generating bespoke tracks without external APIs |
+| `songsee` | Spectrograms, mel/chroma/MFCC of audio files | Music supervisor analyzing tracks; foley-designer designing to a beat; editor visualizing a mix |
+| `spotify` | Spotify control — play, search, queue, manage playlists | Music supervisor sourcing existing tracks; reference research |
+| `youtube-content` | Fetch transcripts + transform to chapters/summaries/posts | Documentary cut, content adaptation, research for explainers |
+| `gif-search` | Find existing GIFs | Editor / concept artist sourcing references |
+| `gifs` | GIF tooling | Masterer producing GIF deliverables |
+
+### Kanban infrastructure (`hermes-agent/skills/devops/`)
+
+| Skill | What it does | When to load |
+|-------|--------------|--------------|
+| `kanban-orchestrator` | Decomposition playbook + anti-temptation rules for orchestrator profiles | Director only |
+| `kanban-worker` | Pitfalls, examples, edge cases for kanban workers (deeper than auto-injected guidance) | Any profile — load when handling tricky multi-step workflows |
+
+The kanban plugin auto-injects baseline orchestration guidance into every
+worker's system prompt — the `kanban_create` fan-out pattern, claim/handoff
+lifecycle, and the "decompose, don't execute" rule for orchestrators.
+`kanban-orchestrator` and `kanban-worker` are deeper playbooks loaded when a
+profile needs them.
+
+## External tools (called from terminal toolset)
+
+These are **not** Hermes skills but external CLIs / APIs that profiles invoke.
+They don't appear in `always_load`; instead the role's terminal commands hit
+them directly.
+
+| Tool | What it does | Profile that uses it |
+|------|--------------|----------------------|
+| `ffmpeg` | Video / audio encode, splice, mux | renderer, editor, audio-mixer, masterer |
+| `ffprobe` | Inspect media | All media-touching profiles |
+| Whisper (CLI or API) | Speech-to-text for captions | captioner |
+| Text-to-image API (FAL / Replicate / OpenAI / Midjourney) | Stills generation | image-generator (alternative to local `comfyui`) |
+| Image-to-video API (Runway / Kling / Luma / Pika) | Animate stills | image-to-video-generator |
+| Text-to-speech API (ElevenLabs / OpenAI TTS / etc.) | Voiceover generation | voice-talent |
+| Suno API or web | Track composition (paired with `songwriting-and-ai-music`) | music-supervisor |
+| Remotion CLI (`npx remotion render`) | React-based motion graphics | renderer-motion-graphics |
+| Manim CE (`manim`) | Math animation render (driven by `manim-video` skill's recipes) | renderer-manim |
+| Blender (`blender -b`) | 3D rendering (alternative to `blender-mcp`) | renderer-3d |
+
+## Built-in Hermes tools for media review
+
+These are native Hermes tools — not invoked via terminal but through their own
+toolsets. Enable them per-profile by adding the toolset to the profile config.
+
+| Tool | Toolset | What it does | Profile that uses it |
+|------|---------|--------------|----------------------|
+| `video_analyze` | `video` (opt-in — `hermes tools enable video`) | Native video understanding — sends full clip to a multimodal LLM (Gemini via OpenRouter) for review without frame extraction. Supports mp4, webm, mov, avi, mkv. 50 MB cap. Model: `AUXILIARY_VIDEO_MODEL` env → `AUXILIARY_VISION_MODEL` fallback. | reviewer, cinematographer, editor |
+| `vision_analyze` | `vision` (core — enabled by default) | Image/frame analysis — review stills, thumbnails, exported frames. Already available to all profiles without opt-in. | reviewer, cinematographer, concept-artist |
+
+## Standard toolset configurations per role
+
+### director
+
+```yaml
+toolsets:
+  - kanban
+  - terminal
+  - file
+skills:
+  always_load:
+    - kanban-orchestrator
+```
+
+The director's terminal access is conventional but the SOUL.md rules forbid
+execution. Audit logs catch violations.
+
+### writer / copywriter
+
+```yaml
+toolsets:
+  - kanban
+  - file
+skills:
+  always_load:
+    - kanban-worker
+    - humanizer            # post-process scripts to strip AI-tells
+```
+
+No terminal — writers don't need it.
+
+### concept-artist
+
+```yaml
+toolsets:
+  - kanban
+  - terminal
+  - file
+skills:
+  always_load:
+    - kanban-worker
+    # plus one or more (style-dependent):
+    # - claude-design       (UI / web product video)
+    # - sketch              (quick mockup variants)
+    # - excalidraw          (hand-drawn frames)
+    # - ascii-art           (ASCII style frames)
+    # - pixel-art           (retro/game aesthetic)
+    # - popular-web-designs (matching known web aesthetic)
+    # - design-md           (text-based design docs)
+```
+
+### storyboarder
+
+```yaml
+toolsets:
+  - kanban
+  - file
+skills:
+  always_load:
+    - kanban-worker
+    # one of:
+    # - excalidraw              (sketch storyboards)
+    # - architecture-diagram    (technical/system content)
+    # - concept-diagrams        (educational / scientific content)
+```
+
+### cinematographer
+
+```yaml
+toolsets:
+  - kanban
+  - terminal
+  - file
+  - video               # video_analyze — review full clips natively
+  - vision              # vision_analyze — review stills / exported frames
+skills:
+  always_load:
+    - kanban-worker
+    # the visual skill that matches the project, e.g.:
+    # - ascii-video            (ASCII projects)
+    # - manim-video            (math/explainer)
+    # - p5js                   (generative)
+    # - comfyui                (AI-generated visuals)
+    # - blender-mcp            (3D)
+    # - touchdesigner-mcp      (real-time/installation)
+```
+
+### renderer (specialized variants)
+
+```yaml
+toolsets:
+  - kanban
+  - terminal
+  - file
+skills:
+  always_load:
+    - kanban-worker
+    # ONE skill per renderer variant (or empty for external-API renderers):
+    # - ascii-video               (renderer-ascii)
+    # - manim-video               (renderer-manim)
+    # - p5js                      (renderer-p5js)
+    # - comfyui                   (renderer-comfyui — img/video AI gen)
+    # - touchdesigner-mcp         (renderer-touchdesigner)
+    # - blender-mcp               (renderer-3d)
+    # - pixel-art                 (renderer-pixel)
+    # - baoyu-comic               (renderer-comic)
+    # - meme-generation           (renderer-meme)
+```
+
+For external-API renderers (image-to-video-generator using Runway, voice-talent
+using ElevenLabs, renderer-motion-graphics using Remotion), `always_load` only
+contains `kanban-worker` — the role's work is API-driven and the API key +
+terminal commands suffice.
+
+For multi-skill renderer setups (rare — usually one variant per skill is
+cleaner) use `--skill <name>` on individual `kanban_create` calls to override
+which skill loads for that specific task.
+
+### image-generator / image-to-video-generator / voice-talent
+
+```yaml
+toolsets:
+  - kanban
+  - terminal
+  - file
+skills:
+  always_load:
+    - kanban-worker
+    # for image-generator that drives ComfyUI locally:
+    # - comfyui
+env_required:
+  # populate based on the chosen API:
+  - FAL_KEY                 # or REPLICATE_API_TOKEN, OPENAI_API_KEY for image-gen
+  - RUNWAY_API_KEY          # or KLING_API_KEY, LUMA_API_KEY for image-to-video
+  - ELEVENLABS_API_KEY      # or OPENAI_API_KEY for TTS
+```
+
+If the user's setup has ComfyUI installed locally, the `comfyui` skill can
+replace the external image-gen API entirely (cheaper, more control, supports
+custom workflows for image-to-video too).
+
+### music-supervisor
+
+```yaml
+toolsets:
+  - kanban
+  - terminal
+  - file
+skills:
+  always_load:
+    - kanban-worker
+    - songsee                         # spectrograms / audio analysis
+    # plus (depending on what the project needs):
+    # - songwriting-and-ai-music      (commissioning Suno tracks)
+    # - heartmula                     (commissioning open-source local generation)
+    # - spotify                       (sourcing existing tracks)
+```
+
+### editor / audio-mixer / captioner / masterer
+
+```yaml
+toolsets:
+  - kanban
+  - terminal
+  - file
+  - video              # video_analyze — editor reviews assembled cuts natively
+  - vision             # vision_analyze — spot-check frames
+skills:
+  always_load:
+    - kanban-worker
+```
+
+These are mostly ffmpeg-driven; no special skill needed beyond `kanban-worker`.
+For captioner add Whisper invocation patterns to the SOUL.md.
+
+### reviewer / brand-cop
+
+```yaml
+toolsets:
+  - kanban
+  - terminal           # for media inspection (ffprobe, etc.)
+  - file
+  - video              # video_analyze — review full clips natively
+  - vision             # vision_analyze — review stills / exported frames
+skills:
+  always_load:
+    - kanban-worker
+```
+
+## API key requirements
+
+Track these in the project setup. The setup script should verify each required
+key is present in `~/.hermes/.env` (or macOS Keychain) before firing the kanban.
+
+| Service | Env var | Used by |
+|---------|---------|---------|
+| ElevenLabs | `ELEVENLABS_API_KEY` | voice-talent |
+| OpenAI | `OPENAI_API_KEY` | image-generator (DALL-E), voice-talent (TTS) |
+| OpenRouter | `OPENROUTER_API_KEY` | reviewer, cinematographer, editor (`video_analyze` routes through `AUXILIARY_VIDEO_MODEL` → OpenRouter) |
+| FAL | `FAL_KEY` | image-generator (FAL flux models) |
+| Replicate | `REPLICATE_API_TOKEN` | image-generator (alternate provider) |
+| Runway | `RUNWAY_API_KEY` | image-to-video-generator |
+| Kling | `KLING_API_KEY` | image-to-video-generator (alternate) |
+| Luma | `LUMA_API_KEY` | image-to-video-generator (alternate) |
+| Suno | `SUNO_API_KEY` | music-supervisor (paired with `songwriting-and-ai-music`) |
+| Spotify | `SPOTIFY_CLIENT_ID` + `SPOTIFY_CLIENT_SECRET` | music-supervisor (paired with `spotify` skill) |
+| Anthropic | `ANTHROPIC_API_KEY` | every Hermes profile (Claude) |
+
+If a key is missing, prompt the user to add it. Storage methods, in order of
+preference: macOS Keychain → `~/.hermes/.env` → environment variable.
+
+## Skill version pinning
+
+If a specific skill version is desired, pass it via the per-task
+`--skill <name>=<version>` flag. The default is whatever's installed.
+
+## Adding a new skill to the matrix
+
+When a new Hermes-public video skill ships:
+
+1. Add a row to the relevant table at the top of this file
+2. If it warrants a specialized renderer variant, add to `role-archetypes.md`
+3. Update relevant per-style examples in `examples.md`