From 8551cffdddd19c36ddd0a437dac430886ad75e82 Mon Sep 17 00:00:00 2001 From: James Russo Date: Tue, 14 Apr 2026 19:13:26 -0700 Subject: [PATCH] docs: add AGENTS.md for universal AI assistant configuration (#278) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## What Adds `AGENTS.md` at two levels: 1. **Repo-level** (`/AGENTS.md`) — for contributors working on HyperFrames itself 2. **Project-level** (`packages/cli/src/templates/_shared/AGENTS.md`) — scaffolded into user projects by `hyperframes init` Also replaces the previous `AGENTS.md → CLAUDE.md` symlink with a standalone file. ## Why AGENTS.md is the emerging universal standard for AI coding tool configuration, supported by Claude Code, Cursor, GitHub Copilot, Gemini CLI, and Codex (60K+ repos). Remotion already has one. For a project that positions itself as AI-native, this is a gap. The project-level file (scaffolded by `init`) ensures every AI tool — not just Claude — gets framework context when working on a user's composition project. The symlink was replaced because symlinks are fragile on Windows and the content should differ (repo-level covers build/test, project-level covers composition rules). ## How - **Repo-level AGENTS.md**: Build/test/lint commands, project structure, key conventions, skills install, doc links - **Project-level AGENTS.md**: Composition-specific — skills, CLI commands, project structure, linting workflow, key rules, doc links - **CLAUDE.md** remains for Claude-specific skill invocation syntax (slash commands) ## Test plan - [ ] Verify AGENTS.md renders correctly on GitHub - [ ] Verify no duplication with CLAUDE.md (AGENTS.md = universal basics, CLAUDE.md = Claude-specific slash commands) - [ ] Manual testing performed - [x] Documentation updated (if applicable) --- AGENTS.md | 76 ++++++++++++++++++++ packages/cli/src/templates/_shared/AGENTS.md | 60 +++++++++++++++- 2 files changed, 135 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md mode change 120000 => 100644 packages/cli/src/templates/_shared/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..f68c11e3b2 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,76 @@ +# Hyperframes + +Open-source video rendering framework: write HTML, render video. + +## Skills + +This repo ships AI agent skills via [vercel-labs/skills](https://github.com/vercel-labs/skills). Install them before writing compositions — they encode framework-specific patterns that generic docs don't cover. + +```bash +npx skills add heygen-com/hyperframes # HyperFrames skills +npx skills add greensock/gsap-skills # GSAP animation skills +``` + +## Build & Test + +```bash +bun install # Install dependencies (NOT pnpm — do not create pnpm-lock.yaml) +bun run build # Build all packages +bun run test # Run all tests +``` + +### Linting & Formatting + +Uses **oxlint** and **oxfmt** (not eslint, not prettier, not biome). + +```bash +bunx oxlint # Lint +bunx oxfmt # Format +bunx oxfmt --check # Check formatting (CI / pre-commit) +``` + +Always lint and format changed files before committing. Lefthook pre-commit hooks enforce this automatically. + +### Composition Validation + +After creating or editing any `.html` composition: + +```bash +npx hyperframes lint # Static HTML structure check +npx hyperframes validate # Runtime check (headless Chrome — catches JS errors, missing assets) +``` + +Both must pass before previewing or considering work complete. + +## Project Structure + +``` +packages/ + cli/ → hyperframes CLI (create, preview, lint, render) + core/ → Types, parsers, generators, linter, runtime, frame adapters + engine/ → Seekable page-to-video capture engine (Puppeteer + FFmpeg) + player/ → Embeddable web component + producer/ → Full rendering pipeline (capture + encode + audio mix) + shader-transitions/ → WebGL shader transitions for compositions + studio/ → Browser-based composition editor UI +registry/ + blocks/ → Installable sub-composition scenes (50+) + components/ → Installable effects and snippets + examples/ → Starter project templates +docs/ → Mintlify documentation site (hyperframes.heygen.com) +skills/ → AI agent skill definitions +``` + +## Key Conventions + +- **Package manager**: bun (not pnpm, not npm for workspace operations) +- **Commit format**: Conventional commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`) +- **TypeScript**: Avoid `any` and `as T` assertions. Prefer type guards and narrowing. +- **Compositions**: HTML files with `data-*` attributes. Clips need `class="clip"`. GSAP timelines must be paused and registered on `window.__timelines`. +- **Frame Adapters**: Animation runtimes plug in via the seek-by-frame adapter pattern. GSAP is the primary adapter. +- **Deterministic rendering**: No `Date.now()`, no unseeded `Math.random()`, no render-time network fetches. + +## Documentation + +- Docs: https://hyperframes.heygen.com/introduction +- Catalog (50+ blocks): https://hyperframes.heygen.com/catalog/blocks/data-chart diff --git a/packages/cli/src/templates/_shared/AGENTS.md b/packages/cli/src/templates/_shared/AGENTS.md deleted file mode 120000 index 681311eb9c..0000000000 --- a/packages/cli/src/templates/_shared/AGENTS.md +++ /dev/null @@ -1 +0,0 @@ -CLAUDE.md \ No newline at end of file diff --git a/packages/cli/src/templates/_shared/AGENTS.md b/packages/cli/src/templates/_shared/AGENTS.md new file mode 100644 index 0000000000..7ed336f96f --- /dev/null +++ b/packages/cli/src/templates/_shared/AGENTS.md @@ -0,0 +1,59 @@ +# HyperFrames Composition Project + +## Skills + +This project uses AI agent skills for framework-specific patterns. Install them if not already present: + +```bash +npx skills add heygen-com/hyperframes # HyperFrames composition skills +npx skills add greensock/gsap-skills # GSAP animation skills +``` + +Skills encode patterns like `class="clip"` on timed elements, `window.__timelines` registration, and `data-*` attribute semantics that are not in generic web docs. Using them produces correct compositions from the start. + +## Commands + +```bash +npx hyperframes preview # preview in browser (studio editor) +npx hyperframes render # render to MP4 +npx hyperframes lint # validate compositions (errors + warnings) +npx hyperframes lint --json # machine-readable output for CI +npx hyperframes docs # reference docs in terminal +``` + +## Project Structure + +- `index.html` — main composition (root timeline) +- `compositions/` — sub-compositions referenced via `data-composition-src` +- `assets/` — media files (video, audio, images) +- `meta.json` — project metadata (id, name) +- `transcript.json` — whisper word-level transcript (if generated) + +## Linting — Always Run After Changes + +After creating or editing any `.html` composition, run the linter before considering the task complete: + +```bash +npx hyperframes lint +``` + +Fix all errors before presenting the result. + +## Key Rules + +1. Every timed element needs `data-start`, `data-duration`, and `data-track-index` +2. Visible timed elements **must** have `class="clip"` — the framework uses this for visibility control +3. GSAP timelines must be paused and registered on `window.__timelines`: + ```js + window.__timelines = window.__timelines || {}; + window.__timelines["composition-id"] = gsap.timeline({ paused: true }); + ``` +4. Videos use `muted` with a separate `