npm - @event4u/agent-config - Versions diffs - 2.23.0 → 2.25.0 - Mend

@event4u/agent-config 2.23.0 → 2.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (82) hide show

package/.agent-src/commands/create-pr/description-only.md +39 -11
package/.agent-src/commands/create-pr.md +59 -5
package/.agent-src/commands/video/from-script.md +123 -0
package/.agent-src/commands/video/scene.md +92 -0
package/.agent-src/commands/video/stitch.md +83 -0
package/.agent-src/commands/video/storyboard.md +95 -0
package/.agent-src/commands/video.md +59 -0
package/.agent-src/contexts/execution/roadmap-process-loop.md +69 -14
package/.agent-src/personas/README.md +5 -1
package/.agent-src/personas/ai-video-technical-director.md +81 -0
package/.agent-src/personas/hollywood-director.md +99 -0
package/.agent-src/profiles/content_creator.yml +5 -0
package/.agent-src/rules/media-governance-routing.md +82 -0
package/.agent-src/rules/persona-governance.md +90 -0
package/.agent-src/rules/post-push-rewrite-discipline.md +70 -0
package/.agent-src/rules/provider-lifecycle-discipline.md +75 -0
package/.agent-src/rules/roadmap-ci-steps-policy.md +145 -0
package/.agent-src/rules/roadmap-progress-sync.md +11 -5
package/.agent-src/skills/character-consistency/SKILL.md +131 -0
package/.agent-src/skills/git-workflow/SKILL.md +133 -0
package/.agent-src/skills/motion-choreographer/SKILL.md +161 -0
package/.agent-src/skills/pixar-storyteller/SKILL.md +120 -0
package/.agent-src/skills/roadmap-writing/SKILL.md +10 -0
package/.agent-src/skills/scene-expander/SKILL.md +137 -0
package/.agent-src/skills/scene-expander/scene-blueprint.schema.yaml +108 -0
package/.agent-src/skills/subagent-orchestration/SKILL.md +17 -15
package/.agent-src/skills/video-director/SKILL.md +126 -0
package/.agent-src/templates/agent-settings.md +19 -0
package/.agent-src/templates/agents/agent-project-settings.example.yml +1 -1
package/.agent-src/templates/roadmaps.md +16 -0
package/.claude-plugin/marketplace.json +11 -1
package/CHANGELOG.md +65 -0
package/README.md +7 -5
package/config/agent-settings.template.yml +54 -0
package/docs/adrs/caveman/0001-default-off-until-bench.md +2 -2
package/docs/adrs/cost/0001-hard-stop-hook.md +1 -1
package/docs/adrs/smoke/0001-per-tier-smoke-scripts.md +2 -2
package/docs/architecture.md +3 -3
package/docs/catalog.md +18 -5
package/docs/contracts/command-clusters.md +1 -0
package/docs/contracts/compression-default-kill-criterion.md +1 -1
package/docs/contracts/file-ownership-matrix.json +405 -0
package/docs/contracts/provider-lifecycle.md +122 -0
package/docs/decisions/ADR-011-domain-pack-readiness.md +213 -0
package/docs/decisions/INDEX.md +1 -0
package/docs/getting-started-by-role.md +10 -0
package/docs/getting-started.md +2 -2
package/docs/parity/ruflo.md +3 -3
package/docs/personas.md +73 -26
package/docs/profiles.md +9 -4
package/package.json +1 -1
package/scripts/_tmp_scan_framework_leakage.py +119 -0
package/scripts/ai-video/adapters/gemini-veo.sh +62 -0
package/scripts/ai-video/adapters/higgsfield.sh +88 -0
package/scripts/ai-video/adapters/kling.sh +59 -0
package/scripts/ai-video/adapters/openai-images.sh +57 -0
package/scripts/ai-video/adapters/sora.sh +60 -0
package/scripts/ai-video/lib/adapter-common.sh +116 -0
package/scripts/ai-video/lib/adapter-contract.md +163 -0
package/scripts/ai-video/lib/fixtures/gemini-veo/result.json +1 -0
package/scripts/ai-video/lib/fixtures/gemini-veo/scene-0001.mp4 +1 -0
package/scripts/ai-video/lib/fixtures/higgsfield/result.json +1 -0
package/scripts/ai-video/lib/fixtures/higgsfield/scene-0001.mp4 +1 -0
package/scripts/ai-video/lib/fixtures/kling/result.json +1 -0
package/scripts/ai-video/lib/fixtures/kling/scene-0001.mp4 +1 -0
package/scripts/ai-video/lib/fixtures/openai-images/result.json +1 -0
package/scripts/ai-video/lib/fixtures/openai-images/scene-0001.png +3 -0
package/scripts/ai-video/lib/fixtures/sora/result.json +1 -0
package/scripts/ai-video/lib/fixtures/sora/scene-0001.mp4 +1 -0
package/scripts/ai-video/lib/load-config.sh +140 -0
package/scripts/ai-video/lib/operator-pick.sh +119 -0
package/scripts/ai-video/lib/parse-blueprint.sh +122 -0
package/scripts/ai-video/lib/redact.sh +85 -0
package/scripts/ai-video/lib/validate-deps.sh +132 -0
package/scripts/ai-video/stitch.sh +154 -0
package/scripts/ai-video/test-pipeline.sh +169 -0
package/scripts/check_portability.py +6 -0
package/scripts/lint_media_policy_linkage.py +140 -0
package/scripts/lint_persona_governance.py +164 -0
package/scripts/lint_roadmap_ci_steps.py +182 -0
package/scripts/schemas/command.schema.json +8 -0
package/scripts/smoke/schema.sh +1 -1

package/.agent-src/commands/create-pr/description-only.md CHANGED Viewed

@@ -39,17 +39,45 @@ The user may or may not provide a PR URL or branch name.
    - If no PR found → use `git diff origin/{default}..HEAD --stat` for the branch diff.
 3. **Never** reuse a PR number from earlier in the conversation.
-### 2. Gather context
-- **Jira ticket**: Extract ticket ID from branch name (e.g. `fix/DEV-4673-description` → `DEV-4673`).
-  - If found → fetch via Jira API (`GET /issue/{ticketId}`).
-  - If not found → ask the user for a ticket number. Proceed without if none.
-- **Diff summary**: `git diff origin/{default}..HEAD --stat` for changed files.
-- **Commit messages**: `git log origin/{default}..HEAD --format="%s"` for what was done.
-- **PR template**: **MUST** read `.github/pull_request_template.md`. This is mandatory, not optional.
-- **Read key changed files** to understand what was done — look for migrations, new classes,
-  modified services, route changes, config changes.
-- **Check roadmap/agent docs** that describe the feature intent (if they exist).
+### 2. Gather context — **one parallel tool-call block**
+The four primary fetches below are **independent** and **must** be
+dispatched in a single parallel tool-call block, not serially. Serial
+reads here add 3+ round-trips per PR for zero benefit.
+```
+parallel:
+  1. Jira API           — GET /issue/{ticketId}   (skip when no ticket ID)
+  2. git diff           — git diff origin/{default}..HEAD --stat
+  3. git log            — git log origin/{default}..HEAD --format="%s"
+  4. view PR template   — .github/pull_request_template.md
+```
+After the block returns:
+- **Jira ticket**: ticket ID is extracted from the branch name
+  (e.g. `fix/DEV-4673-description` → `DEV-4673`) **before** the
+  parallel block. No ticket → skip fetch 1 silently; ask the user
+  for a number only after the block, and only if needed.
+- **PR template missing** → fall back to the structure in § 4.
+- **Read key changed files** (migrations, new classes, modified
+  services, route/config changes) — second parallel block, keyed
+  off the diff summary. Group all file reads in one block.
+- **Check roadmap/agent docs** that describe the feature intent
+  (if they exist) — fold into the second block.
+Anti-pattern (do **not** do this):
+```
+turn 1: fetch Jira
+turn 2: git diff
+turn 3: git log
+turn 4: view template
+turn 5: view file A
+turn 6: view file B
+```
+That's 6 round-trips for what should be 2.
 ### 3. Build the PR title

package/.agent-src/commands/create-pr.md CHANGED Viewed

@@ -94,6 +94,44 @@ Resolve `"draft"` (first match wins):
 3. `routine_confirmations: true` → ask `1. draft / 2. ready`.
 4. Default → `true` (silent draft).
+#### 3a. Tool selection — single-call mandate
+```
+POST THE PR WITH ONE github-api CALL.
+NEVER COMPOSE THE BODY THROUGH SHELL, PYTHON, OR TEMP FILES.
+```
+Use the `github-api` tool **directly** with the markdown body in the
+JSON `data` field. The body is a regular JSON string — escaping is the
+tool's job, not yours.
+```
+github-api
+  method: POST
+  path:   /repos/{owner}/{repo}/pulls
+  data:   { "title": "...", "body": "<markdown>", "head": "<branch>",
+            "base": "main", "draft": <bool> }
+```
+**Hard prohibitions** (each one cost 3+ extra tool calls in past runs):
+- ❌ `python3 -c "import urllib..."` / `python3 - <<PY ... PY` heredocs
+  to serialize the body or POST it.
+- ❌ `save-file PR_BODY.md` → read back → `curl -d @PR_BODY.md`.
+- ❌ `gh pr create --body-file …` shelling out when `github-api` is
+  available in this surface.
+- ❌ Splitting `title` and `body` into two API calls (create + PATCH).
+The body may contain any Markdown — code fences, tables, multi-line
+HTML, emoji. Do **not** preprocess, escape, or strip newlines before
+handing it to `github-api`.
+If the surface genuinely lacks `github-api` (rare), fall back to
+`gh pr create --title "..." --body-file <(echo -n "<body>")` as a
+**single** shell call, never the python-urllib path.
+#### 3b. Submit
 Create the PR with the approved title/body and the resolved `draft`.
 **Verify after `draft: false`** — the GitHub REST API sometimes ignores
@@ -126,18 +164,21 @@ Run this strip-pass **after PR creation and after every body PATCH**:
    - `Pull Request opened by [Augment Code]`
    - `Co-authored by Augment Code`
    - Any `augmentcode.com` link the user did not ask for
-3. If any pattern is present, remove it together with surrounding
+3. **No match → done.** Skip steps 4–5; the body is already clean.
+   This is the common path and **must not** spend a verify-GET.
+4. Match found → remove the footer(s) together with surrounding
    `---` separators and trailing whitespace, then:
    ```
    PATCH /repos/{owner}/{repo}/pulls/{number}
    { "body": "<cleaned body>" }
    ```
-4. Re-fetch the body once more to verify the strip stuck. If a
-   pattern reappears (server re-injection), repeat steps 2–4 once;
+   Re-fetch the body **once** to verify the strip stuck. If a
+   pattern reappears (server re-injection), repeat the PATCH once;
    if it still reappears, surface the issue to the user and stop
    (do not enter a strip/PATCH loop).
-5. Briefly note in the reply how many footers were removed (or
-   "no footers found" if clean).
+5. Briefly note in the reply how many footers were removed (omit
+   the line entirely when nothing was stripped — silence is the
+   expected path, not "no footers found").
 #### 4b. Show the PR URL (verbosity-gated)
@@ -154,6 +195,19 @@ Linked ticket + `routine_confirmations: true` → ask `1. Yes / 2. No`.
 Default (`false`) → skip silently. **Only emit a transition line when
 an actual Jira API call succeeded** — never announce "skipped".
+#### 4d. Settings short-circuit — single read per run
+`verbosity.routine_confirmations`, `verbosity.post_action_reports`, and
+`commands.create_pr.preview_description` are read **once** at the top
+of the run and cached for the whole `/create-pr` invocation. Do **not**
+re-read `.agent-settings.yml` in 4b / 4c — both branches resolve from
+the cached values from step 1.
+When all three resolve to their silent defaults (`false` / `minimal` /
+`false`), steps 4b–4c collapse to the single `→ #N opened: <url>` line
+from 4b and a silent 4c. No extra file reads, no "checking settings…"
+narration, no confirmation prompts.
 ### Rules
 - **Always use the PR template** from `.github/pull_request_template.md`.

package/.agent-src/commands/video/from-script.md ADDED Viewed

@@ -0,0 +1,123 @@
+---
+name: video:from-script
+tier: 2
+cluster: video
+sub: from-script
+description: Drive a script end-to-end through the AI video pipeline — scenes → blueprint → image → operator pick → motion → video → stitch. Dry-run default; network calls require explicit per-turn confirmation.
+disable-model-invocation: true
+personas: [hollywood-director, ai-video-technical-director]
+skills: [scene-expander, video-director, pixar-storyteller, character-consistency, motion-choreographer]
+suggestion:
+  eligible: true
+  trigger_description: "render a video from a script, full AI video pipeline, multi-scene generation"
+  trigger_context: "user supplies a Markdown script with `## Scene N` headings and wants a final MP4"
+---
+# /video:from-script
+`/video:from-script <path-to-script.md> [--image-provider <id>] [--video-provider <id>]`
+Drives a Markdown script through the full pipeline. Provider flags
+override the `<default-image-provider>` / `<default-video-provider>`
+from [`agents/.ai-video.xml`](../../../agents/.ai-video.xml.example);
+absent flags fall back to the XML defaults.
+**Block-on-ambiguity:** a missing scene heading, an unparseable
+character-lock block, or a contradictory provider flag halts the run
+with a precise diff — no silent best-guess.
+## Steps
+### 1. Validate dependencies
+```bash
+scripts/ai-video/lib/validate-deps.sh .agent-src.uncompressed/commands/video/from-script.md
+```
+Fails fast with the missing-id list if any declared persona / skill is
+absent from `.agent-src/personas/` or `.agent-src/skills/`. No network
+call has happened yet.
+### 2. Load config + resolve providers
+Source `scripts/ai-video/lib/load-config.sh`. Resolve image / video
+provider in this order: command flag → `agents/.ai-video.xml` default
+→ fail with the available-providers list.
+### 3. Parse the script
+Run the `scene-expander` skill: split on `## Scene N` headings, extract
+dialogue / action / ambient blocks, and emit one `scene-blueprint.yaml`
+per scene under `<project>/scenes/<id>/`. Schema:
+[`scene-blueprint.schema.yaml`](../../skills/scene-expander/scene-blueprint.schema.yaml).
+### 4. Character lock
+Run `character-consistency` once for the whole project. Writes
+`<project>/character.json` (subject, palette, wardrobe, prop, seed)
+that every later prompt must reuse verbatim.
+### 5. Per-scene image render
+For each scene blueprint:
+1. Compose the eight-block image prompt via `video-director`
+   (style · subject · environment · action · camera · lens · lighting · mood).
+2. **Safety gate (Phase 5 Step 6).** If `AIV_DRYRUN=false`, print the
+   adapter, model, scene count, and estimated cost; refuse to continue
+   without an explicit operator confirmation **in this turn**. Mirrors
+   [`non-destructive-by-default`](../../rules/non-destructive-by-default.md).
+3. Call the image adapter (`run` subcommand) N times where N =
+   `<tuning/best-of-n>` (default 1).
+### 6. Operator pick (best-of-N checkpoint)
+```bash
+scripts/ai-video/lib/operator-pick.sh <project> <scene-id>
+```
+Renders the candidate contact-sheet PNG, pauses, and waits for the
+operator to write `<project>/scenes/<id>/selection.json`. In dry-run
+mode the helper auto-selects the first candidate so the smoke test
+stays unattended.
+### 7. Motion + video render
+Pass the locked image into `motion-choreographer` (per-provider profile)
+→ build the motion prompt → call the video adapter (`submit` / `poll` /
+`fetch`). Same safety gate as Step 5 fires before each live call.
+### 8. Stitch
+Build `<project>/manifest.json` (ordered `{scene_id, clip_path,
+audio_embedded, audio_path?, duration}`) and run:
+```bash
+scripts/ai-video/stitch.sh <project>/manifest.json <project>/final.mp4
+```
+Fail loud on missing clips; offer `--skip-scene <id>` or `--continue`
+per the stitcher contract.
+### 9. Report
+Print: project slug, final MP4 path, scenes rendered, scenes skipped,
+estimated cost (live mode) or `dry-run` marker. No commit. No push.
+## Rules
+- **No commit, no push, no PR.** Pipeline produces artefacts; the
+  operator chooses what to ship.
+- **Dry-run is the default.** Every live network call needs explicit
+  per-turn confirmation.
+- **Block on ambiguity** — never silently best-guess scene splits or
+  provider mismatches.
+- **One project per invocation.** Re-running on the same project
+  resumes from existing artefacts (skips completed scenes).
+## See also
+- [`/video:scene`](scene.md) — single-scene iteration
+- [`/video:storyboard`](storyboard.md) — image-only contact sheet
+- [`/video:stitch`](stitch.md) — re-stitch after operator edits
+- [`scripts/ai-video/lib/adapter-contract.md`](../../../scripts/ai-video/lib/adapter-contract.md)

package/.agent-src/commands/video/scene.md ADDED Viewed

@@ -0,0 +1,92 @@
+---
+name: video:scene
+tier: 2
+cluster: video
+sub: scene
+description: Render a single scene from a one-line idea — scene-expander → blueprint → image → operator pick → motion → video. Dry-run default; live calls require explicit per-turn confirmation.
+disable-model-invocation: true
+personas: [hollywood-director, ai-video-technical-director]
+skills: [scene-expander, video-director, character-consistency, motion-choreographer]
+suggestion:
+  eligible: true
+  trigger_description: "render a single video scene, iterate on one shot, test a prompt without a full script"
+  trigger_context: "user supplies a one-line scene idea and wants a single clip, no multi-scene stitching"
+---
+# /video:scene
+`/video:scene "<idea>" [--image-provider <id>] [--video-provider <id>] [--project <slug>]`
+Single-scene generation for iteration. Same pipeline as
+[`/video:from-script`](from-script.md) but skips the script parser and
+the stitch step — produces one clip under
+`<project>/scenes/<auto-id>/`.
+**Block-on-ambiguity:** an idea string under 12 characters, a
+contradictory provider flag, or a missing project slug on resume halts
+the run with a precise diff.
+## Steps
+### 1. Validate dependencies
+```bash
+scripts/ai-video/lib/validate-deps.sh .agent-src.uncompressed/commands/video/scene.md
+```
+### 2. Load config + resolve providers
+Source `scripts/ai-video/lib/load-config.sh`. Resolve image / video
+provider: flag → `agents/.ai-video.xml` default → fail with the
+available-providers list.
+### 3. Expand the idea
+Run `scene-expander` on the single idea string. Emit one
+`scene-blueprint.yaml` under `<project>/scenes/<id>/`. Project slug
+defaults to `scene-$(date +%Y%m%d-%H%M%S)` when `--project` is absent.
+### 4. Character lock (if `<project>/character.json` absent)
+First run on a fresh project → `character-consistency` builds
+`character.json`. Re-runs reuse the locked descriptor verbatim.
+### 5. Image render + operator pick
+Compose the eight-block image prompt via `video-director`. Safety gate
+fires before any live call (`AIV_DRYRUN=false` requires explicit
+per-turn confirmation). Render `<tuning/best-of-n>` candidates, then:
+```bash
+scripts/ai-video/lib/operator-pick.sh <project> <scene-id>
+```
+Dry-run auto-selects candidate 1.
+### 6. Motion + video render
+`motion-choreographer` builds the motion prompt for the resolved video
+provider; safety gate fires again; adapter `submit` / `poll` / `fetch`
+runs the call.
+### 7. Report
+Print: project slug, scene id, clip path, audio status
+(`embedded` / `muxed` / `none`), live cost or `dry-run` marker. No
+stitch step; no commit; no push.
+## Rules
+- **No commit, no push, no PR.**
+- **Dry-run is the default.** Live calls need explicit per-turn
+  confirmation.
+- **Block on ambiguity** — refuse to invent a project slug, scene id,
+  or character descriptor on resume.
+- **Single scene per invocation.** For multi-scene work use
+  [`/video:from-script`](from-script.md).
+## See also
+- [`/video:from-script`](from-script.md) — multi-scene pipeline
+- [`/video:storyboard`](storyboard.md) — image-only sheet
+- [`/video:stitch`](stitch.md) — combine existing clips

package/.agent-src/commands/video/stitch.md ADDED Viewed

@@ -0,0 +1,83 @@
+---
+name: video:stitch
+tier: 2
+cluster: video
+sub: stitch
+description: Re-stitch existing clips in `<project>/scenes/*/` after operator edits — no re-render. ffmpeg concat driven by manifest.json.
+disable-model-invocation: true
+personas: [ai-video-technical-director]
+skills: []
+suggestion:
+  eligible: true
+  trigger_description: "re-stitch existing video clips, rebuild final MP4 after edits, ffmpeg concat existing scenes"
+  trigger_context: "user has edited clips in `<project>/scenes/*/` and wants the final.mp4 rebuilt without paying for re-renders"
+---
+# /video:stitch
+`/video:stitch <project-slug> [--skip-scene <id>]... [--continue]`
+Re-stitches existing clips after operator edits. **No adapter calls.**
+Reads `<project>/manifest.json`, runs `scripts/ai-video/stitch.sh`,
+writes `<project>/final.mp4`.
+**Block-on-ambiguity:** a missing project slug, a missing
+`manifest.json`, or a clip path that no longer resolves halts the run
+with a precise diff — the operator must say `--skip-scene <id>` or
+`--continue` explicitly.
+## Steps
+### 1. Validate dependencies
+```bash
+scripts/ai-video/lib/validate-deps.sh .agent-src.uncompressed/commands/video/stitch.md
+```
+(Lightweight here — only the `ai-video-technical-director` persona is
+declared; no skill stack to resolve.)
+### 2. Locate the project
+Resolve `<project-slug>` against the working directory. If neither
+`<slug>/manifest.json` nor `agents/ai-video/projects/<slug>/manifest.json`
+exists, fail with the searched paths.
+### 3. Honor operator overrides
+Read `--skip-scene <id>` (repeatable) and `--continue` (proceed past
+the first missing clip) flags. Reject any other flag — this command
+does not render, so `--image-provider` / `--video-provider` are
+contract bugs.
+### 4. Stitch
+```bash
+scripts/ai-video/stitch.sh <project>/manifest.json <project>/final.mp4 \
+  ${SKIP_FLAGS} ${CONTINUE_FLAG}
+```
+The stitcher fails loud on the first unresolved clip unless
+`--continue` is set; on `--skip-scene` it drops the named scene from
+the concat list before invoking `ffmpeg`.
+### 5. Report
+Print: project slug, scenes stitched, scenes skipped, final MP4 path,
+audio status (per-clip `audio_embedded` flags from `manifest.json`).
+No live cost (no network calls happened). No commit. No push.
+## Rules
+- **No adapter calls.** This command must refuse any provider flag.
+- **No commit, no push, no PR.**
+- **Block on missing clips** unless `--continue` is explicitly set.
+- **Manifest is source of truth** — never re-order clips by filename
+  or timestamp; respect `manifest.json` ordering.
+## See also
+- [`/video:from-script`](from-script.md) — full pipeline including
+  initial stitch
+- [`/video:scene`](scene.md) — render one scene
+- [`scripts/ai-video/stitch.sh`](../../scripts/ai-video/stitch.sh) — the underlying tool

package/.agent-src/commands/video/storyboard.md ADDED Viewed

@@ -0,0 +1,95 @@
+---
+name: video:storyboard
+tier: 2
+cluster: video
+sub: storyboard
+description: Image-only storyboard — script → scenes → blueprint → image render → contact-sheet PNG via ffmpeg montage. No video calls.
+disable-model-invocation: true
+personas: [hollywood-director]
+skills: [scene-expander, video-director, character-consistency]
+suggestion:
+  eligible: true
+  trigger_description: "build a storyboard, contact sheet of scenes, image-only preview, validate a script visually before video render"
+  trigger_context: "user wants to see all scenes as stills before committing to motion calls"
+---
+# /video:storyboard
+`/video:storyboard <path-to-script.md> [--image-provider <id>]`
+Renders one locked image per scene, then composes them into a single
+contact-sheet PNG via `ffmpeg` montage. **No video calls.** Useful as a
+cheap pre-flight before [`/video:from-script`](from-script.md).
+**Block-on-ambiguity:** a missing scene heading, an unparseable
+character-lock block, or a `--video-provider` flag (rejected — this
+command does not call video adapters) halts the run with a precise
+diff.
+## Steps
+### 1. Validate dependencies
+```bash
+scripts/ai-video/lib/validate-deps.sh .agent-src.uncompressed/commands/video/storyboard.md
+```
+### 2. Load config + resolve image provider
+Source `scripts/ai-video/lib/load-config.sh`. Resolve image provider:
+`--image-provider` flag → `agents/.ai-video.xml` default → fail. Reject
+`--video-provider` (this command produces no clips).
+### 3. Parse the script
+`scene-expander` splits on `## Scene N`, writes
+`<project>/scenes/<id>/scene-blueprint.yaml` per scene.
+### 4. Character lock
+Single `character-consistency` pass writes `<project>/character.json`.
+Re-runs on the same project reuse it verbatim.
+### 5. Per-scene image render
+For each scene:
+1. `video-director` builds the eight-block image prompt.
+2. **Safety gate (Phase 5 Step 6).** Live mode requires `AIV_DRYRUN=false`
+   AND explicit per-turn confirmation; otherwise the run stops.
+3. Image adapter `run` → write the locked still under
+   `<project>/scenes/<id>/locked.png`.
+### 6. Build the contact sheet
+```bash
+ffmpeg -y \
+  -pattern_type glob -i '<project>/scenes/*/locked.png' \
+  -filter_complex "tile=<cols>x<rows>:padding=8:margin=16" \
+  <project>/storyboard.png
+```
+`<cols>` defaults to `ceil(sqrt(N))`; `<rows>` to `ceil(N/cols)`. The
+helper script `scripts/ai-video/lib/operator-pick.sh` is **not**
+invoked — this command emits a single sheet, not per-scene candidate
+picks.
+### 7. Report
+Print: project slug, scenes rendered, contact-sheet path, live cost or
+`dry-run` marker.
+## Rules
+- **No video adapter calls.** This command must refuse any path that
+  would invoke a video provider.
+- **No commit, no push, no PR.**
+- **Dry-run is the default.** Live image calls need explicit per-turn
+  confirmation.
+- **Reject `--video-provider`.** Surfacing the flag is a contract bug.
+## See also
+- [`/video:from-script`](from-script.md) — full pipeline including video
+- [`/video:scene`](scene.md) — single-scene iteration
+- [`/video:stitch`](stitch.md) — re-stitch existing clips

package/.agent-src/commands/video.md ADDED Viewed

@@ -0,0 +1,59 @@
+---
+name: video
+tier: 2
+cluster: video
+description: Video-creation orchestrator — Hollywood-level AI video pipeline. Routes to from-script, scene, storyboard, stitch.
+type: orchestrator
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "create a video from a script, render a single scene, build a storyboard, re-stitch existing clips, AI video pipeline"
+  trigger_context: "user mentions video generation, scene rendering, storyboard, ffmpeg stitch, or a `.ai-video.xml` config"
+---
+# /video
+Top-level orchestrator for the `/video:*` family — multi-provider AI
+video creation. Reads provider keys + defaults from
+[`agents/.ai-video.xml`](../agents/.ai-video.xml.example) (gitignored
+real file; example shipped). Every subcommand is **dry-run by default**;
+network calls require explicit per-turn confirmation per the adapter
+contract under [`scripts/ai-video/lib/adapter-contract.md`](../scripts/ai-video/lib/adapter-contract.md).
+## Sub-commands
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/video:from-script <path>` | `commands/video/from-script.md` | Full pipeline: script → scenes → blueprint → images → operator pick → motion → video → stitch |
+| `/video:scene "<idea>"` | `commands/video/scene.md` | Single-scene iteration without a full script |
+| `/video:storyboard <path>` | `commands/video/storyboard.md` | Image-only output; contact-sheet storyboard PNG via `ffmpeg` montage |
+| `/video:stitch <slug>` | `commands/video/stitch.md` | Re-stitches existing clips after operator edits, no re-render |
+## Dispatch
+1. Parse `/video <sub-command> [args]`.
+2. Look up the sub-command in the table above and execute its file
+   verbatim with the remaining args.
+3. Unknown / missing sub-command → print the table and ask:
+   > 1. from-script — full script → final video
+   > 2. scene — single-scene iteration
+   > 3. storyboard — image-only contact sheet
+   > 4. stitch — re-stitch existing clips
+## Rules
+- **Do NOT commit, push, or open a PR** — subcommands never do this.
+- **Do NOT chain subcommands.** One `/video <sub>` per turn.
+- **`AIV_DRYRUN=true` is the default.** A live (paid) call requires
+  `AIV_DRYRUN=false` AND an explicit operator confirmation in the same
+  turn; mirrors [`non-destructive-by-default`](../rules/non-destructive-by-default.md).
+- **Run `validate-deps.sh` first.** Every subcommand calls
+  `scripts/ai-video/lib/validate-deps.sh` before any adapter; fails
+  fast on missing personas / skills.
+- **Edit `.agent-src.uncompressed/` only.** Generated mirrors regenerate.
+## See also
+- [`scripts/ai-video/lib/adapter-contract.md`](../scripts/ai-video/lib/adapter-contract.md) — provider adapter v1 contract
+- [`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md) — `video` cluster registration