# Long-Form Video Production Copilot

Agentic long-form video generation pipeline — granular storyboarding, native audio, acting-centric direction, and cross-scene visual continuity.

## Essential Context
> [!IMPORTANT]
> Always reference `project/production_bible.json` and `project/scripts/detailed_script.md` for the project's core narrative, tone, and scene requirements before storyboarding, scene generation, continuity generation, or video generation. For direct image editing, prioritize the user's edit instruction and the source images; only pull production-bible style when the user explicitly asks to restyle or match the project look.

---

## Project Structure
```
project/
├── scripts/
│   ├── detailed_script.md              # Master script (mixed prose + camera script)
│   └── Act_X/
│       └── Scene_XX_[Name].md          # Per-scene storyboard
├── assets/
│   ├── references/
│   │   ├── characters/                 # Production character references
│   │   ├── locations/                  # Production location references
│   │   └── research/                   # Production research references
│   └── shots/                          # Generated shot assets
│       └── Act_X/
│           └── Scene_XX_[Name]/
│               └── Shot_XX/
│                   ├── keyframe.png
│                   └── video.mp4
├── production_bible.json               # Creative vision, specs, characters, locations
├── reference_registry.json             # Character/location/prop visual ground truth
└── scene_status.json                   # Shot states, assets, cinematic metadata
```

---

## Agent

| Agent | File | Mode | Model |
|-------|------|------|-------|
| **Director** | `.opencode/agents/director.md` | **primary** | `mixio/gemini-3.1-pro-low` |

---

## Skills

| Skill | File | Purpose |
|-------|------|---------|
| `script-analysis` | `.opencode/skills/script-analysis/SKILL.md` | AI-limitation-aware script breakdown and segmentation |
| `storyboard-generation` | `.opencode/skills/storyboard-generation/SKILL.md` | Visual/motion prompts for KalaaSetu |
| `image-generation` | `.opencode/skills/image-generation/SKILL.md` | Keyframe generation with iterative QC (max 3 rounds) |
| `video-generation` | `.opencode/skills/video-generation/SKILL.md` | Veo 3.1 cinematic video with frame-anchoring, audio direction, and shot planning |
| `production-manager` | `.opencode/skills/production-manager/SKILL.md` | State tracking (Bible, scene status) |
| `reference-grounded-narrative-sequence-skill` | `.opencode/skills/reference-grounded-narrative-sequence-skill/SKILL.md` | Continuity-safe multi-panel narrative sequences and clean keyframe extraction from references |

---

## Schemas

| Schema | File | Validates |
|--------|------|-----------|
| Production Bible | `schemas/bible.schema.json` | `project/production_bible.json` |
| Scene Status | `schemas/scene.schema.json` | `project/scene_status.json` |
| Shot Spec | `schemas/shot.schema.json` | Per-shot cinematic specs |
| Reference Registry | `schemas/reference_registry.schema.json` | `project/reference_registry.json` |

---

## MCP Servers

| MCP | Purpose |
|-----|---------|
| **KalaaSetu** (`@mixio-pro/kalaasetu-mcp@beta`) | Image/video generation, analysis, editing — all media generation goes through this |

---

## Workflow

### 1. Project Setup
- **Command**: `/project-setup`
- **Action**: Interactive interview → `project/production_bible.json`
- **Run once** at the start of the project.

### 2. Script Analysis
- **Skills**: `script-analysis`
- **Output**: Structured shot list, scene files, metadata extraction

### 3. Reference Readiness
- **Gate**: All characters must have approved references before keyframe generation.

### 4. Keyframe Generation (Phase 1)
- **Skills**: `storyboard-generation`, `image-generation`, `reference-grounded-narrative-sequence-skill`
- **Gate**: User approval of all keyframes before Phase 2
- **Use case**: `image-generation` handles new keyframes and direct image edits, including multi-reference edits that should preserve source look. `reference-grounded-narrative-sequence-skill` is the default only for continuity-safe multi-panel narrative boards or clean extracted frames from one or more references.

### 5. Video Generation (Phase 2)
- **Skills**: `video-generation`
- **Output**: Video files with frame-anchoring for consecutive shots

---

## Critical Rules
1. **Use KalaaSetu** — all media generation MUST go through the `kalaasetu` MCP.
2. **No skipping stages** — images must be approved before video generation.
3. **Frame-anchoring** — consecutive same-location shots must use last-frame → start-frame continuity.
4. **State tracking** — update `project/scene_status.json` after every generation/approval/rejection.
5. **Reference registry** — always use `project/reference_registry.json` as ground truth for character/location appearance.
6. **Max 8 seconds per shot** — Veo 3.1 limit. Split longer actions into multiple shots.
7. **Direct image edits stay source-led** — multiple input images alone do not make the task a narrative board. Keep plain edits in `image-generation` unless the user explicitly asks for multi-panel sequence output.