mindforge-cc 11.5.0 → 11.6.0

package/.agent/skills/video-orchestrator/references/examples.md

@@ -0,0 +1,227 @@
+# Worked Examples
+
+Six concrete pipelines covering different video styles. Each shows the team
+composition, task graph, and skill/tool choices the orchestrator would make
+for that brief. **These are illustrative, not templates** — adapt to the
+actual brief.
+
+## Example 1 — Narrative short film (text-to-image → image-to-video → cut)
+
+**Brief:** A 90-second noir-style short. A detective walks through a rainy
+city. Voiceover narration. AI-generated visuals.
+
+**Team:**
+- `director` — vision, decomposition, approval
+- `writer` — script + voiceover copy (loads `humanizer` for natural voice)
+- `storyboarder` — beat-by-beat shot list (loads `excalidraw`)
+- `image-generator` — generates each shot's still via local ComfyUI workflows
+  (loads `comfyui`)
+- `image-to-video-generator` — animates each still (Runway/Kling, OR
+  ComfyUI's AnimateDiff/WAN workflows via `comfyui`)
+- `voice-talent` — narration via ElevenLabs
+- `audio-mixer` — VO + ambient pad
+- `editor` — assembly + transitions
+- `reviewer` — final QA
+
+**Task graph:**
+```
+T0  director         decompose
+T1  writer           script + voiceover.md                    (parent: T0)
+T2  storyboarder     shot list with framing per beat          (parent: T1)
+T3  image-generator  one still per shot (~12 shots)           (parent: T2)
+T4  image-to-video   animate each still                       (parent: T3)
+T5  voice-talent     generate narration audio                 (parent: T1)
+T6  audio-mixer      mix VO + ambient                         (parent: T5)
+T7  editor           cut + transitions + audio mux            (parents: T4, T6)
+T8  reviewer         final QA                                 (parent: T7)
+```
+
+**Key choices:**
+- Local ComfyUI via `comfyui` skill is preferred over external API for
+  cost/control — but external APIs are fine if ComfyUI isn't installed
+- `editor` profile is ffmpeg-only, no specialized skill required beyond
+  `kanban-worker`
+- Storyboarder produces `storyboard.excalidraw` alongside the markdown
+
+## Example 2 — Product / marketing teaser
+
+**Brief:** A 30-second product teaser for a developer tool. Shows code +
+terminal + UI screen recordings, voiceover, CTA at end. Square 1:1.
+
+**Team:**
+- `director`
+- `copywriter` — taglines, voiceover script, CTA (loads `humanizer`)
+- `concept-artist` — style frames (loads `claude-design` for UI mockups)
+- `renderer-motion-graphics` — animated UI sequences (Remotion CLI)
+- `renderer-ascii` — terminal-style demo scenes (loads `ascii-video`)
+- `voice-talent` — VO via ElevenLabs
+- `editor` — assembly + brand-color treatment
+- `audio-mixer` — VO + light music bed
+- `captioner` — burned subtitles for muted-autoplay platforms
+- `masterer` — produces 1:1 + 9:16 + 16:9 variants
+
+**Task graph:**
+```
+T0  director              decompose
+T1  copywriter            copy.md + cta + vo script               (parent: T0)
+T2  concept-artist        visual-spec.md + style frames           (parent: T1)
+T3a renderer-motion-graphics  scene 1: UI sequence                (parent: T2)
+T3b renderer-ascii        scene 2: terminal demo                  (parent: T2)
+T3c renderer-motion-graphics  scene 3: feature highlight          (parent: T2)
+T3d renderer-motion-graphics  scene 4: CTA card                   (parent: T2)
+T4  voice-talent          narration                                (parent: T1)
+T5  audio-mixer           VO + music bed                          (parent: T4)
+T6  editor                cut + transitions                        (parents: T3*, T5)
+T7  captioner             SRT + burned subtitles                  (parent: T6)
+T8  masterer              1:1, 9:16, 16:9 variants                (parent: T7)
+```
+
+**Key choices:**
+- Multiple specialized renderers (motion-graphics + ASCII) coexist
+- Captioner is included because muted autoplay is the norm on social
+- `claude-design` skill for UI mockups maps directly to the product video idiom
+
+## Example 3 — Music video (synced to provided track)
+
+**Brief:** A 3-minute music video for a provided lo-fi hip-hop track. Visuals
+should pulse with the beat. Generative + ASCII hybrid. Vertical 9:16.
+
+**Team:**
+- `director`
+- `music-supervisor` — analyze track, emit `audio/beats.json` (loads `songsee`)
+- `storyboarder` — beat-aligned shot list (loads `excalidraw`)
+- `renderer-ascii` — ASCII scenes synced to bass kicks (loads `ascii-video`)
+- `renderer-p5js` — generative particle scenes synced to highs (loads `p5js`)
+- `editor` — beat-cut assembly using `beats.json`
+- `reviewer` — sync QA
+
+**Task graph:**
+```
+T0  director              decompose
+T1  music-supervisor      analyze track → beats.json + spectrogram  (parent: T0)
+T2  storyboarder          shot list aligned to beats                (parents: T1, T0)
+T3a renderer-ascii        scene 1: bass-driven ASCII                (parent: T2)
+T3b renderer-p5js         scene 2: high-end particle field          (parent: T2)
+... (more scenes)
+T4  editor                cut to beats + mux track                  (parents: T3*, T1)
+T5  reviewer              sync QA + final approval                  (parent: T4)
+```
+
+**Key choices:**
+- `music-supervisor` runs FIRST — `beats.json` gates the renderers
+- `editor` uses `beats.json` directly to align cuts to bass kicks
+- No voice-talent — music is the audio
+- Two specialized renderers (`ascii-video` + `p5js`) for visual variety
+
+## Example 4 — Math/algorithm explainer
+
+**Brief:** A 2-minute explainer of an algorithm. 3Blue1Brown-style. Animated
+diagrams, equations, narration. Square 1:1.
+
+**Team:**
+- `director`
+- `writer` — narration script (loads `humanizer`)
+- `cinematographer` — visual spec (loads `manim-video`)
+- `renderer-manim` — all animated scenes (loads `manim-video`)
+- `voice-talent` — narration via ElevenLabs
+- `editor` — assembly + audio mux
+- `captioner` — burned subtitles
+
+**Task graph:**
+```
+T0  director           decompose
+T1  writer             script + narration                  (parent: T0)
+T2  cinematographer    visual spec for all scenes           (parent: T1)
+T3a-Tn renderer-manim  scenes 1..N                          (parents: T2)
+T4  voice-talent       narration audio                      (parent: T1)
+T5  editor             cut + mux                            (parents: T3*, T4)
+T6  captioner          SRT + burn                           (parent: T5)
+```
+
+**Key choices:**
+- `manim-video` skill drives both the cinematographer (visual language) and
+  the renderer (actual scene production)
+- The `manim-video` skill's reference docs (animation-design-thinking,
+  scene-planning, equations) auto-load when needed via the renderer's pinned skill
+
+## Example 5 — ASCII video, music-track-only
+
+**Brief:** A 60-second pure-ASCII video reactive to an existing track. No
+voiceover, no other tools. Square 1:1.
+
+**Team:**
+- `director`
+- `music-supervisor` — track analysis (loads `songsee`)
+- `renderer-ascii` — all visuals (loads `ascii-video`)
+- `editor` — assembly + audio mux
+
+**Task graph:**
+```
+T0  director           decompose
+T1  music-supervisor   analyze track                       (parent: T0)
+T2a renderer-ascii     scene 1                             (parents: T1, T0)
+T2b renderer-ascii     scene 2                             (parents: T1, T0)
+T2c renderer-ascii     scene 3                             (parents: T1, T0)
+T3  editor             stitch + mux audio                  (parents: T2*)
+```
+
+**Key choices:**
+- Minimal team (4 profiles) for a focused single-tool project
+- No reviewer — short experimental piece, director approves directly
+- All scenes run through one `renderer-ascii` profile because the `ascii-video`
+  skill covers everything
+
+This example illustrates the rule: **don't over-decompose**. Three scenes
+through one renderer is fine. Don't spawn three renderer profiles.
+
+## Example 6 — Real-time / installation art
+
+**Brief:** A 2-minute audio-reactive visual for a gallery installation. Driven
+by an audio input feed. TouchDesigner-based. 16:9 4K.
+
+**Team:**
+- `director`
+- `cinematographer` — visual language spec (loads `touchdesigner-mcp`)
+- `renderer-touchdesigner` — all visuals + record-to-disk
+  (loads `touchdesigner-mcp`)
+- `audio-mixer` — final loudness pass on the captured audio (optional if
+  pre-mixed source)
+- `editor` — assemble final clip from TouchDesigner recording
+- `reviewer` — visual QA
+
+**Task graph:**
+```
+T0  director                decompose
+T1  cinematographer         TD operator graph spec           (parent: T0)
+T2  renderer-touchdesigner  build TD network + record output (parent: T1)
+T3  editor                  trim + audio mux                 (parent: T2)
+T4  reviewer                final QA                         (parent: T3)
+```
+
+**Key choices:**
+- `touchdesigner-mcp` controls a running TouchDesigner instance — the
+  cinematographer designs the operator graph, renderer builds it
+- Output is a recording from the running TD network, not a render-to-frames
+  process; editor mostly just trims
+
+## Pattern recognition
+
+When the user describes a video, look for these signals to map to an example:
+
+- **Plot, characters, scripted dialogue** → Example 1 (narrative)
+- **Specific product, CTA, brand colors, voiceover** → Example 2 (marketing)
+- **Track file provided, "synced to music"** → Example 3 (music video)
+- **"Explain how X works", math/algorithm/concept walkthrough** → Example 4 (manim explainer)
+- **Terminal aesthetic, ASCII, retro pixel** → Example 5 (ASCII)
+- **"Audio-reactive", "real-time", "installation"** → Example 6 (TouchDesigner)
+- **Comic-style narrative** → use `renderer-comic` (`baoyu-comic` skill)
+- **Retro game / pixel-art aesthetic** → use `renderer-pixel` (`pixel-art` skill)
+- **3D scene, photoreal environment** → use `renderer-3d` (`blender-mcp`)
+- **Generative art, particle system, shader** → use `renderer-p5js` (`p5js`)
+- **AI-generated photoreal stills + animation** → use `renderer-comfyui`
+  (`comfyui`) for both stills and image-to-video
+- **"video about how the system works", recursive demo** → composable from
+  any of the above; the recursion is a rendering technique, not a style
+
+The actual team should be derived from the specific brief — these examples are
+starting points, not endpoints.

package/.agent/skills/video-orchestrator/references/intake.md

@@ -0,0 +1,166 @@
+# Intake — Discovery Question Banks
+
+The discovery process is **adaptive**. Always start with three baseline
+questions to identify the broad style category, then drill into a per-style
+question bank. Ask 2-4 questions at a time, listen, then proceed. Make
+reasonable assumptions whenever the user implies an answer.
+
+## Tier 0 — Baseline (always ask)
+
+1. **What is the video?** — One-sentence pitch
+2. **How long?** — Approximate duration
+3. **Aspect ratio + target platform?** — 16:9 / 9:16 / 1:1 / 4:5; X, IG, YouTube, internal, etc.
+
+From these answers, classify the style category and pick the relevant Tier 1
+follow-ups. **Do not** continue asking until you have at least these three.
+
+## Style classification
+
+Map the brief to one of these archetypes (or a hybrid):
+
+| Archetype | Tells |
+|-----------|-------|
+| **Narrative film** | Plot, characters, scenes-with-events, dialogue, location |
+| **Product / marketing** | A specific product or feature being shown / sold; CTA at end |
+| **Music video** | A specific track exists; visuals sync to music |
+| **Explainer / educational** | A concept being taught; voiceover-driven |
+| **Tutorial / changelog** | Software demo, terminal-heavy, technical |
+| **ASCII / terminal art** | Retro terminal aesthetic explicit, character-grid |
+| **Abstract / loop** | Generative, no plot, often perfect-loop |
+| **Documentary / interview cut** | Real footage, transcription-driven |
+| **Real-time / installation** | Audio-reactive, gallery installation, VJ output |
+
+If ambiguous, **ask** which category fits — don't guess. Hybrids are common
+(e.g., a product video with a narrative arc); decompose into the dominant
+mode + secondary modifiers.
+
+**Recursive / meta** ("a video that shows its own production") is a
+*rendering technique*, not a separate style — compose it from any of the
+above by adding a two-pass render step where pass 2 uses pass 1's output as
+texture inside the final scene.
+
+## Tier 1 — Per-style follow-ups
+
+### Narrative film
+
+- **Setting / world?** — When and where the story takes place
+- **Characters?** — How many, archetypes, who carries dialogue
+- **Beat list or full script?** — Has the user written the story or do we draft it
+- **Dialogue language?** — Spoken lines, on-screen subs only, silent
+- **Visual generation approach?** — Text-to-image (FAL/Midjourney/Imagen) →
+  image-to-video (Runway/Kling), 3D animation (Blender), 2D animation,
+  procedural, or hybrid
+- **Voice approach?** — TTS (which voice), recorded VO, no dialogue
+- **Music / score?** — Commissioned (via `songwriting-and-ai-music` Suno
+  prompts, or local `heartmula`), licensed track provided, silent
+
+### Product / marketing
+
+- **Product?** — Name, what it does, key feature being shown
+- **Target audience?** — Who's watching, what they care about
+- **CTA?** — Visit URL, install, sign up, etc.
+- **Tone?** — Serious, playful, technical, premium, edgy
+- **Brand assets available?** — Logo files, color palette, fonts, existing footage
+- **Animation style?** — Motion graphics (Remotion / AE-style), screen recording,
+  generative, illustrated
+- **Voiceover?** — Yes (which voice / language) or text-only
+- **Music?** — Track provided, license-free needed, custom-composed
+
+### Music video
+
+- **Track file?** — Path to the audio (essential — we'll analyze BPM + beats)
+- **Track length to use?** — Full song or a section
+- **Genre / energy?** — Tells what visual rhythm and density to use
+- **Lyric / narrative content?** — Are there lyrics to render on screen,
+  or is it purely visual?
+- **Visual reference style?** — Existing music videos / artists for reference
+- **Performer footage?** — None, has clips, will provide
+- **Visual generation approach?** — Per-beat generative, edit-driven cuts of stock
+  footage, illustrated, hybrid
+
+### Explainer / educational
+
+- **What concept is being taught?** — One-sentence concept, key takeaway
+- **Audience expertise?** — Beginner / intermediate / expert
+- **Diagram density?** — Heavy math / formulas / code / abstract concepts
+- **Voiceover?** — TTS / recorded / on-screen text only
+- **Tool preference?** — `manim-video` (math), `p5js` (generative),
+  Remotion (UI motion graphics), `comfyui` (AI-generated visuals),
+  `ascii-video` (technical/retro), hybrid
+- **Pacing?** — Fast and dense (3Blue1Brown) or slow and contemplative
+
+### Tutorial / changelog / software demo
+
+- **Software being demonstrated?** — Name, what it does
+- **Demo script?** — Sequence of commands / screens to show
+- **Terminal-only or with GUI?**
+- **Voiceover for narration?**
+- **Diagram support needed?** — Often these benefit from a diagram skill
+  alongside the screen-capture/render step (`excalidraw`,
+  `architecture-diagram`, `concept-diagrams`)
+
+### ASCII / terminal art
+
+- **Source material?** — Generative / driven by audio / converting existing
+  video / static image starting point
+- **Color palette?** — Brand-driven (gold/black/blue), Matrix green, full
+  rainbow, monochrome
+- **Audio reactivity?** — None / loose mood / tight beat sync / FFT-driven
+- **Character set?** — ASCII only / Unicode block-drawing / mystic glyphs
+- **Loop or narrative?** — Perfect loop or one-shot
+
+### Abstract / loop
+
+- **Mood / emotion?** — One word that captures the feel
+- **Motion type?** — Zoom-into-itself, particle drift, wave, geometric, organic
+- **Loop required?** — Perfect loop (Droste-style) or just satisfying ending
+- **Audio?** — Silent, ambient pad, beat-synced
+
+### Documentary / interview cut
+
+- **Source footage?** — Provided clips, length per clip
+- **Transcript / subtitles?** — Provided or to be generated
+- **Story structure?** — Chronological / thematic / arc
+- **B-roll approach?** — Generated, stock library, none
+
+### Real-time / installation
+
+- **Output environment?** — Gallery wall, projector, screen, web embed
+- **Audio source?** — Live audio input, pre-recorded track, both
+- **Reactivity tightness?** — Mood-level (loose) vs. tight beat-sync vs. live
+  parameter control
+- **Tool preference?** — `touchdesigner-mcp` for full TD operator graphs;
+  `p5js` for web-canvas; `comfyui` for generative-AI fed by audio features
+
+## Tier 2 — Always ask near the end
+
+- **Brand assets path?** — Where logo / color palette / fonts / music library lives
+- **Output format requirements?** — Codec preference, target file size, accepted
+  alternates (vertical cut, GIF, audio-only)
+- **Deadline?** — Affects task `max_runtime_seconds` and acceptable scope
+- **Quality bar?** — Rough draft for review / polished final / archival
+- **Existing footage / assets to reuse?** — Anything that should appear, not just inform
+
+## Reasonable assumption defaults
+
+When the user under-specifies, fill in these defaults rather than asking:
+
+| Question | Default |
+|----------|---------|
+| Frame rate | 30 fps for X / IG; 60 fps for tutorials/explainers; 24 fps for narrative film |
+| Resolution | 1080×1080 for square, 1920×1080 for 16:9, 1080×1920 for 9:16 |
+| Codec | H.264 / yuv420p, CRF 18 |
+| Audio codec | AAC 192 kbps |
+| Voice | Provider's mid-range neutral voice unless brand calls for distinctive timbre |
+| Music | Silent (require user to specify if music is wanted) |
+| Captions | On for explainer/tutorial; off for narrative/abstract unless requested |
+| Quality bar | Polished final unless user says draft |
+
+State the assumption explicitly: *"Assuming 30fps and AAC audio unless you say otherwise — proceed?"*
+
+## Anti-patterns
+
+- **Asking 10 questions at once.** Maximum 4 per turn.
+- **Asking for things the brief already implies.** If the user said "music video for my track," do not ask "is there a track?"
+- **Failing to classify before drilling in.** Tier-1 questions depend on classification; mixing them up wastes turns.
+- **Treating "make a video" as enough to proceed.** Always confirm the three baseline questions.

package/.agent/skills/video-orchestrator/references/kanban-setup.md

@@ -0,0 +1,278 @@
+# Kanban Setup — Project Bootstrap & Profile Configuration
+
+Once the brief is locked and the team is designed, the next step is producing
+the actual `setup.sh` that creates the project workspace, configures the agent
+profiles, and fires the initial kanban task.
+
+This file documents the patterns. The companion script
+`scripts/bootstrap_pipeline.py` automates most of it from a structured input
+JSON.
+
+> **Credit:** the single-project-workspace layout, profile-config patching
+> approach, SOUL.md-per-profile convention, and `--workspace dir:<path>` rule
+> are adapted from alt-glitch's original multi-agent video pipeline:
+> [
+> This skill generalizes those patterns across video styles and replaces the
+> string-replacement config patcher with a PyYAML-based one.
+
+## Project workspace structure
+
+Every video project gets one workspace under `~/projects/video-pipeline/<slug>/`:
+
+```
+~/projects/video-pipeline/<slug>/
+├── brief.md                       ← the contract; all tasks reference
+├── TEAM.md                        ← team composition + task graph (director reads this)
+├── taste/
+│   ├── brand-guide.md             ← color, typography, motion rules
+│   ├── emotional-dna.md           ← what the piece should FEEL like
+│   └── style-frames/              ← optional: visual references
+├── audio/
+│   ├── track.mp3                  ← provided music (if any)
+│   ├── voiceover/                 ← per-line TTS clips
+│   └── sfx/                       ← sound effects
+├── assets/
+│   ├── logos/
+│   ├── fonts/
+│   └── existing-footage/          ← reusable provided clips
+├── scenes/
+│   ├── scene-01/
+│   │   ├── VISUAL_SPEC.md         ← cinematographer's per-scene spec
+│   │   ├── render.py              ← renderer's code (or sketch.html, etc.)
+│   │   ├── checkpoints/           ← preview frames for QA
+│   │   └── clip.mp4               ← the deliverable for this scene
+│   ├── scene-02/...
+│   └── ...
+├── checkpoints/                   ← global review frames
+├── tools/                         ← optional project-local helpers
+└── output/
+    ├── final.mp4                  ← stitched + audio
+    ├── final-noaudio.mp4
+    ├── final-9x16.mp4             ← optional: vertical alternate
+    └── captions.srt               ← optional: subtitle file
+```
+
+**The slug** is derived from the brief title: lowercase, hyphen-separated.
+Example: `q3-product-teaser`, `ascii-mood-loop`, `interview-cut-2026-q1`.
+
+## The setup.sh script
+
+The setup script does six things in order:
+
+1. **Create workspace tree** — all directories above
+2. **Create profiles** — `hermes profile create <name> --clone`
+3. **Configure profiles** — patch each profile's
+   `~/.agent/profiles/<name>/config.yaml` to set toolsets, always_load skills,
+   and `cwd`
+4. **Write SOUL.md per profile** — the personality + role definition
+5. **Copy any provided assets + write `brief.md`, `TEAM.md`, and `taste/`**
+6. **Fire the initial kanban task** — `hermes kanban create` assigned to the director
+
+See `assets/setup.sh.tmpl` for the skeleton.
+
+### Profile creation pattern
+
+```bash
+hermes profile create director --clone 2>/dev/null || true
+```
+
+The `--clone` flag clones from the active profile (preserving model, base
+config). The `|| true` makes the script idempotent — re-running won't error if
+the profile already exists.
+
+### Profile config patching
+
+Each profile has a YAML config at `~/.agent/profiles/<name>/config.yaml`. The
+setup script edits exactly two keys:
+
+1. `toolsets:` — replace the default with the role's required toolsets
+2. `skills.always_load:` — list the role's must-load skills (may be empty)
+
+**Do NOT** modify `approvals.mode` (controls user-confirmation of tool calls
+— a security setting that must stay as the user configured it). **Do NOT**
+modify `terminal.cwd` — the kanban dispatcher overrides cwd per-task via
+`--workspace dir:<path>`, so the profile's cwd is irrelevant to the kanban
+work and changing it could break the user's interactive use of the profile.
+
+Use **PyYAML**, not string replacement, so the patch is robust against
+default-config schema drift:
+
+```bash
+configure_profile() {
+    local profile="$1"
+    local toolsets_json="$2"     # JSON array, e.g. '["kanban","terminal","file"]'
+    local skills_json="$3"       # JSON array, e.g. '["kanban-worker","ascii-video"]'
+    python3 - "$profile" "$toolsets_json" "$skills_json" <<'PY'
+import json, os, sys, yaml
+profile, ts_json, sk_json = sys.argv[1:4]
+p = os.path.expanduser(f"~/.agent/profiles/{profile}/config.yaml")
+with open(p) as f:
+    cfg = yaml.safe_load(f) or {}
+cfg["toolsets"] = json.loads(ts_json)
+cfg.setdefault("skills", {})["always_load"] = json.loads(sk_json)
+with open(p, "w") as f:
+    yaml.safe_dump(cfg, f, sort_keys=False)
+PY
+}
+```
+
+PyYAML must be installed in the user's Python (it commonly available
+installs). If absent: `pip install pyyaml`.
+
+The setup script should also **validate** the patch by re-reading the file
+and comparing — see `assets/setup.sh.tmpl` for the validation pattern.
+
+### SOUL.md per profile
+
+Each profile gets a `SOUL.md` at `~/.agent/profiles/<name>/SOUL.md` that
+defines its role, voice, and rules. See `assets/soul.md.tmpl` for the
+template. Customize per role and per project.
+
+The director's SOUL.md should be the most opinionated — its voice flavors
+the entire production. **Critical content for the director's SOUL.md:**
+
+- **Anti-temptation rules:** "Do not execute the work yourself. For every
+  concrete task, create a kanban task and assign it. Decompose, route, comment,
+  approve — that's the whole job." (The `kanban-orchestrator` skill provides
+  the deeper playbook; load it.)
+- **Decomposition steps:** Read `brief.md`, `TEAM.md`, `taste/`. Use the team
+  graph in `TEAM.md` to fan out tasks.
+- **The workspace_path rule** (see below).
+
+Other profiles' SOUL.md is briefer; mostly mechanical: who you are, what you
+read, what you produce, what skills/tools to use, where to write outputs.
+Most non-director profiles should `always_load: kanban-worker` for the
+deeper-than-baseline kanban guidance.
+
+### Initial kanban task
+
+The final action of setup.sh is firing the kanban:
+
+```bash
+hermes kanban create "Direct production of <video title>" \
+    --assignee director \
+    --workspace dir:"$HOME/projects/video-pipeline/${PROJECT_SLUG}" \
+    --tenant ${PROJECT_SLUG} \
+    --priority 2 \
+    --max-runtime 4h \
+    --body "$(cat <<EOF
+Read brief.md, TEAM.md, and taste/.
+Decompose into the team graph defined in TEAM.md.
+All child tasks MUST use:
+  workspace_kind="dir"
+  workspace_path="$HOME/projects/video-pipeline/${PROJECT_SLUG}"
+  tenant="${PROJECT_SLUG}"
+EOF
+)"
+```
+
+The `--workspace dir:<path>` flag is **critical** — it tells the kanban that
+all child tasks share this workspace. Skipping or using `worktree` will
+isolate profiles and break artifact sharing.
+
+## The TEAM.md file
+
+Alongside `brief.md`, write a `TEAM.md` that the director reads. It documents
+the team composition + task graph the orchestrator should follow. This
+removes ambiguity and prevents the director from inventing extra steps.
+
+Example structure (for an ASCII video with a music supervisor and editor):
+
+```markdown
+# Team & Task Graph — <video title>
+
+## Team
+
+- `director` (this profile) — vision, decomposition, approval
+- `cinematographer` — visual spec, quality review (loads `ascii-video`)
+- `renderer-ascii` — ASCII scenes (loads `ascii-video`)
+- `music-supervisor` — track analysis (loads `songsee`)
+- `voice-talent` — narration (uses ElevenLabs API)
+- `audio-mixer` — final mix (ffmpeg)
+- `editor` — assembly (ffmpeg)
+- `reviewer` — final QA gate
+
+## Task Graph
+
+T0: this task — decompose
+ │
+ ├── T1: cinematographer  "Design visual language"            (parent: T0)
+ │    │
+ │    ├── T2a: renderer-ascii   "Scene 1 — title card"        (parent: T1)
+ │    ├── T2b: renderer-ascii   "Scene 2 — main beat"         (parent: T1)
+ │    ├── T2c: renderer-ascii   "Scene 3 — outro"             (parent: T1)
+ │
+ ├── T3: music-supervisor "Analyze track + emit beats.json"   (parent: T0)
+ │
+ ├── T4: voice-talent     "Generate narration"                (parent: T0)
+ │
+ ├── T5: audio-mixer      "Mix VO + bg music"                 (parents: T3, T4)
+ │
+ ├── T6: editor           "Assemble cut + mux audio"          (parents: T2*, T5)
+ │
+ └── T7: reviewer         "Final QA"                          (parent: T6)
+```
+
+The director turns this into actual `kanban_create` calls.
+
+## API-key prerequisites check
+
+Before firing the kanban, verify required keys are available. Check both
+the the agent `.env` (`${AGENT_HOME:-$HOME/.agent}/.env`) and macOS Keychain
+(if on macOS):
+
+```bash
+check_key() {
+    local var="$1"
+    local kc_account="$2"
+    local kc_service="$3"
+    local _agent_env="${AGENT_HOME:-$HOME/.agent}/.env"
+    if grep -q "^${var}=" "$_agent_env" 2>/dev/null && \
+       [ -n "$(grep "^${var}=" "$_agent_env" | cut -d= -f2-)" ]; then
+        return 0
+    fi
+    if command -v security >/dev/null 2>&1 && \
+       security find-generic-password -a "${kc_account}" -s "${kc_service}" -w >/dev/null 2>&1; then
+        return 0
+    fi
+    echo "ERROR: ${var} not set in ${_hermes_env} or Keychain (${kc_account}/${kc_service})"
+    return 1
+}
+
+check_key ELEVENLABS_API_KEY hermes ELEVENLABS_API_KEY || exit 1
+check_key OPENROUTER_API_KEY hermes OPENROUTER_API_KEY || exit 1
+# ...
+```
+
+If a key is missing, the script aborts with a clear message rather than
+firing a kanban that will hit credential errors mid-execution.
+
+## Critical rules
+
+1. **`workspace_kind="dir"` + `workspace_path="<absolute>"` on every kanban_create.** Otherwise profiles can't share artifacts.
+
+2. **Tenant every task.** `--tenant <project-slug>` keeps the dashboard scoped
+   and prevents cross-pollination with other ongoing kanbans.
+
+3. **Idempotency keys.** For tasks that should not duplicate on re-run (e.g.,
+   setup creating profiles), use the `idempotency_key` argument or check
+   existence first.
+
+4. **`max_runtime_seconds` per task.** Renderers that get stuck eat compute.
+   Standard defaults:
+   - Renderer task: 1800s (30min)
+   - Editor task: 600s (10min)
+   - Voice-talent task: 300s (5min)
+   - Image-generator task: 600s (10min)
+   - Image-to-video-generator task: 900s (15min)
+
+5. **Heartbeats for long renders.** Tasks expected to run >5min should emit
+   `kanban_heartbeat` periodically with progress. Renderers should report
+   frame counts; the editor should report assembly progress.
+
+6. **The `audio/` and `taste/` dirs are populated BEFORE firing the kanban.**
+   Don't ask the director's pipeline to source these — copy at setup time.
+
+7. **`brief.md` is read-only after setup.** If the brief changes during
+   execution, that's a significant pivot — re-fire the kanban rather than edit
+   live.