agentleFS
vericontextvericontext/vibeframe/AGENTS.md

vibeframe

AGENTS.md185 starsChanged todayMITView on GitHub

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. Monorepo: Turborepo + pnpm workspaces. ESM. TypeScript strict mode. Architecture: Use vibe schema --list and vibe schema <command> as the source of truth for CLI command availability and parameters. Canonical user-facing…

  • Reads credentials
  • Installs packages
  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 31,439 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository11 other files it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

24 rules. About 0 are common, 6 are distinctive, and 18 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 18

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Very specific:

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

    line 36
  2. Very specific:

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

    line 52
  3. Very specific:

    When invoking VibeFrame commands from an agent context:

    line 58
  4. Distinctive:

    Treat your host's agent loop (Claude Code, Codex, Cursor, or another coding-agent host) as the outer loop for long-running video work.

    line 60
  5. Very specific:

    Prefer --json for structured output.

    line 65
  6. Very specific:

    Run --dry-run before paid or mutating operations when the command supports it.

    line 66
  7. Very specific:

    When a review report includes nextActions, prefer it over inventing commands: run only safeToAutoRun:true actions automatically, ask before …

    line 67
  8. Very specific:

    Use vibe schema <command> before constructing non-trivial arguments.

    line 71
  9. Very specific:

    Use --stdin for complex option payloads instead of fragile shell quoting.

    line 74
  10. Distinctive:

    When adding CLI commands, expose them as MCP tools only when natural-language invocation is useful.

    line 82
  11. Very specific:

    Add a manifest entry (packages/cli/src/tools/manifest/) with a schema that matches the CLI behavior.

    line 91
  12. Distinctive:

    Add focused tests for the executor and wrapper.

    line 92
  13. Distinctive:

    Do not maintain a separate hardcoded cost table in docs or prompts.

    line 96
  14. Very specific:

    Run pnpm build after TypeScript changes.

    line 114
  15. Very specific:

    Run pnpm lint after changes and fix errors before committing.

    line 115
  16. Distinctive:

    Do not leave unused imports.

    line 116
  17. Very specific:

    Do not suppress lint with // eslint-disable or @ts-ignore.

    line 117
  18. Very specific:

    Use exitWithError() from commands/output.ts for structured errors.

    line 118
  19. Very specific:

    Use requireApiKey() from utils/api-key.ts for required API keys.

    line 119
  20. Very specific:

    Use hasApiKey() for side-effect-free key detection.

    line 120
  21. Very specific:

    Use resolveProvider() / provider registry helpers instead of duplicating fallback logic.

    line 121
  22. Very specific:

    Before changing a provider integration, read its .agents/references/providers/<provider>.md (models, rejected params, deprecation dates) …

    line 122
  23. Very specific:

    After editing the catalog, run pnpm gen:models (MODELS.md is partly generated).

    line 128
  24. Distinctive:

    Before pushing from any host, run the shared pre-push gate or enable the repo Git hook:

    line 188

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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/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) -> Executors (scene projects, one-shot media) -> AI Providers + FFmpeg + Hyperframes

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
  • Spend and provenance: take (the record of every paid generation; see docs/take-graph.md)
  • Setup & hosts: setup, doctor, host
  • Lower-level operations: scene, design, detect, media, assemble

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

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 and provider-backed remix workflows.
  • Use --stdin for complex option payloads instead of fragile shell quoting.

Provider assets are inputs, not always the final product. For factual, data-heavy, or typography-heavy videos, prefer deterministic HTML/CSS/JS composition for text, layout, motion, timing, and reviewability.

CLI And Tool Sync

When adding CLI commands, expose them as MCP tools only when natural-language invocation is useful.

Naming: vibe <group> <action> maps to <group>_<action> in snake_case.

Pattern:

  1. Extract a testable execute*() function from the command module.
  2. Reuse the same executor from the CLI, the YAML pipeline, and the MCP tool where practical.
  3. Add a manifest entry (packages/cli/src/tools/manifest/) with a schema that matches the CLI behavior.
  4. Add focused tests for the executor and wrapper.

Cost Awareness

Do not maintain a separate hardcoded cost table in docs or prompts. The CLI stamps cost tiers on commands; use:

vibe schema --list
vibe schema --list --filter free
vibe schema generate.video

General expectation:

  • Free/local: schema, setup/doctor, detect/media, many FFmpeg edits.
  • Low: speech, transcription, inspection, simple AI-assisted edits.
  • High: image generation, storyboard/motion generation.
  • Very high: video generation and expensive provider-backed transforms.

Code Quality

  • Run pnpm build after TypeScript changes.
  • Run pnpm lint after changes and fix errors before committing.
  • Do not leave unused imports.
  • Do not suppress lint with // eslint-disable or @ts-ignore; fix the root cause.
  • Use exitWithError() from commands/output.ts for structured errors.
  • Use requireApiKey() from utils/api-key.ts for required API keys.
  • Use hasApiKey() for side-effect-free key detection.
  • Use resolveProvider() / provider registry helpers instead of duplicating fallback logic.
  • Before changing a provider integration, read its .agents/references/providers/<provider>.md (models, rejected params, deprecation dates) and run pnpm providers:check.
  • Model IDs, CLI aliases, defaults, lifecycle dates, and list prices live in the model catalog (packages/ai-providers/src/catalog/catalog.ts). Read them through findModel() / defaultModel(); do not hardcode model IDs. After editing the catalog, run pnpm gen:models (MODELS.md is partly generated).
  • Video providers implement VideoGenerator (packages/ai-providers/src/video/) and image providers implement ImageGenerator (src/image/): HTTP goes through providerRequest, failures are ProviderErrors with a kind, and each provider passes its contract suite. The CLI opens providers through createVideoGenerator / createImageGenerator and branches on error.kind, never on provider names or wording.

Conventions

  • Conventional commits: feat:, fix:, docs:, refactor:, chore:.
  • Git & PR workflow: branch off main as feat/<topic>, fix/<topic>, or chore/<topic>. One PR = one coherent scope - do not stack unrelated commits onto an open PR branch. Rebase/split when scope drifts.
  • Every commit reaches main via a PR - including chore: bump version release commits. Branch → PR → CI green → merge. Do not push directly to main, even as a maintainer with admin bypass (main allows it, but the policy does not). Release bumps go on a chore/release-<version> (or the feature) branch and merge through the same gate as any other change.
  • Bump at release time, not per PR. feat:/fix: PRs merge without a version bump. When you decide to release, /release bumps once and regenerates CHANGELOG.md so the new version covers every commit since the last tag. The push gate warns about unreleased work but never blocks on it; the blocking check lives in .github/workflows/release-tag.yml, which refuses to tag a version that does not describe HEAD.
  • Version bumps default to patch during 0.x. patch is the default; minor is rare. Use minor only for new public CLI command namespaces, new MCP tool families, public API contract additions, or large product milestones; reserve major for breaking changes or the 1.0 milestone. The shared push gate (scripts/pre-push-validate.sh) blocks a minor/major bump unless the chore: bump version commit carries a Release-Type: minor: <reason> (or major) trailer, or VIBE_ALLOW_MINOR=1 is set.
  • API keys belong in local config or .env-style files, never committed.
  • See MODELS.md for provider details.
  • CHANGELOG.md is generated with git-cliff --tag vX.Y.Z -o CHANGELOG.md.
  • CI never publishes npm packages. Once the version commit lands on main and CI passes, the release tag is created automatically by the Create release tag workflow. Publishing stays manual: run the Publish to npm workflow with that tag. (Tags pushed by a workflow cannot trigger another workflow, so auto-tagging never reaches publish.yml.)
  • Release state is computed in one place - scripts/release-status.sh. The push gate, the tag workflow, and the daily drift check all call it. Do not reimplement version/tag comparisons anywhere else.

Verification

Match verification to the change:

  • TypeScript or command behavior: run pnpm build, pnpm lint, and focused tests.
  • CLI schema/reference changes: run pnpm gen:reference:check when relevant.
  • Scene/video work: run vibe scene lint, vibe render, and vibe inspect render --cheap.
  • pnpm test skips the Chrome/CLI-spawning integration tests for speed; run pnpm -F @vibeframe/cli test:integration when touching rendering or scene code (CI always runs them).
  • Provider or build-pipeline changes: extend the fake provider network (packages/cli/src/testing/fake-provider-network.ts) so the real request and file-write path is tested without paid calls.

Before pushing from any host, run the shared pre-push gate or enable the repo Git hook:

pnpm hooks:install
bash scripts/pre-push-validate.sh

Claude Code's .claude/hooks/pre-push-validate.sh and Git's .githooks/pre-push both delegate to scripts/pre-push-validate.sh, so Codex, Claude Code, and direct terminal pushes use the same version/SSOT checks.

Agent Hosts & Sync

vibe init writes one AGENTS.md (plus a CLAUDE.md that imports it) that serves every bash-capable host; --mcp adds MCP config for Claude Code, Codex, and Cursor. It does not emit per-host files - projectFiles in agent-host-detect.ts is a detection list, not a scaffold list. Separately, pnpm agent-sync keeps three hosts' generated config (Claude Code, Codex, Cursor) in sync from one canonical source. Full map + workflows: docs/agent-hosts.md.

  • Canonical (edit these): AGENTS.md (this file - Codex/Cursor read it natively; Claude imports it via CLAUDE.md = @AGENTS.md) and cross-host skills in .agents/skills/<name>/SKILL.md.
  • Generated by pnpm agent-sync (never edit; marked DO NOT EDIT): .claude/skills/*, the MCP block in .codex/config.toml, and mcpServers.vibeframe in .cursor/mcp.json.
  • Claude-only, NOT propagated to Codex/Cursor: .claude/rules/* (path-scoped), .claude/agents/*, .claude/hooks/*, .claude/settings.json.
  • Where new guidance goes: shared rules → AGENTS.md or .agents/skills/; Claude-only ergonomics → .claude/. Keep this file lean (it loads into every session and is read by every host).
  • Enforced: pnpm agent-sync:check runs in the pre-push gate and CI. After editing a canonical source, run pnpm agent-sync and commit the result.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.