npm package: @milenyumai/film-kit-multi
Description: Multi-agent parallel shot generation for OpenAI Codex App, Claude Code Agent Teams, and Antigravity Mission Control with specialist validators for Hollywood-standard cinematic prompt engineering.
Latest version: 1.4.3

# @milenyumai/film-kit-multi

Professional multi-agent cinematic prompt kit for OpenAI Codex App, Claude Code Agent Teams, and Antigravity Mission Control.

## What It Does

- Generates a lead-directed multi-agent production surface.
- Uses Lead Director, Shot Generator teammates, and 9 specialist validators.
- Supports `veo31` and `kling-3.0`.
- Enforces spatial contracts for gaze, depth, scale, and compositing realism.
- Determines target shot count with a director-grade pacing method before batch sizing.
- Keeps project-level `voiceCast` identity and shot-level `Audio Plan` for voice-design workflows.
- Keeps project-level `visual_world` for semantic consistency across camera, named camera movement strategy, light/shadow, scale, reflections, physics, and chain rules.

## Install

```bash
npm i -D @milenyumai/film-kit-multi
```

## Init

```bash
npx @milenyumai/film-kit-multi init
npx @milenyumai/film-kit-multi init --model veo31
npx @milenyumai/film-kit-multi init --model kling-3.0 --kling-preset ultra-realism
npx @milenyumai/film-kit-multi init --overwrite
```

## Generated Runtime

- `CLAUDE.md` + `.claude/CLAUDE.md`
- native Claude subagents under `.claude/agents/`
- OpenAI Codex App config under `.codex/config.toml`
- OpenAI Codex custom agents under `.codex/agents/*.toml`
- Codex skill mirror under `.agents/skills/*/SKILL.md`
- multi rules under `.claude/rules/`
- Antigravity skills:
  - `.agent/skills/shotforge-generate/SKILL.md`
  - `.agent/skills/shotforge-generate-multi/SKILL.md`

## Specialist Agents (9)

Specialists run in three phases after all shot batches complete:

### Phase A — File integrity (must pass before Phase B)

| Agent | Report | What It Checks |
|-------|--------|----------------|
| `continuity-editor` | `CONTINUITY-REPORT.md` | First-frame entry match, cross-batch chain, file completeness, shot count |

### Phase B — Content quality (run in parallel)

| Agent | Report | What It Checks |
|-------|--------|----------------|
| `safety-auditor` | `SAFETY-REPORT.md` | Visual anonymization, dialogue name policy, sensitive content reframing, avoid lines, music policy, Kling grammar |
| `stability-auditor` | `STABILITY-REPORT.md` | Camera position, character placement, framing, depth complexity, lighting safety |
| `dialogue-auditor` | `DIALOGUE-REPORT.md` | Voice tone consistency, `voiceCast` binding, SFX scene match, audio direction completeness |
| `character-consistency-auditor` | `CHARACTER-REPORT.md` | Description drift, clothing continuity, anonymous identity stability |
| `color-continuity-auditor` | `COLOR-REPORT.md` | Light direction consistency, color temperature, atmosphere coherence |
| `semantic-auditor` | `SEMANTIC-REPORT.md` | `visual_world`, perspective/geometry, shadow vector, scale map, reflections, physics/anatomy, foreground/background coherence, contextual contradictions, chained ILK reuse |
| `pacing-auditor` | `PACING-REPORT.md` | Duration variety, dramatic arc alignment, transition variety |

### Phase C — Delivery gate (must run last)

| Agent | Report | What It Checks |
|-------|--------|----------------|
| `delivery-editor` | `DELIVERY-REPORT.md` | File completeness, packaging, shot plan match, all specialist reports pass |

## Workflow

- `/generate` -> lead planning + teammate spawning + 3-phase specialist validation
- `/chain` -> chained continuation
- `/safety-check` -> specialist validation
- `/recover` -> deterministic recovery with impacted range definition
- `/finish` -> final delivery summary

## Contracts

- one file per shot
- `team-plan.json` is authoritative
- `team-plan.json` carries the authoritative top-level `voiceCast`
- `team-plan.json` carries the authoritative top-level `visual_world`
- target shot count is selected from `min_functional_shots` and `max_tasteful_shots`, not guessed
- hard gate: `ILK >= 80`, `SON >= 80`, `VIDEO >= 120`, `coverage >= 70`
- chain hard gate: chained `ILK FRAME` code block contains only `Use SHOT[prev]_END as exact first frame`
- semantic consistency gate for all shots:
  - perspective/geometry
  - single shadow vector
  - scale map
  - reflection handling
  - gravity/contact physics
  - anatomy risk
  - foreground/background coherence
  - contextual contradiction check
- spatial realism gate for interacting subjects:
  - eyeline target
  - plane map
  - shared light source
  - contact and depth cues

## Director-Grade Shot Sizing

- splits the scenario into dramatic units, not sentences
- computes `min_functional_shots` and `max_tasteful_shots`
- selects `selected_target_shots` from the workable middle, unless a reveal, reset, or action phase justifies more
- considers dialogue pressure, action density, spatial complexity, and emotional landing time
- prevents both fake pace inflation and over-compressed one-breath coverage

## Best For

- 10+ shot productions
- parallel shot generation
- continuity-heavy projects
- Antigravity Mission Control workflows

## License

MIT