opencode-skills-collection 4.0.73 → 4.0.75

package/bundled-skills/electron-drive-skill/scripts/drive.mjs

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+/**
+ * Start an Electron app under Playwright and operate it from the command line,
+ * one command per call. Written for coding agents, usable by anyone.
+ *
+ * Run it from anywhere inside the project; see SKILL.md and README.md.
+ */
+import { spawn, spawnSync } from 'node:child_process'
+import { existsSync, mkdirSync, openSync, readFileSync, rmSync, statSync } from 'node:fs'
+import http from 'node:http'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import {
+  daemonLogPath,
+  driveRoot,
+  isAlive,
+  loadConfig,
+  parseArgs,
+  profileDir,
+  PROJECT_ROOT,
+  readState,
+  startOptions,
+  statePath
+} from './lib.mjs'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+
+const USAGE = `drive <command>
+
+  start [--dev] [--build] [--profile <name>] [--fresh]
+        Launch the app on a scratch profile. Default: the last build
+        ('build' in drive.config.json runs first with --build). --dev: the
+        dev launch, against a renderer dev server you started yourself.
+        --fresh wipes the profile first (first-run state).
+  status                           whether the app is up, its profile and window
+  snapshot                         accessibility tree of the window
+  screenshot [--out <png>] [--selector <css>]
+  click <target>                   Playwright selector: 'text=Settings', 'role=button[name="Save"]', css
+  fill <target> <text>
+  select <target> <value|label>    a <select>, by option value or visible label
+  press <key>                      e.g. Enter, Escape, Control+K
+  wait <target> [--timeout <ms>]
+  eval <js | ->                    in the renderer; an expression, or a body with 'return'
+  main <js | ->                    in the main process; 'electron' and 'process' are in scope
+                                   '-' reads the code from stdin
+  logs [--lines <n>]               recent console output, plus 'logFile' from the config
+  stop                             quit the app and the daemon
+`
+
+const fail = (message) => {
+  console.error(message)
+  process.exit(1)
+}
+
+const send = (command, args = {}) => {
+  const state = readState()
+  if (!state || !isAlive(state.pid)) {
+    if (state) rmSync(statePath(), { force: true })
+    return fail("Nothing is running. Start it with 'drive start'.")
+  }
+
+  const body = JSON.stringify({ token: state.token, command, args })
+  return new Promise((resolve, reject) => {
+    const request = http.request(
+      { host: '127.0.0.1', port: state.port, method: 'POST', headers: { 'content-type': 'application/json' } },
+      (response) => {
+        let data = ''
+        response.on('data', (chunk) => {
+          data += chunk
+        })
+        response.on('end', () => {
+          try {
+            const parsed = JSON.parse(data)
+            if (parsed.ok) resolve(parsed.result)
+            else reject(new Error(parsed.error))
+          } catch (e) {
+            reject(e)
+          }
+        })
+      }
+    )
+    request.on('error', reject)
+    request.end(body)
+  })
+}
+
+const print = (result) => {
+  if (typeof result === 'string') console.log(result)
+  else console.log(JSON.stringify(result, null, 2))
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+const urlUp = (url) =>
+  new Promise((resolve) => {
+    const request = http.get(url, { timeout: 1000 }, (response) => {
+      response.resume()
+      resolve(true)
+    })
+    request.on('error', () => resolve(false))
+    request.on('timeout', () => {
+      request.destroy()
+      resolve(false)
+    })
+  })
+
+/** The file Electron will run for `args[0]`: the file itself, or a package's `main`. */
+const entryFile = (target) => {
+  const resolved = path.resolve(PROJECT_ROOT, target)
+  if (!existsSync(resolved) || !statSync(resolved).isDirectory()) return resolved
+  const pkg = JSON.parse(readFileSync(path.join(resolved, 'package.json'), 'utf8'))
+  return path.join(resolved, pkg.main ?? 'index.js')
+}
+
+const start = async (flags) => {
+  const options = startOptions(flags)
+  const config = loadConfig()
+  const existing = readState()
+  if (existing && isAlive(existing.pid)) {
+    fail(`Already driving the app (profile '${existing.profile}', ${existing.mode}). Run 'drive stop' first.`)
+  }
+  if (existing) rmSync(statePath(), { force: true })
+
+  if (options.mode === 'dev') {
+    if (options.build) fail("--build applies to the built app only. With --dev, the dev server rebuilds the renderer.")
+    if (config.dev.url && !(await urlUp(config.dev.url))) {
+      fail(`The renderer dev server is not up at ${config.dev.url}. Start it first, without letting it launch its own Electron.`)
+    }
+  } else {
+    if (options.build) {
+      if (!config.build) fail("--build needs a 'build' command in drive.config.json.")
+      console.log(`Building (${config.build})...`)
+      const built = spawnSync(config.build, { cwd: PROJECT_ROOT, stdio: 'inherit', shell: true })
+      if (built.status !== 0) fail(`'${config.build}' failed.`)
+    }
+    const entry = entryFile(config.args[0] ?? '.')
+    if (!existsSync(entry)) fail(`No built app: ${entry} does not exist. Run 'drive start --build'.`)
+    const ageMinutes = Math.round((Date.now() - statSync(entry).mtimeMs) / 60000)
+    console.log(`Using the build from ${ageMinutes} minute(s) ago. Pass --build to rebuild.`)
+  }
+
+  const dataDir = profileDir(options.profile)
+  if (options.fresh) rmSync(dataDir, { recursive: true, force: true })
+  mkdirSync(dataDir, { recursive: true })
+  mkdirSync(driveRoot(), { recursive: true })
+
+  const logFd = openSync(daemonLogPath(), 'w')
+  const daemon = spawn(
+    process.execPath,
+    [path.join(here, 'daemon.mjs'), options.mode, options.profile, dataDir],
+    {
+      cwd: PROJECT_ROOT,
+      detached: true,
+      stdio: ['ignore', logFd, logFd],
+      env: { ...process.env, DRIVE_PROJECT_ROOT: PROJECT_ROOT }
+    }
+  )
+  daemon.unref()
+
+  console.log(`Starting (${options.mode}, profile '${options.profile}')...`)
+  const deadline = Date.now() + 120_000
+  while (Date.now() < deadline) {
+    if (readState()) break
+    if (!isAlive(daemon.pid)) {
+      console.error(readFileSync(daemonLogPath(), 'utf8'))
+      fail('The driver failed to start the app (log above).')
+    }
+    await sleep(500)
+  }
+  if (!readState()) fail(`Timed out waiting for the app. See ${daemonLogPath()}.`)
+  print(await send('status'))
+}
+
+/** The code argument, or stdin when it is '-'. */
+const codeFrom = (positional) =>
+  positional.length === 1 && positional[0] === '-' ? readFileSync(0, 'utf8') : positional.join(' ')
+
+const run = async () => {
+  const { command, positional, flags } = parseArgs(process.argv.slice(2))
+  const need = (count, what) => {
+    if (positional.length < count) fail(`Usage: drive ${command} ${what}`)
+  }
+
+  switch (command) {
+    case 'start':
+      return start(flags)
+    case 'status': {
+      const state = readState()
+      if (!state || !isAlive(state.pid)) return print('Not running.')
+      return print(await send('status'))
+    }
+    case 'stop': {
+      const state = readState()
+      if (!state || !isAlive(state.pid)) {
+        rmSync(statePath(), { force: true })
+        if (state?.electronPid && isAlive(state.electronPid)) {
+          process.kill(state.electronPid, 'SIGKILL')
+          return print('The daemon was gone but the app was not; killed it.')
+        }
+        return print('Not running.')
+      }
+      return print(await send('stop'))
+    }
+    case 'snapshot':
+      return print(await send('snapshot'))
+    case 'screenshot':
+      return print(
+        await send('screenshot', {
+          out: typeof flags.out === 'string' ? path.resolve(flags.out) : undefined,
+          selector: typeof flags.selector === 'string' ? flags.selector : undefined
+        })
+      )
+    case 'click':
+      need(1, '<target>')
+      return print(await send('click', { target: positional[0] }))
+    case 'fill':
+      need(2, '<target> <text>')
+      return print(await send('fill', { target: positional[0], text: positional.slice(1).join(' ') }))
+    case 'select':
+      need(2, '<target> <value|label>')
+      return print(await send('select', { target: positional[0], value: positional.slice(1).join(' ') }))
+    case 'press':
+      need(1, '<key>')
+      return print(await send('press', { key: positional[0] }))
+    case 'wait':
+      need(1, '<target>')
+      return print(
+        await send('wait', {
+          target: positional[0],
+          timeout: typeof flags.timeout === 'string' ? Number(flags.timeout) : undefined
+        })
+      )
+    case 'eval':
+      need(1, '<js>')
+      return print(await send('eval', { code: codeFrom(positional) }))
+    case 'main':
+      need(1, '<js>')
+      return print(await send('main', { code: codeFrom(positional) }))
+    case 'logs':
+      return print(await send('logs', { lines: typeof flags.lines === 'string' ? Number(flags.lines) : undefined }))
+    case 'help':
+    case '--help':
+      return print(USAGE)
+    default:
+      return fail(`Unknown command '${command}'.\n\n${USAGE}`)
+  }
+}
+
+run().catch((e) => fail(e.message))

package/bundled-skills/electron-drive-skill/scripts/lib.mjs

@@ -0,0 +1,165 @@
+/**
+ * The pure half of the driver: project discovery, config, argument parsing,
+ * paths and the state file. No Playwright and no Electron here, so it can be
+ * tested without launching anything (`node --test scripts/`).
+ */
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+
+/** The nearest directory at or above `from` with a package.json. */
+export const findProjectRoot = (from = process.cwd()) => {
+  let dir = path.resolve(from)
+  for (;;) {
+    if (existsSync(path.join(dir, 'package.json'))) return dir
+    const parent = path.dirname(dir)
+    if (parent === dir) throw new Error(`No package.json at or above ${from}. Run the driver from inside your Electron project.`)
+    dir = parent
+  }
+}
+
+export const PROJECT_ROOT = process.env.DRIVE_PROJECT_ROOT
+  ? path.resolve(process.env.DRIVE_PROJECT_ROOT)
+  : findProjectRoot()
+
+/**
+ * `drive.config.json` at the project root, over the defaults. Every field is
+ * optional; with no file at all, `start` runs `electron .` on the last build.
+ */
+export const loadConfig = (root = PROJECT_ROOT) => {
+  const file = path.join(root, 'drive.config.json')
+  let config = {}
+  if (existsSync(file)) {
+    try {
+      config = JSON.parse(readFileSync(file, 'utf8'))
+    } catch (e) {
+      throw new Error(`${file} is not valid JSON: ${e.message}`)
+    }
+  }
+  return {
+    build: config.build ?? null,
+    args: config.args ?? ['.'],
+    env: config.env ?? {},
+    logFile: config.logFile ?? null,
+    dev: {
+      args: config.dev?.args ?? config.args ?? ['.'],
+      env: config.dev?.env ?? {},
+      url: config.dev?.url ?? null
+    }
+  }
+}
+
+/**
+ * Everything the driver owns lives under here, never in the real profile. One
+ * directory per project, so two apps never share a scratch profile.
+ */
+export const driveRoot = (root = PROJECT_ROOT) => {
+  if (process.env.DRIVE_ROOT) return process.env.DRIVE_ROOT
+  const hash = createHash('sha256').update(root).digest('hex').slice(0, 8)
+  return path.join(tmpdir(), 'electron-drive', `${path.basename(root)}-${hash}`)
+}
+
+export const statePath = () => path.join(driveRoot(), 'daemon.json')
+export const daemonLogPath = () => path.join(driveRoot(), 'daemon.log')
+export const screenshotDir = () => path.join(driveRoot(), 'screenshots')
+
+/**
+ * A profile name becomes a directory name, so it is restricted to something
+ * that cannot climb out of `profiles/`.
+ */
+export const profileDir = (profile) => {
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(profile)) {
+    throw new Error(`Invalid profile name '${profile}': letters, digits, '-' and '_' only.`)
+  }
+  return path.join(driveRoot(), 'profiles', profile)
+}
+
+export const readState = () => {
+  const file = statePath()
+  if (!existsSync(file)) return null
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+export const isAlive = (pid) => {
+  if (!pid) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (e) {
+    return e?.code === 'EPERM'
+  }
+}
+
+const BOOLEAN_FLAGS = new Set(['dev', 'build', 'fresh'])
+
+/**
+ * `drive <command> [positional...] [--flag [value]]`.
+ *
+ * Flags known to be boolean take no value, so `start --dev --fresh` is two
+ * flags rather than `dev = '--fresh'`. Everything after a bare `--` is
+ * positional, for JavaScript that itself starts with dashes.
+ */
+export const parseArgs = (argv) => {
+  const [command = 'help', ...rest] = argv
+  const positional = []
+  const flags = {}
+
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i]
+    if (arg === '--') {
+      positional.push(...rest.slice(i + 1))
+      break
+    }
+    if (arg.startsWith('--')) {
+      const name = arg.slice(2)
+      const next = rest[i + 1]
+      if (BOOLEAN_FLAGS.has(name) || next === undefined || next.startsWith('--')) {
+        flags[name] = true
+      } else {
+        flags[name] = next
+        i += 1
+      }
+    } else {
+      positional.push(arg)
+    }
+  }
+
+  return { command, positional, flags }
+}
+
+export const startOptions = (flags) => ({
+  mode: flags.dev ? 'dev' : 'built',
+  build: flags.build === true,
+  profile: typeof flags.profile === 'string' ? flags.profile : 'default',
+  fresh: flags.fresh === true
+})
+
+/**
+ * The child's environment: the caller's, minus the variables that break a
+ * launch, plus the config's, where `{profile}` becomes the scratch profile
+ * directory.
+ *
+ * `ELECTRON_RUN_AS_NODE=1` makes Electron start as plain Node, where `app` is
+ * undefined and nothing works, and some shells set it.
+ */
+export const childEnv = (base, dataDir, mode, extra) => {
+  const env = { ...base }
+  delete env.ELECTRON_RUN_AS_NODE
+  if (mode === 'dev') env.NODE_ENV = 'development'
+  else delete env.NODE_ENV
+  for (const [key, value] of Object.entries(extra)) {
+    env[key] = String(value).replaceAll('{profile}', dataDir)
+  }
+  return env
+}
+
+/**
+ * JavaScript from the command line, made into an async function body: a bare
+ * expression is returned, anything with its own `return` is used as written.
+ */
+export const asFunctionBody = (code) => (/\breturn\b/.test(code) ? code : `return (${code})`)

package/bundled-skills/electron-drive-skill/scripts/lib.test.mjs

@@ -0,0 +1,56 @@
+// node --test scripts/
+import assert from 'node:assert/strict'
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { test } from 'node:test'
+
+const project = mkdtempSync(path.join(tmpdir(), 'drive-test-'))
+writeFileSync(path.join(project, 'package.json'), '{}')
+process.env.DRIVE_PROJECT_ROOT = project
+delete process.env.DRIVE_ROOT
+const lib = await import('./lib.mjs')
+
+test('parses commands, valued and boolean flags, and --', () => {
+  assert.deepEqual(lib.parseArgs(['fill', 'role=textbox', 'hello', 'world']), {
+    command: 'fill',
+    positional: ['role=textbox', 'hello', 'world'],
+    flags: {}
+  })
+  assert.deepEqual(lib.parseArgs(['start', '--dev', '--profile', 'x', '--fresh']).flags, {
+    dev: true,
+    profile: 'x',
+    fresh: true
+  })
+  assert.deepEqual(lib.parseArgs(['eval', '--', '--x', '1']).positional, ['--x', '1'])
+  assert.equal(lib.parseArgs([]).command, 'help')
+})
+
+test('keeps profiles inside the driver root', () => {
+  assert.ok(lib.profileDir('default').startsWith(lib.driveRoot()))
+  for (const bad of ['../../Library', 'a/b', '']) assert.throws(() => lib.profileDir(bad), /Invalid profile/)
+})
+
+test('child env drops ELECTRON_RUN_AS_NODE and fills {profile}', () => {
+  const env = lib.childEnv({ ELECTRON_RUN_AS_NODE: '1', NODE_ENV: 'test', KEEP: 'me' }, '/scratch', 'built', {
+    APP_DATA: '{profile}/data'
+  })
+  assert.deepEqual(env, { KEEP: 'me', APP_DATA: '/scratch/data' })
+  assert.equal(lib.childEnv({}, '/s', 'dev', {}).NODE_ENV, 'development')
+})
+
+test('config defaults to electron . with no file', () => {
+  assert.deepEqual(lib.loadConfig(project).args, ['.'])
+  assert.deepEqual(lib.loadConfig(project).dev.args, ['.'])
+})
+
+test('a malformed config names the file', () => {
+  const broken = mkdtempSync(path.join(tmpdir(), 'drive-test-'))
+  writeFileSync(path.join(broken, 'drive.config.json'), '{ "args": [".",] }')
+  assert.throws(() => lib.loadConfig(broken), /drive\.config\.json is not valid JSON/)
+})
+
+test('wraps bare expressions, keeps bodies with return', () => {
+  assert.equal(lib.asFunctionBody('1 + 1'), 'return (1 + 1)')
+  assert.equal(lib.asFunctionBody('return 2'), 'return 2')
+})

package/bundled-skills/film-crew/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: film-crew
+description: "Turn a one-line AI video idea into a shot list and per-shot, model-ready prompts via a film crew (director, DP, gaffer, editor, script supervisor). Also fixes failing video prompts and diagnoses bad clips before a reroll. Works with Wan, LTX, Kling, Veo, Seedance, Hailuo, Runway."
+category: media
+risk: safe
+source: "https://github.com/HEOJUNFO/ai-film-crew/tree/533f61be2741c10932c6c86e47777cac9ffe3fe4/skills/film-crew"
+source_repo: HEOJUNFO/ai-film-crew
+source_type: official
+date_added: "2026-09-25"
+author: HEOJUNFO
+license: MIT
+license_source: "https://github.com/HEOJUNFO/ai-film-crew/blob/533f61be2741c10932c6c86e47777cac9ffe3fe4/LICENSE"
+tags: [video, text-to-video, shot-list, prompting, film]
+tools: [claude, codex, cursor, gemini]
+---
+
+# Film Crew
+
+You are the producer. You don't write one prompt and hope. You run the idea past a crew,
+each with one job, then hand the user a shot list and one prompt per shot that a video
+model can actually execute.
+
+Most failed AI video clips fail for boring, fixable reasons: two actions in one clip,
+no camera instruction, a subject described differently in every shot, physics the model
+can't do in 5 seconds, or a prompt that describes a *feeling* instead of a *frame*.
+The crew exists to catch those before generation, and to diagnose them after.
+
+## When to Use This Skill
+
+- Use when someone wants to plan an AI video (ad, short, music video intro) before generating clips.
+- Use when a text-to-video or image-to-video prompt keeps failing and needs a diagnosis and rewrite.
+- Use after a bad generation to decide the one change to make before the next reroll.
+- Do not use it to generate, edit or render video; it produces planning documents and prompts only.
+
+## Modes
+
+Pick the mode from the request. Default is **Plan**.
+
+| Mode | When | Output |
+|---|---|---|
+| **Plan** | "make a video of…", an idea, a script, a product | `SHOT_LIST.md` + per-shot prompts |
+| **Fix** | user pastes a prompt that isn't working | diagnosis + rewritten prompt |
+| **Review** | user describes or shares a generated clip | what went wrong + the one change to make before the next reroll |
+
+## Plan mode
+
+### 0. Intake (keep it short)
+
+Only ask what you can't reasonably default. Ask at most 3 questions, in one message.
+If the user said "just go", use the defaults.
+
+| Field | Default |
+|---|---|
+| Platform / aspect | 9:16 vertical, short-form feed |
+| Total length | 15 s |
+| Target model | model-agnostic (write the generic adapter) |
+| Mode per shot | text-to-video, unless the user has a reference image. **Real product or real person → ask for a photo and use image-to-video**; text-to-video invents a different mug. |
+| Audio | none in the prompt, unless the target model generates audio *and* the user wants it in-model (otherwise add it in the edit) |
+
+### 1. Run the crew, in order
+
+Read each role file before running that role. Each role writes its own short section.
+Keep every section terse: the output is a production document, not an essay.
+
+1. **Director** → `references/roles/director.md` — logline, intent, beat sheet with timings, the hook.
+2. **Production designer** → `references/roles/production-designer.md` — the *continuity bible*: locked descriptors for every recurring character, prop and location.
+3. **Director of photography** → `references/roles/dp.md` — per shot: size, lens, angle, height, ONE camera move.
+4. **Gaffer** → `references/roles/gaffer.md` — time of day, key direction, color temperature, practicals, contrast.
+5. **Editor** → `references/roles/editor.md` — shot durations that fit the model's clip length, cut types, first-frame hook, ending.
+6. **Sound** → `references/roles/sound.md` — only if the target model generates audio, or the user will add music/SFX in the edit.
+7. **Script supervisor** → `references/roles/script-supervisor.md` — continuity + feasibility + "unslop" pass. Has veto power: any shot it flags gets rewritten before output.
+
+### 2. Write the prompts
+
+Read `references/model-prompting.md`. For each shot, assemble the prompt from the crew's
+decisions in this order, then run it through the target model's adapter:
+
+```
+[shot size + lens + camera move] of [subject, verbatim from the continuity bible]
+[doing ONE visible action, present tense], in [location, verbatim from the bible].
+[lighting from the gaffer]. [style / film look]. [audio line, only if supported]
+```
+
+This order is the generic default. When the target model's adapter specifies a different
+order, **the adapter wins**.
+
+Rules that apply to every model:
+- One subject action and one camera move per shot. Two actions = two shots.
+- Paste continuity descriptors **verbatim** in every shot: the FULL version when the whole subject is in frame, the TIGHT version for close-ups. Never paraphrase either.
+- Describe what the camera sees, not what the viewer should feel. "Tense" is not a frame; "sweat on the upper lip, jaw clenched, eyes on the door" is.
+- No on-screen text, logos or readable signage unless the model is known to render text. Add text in the edit.
+- Keep each shot within the model's max clip length (see adapter). Plan for 1–2 s of handles.
+- Image-to-video: describe only motion and camera. Don't re-describe what's already in the image.
+
+### 3. Output
+
+Write `SHOT_LIST.md` using `references/templates/shot-list.md`. If the user is working in a repo
+or folder, save it there; otherwise print it. Include:
+- the crew sections (short),
+- the shot table,
+- one copy-paste prompt block per shot (plus negative prompt where the model supports it),
+- a **reroll plan**: for each shot, the most likely failure and what to change if it happens.
+
+End with one line telling the user which shot is highest-risk and why.
+
+## Fix mode
+
+1. Read `references/roles/script-supervisor.md` and `references/unslop.md`.
+2. Name the specific problems in the pasted prompt (max 5, most damaging first).
+3. Rewrite it using the Plan-mode prompt order. If it contains two actions, split it into two shots and say so.
+4. Show before → after. Keep the user's intent; change the mechanics.
+
+## Review mode
+
+Read `references/reroll-review.md`. Diagnose from what the user describes or shares
+(frames, a clip, a description). Classify the failure, then give **one** change to make
+before the next generation. Changing five things at once means you learn nothing from the reroll.
+
+## Limitations
+
+- It plans, diagnoses, and rewrites prompts; it does not generate, edit, or render video.
+- Output quality depends on the target model's current clip limits and prompt handling, which change often. Check the model's own docs before trusting an adapter's defaults.
+- Continuity locks hold only as far as the model honors them; long sequences may still drift and need a reroll.
+- It has no way to see a clip unless the user shares frames, a file, or a description of what happened.
+
+## Tone
+
+Talk like a working crew: specific, fast, no hype. Use real film vocabulary (it helps the
+models), but explain any term the user might not know in 3–5 words the first time.

package/bundled-skills/film-crew/references/model-prompting.md

@@ -0,0 +1,89 @@
+# Model prompting adapters
+
+The crew's decisions are model-agnostic. This file turns them into the phrasing each model
+family tends to follow best.
+
+> Video models change every few months. Treat these as conservative defaults, check the
+> model's current docs for hard limits (clip length, resolution, prompt length), and send a
+> PR when something here goes stale.
+
+## Generic adapter (use when the model is unknown)
+
+One paragraph, present tense, concrete, in this order:
+
+1. Shot size, lens, camera move
+2. Subject (verbatim from the continuity bible)
+3. The one action
+4. Location (verbatim)
+5. Lighting
+6. Look / film stock
+7. Audio (only if the model generates audio)
+
+~40–90 words. Longer is fine for open-weights models; shorter for models with prompt
+rewriting ("prompt enhancement") turned on.
+
+## Open-weights models (Wan, HunyuanVideo, LTX-Video, Mochi, CogVideoX…)
+
+- **Be literal and long.** These models generally reward detailed, chronological,
+  paragraph-style descriptions (roughly 60–150 words): what's in frame, what moves, in
+  what order.
+- **Describe motion in sequence:** "…lifts the cup, pauses, then sets it down."
+- **Use the negative prompt** if your workflow exposes one:
+  `blurry, warped hands, extra fingers, morphing, flicker, text, watermark, logo, static frame, oversaturated`
+- **Seed discipline:** when rerolling to test a single change, keep the seed fixed so you
+  isolate the effect of the change.
+- Clip length is bounded by frame count and VRAM. Plan short shots and cut them together.
+
+## Kling
+
+- Structure: subject → movement → scene → camera → lighting → atmosphere.
+- Keep it tighter than open-weights prompts; one clear action.
+- Clip length is chosen from presets (commonly 5 s or 10 s). Plan with the editor's
+  fixed-length rule.
+- Negative prompt: use it where your version/interface exposes the field.
+- Some newer versions can generate audio. If yours does and the user wants in-model
+  sound, apply the audio rules from the Veo section; otherwise keep sound out of the prompt.
+- Image-to-video: describe only the motion and the camera; the image already carries the
+  look.
+
+## Veo (and other models that generate audio)
+
+- Write sound explicitly, as its own sentence(s):
+  - Dialogue: `The barista says, "Sorry — my fault."`
+  - SFX: `SFX: paper cup hits tile, liquid splash.`
+  - Ambience: `Ambient café murmur, espresso machine hiss.`
+- Keep dialogue short (one line per shot). Long lines drift out of sync.
+- Camera and lens terminology is followed well; use it.
+
+## Seedance and other multi-shot-capable models
+
+- If your version supports multiple shots in one generation, you can write the sequence
+  explicitly: `Shot 1: … Cut to Shot 2: …`. Keep each shot to one action and restate the
+  character descriptors in each.
+- If you need tight control, still generate shot by shot and cut in the edit.
+
+## Hailuo / MiniMax
+
+- Camera moves can be stated plainly in the prompt ("slow push-in", "pan left"). Some
+  versions and front-ends accept bracketed camera commands such as `[Push in]` or
+  `[Pan left]`; use them if your interface documents them.
+- Keep one move per shot even when the syntax allows chaining several.
+
+## Runway / Luma / Pika / Sora-style prompt-enhanced models
+
+- These often rewrite your prompt. Put the non-negotiables first (subject descriptors,
+  the action, the camera move) and keep the prompt short enough that the rewrite doesn't
+  bury them.
+- For image-to-video: motion + camera only.
+
+## Image-to-video (every model)
+
+The most reliable way to keep a character consistent across shots:
+1. Generate or pick **one** reference still per character/location.
+2. Use it as the first frame for every shot where they appear.
+3. In the prompt, describe **only** what moves and how the camera moves.
+
+## Clip length cheat sheet
+
+Check your model's current limit. Common ranges in practice: 4–10 s per generation.
+The editor role should never plan a shot longer than the limit minus ~1 s of handles.