Files
hyperframes/AGENTS.md
T
James Russo 8551cffddd docs: add AGENTS.md for universal AI assistant configuration (#278)
## 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)
2026-04-14 19:13:26 -07:00

77 lines
2.9 KiB
Markdown

# 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 <files> # Lint
bunx oxfmt <files> # Format
bunx oxfmt --check <files> # 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 <hyperframes-player> 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