@warpgogol/forge 0.12.1 → 0.14.0

package/profiles/editframe-html-templates/composition-agents.md

@@ -10,16 +10,45 @@ This workspace contains an Editframe video composition.
 
 ## Quality invariants
 
-- **VIDEO-01**: Composition filenames must use kebab-case (lowercase letters, digits, hyphens only). This ensures consistent naming across the project. Severity: error.
-- **VIDEO-02**: Scene durations must use `contain` fit mode by default to avoid unexpected cropping of video content. Use `cover` or `fill` only when intentionally overriding the default. Severity: warning.
-- **VIDEO-03**: All speech audio elements (`ef-audio` with speech content) must have corresponding `ef-captions` elements for accessibility. Severity: error.
+| ID | Description | Severity |
+| --- | --- | --- |
+| VIDEO-01 | Composition filenames must use kebab-case (lowercase letters, digits, hyphens only). | error |
+| VIDEO-02 | Scene durations must use `contain` fit mode by default to avoid unexpected cropping. Use `cover` or `fill` only when intentionally overriding. | warning |
+| VIDEO-03 | All speech audio elements (`ef-audio` with speech content) must have corresponding `ef-captions` elements for accessibility. | error |
+
+Additional time model invariants (VIDEO-04 through VIDEO-09) may be available. Run `forge doctor` to check the full invariant set enforced by the active profile.
+
+## Time model concepts
+
+Editframe compositions use a time model based on `ef-timegroup` elements:
+
+- **`ef-timegroup`** — a container that groups scenes and controls timing. The root timegroup defines the composition's total duration.
+- **`mode`** — timing behavior for children: `sequence` (play one after another), `fixed` (play at absolute offset), `contain` (fit within parent duration), `fit` (scale to fit).
+- **`duration`** — CSS time string (e.g. `5s`, `300ms`, `2.5s`) defining how long the element plays.
+- **`offset`** — CSS time string defining when the element starts relative to its parent.
+- **`fps`** — positive integer defining frames per second (e.g. `30`, `60`).
+- **`loop`** — boolean, only on the root timegroup. Nested timegroups should not loop.
 
 ## Workflow
 
 1. Create a `.html` file with Editframe custom elements (`ef-timegroup`, `ef-video`, `ef-audio`, `ef-text`, `ef-captions`).
 2. Run `editframe preview` to preview the composition in the browser.
-3. Run `editframe check` to validate the composition structure.
-4. Run `editframe render -o dist/<name>.mp4` to produce the final video output.
+3. Run `ef-composition-review` to review the composition for time model correctness, accessibility, and best practices.
+4. Run `editframe check` to validate the composition structure.
+5. Run `editframe render -o dist/<name>.mp4` to produce the final video output.
+6. Run `ef-render-verify` to verify the render — validation, build, determinism, output inspection.
+
+## Skills
+
+- **ef-onboard** — onboard a new project: prerequisites, discovery, scaffold, preview. Trigger: "create a new video project".
+- **ef-composition-review** — review a composition for time model correctness, accessibility, and best practices before rendering. Trigger: "review this composition".
+- **ef-render-verify** — verify a render: validate, build, check determinism, inspect output. Trigger: "render and verify".
+
+## External resources
+
+- [Editframe llms.txt](https://editframe.com/llms.txt) — machine-readable index of Editframe domain skills
+- [Editframe composition skill](https://editframe.com/skills/composition.md) — full reference for time model, elements, and rendering
+- [Editframe getting started](https://editframe.com/getting-started) — step-by-step guide and agent prompt
 
 ## Reference template
 

package/profiles/editframe-html.yaml

@@ -55,6 +55,7 @@ workspaceTypes:
       contains: ef-timegroup
       packageJsonDep: "@editframe/cli"
     skills:
+      - ef-onboard
       - ef-composition-review
       - ef-render-verify
     agentsMdTemplate: editframe-html-templates/composition-agents.md
@@ -80,6 +81,56 @@ invariants:
       kind: file-contains
       glob: "compositions/**/*.html"
       pattern: ef-captions
+  - id: VIDEO-04
+    rule: 'Root ef-timegroup must declare duration or use mode="contain" or mode="fit"'
+    severity: error
+    check:
+      kind: file-contains
+      glob: "compositions/**/*.html"
+      pattern: 'ef-timegroup[^>]*(duration|mode="contain"|mode="fit")[^>]*>'
+  - id: VIDEO-05
+    rule: All duration values must be valid CSS time strings (e.g. 5s, 500ms, 2.5s)
+    severity: error
+    check:
+      kind: html-attribute-pattern
+      glob: "compositions/**/*.html"
+      element: "ef-timegroup"
+      attribute: "duration"
+      pattern: "^\\d+(\\.\\d+)?(s|ms)$"
+  - id: VIDEO-06
+    rule: "mode attribute must be one of: sequence, fixed, contain, fit"
+    severity: error
+    check:
+      kind: html-attribute-pattern
+      glob: "compositions/**/*.html"
+      element: "ef-timegroup"
+      attribute: "mode"
+      pattern: "^(sequence|fixed|contain|fit)$"
+  - id: VIDEO-07
+    rule: fps must be a positive integer (default 30)
+    severity: warning
+    check:
+      kind: html-attribute-pattern
+      glob: "compositions/**/*.html"
+      element: "ef-timegroup"
+      attribute: "fps"
+      pattern: "^[1-9]\\d*$"
+  - id: VIDEO-08
+    rule: loop attribute should only be used on the root ef-timegroup (no effect on render for nested groups)
+    severity: warning
+    check:
+      kind: file-not-contains
+      glob: "compositions/**/*.html"
+      negatedPattern: "<ef-timegroup[^>]*loop[^>]*>[\\s\\S]*<ef-timegroup[^>]*loop"
+  - id: VIDEO-09
+    rule: offset values must be valid CSS time strings (e.g. 0.5s, 3s, 500ms)
+    severity: warning
+    check:
+      kind: html-attribute-pattern
+      glob: "compositions/**/*.html"
+      element: "ef-timegroup"
+      attribute: "offset"
+      pattern: "^\\d+(\\.\\d+)?(s|ms)$"
 workspace:
   dirs:
     - compositions

package/skills/fo/ef-composition-review/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: ef-composition-review
+description: Review an Editframe HTML composition for time model correctness, accessibility, and best practices
+invocation: user
+category: fo
+concerns: read-only
+dependsOn: []
+languagePolicy: ref(PREFERENCES.md)
+---
+
+<!-- skill-lint-disable SKILL-17 -->
+
+# ef-composition-review
+
+Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
+
+A read-only review of an Editframe HTML composition file. The skill checks time model correctness, accessibility, asset references, automated invariants, and manual best practices. It does **not** modify any file — it produces a structured report and stops.
+
+## Scope
+
+This skill reviews `.html` composition files that use Editframe custom elements (`ef-timegroup`, `ef-video`, `ef-audio`, `ef-text`, `ef-captions`). It is designed for projects using the `editframe-html` stack profile.
+
+## Process
+
+### 1. Empty state check
+
+Scan the `compositions/` directory for `.html` files. If no compositions are found, report "No compositions found — nothing to review" and stop. Do not report false positives on an empty project.
+
+### 2. Time model review
+
+For each composition file:
+
+- Check that the root `ef-timegroup` declares a `duration` attribute or uses `mode="contain"` / `mode="fit"`.
+- Check that all `duration` and `offset` values are valid CSS time strings (e.g. `5s`, `300ms`, `2.5s`).
+- Check that `mode` values are one of: `sequence`, `fixed`, `contain`, `fit`.
+- Check that `fps` is a positive integer (e.g. `30`, `60`).
+- Check that `loop` is only present on the root `ef-timegroup` — nested timegroups should not loop.
+
+### 3. Accessibility review
+
+- Check that all `ef-audio` elements with speech content have corresponding `ef-captions` elements.
+- Check that `ef-text` elements have sufficient contrast between foreground and background colors (if declared via inline styles or CSS classes).
+
+### 4. Asset reference review
+
+- Check that all `src` attributes in `ef-video`, `ef-audio`, and `ef-image` elements point to files that exist in the `assets/` directory.
+- Check that asset filenames use kebab-case (lowercase letters, digits, hyphens only).
+
+### 5. Invariant check
+
+Run `forge doctor` to check all profile invariants automatically. For the `editframe-html` profile, this covers VIDEO-01 through VIDEO-09 (filename conventions, scene fit modes, captions, and time model invariants). Review the output and include any violations in the report.
+
+### 6. Manual best practices
+
+Review aspects not covered by automated invariants:
+
+- Scene composition quality — are scenes well-structured with clear transitions?
+- Narrative pacing — does the timing flow naturally?
+- Visual hierarchy — are text elements readable and well-positioned?
+- Asset reuse — are assets reused efficiently across scenes?
+
+Do not duplicate checks that `forge doctor` already performs.
+
+### 7. Report
+
+Summarize findings organized by category (time model, accessibility, assets, invariants, best practices). For each finding, include the file path, line number (if applicable), severity (error / warning / info), and a specific recommendation.

package/skills/fo/ef-onboard/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: ef-onboard
+description: Onboard a new Editframe video project — check prerequisites, discover requirements, scaffold, and start preview. Use when the operator asks to create a new video project.
+invocation: user
+category: fo
+concerns: content-mutation
+dependsOn: []
+languagePolicy: ref(PREFERENCES.md)
+triggers:
+  - "create a new editframe project"
+  - "start a new video project"
+  - "build a video with editframe"
+  - "create a video composition"
+---
+
+<!-- skill-lint-disable SKILL-17 -->
+
+# ef-onboard
+
+Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
+
+Guide the operator through creating a new Editframe video project within a Forge-managed workspace. The skill covers prerequisites check, discovery, scaffold, Editframe domain skills installation, domain knowledge reading, and build + preview.
+
+## Process
+
+### 1. Prerequisites check
+
+- **Node.js 18+**: Run `node --version`. If missing or below 18, direct the operator to `https://nodejs.org/en/download/` or install via the system package manager.
+- **FFmpeg**: Run `ffmpeg -version`. If missing, direct the operator to `https://ffmpeg.org/download.html` or install via the system package manager (`apt install ffmpeg`, `brew install ffmpeg`).
+- If either prerequisite is missing and cannot be installed automatically, stop and ask the operator to install it manually.
+
+### 2. Discovery
+
+Ask the operator:
+
+1. **Project type**:
+   - Single video (product demo, social media video, personal project)
+   - Video template (reusable with different assets — birthday card, wedding announcement)
+   - Video editing tool (custom editor built with Editframe as the engine)
+   - Video workflow automation (script that generates videos from triggers)
+   - Something else (ask them to describe it)
+
+2. **Existing assets**:
+   - Video clips, images, or audio files (file paths or URLs)
+   - Website URLs to use as content source — if provided, download and cache all relevant assets locally before building
+   - No existing assets — start from scratch
+
+3. **Stack preference**:
+   - Vanilla HTML/CSS/JS (simpler, no build step beyond Vite)
+   - React + TypeScript (component-based, type-safe)
+   - No preference — recommend HTML for single videos, React for templates and editors
+
+4. **Node.js/React libraries**: Ask if the operator has any libraries in mind (e.g. AnimeJS for animations, Tailwind for styling).
+
+Prioritize getting all answers before starting to build. This minimizes wait time for the operator.
+
+### 3. Scaffold
+
+Run `forge create --profile editframe-html` to scaffold the project with Forge governance (invariants, AGENTS.md templates, forge skills).
+
+The `editframe-html` profile currently targets HTML compositions only — it does not support a `--template react` flag. If the operator chose React, scaffold with `forge create --profile editframe-html`, then instruct the agent to install `@editframe/react` manually (`pnpm add @editframe/react`) after scaffold.
+
+If `forge create` fails (missing profile, network error, permission issue), report the error to the operator and stop. Do not proceed to subsequent steps without a scaffolded project.
+
+### 4. Install Editframe domain skills
+
+Editframe publishes domain skills via `npm create @editframe`. To make them available alongside forge skills:
+
+1. Run `npm create @editframe@latest` in the project directory. This installs Editframe's domain skills to `.agents/skills/editframe-*/`.
+2. Report which skills were installed.
+3. If the command fails (network issues, npm errors, unsupported flags), fall back to referencing the online documentation: direct the agent to read `https://editframe.com/llms.txt` and `https://editframe.com/skills/composition.md` before building. Do not use unverified CLI flags — if `npm create @editframe` prompts interactively, answer the prompts based on the operator's discovery answers from Step 2.
+
+### 5. Read domain knowledge
+
+Before building, the agent MUST read the `editframe-composition` skill (either from `.agents/skills/editframe-composition/SKILL.md` if installed, or from `https://editframe.com/skills/composition.md`). This provides domain knowledge about:
+
+- Time model (`ef-timegroup`, modes, duration, offset)
+- Media elements (`ef-video`, `ef-audio`, `ef-image`, `ef-text`, `ef-captions`)
+- CSS animations and transitions
+- Rendering pipeline
+
+The agent should also read `editframe-dev-server` if the project uses the dev server.
+
+### 6. Build and preview
+
+1. Build the initial composition based on the operator's answers from Step 2. Use the discovery answers (project type, assets, stack preference, libraries) to determine composition structure, asset placement, and optional dependencies.
+2. Run `forge dev` to start the preview server (delegates to `editframe preview` per the `editframe-html` profile's `devServer.command`).
+3. Report the localhost URL to the operator.
+4. Run `forge doctor` to check all profile invariants on the initial composition. For the `editframe-html` profile, this covers VIDEO-01 through VIDEO-09.
+5. Report any invariant violations and suggest fixes.

package/skills/fo/ef-render-verify/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: ef-render-verify
+description: Verify an Editframe render — validate, build, check determinism, inspect output
+invocation: user
+category: fo
+concerns: read-only
+dependsOn: []
+languagePolicy: ref(PREFERENCES.md)
+---
+
+<!-- skill-lint-disable SKILL-17 -->
+
+# ef-render-verify
+
+Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
+
+A read-only verification of an Editframe render pipeline. The skill runs validation, build, determinism check, and output inspection, then reports pass/fail for each step. It does **not** modify any file.
+
+## Scope
+
+This skill verifies render output for `.html` composition files using the `editframe-html` stack profile. It uses `forge validate`, `forge build`, and `forge determinism check` — all profile-driven commands.
+
+## Process
+
+### 1. Pre-render validation
+
+Run `forge validate` to check the composition with the profile's validate command (typically `editframe check`). Review the output for any validation errors. If validation fails, report the errors and stop — do not proceed to render.
+
+### 2. Render
+
+Run `forge build` to produce the MP4 output. Review the output for any build errors. If the build fails, report the errors and stop.
+
+### 3. Determinism check
+
+Run `forge determinism check` to verify the render is reproducible — two builds produce identical output. Review the output hash comparison. If the hashes differ, report the mismatch and stop.
+
+### 4. Output inspection
+
+Check the render output:
+
+- Verify the output MP4 file exists at the expected path (`dist/{composition}.mp4`).
+- Check that the file size is non-zero.
+- Check that the duration matches the root `ef-timegroup`'s `duration` attribute (if ffprobe or equivalent is available).
+
+### 5. Report
+
+Summarize the verification results — pass/fail for each step:
+
+| Step              | Status      | Details                                |
+| ----------------- | ----------- | -------------------------------------- |
+| Validation        | pass / fail | <error details or "all checks passed"> |
+| Build             | pass / fail | <error details or "build completed">   |
+| Determinism       | pass / fail | <hash comparison result>               |
+| Output inspection | pass / fail | <file exists, size, duration check>    |
+
+If all steps pass, the render is verified. If any step fails, provide specific recommendations for fixing the issue.