From d8f1af1ef10a87e672231d99e610e2d28b6da6d3 Mon Sep 17 00:00:00 2001
From: ukimsanov <ular.kimsanov@heygen.com>
Date: Sat, 18 Apr 2026 23:17:29 -0400
Subject: [PATCH] feat(capture): write AGENTS.md alongside CLAUDE.md + skill
 refinements from regression tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Capture pipeline:
- agentPromptGenerator now writes AGENTS.md + CLAUDE.md (drop legacy
  .cursorrules), matching the dual-file convention already used by the
  _shared templates in hyperframes init. AGENTS.md is picked up natively by
  Cursor, Codex, Gemini CLI, Windsurf, Aider, and Jules; CLAUDE.md covers
  Claude Code. Both files share the same content — a capture data inventory
  that points agents to the website-to-hyperframes skill.

website-to-hyperframes skill refinements (derived from 8-site regression test):
- Drop slash-command phrasing throughout SKILL.md and step-6-build.md so the
  skill works identically across Claude Code (slash), Cursor (auto-discover
  by description), and other agents.
- Remove stale HANDOFF.md references from SKILL.md step-7 summary and
  reference table — matches the intent of the prior step-7 cleanup.
- step-5-vo: specify narration.txt filename convention (pronunciation-
  substituted spoken text; distinct from SCRIPT.md the creative doc).
- step-6 self-review adds three rules derived from actual lint warnings
  observed across the 8 regression runs:
    - Every <template> root needs data-start + data-duration (catches
      root_composition_missing_data_start/duration, seen in 4/8 runs).
    - Caption exits need a hard tl.set kill after tl.to(opacity:0), or
      per-word karaoke tweens can leave captions stuck on screen
      (caption_exit_missing_hard_kill).
    - No duplicate media nodes with identical src + start + duration, or
      the compiler discovers them twice (duplicate_media_discovery_risk).

Housekeeping:
- .gitignore: add cursor-tests/, basecamp-video/, projects/, videos/ —
  local regression-test scratch dirs that should never be committed.
- Remove two broken symlinks from .claude/skills/ that pointed to paths
  which never existed in the repo (.claude/skills/ is already gitignored).

Made-with: Cursor
---
 .claude/skills/hyperframes-captions                  |  1 -
 .claude/skills/hyperframes-compose                   |  1 -
 .gitignore                                           |  8 ++++++++
 packages/cli/src/capture/agentPromptGenerator.ts     | 12 ++++++++----
 packages/cli/src/capture/scaffolding.ts              | 12 ++++++------
 skills/website-to-hyperframes/SKILL.md               |  6 +++---
 .../website-to-hyperframes/references/step-5-vo.md   |  2 ++
 .../references/step-6-build.md                       |  7 +++++--
 8 files changed, 32 insertions(+), 17 deletions(-)
 delete mode 120000 .claude/skills/hyperframes-captions
 delete mode 120000 .claude/skills/hyperframes-compose

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 `<template>` root element** — not just `index.html`, but every sub-composition's root — has `data-start="0"` **and** `data-duration="<beat_seconds>"`. The linter warns `root_composition_missing_data_start` / `root_composition_missing_data_duration` when missing; without `data-duration` the runtime may infer `Infinity` on repeating animations and stall playback.
+- [ ] **Caption exits have a hard kill.** If you animate captions out with `tl.to(groupEl, { opacity: 0 }, group.end)`, follow it with `tl.set(groupEl, { opacity: 0, visibility: "hidden" }, group.end)` as a deterministic kill — per-word karaoke tweens can override the exit tween and leave captions stuck on screen. Linter: `caption_exit_missing_hard_kill`.
+- [ ] **No duplicate media nodes.** If the same image/video source is referenced twice with identical `data-start` + `data-duration`, the compiler discovers it twice and can double-render. Dedupe by using a single `<img>` with appropriate z-layering, or stagger the `data-start` values. Linter: `duplicate_media_discovery_risk`.
 
 **If `skills/hyperframes-animation-map/` is installed**, run it: