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)
This commit is contained in:
James Russo
2026-04-14 19:13:26 -07:00
committed by GitHub
parent cd17074f3b
commit 8551cffddd
2 changed files with 135 additions and 1 deletions
+76
View File
@@ -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 <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
@@ -1 +0,0 @@
CLAUDE.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 <topic> # 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 `<audio>` element for the audio track
5. Sub-compositions use `data-composition-src="compositions/file.html"`
6. Only deterministic logic — no `Date.now()`, no `Math.random()`, no network fetches
## Documentation
Full docs: https://hyperframes.heygen.com/introduction
Machine-readable index for AI tools: https://hyperframes.heygen.com/llms.txt