Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

feat: guide automatic local component development

rponeb932e45ab622
diff --git a/.agents/skills/hypit/SKILL.md b/.agents/skills/hypit/SKILL.md
index a76ed46e..81b6b483 100644
--- a/.agents/skills/hypit/SKILL.md
+++ b/.agents/skills/hypit/SKILL.md
@@ -40,9 +40,14 @@ tool-driven task rather than an ordinary hand-authored video task.
where evidence conflicts or remains uncertain.
5. Choose the packages needed by the observed video and run `inspect_svml_vocabulary` before
writing any component, attribute, child, port, or Recipe.
-6. Write one complete `main.svml`, one `studio.svs`, and one `build.svrun`. Do not write one partial
+6. Decide whether existing packages can express every observed behavior. Prefer composing existing
+ packages when their declared Types, time behavior and outputs are sufficient. If no legal
+ composition can express an observation, follow "Develop a missing local component" below before
+ writing a tag for it.
+7. Write one complete `main.svml`, one `studio.svs`, and one `build.svrun`. Do not write one partial
SVML fragment per shot and concatenate them.
-7. Run the existing `pnpm hypit check` command and repair the sources until the project is legal.
+8. Run the existing `pnpm hypit check` command and repair the package or sources until the project
+ is legal.
Gemini is only the eyes and ears. It returns natural-language evidence, never SVML, SVS, SVRun,
component declarations, prompts containing package syntax, or a final structural decision. The
@@ -63,6 +68,59 @@ The reconstruction invariants are mandatory:
- Reuse the full-reference people, voice, and product evidence. Describe a promoted product once;
do not invent a new product description in every shot.
+## Develop a missing local component
+
+This branch is part of reference reconstruction, but it is ordinary Hypit package development, not
+a VLM capability. `reference-video-tools` must remain limited to preparation, observation and
+vocabulary inspection. Do not add a component generator command to it.
+
+Enter this branch only after comparing the observation against the selected packages' README and
+the complete `inspect_svml_vocabulary` result. Prefer a composition of existing components. Do not
+force a similar-looking tag to express behavior its declaration does not own, and do not write an
+unknown tag into `main.svml` before its package exists.
+
+Before creating the package, read these sources completely:
+
+1. `docs/guide/author-packages.md`
+2. `docs/guide/packages.md`
+3. `docs/guide/conventions.md`
+4. `packages/component-kit/README.md`
+5. The README, Manifest, Surface, Component and activation files of the closest existing package
+
+Create one new package under the current project's `packages/local-<slug>/`. The physical and
+logical name is `@hypit/local-<slug>`, the physical version is `0.0.0-dev`, and Module identities
+use logical version `1`. The package is project-local even when the current project is the Hypit
+checkout. Never edit, delete, extend or overwrite an existing package to fill this gap, and never
+ask for permission merely to create this new local package once the gap is established.
+
+The main agent, not Gemini, writes the package. Gemini must not receive or produce TypeScript,
+`package.json`, Manifest, Surface, Producer, Validator, package syntax or implementation code. Use
+its natural-language observation only as evidence for the component's required behavior.
+
+Implement the complete package rather than a syntax stub. Include the package manifest and README,
+Module Manifest and Types, every required Producer and Validator, Markup Surface declaration and
+decoder, activation contribution, and the necessary lowering, Fragment or render implementation.
+Add a preview for a visual Surface. Decide raw versus structured Surface, timing dependencies,
+ProgramSpace, Frame, SemanticMap, Artifact, Recipe and output Types from the observed behavior and
+the closest package architecture; do not copy a fixed template blindly.
+
+Connect the new package through normal Node package resolution:
+
+- Reuse the current project's workspace configuration when it already includes `packages/*`.
+- Otherwise add the smallest `pnpm-workspace.yaml` and package dependency changes that include the
+ new package.
+- Add the local package as a `workspace:*` dependency where the project's package root can resolve
+ it, then run the necessary `pnpm install`.
+- Run `pnpm check`, followed by the existing `pnpm hypit check` for `main.svml`, `studio.svs` and
+ `build.svrun`. Use `--workspace` or `--package-root` only when the project layout requires them.
+- Repair package resolution first, then activation, Manifest/implementation agreement, Surface
+ decoding, Producer/Validator behavior, and finally the three project sources.
+
+The package is complete only after the existing checks accept it. Never create a check wrapper.
+After the reconstruction is accepted, tell the user that the local package can be moved into the
+official Hypit repository as a separate contribution if they want to keep it generally available;
+do not perform that promotion automatically.
+
## Read the package README before writing its syntax
Before writing any element from a package, read that package's README. The import
diff --git a/.agents/skills/hypit/agents/openai.yaml b/.agents/skills/hypit/agents/openai.yaml
index 19c7d695..ed4218a8 100644
--- a/.agents/skills/hypit/agents/openai.yaml
+++ b/.agents/skills/hypit/agents/openai.yaml
@@ -1,4 +1,4 @@
interface:
display_name: "Hypit"
short_description: "Build SVML videos and reconstruct reference videos with CLI tools"
- default_prompt: "Use $hypit to author, validate, or refine native SVML video sources; for reference-video reconstruction, run prepare_reference, observe_reference, and inspect_svml_vocabulary before writing complete SVML, SVS, and SVRun sources."
+ default_prompt: "Use $hypit to author, validate, or refine native SVML video sources; for reference-video reconstruction, run prepare_reference, observe_reference, and inspect_svml_vocabulary before writing complete SVML, SVS, and SVRun sources. If current vocabulary cannot express an observation, read the Hypit author-package guides and implement a complete project-local @hypit/local-* package without modifying existing packages."
diff --git a/.agents/skills/hypit/references/reference-vlm.md b/.agents/skills/hypit/references/reference-vlm.md
index f9b87212..7f39f612 100644
--- a/.agents/skills/hypit/references/reference-vlm.md
+++ b/.agents/skills/hypit/references/reference-vlm.md
@@ -23,6 +23,7 @@ run prepare_reference
→ run observe_reference for all shots
→ run observe_reference with one narrow follow-up for each unresolved conflict
→ run inspect_svml_vocabulary for the packages actually needed
+→ if vocabulary is insufficient, develop and install one complete project-local package
→ main agent writes complete main.svml, studio.svs, build.svrun
→ pnpm hypit check
→ repair source syntax and run pnpm hypit check again
@@ -49,3 +50,49 @@ After observations, read the selected package README as syntax authority as well
vocabulary returned by the `inspect_svml_vocabulary` CLI. Author one complete dependency graph, not separate
per-shot source fragments. Use only declared tags, attributes, children, ports, Recipe properties,
and admitted values. Use the existing `pnpm hypit check`; do not add or invent a check wrapper.
+
+## When the vocabulary has a real gap
+
+First try to express the observation by composing existing packages. A tag that looks similar is
+not sufficient: its declared inputs, outputs, timing behavior and visual result must actually cover
+the observation. Never write a nonexistent tag and plan to implement it later.
+
+If no existing legal composition can express the result, stop authoring the three source files and
+develop a project-local author package. This is main-agent software development; it is not a fourth
+reference-video command and it is not work for Gemini.
+
+Read all of the following before editing:
+
+- `docs/guide/author-packages.md`
+- `docs/guide/packages.md`
+- `docs/guide/conventions.md`
+- `packages/component-kit/README.md`
+- The closest existing package's README, `manifest.ts`, `surface.ts`, `component.ts`, and
+ `activation.ts`
+
+Create only a new `packages/local-<slug>/` package named `@hypit/local-<slug>`. Do not change an
+existing Hypit package. The new package must have a complete Module Manifest, Types, Producers and
+Validators as required, Markup Surface declaration and decoder, activation descriptor, README,
+visual preview when applicable, and the implementation that produces its declared result. A Surface
+or vocabulary declaration without executable implementation is not a component.
+
+Connect the package to the current project's existing pnpm workspace and package root through an
+ordinary `workspace:*` dependency and `pnpm install`. Do not hide it under `.hypit/`, modify the
+package loader, or add a private registry. Then run:
+
+```bash
+pnpm check
+pnpm hypit check main.svml
+pnpm hypit check studio.svs
+pnpm hypit check build.svrun
+```
+
+Use the appropriate source paths and existing `--workspace` or `--package-root` options when the
+project layout needs them. Fix resolution, activation and package implementation errors before
+repairing source usage. Only continue the reconstruction when all existing checks accept the new
+package and final sources.
+
+Gemini must not write the local package or see its TypeScript and package syntax. The observed video
+is evidence for the behavior; the main agent owns all package architecture and code. If the user
+later approves the result, offer to promote the project-local package into the official Hypit
+repository as a separate contribution, but never move it automatically.