Work with OpenStory (github.com/openstory-so/openstory), the open-source AI script-to-video sequence platform built on Bun + TanStack Start + Cloudflare Workers (D1, R2, Workflows, Durable Objects) with Drizzle, Better Auth, and Fal.ai/OpenRouter models. Routes one request to one mode: run it locally (`bun install && bun dev` on Miniflare, `FAL_KEY` / `OPENROUTER_KEY`), trace the storyboard pipeline (scene split, casting, prompts, frame images, motion, music), author a Cloudflare Workflow under the three-place wiring and no-mid-run-read `scopedDb` contract, add or update an image/video/audio/LLM model, ship a safe D1 + Drizzle migration, or deploy. Use when the user mentions OpenStory or is operating this codebase. Triggers on: openstory, openstory.so, script to video, AI video sequence platform, storyboard workflow, triggerWorkflow, OpenStoryWorkflowEntrypoint, WorkflowScopedDb, IMAGE_MODELS, fal.ai model registry, D1 CASCADE data loss, flatten-migrations, deploy Cloudflare Workers video app.
Instrucciones de origen · Vista previa de solo lectura
name
openstory
description
Work with OpenStory (github.com/openstory-so/openstory), the open-source AI script-to-video sequence platform built on Bun + TanStack Start + Cloudflare Workers (D1, R2, Workflows, Durable Objects) with Drizzle, Better Auth, and Fal.ai/OpenRouter models. Routes one request to one mode: run it locally (`bun install && bun dev` on Miniflare, `FAL_KEY` / `OPENROUTER_KEY`), trace the storyboard pipeline (scene split, casting, prompts, frame images, motion, music), author a Cloudflare Workflow under the three-place wiring and no-mid-run-read `scopedDb` contract, add or update an image/video/audio/LLM model, ship a safe D1 + Drizzle migration, or deploy. Use when the user mentions OpenStory or is operating this codebase. Triggers on: openstory, openstory.so, script to video, AI video sequence platform, storyboard workflow, triggerWorkflow, OpenStoryWorkflowEntrypoint, WorkflowScopedDb, IMAGE_MODELS, fal.ai model registry, D1 CASCADE data loss, flatten-migrations, deploy Cloudflare Workers video app.
allowed-tools
Bash Read Write Edit Glob Grep
compatibility
Requires Bun >= 1.3.0 < 2 and Node >= 24 < 25. Local dev needs no Docker, no external database, and no Cloudflare account — the full stack (D1, R2, Workflows, Durable Objects, email) runs in Workerd via Miniflare. AI generation needs `FAL_KEY` and/or `OPENROUTER_KEY` and spends real money. Video export is production-only (container binding). MIT licensed.
OpenStory turns a written script into a styled video sequence: it splits the
script into scenes, casts characters and locations from reusable team
libraries, builds visual/motion/music prompts, renders frames through Fal.ai,
animates them into motion clips, scores them, and merges the result. The whole
app is a single Cloudflare Worker (src/server.ts) — D1 for data, R2 for
media, 33 named Cloudflare Workflows for durable generation, and a Durable
Object for SSE progress. Local dev runs that same Workerd runtime through
Miniflare, so there is no "works locally, breaks in prod" gap.
When to use this skill
Cloning, bootstrapping, or running OpenStory locally (bun dev), or wiring
the FAL_KEY / OPENROUTER_KEY needed for generation
Tracing or debugging the storyboard pipeline: why a sequence is stuck, which
phase failed, what a workflow step actually produced
Adding or changing a Cloudflare Workflow, or hitting the
WorkflowScopedDb / mid-run-read / replay-idempotency rules
Adding, hiding, or repricing an image / image-to-video / audio / LLM model
Changing the Drizzle schema or shipping a D1 migration safely
Contributing a PR (branch naming, Lefthook gates, pre-push checks)
Diagnosing one of the documented traps (bun test vs bun run test, remote
D1 binding leak, nested migration files, silent cron drift, empty pricing)
When not to use this skill
Generic "make me an AI video" requests with no OpenStory repo involved →
use video-production, vox-director, or video-shotcraft
Local desktop/timeline video editing → opencut, palmier-pro
Generic Cloudflare Workers/D1/Wrangler questions unrelated to this codebase →
use the Cloudflare docs directly; this skill only encodes OpenStory's own
contracts
Generic TanStack Start / Drizzle / Better Auth tutorials → those belong to
their own docs; here they only appear as OpenStory conventions
Instructions
Step 1: Pick exactly one mode before touching anything
Mode
Use when
Go to
run-local
first run, env keys, "nothing generates"
Step 2
pipeline-trace
a sequence is stuck/wrong, you need phase-level truth
Step 3
workflow-authoring
adding or editing src/lib/workflows/*-workflow.ts
Step 4
model-catalog
add/hide/reprice an image, video, audio, or LLM model
Do not blend modes. If two apply, do the read-only one first.
Step 2: run-local — get a working local stack
git clone https://github.com/openstory-so/openstory.git
cd openstory && bun install && bun dev # http://localhost:3000
bun dev is self-bootstrapping: scripts/ensure-env.ts writes .env.local
with generated BETTER_AUTH_SECRET / API_KEY_ENCRYPTION_KEY, then
db:migrate:local → db:seed:local → vite dev. No Docker, no external DB,
no Cloudflare account.
Generation stays dark until you add keys — bun setup (interactive) or paste
into .env.local:
Read the startup banner.bun dev prints its wrangler bindings. If DB
shows REMOTE, kill the server immediately — that is the prod-D1 leak
described in references/troubleshooting.md.
Full script/env tables: references/commands.md.
Read-only host check: bash .agent-skills/openstory/scripts/openstory.sh doctor [repo_path].
Step 3: pipeline-trace — name the phase before guessing
Phases, in order: Verify+Prepare → Poster (non-critical) → Scene Splitting →
Casting (talent ∥ location) → References & Prompts (character sheets ∥
location sheets ∥ visual prompts) → Frame Images then Motion/Music prompts
(sequential since #929) → Motion + Music → Complete.
Identify the failing phase from workflowRunId / sequence_events before
changing code. Phase details and per-phase inputs/outputs are in
references/architecture.md.
Step 4: workflow-authoring — obey the three-place wiring and scopedDb
A new workflow is not "added" until it exists in all three places, which
src/lib/workflow/wiring-consistency.test.ts enforces:
wrangler.jsonc → workflows[] (and the [env.production] / [env.test]
blocks — workflow config is not inherited)
a re-export of the class from src/server.ts
an entry in TRIGGER_TO_BINDING (src/lib/workflow/trigger-bindings.ts)
Then: extend OpenStoryWorkflowEntrypoint, implement
runImpl(event, step, scopedDb), and wrap every unit of work in
step.do('step-name', ...). Trigger only through triggerWorkflow() — never
a raw fetch().
Three hard rules that cost the most time when broken:
No mid-run D1 reads.scopedDb is write-only by type. The only hatches
are scopedDb.credentials.*, scopedDb.claims.*, scopedDb.liveRead.*.
The body replays from the top on every step callback. Steps must be
idempotent; do not pass large blobs across step boundaries.
retries/retryDelay on triggerWorkflow() are no-ops. Retries belong
on step.do() or the class.
Step 5: model-catalog — check llms.txt first, never hand-write schemas
Motion per-model params → src/lib/motion/generated/endpoint-map.ts
(generated — run bun motion:codegen, do not edit by hand)
Before changing any fal endpoint, read
https://fal.ai/models/{model-path}/llms.txt — the machine-readable param
spec is authoritative and more current than the HTML docs. Then
bun models:check to diff the catalog. Retiring a model means marking it
hidden (not selectable), not deleting it — existing rows still reference it.
Current registry snapshot and defaults: references/architecture.md.
Step 6: schema-migration — assume the CASCADE trap is live
bun db:generate # drizzle-kit, from schema changes only
bun db:migrate:local# apply locally
Never hand-write migration SQL. Never hand-write Better Auth tables — run
bun auth:generate, port the output verbatim into
src/lib/db/schema/auth.ts, then bun db:generate.
The dangerous part: D1 runs multi-statement migrations inside an implicit
transaction where PRAGMA foreign_keys = OFF is silently ignored, so the
SQLite table-rebuild pattern fires every inbound ON DELETE CASCADE. This
already destroyed prod auth tables once (#612). Prefer
ALTER TABLE … RENAME/ADD/DROP COLUMN over rebuilds, and avoid
ON DELETE CASCADE on FKs to user, teams, sequences. The Lefthook
guard is scripts/check-migrations.ts.
Also: drizzle-kit only diffs exported tables — dropping a named export
from src/lib/db/schema/index.ts makes the next db:generate emit
DROP TABLE (#898).
Step 7: deploy — pick the path, then respect CLOUDFLARE_ENV
Zero-config: the Deploy-to-Cloudflare button clones the repo (a clone,
not a fork), provisions everything in the default wrangler.jsonc block,
and prompts only for BETTER_AUTH_SECRET + API_KEY_ENCRYPTION_KEY. AI
keys go in afterwards via Settings → API Keys or wrangler secret put.
Upstream repo: Workers Builds auto-deploys main
(bun run build with CLOUDFLARE_ENV=production, then
bun run deploy:production).
Manual: bun cf:typegen && bun cf:deploy:prd.
PRs: GitHub Actions creates a per-PR Worker, D1, namespaced workflows,
and container app; closing the PR tears them down.
A build without CLOUDFLARE_ENV=production bakes the default block (with the
deliberately-invalid placeholder D1 id) and fails loudly. That placeholder is
a safety feature — do not "fix" it.
Step 8: contribute — the branch name is a hard gate
Branches must be <issue-number>-feature-name (e.g. 393-improve-readme);
Lefthook extracts the issue number and tags commits #<issue>, and the PR
body must contain Closes #<issue>.
Before pushing:
bun lint && bun format:check && bun typecheck && bun run test
bun run test (not bun test), bun run build (not bun build), tsgo
(not tsc). These three are the most repeated mistakes in the repo's own
docs.
Best practices
Trust the runtime parity, not your memory — local dev is real Workerd
via Miniflare, so reproduce in bun dev before theorizing about a
Cloudflare-only bug.
Name the pipeline phase before editing code — the storyboard workflow
has 7 phases with different owners; a "generation failed" report without a
phase is not yet actionable.
Treat scopedDb as a type-level contract, not a suggestion — if you
need a read mid-run, you almost certainly need a snapshot from an earlier
step.do() instead.
Three-place workflow wiring or it does not exist — wrangler.jsonc,
src/server.ts, TRIGGER_TO_BINDING. Run the wiring test.
Never add "remote": true to a D1 binding and never commit a real
prod database_id into the default block.
Assume every migration might rebuild a table — check for CASCADE
fan-out before applying anything to prod, and export first.
Generation costs real money — FAL_KEY spends per call. Use the
cheapest preview model when iterating, and never loop retries on a failing
generation.
Cron changes must land in three places too — default block,
[env.production], and the constant the scheduled() handler string-
matches. A mismatch fails silently by succeeding.
Example 1: First run, then verify the host is actually ready
git clone https://github.com/openstory-so/openstory.git
cd openstory && bun install && bun dev
# in another shell:
bash .agent-skills/openstory/scripts/openstory.sh doctor ./openstory
doctor reports Bun/Node versions against the engine range, whether
.env.local exists, and which AI keys are set — without writing anything.
Prints which of FAL_KEY, OPENROUTER_KEY, XAI_API_KEY,
BETTER_AUTH_SECRET, API_KEY_ENCRYPTION_KEY are present in .env.local
(names only — never values).
