Skip to content

Commit 0f8eb89

Browse files
fix(skills): search the component catalog before hand-building a look (#3829)
* fix(motion-graphics): make the catalog search fire before hand-authoring The workflow's only reuse instruction pointed at catalog-map.md, a hand-maintained snapshot of ~60 registry items, and no file in the skill ever named `hyperframes catalog --query`. An agent asked mid-build for CRT scanlines and a glitch effect had no instruction to search, so it hand-authored both while caption-glitch-rgb ("RGB chromatic aberration with CRT scanline overlay") ranks first for that query on either tier. The search reads the hosted registry and needs nothing installed, from any directory with no project, so "the components were not installed" was never the cause. Say that where the reader is, since the wrong diagnosis is the intuitive one. Director Part 2 and the Builder now run the search before naming a block, and catalog-map.md is labelled a partial snapshot whose misses prove nothing. Pinned by a content test in coreSkillContent.test.ts. * fix(skills): search the component catalog before hand-building a look Authoring workflows never told the agent to search the component library, so agents rebuilt effects the registry already shipped. A user reported building an effect from scratch that the registry already contained; the search that would have found it needs nothing installed, which is why the usual self-diagnosis ("I forgot to install the components") is wrong. All ten workflow skills carried zero mentions of `hyperframes catalog`. The instruction lived only in hyperframes-cli and hyperframes-registry, both loaded on demand, and the registry skill's own trigger named the command rather than the symptom - circular, because an agent that never thought to search could not reach the doc telling it to search. - Eight workflows now run the search at the point they decide what to build, before authoring. The two that compile through a closed authoring vocabulary (embedded-captions, talking-head-recut) document why they deliberately do not. - hyperframes-registry triggers on the symptom (a named look, effect, treatment or transition) instead of the command name; the router table and the catalog surfaces carry the same framing. - Fixes hand-maintained lists that had drifted: bar-chart-race was listed as a hand-author gap in two files while shipping in the registry; stat-motion was named as an installable block and is not one; the caption-* family count was one high; the registry discovery tables claimed to be the block list while covering 97 of 180. - bun run lint:skills now fails when a doc marked as a registry snapshot names an item the registry does not have. * refactor(scripts): reuse native recursive readdir and the shared registry type Simplify pass on the new registry-snapshot check, behaviour identical: - collectMarkdownFiles uses readdirSync({ recursive: true }) instead of hand-rolled recursion, matching scripts/generate-template-previews.ts. - registryItemNames types registry.json with the exported RegistryManifest instead of an ad hoc inline shape, matching scripts/catalog/build-local-vectors.ts. The runtime guard stays: a cast describes the file, it does not validate it. - One report() helper replaces the duplicated print-and-count block in both lint passes. * refactor(scripts): name the registry check's blind spots and stop self-arming Applies the review findings on the new check, behaviour identical except where noted: - lintRegistryItemRefs returns null for an unmarked file instead of an empty array, so "not a snapshot" and "a clean snapshot" have one owner and the marker is matched once rather than twice. - Marker detection ignores fenced blocks, so a doc that documents the marker syntax in an example no longer arms the check on itself. The id scan still reads full content, so fenced examples stay covered. - The header comment and two tests now pin both known false negatives: identifiers outside backticks, and single-word item names. Measured on the six marked files, dropping the hyphen requirement would monitor 3 more items and force 46 allow= entries for ordinary prose words, so the requirement stays and the gap is stated instead of silent. * chore(skills): regenerate skills manifest after catalog-search edits
1 parent db51d54 commit 0f8eb89

28 files changed

Lines changed: 309 additions & 43 deletions

File tree

‎CLAUDE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ Atomic capabilities the creation workflows compose against — pull one when you
4141
- `/media-use` — the media OS: resolve any media need (BGM, SFX, image, icon, logo, voice, color grade, LUT) into a frozen local file or paste-ready block + ledger record; generate via TTS / music / image models when the catalog misses; transcribe, caption, remove backgrounds, and reuse assets across projects. One shared `scripts/audio.mjs` engine + manifest tracking; keeps search noise on disk.
4242
- `/hyperframes-audio` — mix the audio already placed in a composition: voiceover carve (dip a music bed only in the bands the voice occupies, static or dynamic, level match included), the effect chain (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), automation envelopes on volume or any effect parameter, and submix buses (`<hf-audio-group>`) that carry one chain, fader and automation clock for several tracks at once. Sourcing the audio is `/media-use`; this is what happens to it afterwards.
4343
- `/hyperframes-cli` — CLI dev loop: `init`, `add`, `lint`, `check`, `snapshot`, `preview`, `render`, `publish`, `doctor`, `lambda` (AWS Lambda cloud rendering).
44-
- `/hyperframes-registry` — install and wire registry blocks and components into compositions via `hyperframes add`. Covers authoring a new block or component to contribute upstream.
44+
- `/hyperframes-registry` — search, install and wire registry blocks and components into compositions via `hyperframes catalog` / `hyperframes add`. Load it before hand-building any named look, effect, treatment or transition: the search ranks the whole hosted registry with nothing installed. Covers authoring a new block or component to contribute upstream.
4545
- `/figma` — import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations (MCP) and shaders (MCP source / native export) into a composition.
4646

4747
## Skill catalog maintenance

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,7 @@ Atomic capabilities the creation workflows compose against — pull one when you
103103
| `/media-use` | The media OS — resolve any media need (BGM, SFX, image, icon, logo, voice, color grade, LUT) into a frozen local file or paste-ready block + ledger record, generate via TTS/music/image models when the catalog misses, transcribe, caption, remove backgrounds, and reuse assets across projects. One shared audio engine + manifest tracking. |
104104
| `/hyperframes-cli` | CLI dev loop — `init`, `lint`, `check`, `snapshot`, `preview`, `render`, `publish`, `doctor`, plus HeyGen-hosted cloud rendering (`cloud render`) and AWS Lambda rendering (`lambda deploy / render / progress`). |
105105
| `/hyperframes-audio` | Mix the audio already placed in a composition — voiceover carve (dip a music bed only in the bands the voice occupies, static or dynamic, level match included), the effect chain (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), automation envelopes on volume or any effect parameter, and submix buses (`<hf-audio-group>`) carrying one chain, fader and automation clock for several tracks at once. Sourcing the audio is `/media-use`. |
106-
| `/hyperframes-registry` | Install and wire registry blocks and components into compositions via `hyperframes add`. Authoring a new block or component to contribute upstream. |
106+
| `/hyperframes-registry` | Search, install and wire registry blocks and components into compositions via `hyperframes catalog` / `hyperframes add`. Load before hand-building any named look, effect, treatment or transition. Authoring a new block or component to contribute upstream. |
107107
| `/figma` | Import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations (MCP) and shaders (MCP source / native export) into a composition. |
108108

109109
For visual design handoff workflows, see the [Claude Design guide](https://hyperframes.heygen.com/guides/claude-design) and [Open Design guide](https://hyperframes.heygen.com/guides/open-design).

‎docs/prompting/overview.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ The installer shows a picker. Select the **core skills** below — every project
5252
| `/hyperframes-creative` | Creative direction — design spec, palettes, typography, narration, beats |
5353
| `/hyperframes-cli` | Dev-loop CLI — `init`, `lint`, `check`, `preview`, `render`, `doctor` |
5454
| `/media-use` | Media OS — TTS voiceover (`tts`), `transcribe`, `remove-background`, plus BGM / SFX / image resolution |
55-
| `/hyperframes-registry` | Block and component installation via `hyperframes add` |
55+
| `/hyperframes-registry` | Search the catalog before hand-building a look; install via `hyperframes add` |
5656
| `/hyperframes-keyframes`| Seek-safe keyframe authoring across runtimes, plus `hyperframes keyframes` diagnostics |
5757
| `/general-video` | The general authoring workflow — multi-scene pieces, reels, montages, remixes, and the home of **companion mode**; the fallback when no workflow below fits |
5858

‎packages/cli/src/commands/coreSkillContent.test.ts‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,73 @@ describe("media treatment routing documentation", () => {
132132
}
133133
});
134134

135+
it("makes the motion-graphics build path run a live catalog search, not read a snapshot", () => {
136+
// The failure this pins: a user inside /motion-graphics asked for "CRT scanlines
137+
// and glitch effects" and the agent hand-authored both, while `caption-glitch-rgb`
138+
// ("RGB chromatic aberration with CRT scanline overlay") ranks first for that exact
139+
// query on either tier. Every reuse instruction in the workflow pointed at
140+
// catalog-map.md, a hand-maintained snapshot, and none named the search. The search
141+
// needs nothing installed, so "I forgot to install the components" was never the cause.
142+
for (const file of [
143+
["skills", "motion-graphics", "catalog-map.md"],
144+
["skills", "motion-graphics", "agents", "director.md"],
145+
["skills", "motion-graphics", "agents", "builder.md"],
146+
]) {
147+
expect(read(...file)).toContain("npx hyperframes catalog --query");
148+
}
149+
// And it must say the search stands alone, or the next reader re-derives the
150+
// creator's wrong diagnosis: that a catalog you have not installed cannot be searched.
151+
expect(read("skills", "motion-graphics", "catalog-map.md")).toContain(
152+
"needs nothing installed",
153+
);
154+
});
155+
156+
it("routes every authoring workflow through the live catalog search, or documents why not", () => {
157+
// The same failure one layer up. The search instruction lived only in
158+
// hyperframes-cli and hyperframes-registry, both loaded on demand, and the
159+
// registry skill's own trigger named the command ("use when running
160+
// hyperframes catalog") — circular, because the agent that never thought to
161+
// search could not reach the doc telling it to search. All ten workflow
162+
// skills carried zero mentions of the command.
163+
for (const file of [
164+
["skills", "motion-graphics", "agents", "director.md"],
165+
["skills", "product-launch-video", "SKILL.md"],
166+
["skills", "faceless-explainer", "SKILL.md"],
167+
["skills", "pr-to-video", "SKILL.md"],
168+
["skills", "music-to-video", "SKILL.md"],
169+
["skills", "general-video", "SKILL.md"],
170+
["skills", "slideshow", "SKILL.md"],
171+
["skills", "remotion-to-hyperframes", "SKILL.md"],
172+
]) {
173+
const doc = read(...file);
174+
expect(doc, file.join("/")).toContain("npx hyperframes catalog --query");
175+
// "I forgot to install the components" was the wrong self-diagnosis that
176+
// hid this bug. Every copy of the instruction has to kill it on the spot.
177+
expect(doc, file.join("/")).toContain("nothing installed");
178+
}
179+
180+
// The two workflows that deliberately do NOT search. Both compile their
181+
// output through a closed authoring vocabulary (embedded-captions' locked
182+
// caption engines, talking-head-recut's `data-anim` card kinds), and a
183+
// registry item is a standalone composition with no place to mount. The
184+
// exemption is written into each skill so the next reader does not close
185+
// the gap with an instruction that would be false there.
186+
for (const file of [
187+
["skills", "embedded-captions", "SKILL.md"],
188+
["skills", "talking-head-recut", "SKILL.md"],
189+
]) {
190+
expect(read(...file), file.join("/")).toContain(
191+
"does not search the HyperFrames component registry",
192+
);
193+
}
194+
195+
// The symptom-triggered description is the other half of the fix: the skill
196+
// has to be reachable from the user naming an effect, not from the command.
197+
const registrySkill = read("skills", "hyperframes-registry", "SKILL.md");
198+
expect(registrySkill).toContain("Use BEFORE hand-building any named visual");
199+
expect(registrySkill).toContain("CRT scanlines");
200+
});
201+
135202
it("gives agents a process-owned preview lifecycle in new project instructions", () => {
136203
for (const file of ["AGENTS.md", "CLAUDE.md"]) {
137204
const template = read("packages", "cli", "src", "templates", "_shared", file);

‎scripts/lint-skills.test.mjs‎

Lines changed: 56 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88

99
import test from "node:test";
1010
import assert from "node:assert/strict";
11-
import { lintFrontmatter } from "./lint-skills.ts";
11+
import { lintFrontmatter, lintRegistryItemRefs } from "./lint-skills.ts";
1212

1313
const wrap = (frontmatter) => `---\n${frontmatter}\n---\n\n# body\n`;
1414

@@ -125,3 +125,58 @@ test("invalid: top-level scalar (frontmatter is not a mapping)", () => {
125125
// be non-empty.
126126
assert.ok(violations.length > 0);
127127
});
128+
129+
// ---------------------------------------------------------------------------
130+
// Registry-snapshot drift guard
131+
// ---------------------------------------------------------------------------
132+
133+
const KNOWN = new Set(["caption-glitch-rgb", "code-diff", "data-chart"]);
134+
const MARKER = "<!-- registry-items: -->";
135+
136+
test("registry refs: unmarked file is never checked", () => {
137+
// Opt-in is the whole design. Most kebab-case backticks in skill docs are CSS
138+
// properties, data-* attributes or skill directory names, and a check that
139+
// flags those gets switched off. null (not []) distinguishes "not a snapshot"
140+
// from "a snapshot with nothing wrong", which is what the counter reports.
141+
assert.equal(lintRegistryItemRefs("Use `not-a-real-item` here.\n", KNOWN), null);
142+
});
143+
144+
test("registry refs: a marker inside a fenced block does not arm the check", () => {
145+
// Otherwise a doc that documents this marker's own syntax arms the check on
146+
// itself, and every identifier in it starts failing for no stated reason.
147+
const doc = ["# Doc", "", "```md", MARKER, "```", "", "Use `not-a-real-item`."].join("\n");
148+
assert.equal(lintRegistryItemRefs(doc, KNOWN), null);
149+
});
150+
151+
test("registry refs: marked file passes when every id is real", () => {
152+
const doc = `${MARKER}\n\nUse \`caption-glitch-rgb\` or \`code-diff\`.\n`;
153+
assert.deepEqual(lintRegistryItemRefs(doc, KNOWN), []);
154+
});
155+
156+
test("registry refs: marked file flags an id the registry does not have", () => {
157+
const doc = `${MARKER}\n\nInstall \`text-wave-distort\` for the wobble.\n`;
158+
const violations = lintRegistryItemRefs(doc, KNOWN);
159+
assert.equal(violations.length, 1);
160+
assert.equal(violations[0].line, 3);
161+
assert.ok(violations[0].message.includes("text-wave-distort"));
162+
});
163+
164+
test("registry refs: allow= exempts a legitimately non-item identifier", () => {
165+
const doc = `<!-- registry-items: allow=dark-plus,pin-rollout -->\n\n\`dark-plus\` and \`pin-rollout\`.\n`;
166+
assert.deepEqual(lintRegistryItemRefs(doc, KNOWN), []);
167+
});
168+
169+
test("registry refs: non-id backticks are ignored", () => {
170+
const doc = `${MARKER}\n\n\`--json\`, \`Foo-Bar\`, \`a b-c\`, \`UPPER-CASE\`.\n`;
171+
assert.deepEqual(lintRegistryItemRefs(doc, KNOWN), []);
172+
});
173+
174+
test("registry refs: single-word ids are a KNOWN blind spot, not an accident", () => {
175+
// The pattern requires a hyphen, so real single-word registry items (glitch,
176+
// flowchart, typewriter, confetti, separator, vignette, vignelli) are never
177+
// checked. Pinned here so the tradeoff is visible in code, not just in a
178+
// comment: dropping the hyphen would cost 46 allow= entries of prose nouns
179+
// across the marked files to monitor 3 more items. See lint-skills.ts header.
180+
const doc = `${MARKER}\n\n\`glitch\` was renamed and this doc was not updated.\n`;
181+
assert.deepEqual(lintRegistryItemRefs(doc, KNOWN), []);
182+
});

‎scripts/lint-skills.ts‎

Lines changed: 95 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
import { readFileSync, readdirSync, statSync } from "node:fs";
1313
import { join, relative } from "node:path";
1414
import { parse as parseYaml, YAMLParseError } from "yaml";
15+
import type { RegistryManifest } from "../packages/core/src/index.js";
1516

1617
const REPO_ROOT = join(import.meta.dirname, "..");
1718
// Every location that ships SKILL.md files gets linted. `skills/` is the
@@ -256,6 +257,79 @@ function lintInlinePatterns(file: string, stripped: string): Violation[] {
256257
.flatMap((line, i) => (line ? matchDangerousPatterns(file, line, i + 1) : []));
257258
}
258259

260+
// ---------------------------------------------------------------------------
261+
// Registry-item references in hand-maintained snapshots
262+
// ---------------------------------------------------------------------------
263+
//
264+
// A skill doc that snapshots part of the component registry rots in silence:
265+
// nothing fails when an item is renamed or dropped, and the agent that follows
266+
// the doc runs `hyperframes add <gone>` and dies. A doc opts into this check
267+
// with a marker line, after which every registry-item-shaped identifier in a
268+
// backtick span must name a real item in registry/registry.json:
269+
//
270+
// <!-- registry-items: allow=some-suffix,another-suffix -->
271+
//
272+
// Opt-in rather than repo-wide on purpose. Kebab-case backticks are also CSS
273+
// properties, `data-*` attributes, skill directory names, script names, and
274+
// motion-graphics category names, and a check that flags those is a check
275+
// people turn off. `allow=` carries the few non-item identifiers a snapshot
276+
// legitimately names (bare suffixes under a spelled-out prefix, ids the doc
277+
// itself marks as hand-authored).
278+
//
279+
// TWO KNOWN BLIND SPOTS, both deliberate, both false NEGATIVES (this check
280+
// never invents a violation, it only misses some):
281+
//
282+
// 1. Identifiers outside a backtick span are not seen. A bare `bar-chart-race`
283+
// in prose slipped past this check while it was a live defect elsewhere.
284+
// 2. Single-word item names are not seen, because the pattern below requires a
285+
// hyphen. Measured on the six currently-marked files: dropping the hyphen
286+
// requirement would monitor 3 more real items (`glitch`, `flowchart`,
287+
// `typewriter`) and force 46 new allow= entries for ordinary prose words
288+
// ("add", "line", "name", "height", "text"). A 15:1 noise ratio is how a
289+
// check gets switched off, so the hyphen requirement stays.
290+
const REGISTRY_MARKER = /<!--\s*registry-items:\s*(?:allow=([^\s]*))?\s*-->/;
291+
const REGISTRY_ITEM_ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)+$/;
292+
293+
function registryItemNames(): Set<string> {
294+
const raw = readFileSync(join(REPO_ROOT, "registry", "registry.json"), "utf-8");
295+
// The cast describes the file; it does not validate it. The runtime filter and
296+
// the throw below are what actually stop us linting against an empty set.
297+
const parsed = JSON.parse(raw) as RegistryManifest;
298+
const names = (parsed.items ?? []).map((item) => item.name).filter((name) => Boolean(name));
299+
if (names.length === 0) {
300+
throw new Error("registry/registry.json parsed to zero item names — refusing to lint blind.");
301+
}
302+
return new Set(names);
303+
}
304+
305+
/** `null` when the file is not marked as a registry snapshot; otherwise its violations. */
306+
export function lintRegistryItemRefs(content: string, known: Set<string>): LineViolation[] | null {
307+
// Marker detection ignores fenced blocks so a doc that *documents* the marker
308+
// syntax in an example does not arm the check on itself. The scan below still
309+
// reads full content, so ids inside fenced examples stay covered.
310+
const marker = stripFencedBlocks(content).match(REGISTRY_MARKER);
311+
if (!marker) return null;
312+
const allowed = new Set((marker[1] ?? "").split(",").filter(Boolean));
313+
return content.split("\n").flatMap((line, index) => {
314+
const dead = [...new Set([...line.matchAll(/`([^`\n]+)`/g)].map((m) => (m[1] ?? "").trim()))]
315+
.filter((token) => REGISTRY_ITEM_ID.test(token))
316+
.filter((token) => !known.has(token) && !allowed.has(token));
317+
return dead.map((token) =>
318+
violation(
319+
index + 1,
320+
`"${token}" is not an item in registry/registry.json, but this file is marked as a registry snapshot. Correct the name, remove it, or add it to the marker's allow= list if it is legitimately not an item.`,
321+
line.trim(),
322+
),
323+
);
324+
});
325+
}
326+
327+
function collectMarkdownFiles(dir: string): string[] {
328+
return readdirSync(dir, { withFileTypes: true, recursive: true })
329+
.filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
330+
.map((entry) => join(entry.parentPath, entry.name));
331+
}
332+
259333
function lintFile(filePath: string): Violation[] {
260334
const raw = readFileSync(filePath, "utf-8");
261335
const file = relative(process.cwd(), filePath);
@@ -281,18 +355,35 @@ if (files.length === 0) {
281355

282356
let totalViolations = 0;
283357

284-
for (const file of files) {
285-
const violations = lintFile(file);
358+
function report(file: string, violations: LineViolation[]): void {
286359
for (const v of violations) {
287-
console.error(`${v.file}:${v.line}: ${v.message}`);
360+
console.error(`${file}:${v.line}: ${v.message}`);
288361
console.error(` ${v.text}\n`);
289362
totalViolations++;
290363
}
291364
}
292365

366+
for (const file of files) {
367+
report(relative(process.cwd(), file), lintFile(file));
368+
}
369+
370+
const knownItems = registryItemNames();
371+
let snapshotsChecked = 0;
372+
for (const dir of SKILLS_DIRS) {
373+
if (!statSync(dir, { throwIfNoEntry: false })?.isDirectory()) continue;
374+
for (const path of collectMarkdownFiles(dir)) {
375+
const found = lintRegistryItemRefs(readFileSync(path, "utf-8"), knownItems);
376+
if (found === null) continue;
377+
snapshotsChecked++;
378+
report(relative(process.cwd(), path), found);
379+
}
380+
}
381+
293382
if (totalViolations > 0) {
294383
console.error(`\n${totalViolations} skill lint error(s) found.`);
295384
process.exit(1);
296385
} else {
297-
console.log(`Checked ${files.length} skill file(s) — no issues found.`);
386+
console.log(
387+
`Checked ${files.length} skill file(s) and ${snapshotsChecked} registry snapshot(s) against ${knownItems.size} registry items — no issues found.`,
388+
);
298389
}

0 commit comments

Comments
 (0)