diff --git a/.claude/skills/hyperframes-captions b/.claude/skills/hyperframes-captions deleted file mode 120000 index a3c2afaa5..000000000 --- a/.claude/skills/hyperframes-captions +++ /dev/null @@ -1 +0,0 @@ -../../skills/hyperframes-captions \ No newline at end of file diff --git a/.claude/skills/hyperframes-compose b/.claude/skills/hyperframes-compose deleted file mode 120000 index 8028a889f..000000000 --- a/.claude/skills/hyperframes-compose +++ /dev/null @@ -1 +0,0 @@ -../../skills/hyperframes-compose \ No newline at end of file diff --git a/.gitignore b/.gitignore index cade4306e..02624753e 100644 --- a/.gitignore +++ b/.gitignore @@ -78,3 +78,11 @@ captures/ *-ad/ *-tour/ *-brand/ + +# Local regression-test scratch directories (website-to-hyperframes runs). +# These hold per-site captures, SCRIPT/STORYBOARD/DESIGN.md, compositions, +# narration audio, rendered MP4s — all reproducible, never commit. +cursor-tests/ +basecamp-video/ +projects/ +videos/ diff --git a/packages/cli/src/capture/agentPromptGenerator.ts b/packages/cli/src/capture/agentPromptGenerator.ts index fb977d5c1..b5ea2bb46 100644 --- a/packages/cli/src/capture/agentPromptGenerator.ts +++ b/packages/cli/src/capture/agentPromptGenerator.ts @@ -1,9 +1,13 @@ /** - * Generate CLAUDE.md (and .cursorrules) for captured website projects. + * Generate AGENTS.md and CLAUDE.md for captured website projects. + * + * Writes the same content to both filenames so any AI agent auto-discovers it: + * - AGENTS.md — universal convention (Cursor, Codex, Gemini CLI, Windsurf, Aider, Jules) + * - CLAUDE.md — Claude Code convention * * This file generates a DATA INVENTORY that tells the AI agent what files * exist and what they contain. The actual workflow lives in the - * /website-to-hyperframes skill — this file points agents there. + * website-to-hyperframes skill — this file points agents there. */ import { writeFileSync } from "node:fs"; @@ -32,8 +36,8 @@ export function generateAgentPrompt( hasShaders, detectedLibraries, ); + writeFileSync(join(outputDir, "AGENTS.md"), prompt, "utf-8"); writeFileSync(join(outputDir, "CLAUDE.md"), prompt, "utf-8"); - writeFileSync(join(outputDir, ".cursorrules"), prompt, "utf-8"); } function buildPrompt( @@ -104,7 +108,7 @@ function buildPrompt( Source: ${url} -To create a video from this capture, use the \`/website-to-hyperframes\` skill. +To create a video from this capture, use the \`website-to-hyperframes\` skill. ## What's in This Capture diff --git a/packages/cli/src/capture/scaffolding.ts b/packages/cli/src/capture/scaffolding.ts index 55ae55f12..befeb210e 100644 --- a/packages/cli/src/capture/scaffolding.ts +++ b/packages/cli/src/capture/scaffolding.ts @@ -2,7 +2,7 @@ * Project scaffolding helpers for the website capture pipeline. * * Handles .env file loading and HyperFrames project scaffold generation - * (index.html, meta.json, CLAUDE.md). + * (index.html, meta.json, AGENTS.md, CLAUDE.md). */ import { existsSync, writeFileSync, readFileSync } from "node:fs"; @@ -44,10 +44,10 @@ export function loadEnvFile(startDir: string): void { } /** - * Generate the project scaffold files: index.html, meta.json, and CLAUDE.md. + * Generate the project scaffold files: index.html, meta.json, AGENTS.md, CLAUDE.md. * * Only creates files that don't already exist (index.html, meta.json). - * Always generates CLAUDE.md via agentPromptGenerator. + * Always (re)generates AGENTS.md + CLAUDE.md via agentPromptGenerator. */ export async function generateProjectScaffold( outputDir: string, @@ -78,7 +78,7 @@ export async function generateProjectScaffold( ); } - // Generate CLAUDE.md + .cursorrules (AI agent instructions — always, regardless of API keys) + // Generate AGENTS.md + CLAUDE.md (AI agent instructions — always, regardless of API keys) try { const { generateAgentPrompt } = await import("./agentPromptGenerator.js"); generateAgentPrompt( @@ -92,8 +92,8 @@ export async function generateProjectScaffold( catalogedAssets, detectedLibraries, ); - progress("agent", "CLAUDE.md generated"); + progress("agent", "AGENTS.md + CLAUDE.md generated"); } catch (err) { - warnings.push(`CLAUDE.md generation failed: ${err}`); + warnings.push(`AGENTS.md/CLAUDE.md generation failed: ${err}`); } } diff --git a/skills/website-to-hyperframes/SKILL.md b/skills/website-to-hyperframes/SKILL.md index 8d73fefd5..4f76d8b0e 100644 --- a/skills/website-to-hyperframes/SKILL.md +++ b/skills/website-to-hyperframes/SKILL.md @@ -70,7 +70,7 @@ Generate TTS audio, transcribe for word-level timestamps, and map timestamps to ## Step 6: Build Compositions -**Read:** The `/hyperframes` skill (invoke it — every rule matters) +**Read:** The `hyperframes` skill (load it — every rule matters) **Read:** [references/step-6-build.md](references/step-6-build.md) Build each composition following the storyboard. After each one: self-review for layout, asset placement, and animation quality. @@ -83,7 +83,7 @@ Build each composition following the storyboard. After each one: self-review for **Read:** [references/step-7-validate.md](references/step-7-validate.md) -Lint, validate, preview. Create a HANDOFF.md for multi-session continuity. +Lint, validate, preview. Deliver the final render. **Gate:** `npx hyperframes lint` and `npx hyperframes validate` pass with zero errors. @@ -117,5 +117,5 @@ Lint, validate, preview. Create a HANDOFF.md for multi-session continuity. | [step-4-storyboard.md](references/step-4-storyboard.md) | Step 4 — per-beat creative direction | | [step-5-vo.md](references/step-5-vo.md) | Step 5 — TTS, transcription, timing | | [step-6-build.md](references/step-6-build.md) | Step 6 — building compositions with self-review | -| [step-7-validate.md](references/step-7-validate.md) | Step 7 — lint, validate, preview, handoff | +| [step-7-validate.md](references/step-7-validate.md) | Step 7 — lint, validate, snapshot, preview | | [techniques.md](references/techniques.md) | Steps 4 & 6 — 10 visual techniques with code patterns (SVG drawing, Canvas 2D, 3D, typography, Lottie, video, typing, variable fonts, MotionPath, transitions) | diff --git a/skills/website-to-hyperframes/references/step-5-vo.md b/skills/website-to-hyperframes/references/step-5-vo.md index be656c6eb..51d91dd0c 100644 --- a/skills/website-to-hyperframes/references/step-5-vo.md +++ b/skills/website-to-hyperframes/references/step-5-vo.md @@ -14,6 +14,8 @@ Pick the voice that sounds most natural and conversational. Listen for pacing Generate the full script as `narration.wav` (or `.mp3`) in the project directory. +**Also save the exact spoken text** — with pronunciation substitutions applied (e.g., `API` → `A P I`, `$2T` → `two trillion`) — as `narration.txt` in the same directory. This is the string passed to TTS, distinct from `SCRIPT.md` which is the human-readable creative doc. Having `narration.txt` makes it trivial to regenerate the audio later with a different voice without re-deriving the substitutions. Name it exactly `narration.txt` — not `narration-input.txt` or variations. + ## Transcribe for word-level timestamps ```bash diff --git a/skills/website-to-hyperframes/references/step-6-build.md b/skills/website-to-hyperframes/references/step-6-build.md index 2ec797dc9..d1f641c62 100644 --- a/skills/website-to-hyperframes/references/step-6-build.md +++ b/skills/website-to-hyperframes/references/step-6-build.md @@ -30,12 +30,12 @@ FONTS — use @font-face with the captured font files, NOT Google Fonts: Read DESIGN.md for exact colors and Do's/Don'ts. Read techniques.md for animation code patterns. -Invoke /hyperframes for composition structure rules. +Load the `hyperframes` skill for composition structure rules. ``` After each sub-agent finishes, verify the composition references `../assets/` — if it used inline SVGs or Google Fonts instead of the captured files, fix it before moving on. -Invoke the `/hyperframes` skill first — it has the rules for data attributes, timeline contracts, deterministic rendering, and layout. Everything below supplements those rules, not replaces them. +Load the `hyperframes` skill first — it has the rules for data attributes, timeline contracts, deterministic rendering, and layout. Everything below supplements those rules, not replaces them. --- @@ -113,6 +113,9 @@ After building the composition, check WITH ACTUAL CODE: - [ ] No full-screen dark linear gradients (H.264 creates visible banding — use solid + localized radial glows) - [ ] Timeline registered: `window.__timelines["comp-id"] = tl` - [ ] Colors match DESIGN.md exactly (paste the HEX value, don't approximate) +- [ ] **Every `