vibeframe: Instructions file for Codex

AGENTS.md

VibeFrame is a frontier-video-generation layer for coding agents: CLI-first, MCP-ready. It generates video assets on the user's own provider keys (Seedance, Runway, Kling, Gemini Omni) behind dry runs and a hard --max-cost ceiling, delegates scene composition to upstream Hyperframes, and builds the generation, cost, and review layer around it.

Repository Shape

Monorepo: Turborepo + pnpm workspaces. ESM. TypeScript strict mode.

Packages:

• packages/cli - CLI and command implementations.
• packages/core - Timeline/project primitives and FFmpeg-oriented editing model.
• packages/ai-providers - Provider registry and provider implementations.
• packages/mcp-server - MCP wrapper around the CLI, bundled with esbuild.
• apps/web - Next.js public site.

Architecture:

CLI (Commander.js) -> Engine (Project state) -> Core (Zustand + FFmpeg) -> AI Providers

Commands

pnpm install && pnpm build    # Setup
pnpm test                     # Run all tests
pnpm lint                     # Lint (0 errors policy)
pnpm -F @vibeframe/cli test   # Single package

Use vibe schema --list and vibe schema <command> as the source of truth for CLI command availability and parameters.

CLI Shape

Canonical user-facing workflows:

• Project video flow: init, plan, build, preview, render (edit beats with storyboard, poll async work with status)
• One-shot media: generate, edit, inspect, audio, remix
• Automation: run, schema, context, guide
• Setup & hosts: setup, doctor, host
• Lower-level operations: scene, design, timeline, detect, batch, media, assemble

Do not introduce docs, examples, or agent instructions that use removed namespaces such as vibe ai, vibe project, vibe export, or vibe pipeline.

Agent Workflow Rules

When invoking VibeFrame commands from an agent context:

• Treat your host's agent loop (Claude Code, Codex, Cursor, or another coding-agent host) as the outer loop for long-running video work. VibeFrame should provide video-specific commands, JSON reports, cost gates, deterministic repair, render inspection, and nextActions/fixOwner recovery contracts, not a competing primary agent loop.
• Prefer --json for structured output.
• Run --dry-run before paid or mutating operations when the command supports it.
• When a review report includes nextActions, prefer it over inventing commands: run only safeToAutoRun:true actions automatically, ask before requiresConfirmation:true, and treat retryWith as the compatibility fallback.
• Use vibe schema <command> before constructing non-trivial arguments.
• Confirm with the user before high/very-high cost operations such as generate video, edit fill-gaps, and provider-backed remix workflows.
• Use --stdin for complex option payloads instead of fragile shell quoting.