@laitszkin/apollo-toolkit 2.0.0

package/version-release/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: version-release
+description: "Guide the agent to prepare and publish a versioned release (version bump, changelog, tag, and push). Use only when users explicitly request version/tag/release work. If the release scope includes new completed spec files, run `specs-to-project-docs` before finalizing the release so project docs are standardized into categorized files and the old specs are removed or archived."
+---
+
+# Version Release
+
+## Dependencies
+
+- Required: none.
+- Conditional: `review-change-set`, `discover-edge-cases`, and `harden-app-security` for code-affecting releases before metadata edits and the final commit; `specs-to-project-docs` when the release scope includes new completed spec files.
+- Optional: none.
+- Fallback: If a required release dependency is unavailable for a code-affecting scope, or if `specs-to-project-docs` is required for spec conversion but unavailable, stop and report the missing dependency.
+
+## Standards
+
+- Evidence: Inspect the active change set and the release range before touching version files, tags, or changelog entries.
+- Execution: Use this workflow only for explicit release intent, run the required quality gates, standardize project docs into categorized files when new specs are present, then update versions, docs, commit, tag, and push.
+- Quality: Never guess versions, align user-facing docs with actual code, and convert completed planning docs into standardized categorized project docs before the release is published.
+- Output: Produce a versioned release commit and tag with synchronized changelog and relevant repository documentation.
+
+## Overview
+
+Run a standardized release workflow for versioned delivery:
+
+- resolve release scope
+- align project code and standardized categorized project documentation
+- bump version files
+- update changelog and relevant docs
+- commit, tag, and push
+
+## References
+
+Load only when needed:
+
+- `references/semantic-versioning.md`
+- `references/commit-messages.md`
+- `references/branch-naming.md`
+- `references/changelog-writing.md`
+- `references/readme-writing.md`
+
+## Workflow
+
+1. Inspect current changes
+   - Run `git status -sb`, `git diff --stat`, and `git diff --cached --stat`.
+   - Check staged files with `git diff --cached --name-only`.
+2. Confirm release intent
+   - Use this skill only when the user explicitly requests version/tag/release work.
+   - If no release intent is present, use `commit-and-push` instead.
+3. Classify changes and run dependencies when required
+   - `code-affecting`: runtime code, tests, build scripts, CI logic, or behavior-changing config.
+   - `docs-only`: documentation/content updates only.
+   - `new-specs-present`: the current change set or release range adds or updates completed planning files such as `spec.md`, `tasks.md`, `checklist.md`, or their containing plan directories.
+   - For code-affecting changes, run `review-change-set` to challenge architecture and simplification assumptions in the active change set.
+   - For code-affecting changes, run `discover-edge-cases` and resolve any confirmed findings.
+   - For code-affecting changes, ensure `harden-app-security` has been executed for the same scope as an adversarial quality gate.
+4. Identify release range
+   - Find latest version tag with `git describe --tags --abbrev=0` (fallback to `git tag --list`).
+   - If no tags exist, use initial commit from `git rev-list --max-parents=0 HEAD`.
+   - Review `git log --oneline <range>` and `git diff --stat <range>`.
+5. Standardize project docs when new specs are in scope
+   - Execute `specs-to-project-docs` when `new-specs-present` is true and the related implementation scope is complete enough for documentation consolidation.
+   - Let `specs-to-project-docs` convert the relevant specs into categorized project docs such as `docs/README.md`, `docs/getting-started.md`, `docs/configuration.md`, `docs/architecture.md`, `docs/features.md`, and `docs/developer-guide.md`.
+   - Let the skill normalize any existing project docs to the same structure and remove or archive superseded source spec files.
+   - If the specs still represent active unfinished work, do not convert them yet; report that the spec files remain active and should not be deleted.
+6. Align code and project docs
+   - Compare release range changes with user-facing docs and operational docs to ensure they match actual code behavior.
+   - Required alignment targets include project docs such as `README.md`, usage/setup docs, API docs, deployment/runbook docs, and release notes sources when present.
+   - After `specs-to-project-docs` runs, treat the categorized outputs as the canonical project-doc structure.
+   - If mismatches are found, update the relevant project docs before version bumping/tagging.
+7. Decide version and tag format
+   - Read existing version files (for example `project.toml`, `package.json`, or repo-specific version files).
+   - Infer existing tag format (`vX.Y.Z` or `X.Y.Z`) from repository tags.
+   - If the user provides the target version, use it directly.
+   - If it is missing, ask the user for the target version or semver bump type.
+   - Provide recommendations only when explicitly requested.
+8. Update version files
+   - Update every detected version file consistently.
+   - Preserve file formatting; change only version values.
+9. Update release docs
+   - Update `CHANGELOG.md` with a new version entry using the selected release range.
+   - Update `README.md` only when behavior or usage changed.
+   - Update `AGENTS.md` only when agent workflow/rules changed.
+10. Commit and tag
+   - Create a release-oriented commit message (for example `chore(release): bump version and update changelog`) when applicable.
+   - Create the version tag locally after commit.
+11. Push
+   - Push commit(s) and the release tag to the current branch.
+
+## Notes
+
+- Never guess versions; always read from files and user intent.
+- If tests are required by repository conventions, run them before commit.
+- If a new branch is required, follow `references/branch-naming.md`.

package/version-release/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Version Release"
+  short_description: "Prepare a versioned release with bump, changelog, tag, and push"
+  default_prompt: "Use $version-release only for explicit release/version/tag requests: inspect the release scope, and for code-affecting changes run $review-change-set, $discover-edge-cases, and $harden-app-security as quality gates, run $specs-to-project-docs when the release scope includes new completed spec files so project docs are standardized into categorized files and old specs are removed or archived, align user-facing docs with real behavior, update version files and CHANGELOG, create the release commit and tag, and push both commits and tags."

package/version-release/references/branch-naming.md

@@ -0,0 +1,15 @@
+# Branch Naming Instructions
+
+Use a short, descriptive branch name in this pattern:
+
+- type/short-description
+- type/issue-id-short-description (if issue ids are used)
+
+Guidelines:
+- Use lowercase letters and hyphens only.
+- Align type with commit message types (feat, fix, docs, chore, refactor, test).
+- Do not rename the current branch unless the user explicitly asks.
+
+Examples:
+- feat/add-rpc-timeouts
+- fix/1234-parse-registry

package/version-release/references/changelog-writing.md

@@ -0,0 +1,8 @@
+# CHANGELOG Writing
+
+Follow the existing changelog format. If none is defined, use Keep a Changelog style.
+
+- Add a new version heading with the release date (YYYY-MM-DD).
+- Group entries under clear sections: Added, Changed, Fixed, Removed, Deprecated, Security.
+- Write user-facing bullets; avoid commit hashes or internal-only details.
+- Call out breaking changes explicitly.

package/version-release/references/commit-messages.md

@@ -0,0 +1,19 @@
+# Commit Message Instructions
+
+Use a concise Conventional Commit style:
+
+- Format: type: short subject
+- Subject: imperative, lower case, no trailing period, <= 72 chars
+- Scope: include only if the repo already uses it (type(scope): subject)
+- Select `type` from the actual change intent in the staged diff (feature, bugfix, docs, etc.)
+- Do not use version-only subjects (for example `feat: v1.2.3`)
+- If the commit only contains release metadata, use `chore(release): ...`
+
+Common types:
+- feat, fix, docs, chore, refactor, test, style, perf, build, ci
+
+Examples:
+- feat: add rpc retry backoff
+- fix: handle empty response payload
+- docs: update env var table
+- chore(release): bump version and update changelog

package/version-release/references/readme-writing.md

@@ -0,0 +1,12 @@
+# README Writing
+
+Update README only when it contradicts the code changes.
+
+Check and update as needed:
+- Overview and feature list
+- Installation and setup steps
+- Usage examples and CLI commands
+- Configuration or environment variables
+- API or integration instructions
+
+Keep edits minimal and consistent with the existing style.

package/version-release/references/semantic-versioning.md

@@ -0,0 +1,12 @@
+# Semantic Versioning
+
+Use MAJOR.MINOR.PATCH for release versions.
+
+- MAJOR: incompatible or breaking changes.
+- MINOR: backward-compatible new features.
+- PATCH: backward-compatible bug fixes.
+
+Pre-release or build metadata (for example, 1.2.3-rc.1) is allowed only if the repo already uses it.
+Prefer the existing tag format and prefix (v1.2.3 vs 1.2.3).
+
+If the change type is ambiguous, choose the lower bump and ask the user to confirm.

package/video-production/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [0.6.0] - 2026-02-17
+
+### Added
+- Enforce `16:9` output as the default long-video aspect ratio (default `1920x1080`).
+- Require fresh storyboard image generation per run (no reuse of previously generated storyboard pictures).
+- Add an audience-retention animation requirement for long-form timelines and an animation planning section in the plan template.
+
+### Changed
+- Remove climax-short-clip planning/output requirements and replace them with chapter-level animation planning.
+- Update `SKILL.md`, `README.md`, `agents/openai.yaml`, and `references/plan-template.md` to match the new 16:9 + fresh-images + animation-first long-video workflow.
+
+### Removed
+- Remove `text-to-short-video` as a dependency from the default long-form workflow.
+- Remove related climax-scene short-video generation and integration steps.
+
+## [0.5.0] - 2026-02-17
+
+### Added
+- Require integrating every climax short clip generated by `text-to-short-video` into the final long-form timeline.
+- Add a compact plan template with four required sections: `Meta Data`, `Reference Text`, `Images Needed To Be Generated`, and `Climax Scenes Selected And Videos To Be Generated`.
+
+### Changed
+- Replace the single important-section short-clip flow with climax-scene selection for text-driven jobs.
+- Update `SKILL.md`, `README.md`, and `agents/openai.yaml` to capture climax-scene locks, clip integration positions, and source-reference-only planning guidance.
+
+## [0.4.0] - 2026-02-17
+
+### Added
+- Add long-form structure and timing-plan requirements to the plan template for 10+ minute productions.
+- Add optional highlight-clip flow that allows `text-to-short-video` only when explicitly requested.
+
+### Changed
+- Reposition the skill as a long-form video production workflow (default target: more than 10 minutes) instead of short-video-first behavior.
+- Replace key-segment-first short pipeline rules with chaptered long-form planning, timing, and rendering guidance in `SKILL.md`, `README.md`, and `agents/openai.yaml`.
+
+## [0.3.0] - 2026-02-17
+
+### Added
+- Add `text-to-short-video` as the default text-first production dependency.
+- Require extracting the most important text segment before short-video generation unless the user locks an exact segment.
+- Add recurring-role prompt policy: reuse existing role skeletons and create new JSON prompt entries only for undefined roles.
+- Add `Key Segment` and `Prompt Strategy` sections to `references/plan-template.md`.
+- Add `prompts.json` path to the output contract.
+
+### Changed
+- Update `SKILL.md`, `README.md`, and `agents/openai.yaml` to enforce text abstraction plus role-aware prompt reuse before generation.
+
+## [0.2.0] - 2026-02-16
+
+### Added
+- Require generating a pre-production plan markdown in `<project_dir>/docs/plans/` named with `<YYYY-MM-DD>-<content_name>.md`.
+- Define mandatory plan sections for `Video Transcripts` and `Images To Generate`.
+- Add `references/plan-template.md` as the canonical pre-generation plan template.
+- Add square-bracketed guidance and placeholders in the template, including explicit instruction to remove them after filling.
+- Add plan markdown path to the output contract.
+
+### Changed
+- Enforce explicit user confirmation of the plan document before running any generation or rendering step.
+- Require creating plan files from the reference template before generation.
+- Require replacing and removing all square-bracket placeholder/instruction text before sending the plan for user confirmation.
+- Update the agent default prompt and README to reflect the template-driven plan-first workflow.
+
+## [0.1.3] - 2026-02-15
+
+### Added
+- Require preserving the Remotion workspace by default so users can revise and re-render later.
+- Add Remotion workspace path to output locations and output contract.
+
+### Changed
+- Update agent default prompt to explicitly keep the Remotion project unless cleanup is requested.
+
+## [0.1.2] - 2026-02-15
+
+### Added
+- Require subtitle color and depth to adapt to image color elements in the subtitle-safe area.
+- Add subtitle readability verification with minimum contrast target (`4.5:1`) and fallback backing plate rule.
+- Add `subtitle-contrast-report.json` to the output contract for traceable subtitle style decisions.
+
+### Changed
+- Replace fixed subtitle text/stroke/shadow defaults with an adaptive color/depth strategy.
+- Update README and agent default prompt to emphasize image-aware subtitle readability behavior.
+
+## [0.1.1] - 2026-02-15
+
+### Added
+- Require explicit user confirmation before any video production starts.
+- Define a unified subtitle style profile shared by single and multi outputs.
+- Add subtitle segment processing rules (overlap filtering, clamping, and local time rebasing).
+
+### Changed
+- Enforce cue-by-cue subtitle timing in Remotion rendering.
+- Extend output contract to include subtitle style config path and subtitle sync verification.
+- Update README and agent default prompt to reflect subtitle style and sync requirements.
+
+## [0.1.0] - 2026-02-15
+
+### Added
+- Initial `video-production` skill release.
+- End-to-end workflow across storyboard generation, narration/subtitles, and Remotion rendering.
+- Support for both single long video output and multi-clip segmented output.

package/video-production/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Yamiyorunoshura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/video-production/README.md

@@ -0,0 +1,68 @@
+# Video Production Skill
+
+A Codex skill for long-form video production (more than 10 minutes) that follows user instructions and invokes only the needed dependency skills.
+
+## Capabilities
+
+- Adapts the workflow to user-provided assets instead of forcing a fixed pipeline.
+- Uses a long-form chaptered workflow as the default text-to-video path.
+- Abstracts a complete long-form story arc and chapter map before generation (unless user locks a structure).
+- Enforces final output at `16:9` (default `1920x1080`).
+- Ensures `<project_dir>/roles/roles.json` exists first (create if missing), then reuses existing recurring-role prompts and only defines missing roles.
+- Regenerates required storyboard images per run (no reuse of previously generated storyboard pictures).
+- Calls voice/subtitle generation only when audio or SRT is missing.
+- Uses Remotion best practices to compose and render final output.
+- Requires timeline animation for long videos to improve audience retention.
+- Asks interactive clarifying questions when key information is missing (for example subtitle style, target duration, chapter pacing, and animation style).
+- Creates `<project_dir>/docs/long-video-plans/<YYYY-MM-DD>-<content_name>.md` from `references/plan-template.md` before generation and waits for user confirmation.
+- Uses a compact plan template with only four sections: meta data, reference text, images needed, and animation plan.
+- Defaults to one long-form video unless the user explicitly requests multi-episode output.
+- Preserves the Remotion project by default for later edits.
+- Maintains Remotion `.gitignore` (including `node_modules/` and build/cache outputs) to keep git projects clean.
+
+## Dependency Skills
+
+- `openai-text-to-image-storyboard`
+- `docs-to-voice`
+- `remotion-best-practices`
+
+## Typical Inputs
+
+- `project_dir`
+- source text (or existing assets)
+- `content_name`
+- existing role prompt source (optional `prompts.json` or role definitions)
+- reference text sources (path/URL + scope notes; no full text embedding in plan)
+- target duration (10+ minutes for long-form requests)
+- chapter pacing preference
+- subtitle style preferences
+- animation style preference
+
+## Output Contract
+
+Return absolute paths for:
+
+- plan markdown file (`<project_dir>/docs/long-video-plans/<YYYY-MM-DD>-<content_name>.md`)
+- roles.json file (`<project_dir>/roles/roles.json`, used for role reuse/initialization)
+- prompts.json file (if used)
+- storyboard directory (if used)
+- narration audio file (if used)
+- subtitle SRT file (if used)
+- final rendered long-form MP4 (`16:9`, with planned animations)
+- Remotion workspace directory
+- Remotion `.gitignore` file path
+
+## Files
+
+- `SKILL.md` - workflow and execution rules
+- `agents/openai.yaml` - display metadata and default prompt
+- `references/plan-template.md` - pre-generation plan markdown template
+- `references/roles-json.md` - recurring-role schema for `roles.json`
+
+## Quick Start
+
+In Codex, call the skill directly:
+
+```text
+Use $video-production to generate a long-form video based on my instructions.
+```

package/video-production/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: video-production
+description: Generate long-form videos (more than 10 minutes) by following user instructions and invoking related skills only when needed (`openai-text-to-image-storyboard`, `docs-to-voice`, `remotion-best-practices`). For text inputs, extract a complete long-form story arc, generate fresh storyboard images (no reuse of previously generated pictures), and render a 16:9 animated long-form video.
+---
+
+# Video Production
+
+## Dependencies
+
+- Required: `remotion-best-practices` for final composition and rendering.
+- Conditional: `openai-text-to-image-storyboard` when visuals must be generated and `docs-to-voice` when narration or subtitles must be generated.
+- Optional: none.
+- Fallback: If a required generation or rendering dependency is unavailable for the chosen path, stop and report the blocked dependency.
+
+## Standards
+
+- Evidence: Follow user instructions first, collect only the inputs needed for the selected path, and clarify preference-sensitive details before generation.
+- Execution: Create a long-video plan, wait for explicit approval, then run image generation, narration, and Remotion rendering in order.
+- Quality: Keep output longer than 10 minutes by default, enforce `16:9`, reuse role identities correctly, and never reuse previously generated storyboard images.
+- Output: Return absolute artifact paths, runtime and chapter summaries, animation verification, role reuse notes, and generated-image policy confirmation.
+
+## Core Rules
+
+1. Follow user instructions first. Use the required execution sequence below unless the user explicitly overrides it.
+2. For text-driven requests, use a long-form pipeline by default and target final output longer than 10 minutes.
+3. Before generation, turn source text into a coherent long-form structure (hook, chapter progression, and closing).
+4. The final output aspect ratio must be `16:9` (default resolution: `1920x1080`).
+5. Role prompt policy for prompt generation:
+   - always ensure `<project_dir>/roles/roles.json` exists before any prompt generation
+   - if a recurring role already has a defined prompt skeleton, reuse it without rewriting identity fields
+   - if a recurring role appears but is not defined, generate new role entries using the supported `prompts.json` schema
+6. Call only relevant dependency skills:
+   - `openai-text-to-image-storyboard`: generate storyboard images when user did not provide usable visuals
+   - `docs-to-voice`: generate narration/timeline/SRT when user did not provide audio or subtitles
+   - `remotion-best-practices`: compose and render the final long-form output
+7. Do not reuse previously generated storyboard pictures. Generate fresh images for each run unless the user provides external assets to use.
+8. Long-form videos must include timeline animation to maintain audience focus (for example pan/zoom, parallax, controlled camera moves, and chapter transitions).
+9. Before any asset generation or rendering, create a plan markdown in `<project_dir>/docs/long-video-plans/` and wait for explicit user confirmation.
+10. Never ask the user whether to output a single video or multiple episodes.
+   - If the user explicitly asks for episodes/parts, produce multi-episode output.
+   - Otherwise default to one full long video.
+11. Keep Remotion project files unless the user explicitly asks for cleanup.
+12. Keep git repositories clean by ensuring Remotion dependency/build/cache artifacts are ignored.
+
+## Required Execution Sequence
+
+When this skill is triggered, run the production stages in this order:
+
+1. Generate the production plan markdown and wait for explicit user confirmation before any generation.
+2. Check whether images are needed; generate missing images with `openai-text-to-image-storyboard` (fresh generation only, no reuse of previously generated pictures).
+3. Generate the narration/audio track with `docs-to-voice` when usable audio is not already provided.
+4. Use `remotion-best-practices` to combine prepared assets (images, audio/subtitles, and planned animations) into the final `16:9` long-form video.
+
+## Interactive Clarification (Required)
+
+Before running generation commands, check whether details are sufficient. If not, ask concise targeted questions and wait for user replies.
+Do not guess preference-sensitive options.
+
+Prioritize asking these missing items:
+
+- target total duration (default recommendation: 10-15 minutes when user says long video)
+- chapter pacing (chapter count or average chapter duration)
+- subtitle style (font, size, color, stroke/background, position, max lines)
+- narration language/voice tone (if narration must be generated)
+- visual style keywords (if storyboard images must be generated)
+- animation style preference (subtle/cinematic/dynamic, transition density, motion intensity)
+- existing role prompt source (user-provided prompt file or existing `<project_dir>/pictures/<content_name>/prompts.json`) when recurring roles are expected
+- output location / filename rules when not obvious
+
+Ask only the minimum set required to unblock progress.
+
+## Inputs to Collect
+
+Collect only what is needed for the requested job (not everything by default):
+
+- `project_dir`
+- `content_name`
+- source script/text (unless the user provides complete audio + subtitles)
+- extracted long-form story arc with chapter breakdown (unless user provides an exact chapter structure)
+- source reference set (file paths/URLs and scope notes; do not inline full long text in plan)
+- final transcript text used for narration/subtitles
+- existing prompt assets (`prompts.json`, character roster, or user-defined role prompts)
+- user-provided assets (images, audio, subtitles, branding)
+- animation direction for chapter segments
+- output requirements from user instructions
+
+## Workflow
+
+### 1) Read user intent and choose skill calls
+
+Create a concise execution checklist:
+
+- what the user already provided
+- what still needs generation
+- whether to run the long-form text path or fallback asset path
+- which dependency skills will be called
+- where animation beats are required in the timeline
+- what will be skipped
+
+### 2) Abstract long-form story arc and chapter timing (text-first path)
+
+When the request includes source text and the user did not lock a specific structure:
+
+- extract one self-contained long-form narrative arc suitable for a 10+ minute video
+- split content into chapters with clear transitions and duration targets
+- preserve original wording for key hooks and turning points whenever possible
+- ensure narrative continuity (setup -> development -> escalation -> payoff/closing)
+- define chapter-level animation intent to avoid long static visual stretches
+
+If the user already provides an exact chapter structure, reuse it directly and skip abstraction for those parts.
+
+### 3) Resolve role prompt reuse and ensure `roles.json` exists before prompt generation
+
+Before generating or updating `prompts.json`:
+
+1. detect recurring roles across all chapters
+2. set target role file path:
+   - `<project_dir>/roles/roles.json`
+3. if `roles.json` exists, read it first and reuse matching roles
+4. if `roles.json` does not exist, create it first using `references/roles-json.md`
+   - include detected recurring roles when available
+   - if no recurring roles are detected, initialize with `{"characters": []}`
+5. load reusable prompt sources in this order:
+   - user-provided prompt file or role definitions
+   - existing `<project_dir>/pictures/<content_name>/prompts.json` (if present)
+6. apply role policy:
+   - defined role: reuse existing role skeleton following `references/roles-json.md`
+   - undefined role: add a new role entry following `references/roles-json.md`
+7. choose schema:
+   - use structured format with `characters` + `scenes` when recurring roles exist
+   - use simple list format only when no recurring roles need continuity
+
+### 4) Create production plan markdown and wait for confirmation
+
+Before generating images/audio/subtitles/video:
+
+- create directory `<project_dir>/docs/long-video-plans/` if missing
+- create a plan file named `<YYYY-MM-DD>-<content_name>.md`
+- load the reference template at `references/plan-template.md`
+- copy the template into the plan file first, then fill it
+- use local date for `YYYY-MM-DD`; sanitize `content_name` for filename safety
+- keep this long-video plan location separate from short-video plans (`<project_dir>/docs/plans/`)
+- include only these sections:
+  - `## Meta Data`
+  - `## Reference Text`
+  - `## Images Needed To Be Generated`
+  - `## Animation Plan For Audience Retention`
+- in `Meta Data`, include compact runtime/layout/output metadata and keep aspect ratio at `16:9`
+- in `Reference Text`, include only source references (file paths/URLs + range/scope + purpose), not full long text
+- in `Images Needed To Be Generated`, list every image required for this run and mark all as fresh generation (no generated-image reuse)
+- in `Animation Plan For Audience Retention`, include chapter-level animation type, transition, and focus goal
+- replace all square-bracket placeholders with concrete content
+- remove all square-bracket placeholder/instruction text before sharing the plan for confirmation
+- return the absolute plan file path to the user and ask for explicit confirmation
+- do not run generation/render commands until user confirms the plan document
+
+### 5) Generate and integrate the long-form video in required order (default path)
+
+After plan confirmation:
+
+- run `openai-text-to-image-storyboard` for all approved storyboard assets that need generation in the current run
+- generate narration/subtitles chapter-by-chapter with `docs-to-voice` when needed
+- compose one continuous Remotion timeline with `remotion-best-practices`
+  - maintain `16:9` output
+  - apply planned animation beats across opening, middle, and closing chapters
+  - avoid long static holds by using motion or transition treatment
+- verify total rendered runtime is longer than 10 minutes unless the user explicitly requested shorter
+- verify animation is present in the final render and aligns with the approved plan
+
+### 6) Keep reusable project artifacts
+
+Default workspace:
+
+- `<project_dir>/video/<content_name>/remotion/`
+
+Keep Remotion sources by default unless the user explicitly requests cleanup.
+
+Git hygiene (required):
+
+- create or update `<project_dir>/video/<content_name>/remotion/.gitignore`
+- do not remove user-defined ignore rules already in that file
+- ensure it includes at least these entries:
+  - `node_modules/`
+  - `.cache/`
+  - `dist/`
+  - `build/`
+  - `out/`
+  - `.DS_Store`
+  - `*.log`
+
+## Output Contract
+
+Return absolute paths for produced artifacts:
+
+- plan markdown file (`<project_dir>/docs/long-video-plans/<YYYY-MM-DD>-<content_name>.md`)
+- `roles.json` file used for role reuse/initialization (`<project_dir>/roles/roles.json`)
+- `prompts.json` file used for generation
+- storyboard directory (if generated or used; generated storyboard images must be fresh for this run)
+- narration audio file (if generated or used)
+- subtitle SRT file (if generated or used)
+- final long-form MP4 in `16:9` with planned animations
+- Remotion workspace directory
+- Remotion `.gitignore` file path
+
+Also report:
+
+- extracted long-form structure summary (and whether it was user-locked or agent-abstracted)
+- chapter duration summary and total runtime
+- animation plan summary (planned vs actual)
+- role prompt reuse summary (reused vs newly defined roles)
+- what assumptions were clarified through interactive questions
+- subtitle sync verification (first/middle/last cue spot check)
+- generated-image policy verification (fresh generation confirmed, no generated-image reuse)

package/video-production/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Video Production"
+  short_description: "Generate 16:9 long-form videos with plan confirmation, fresh images, and timeline animations"
+  default_prompt: "Use $video-production to produce long-form videos (more than 10 minutes) by following user instructions. For text inputs, extract a coherent long-form story arc, split it into timed chapters, and keep final output at 16:9 (default 1920x1080). Before generating or updating prompts, detect recurring roles and ensure <project_dir>/roles/roles.json exists first (create it if missing using references/roles-json.md), then reuse existing role prompt skeletons and generate new role entries only for undefined roles using the supported JSON prompt schema. Do not reuse previously generated storyboard pictures; generate fresh storyboard images for each run unless the user supplies external assets. If required details are missing, ask interactive clarifying questions first (for example target duration, chapter pacing, subtitle style, voice, animation style, or role prompt source). Before any generation starts, create a plan markdown at <project_dir>/docs/long-video-plans/<YYYY-MM-DD>-<content_name>.md from references/plan-template.md with only these sections: meta data, reference text, images needed to be generated, and animation plan for audience retention. In the reference text section, refer to source locations only and do not embed full long text. Replace all square-bracket placeholders with concrete content, remove placeholder/instruction text, and then wait for explicit user confirmation. Do not ask whether output should be single or multi-episode; infer from the user request (default to single unless episodes are explicitly requested). Use docs-to-voice when audio/subtitles are missing and remotion-best-practices for final assembly. The final render must include timeline animations to maintain audience focus. Keep the Remotion workspace and ensure its .gitignore excludes dependency/build/cache artifacts (such as node_modules/) so git repositories stay clean."

package/video-production/references/plan-template.md

@@ -0,0 +1,54 @@
+# Video Production Plan
+
+[Instruction: Copy this template to `<project_dir>/docs/long-video-plans/<YYYY-MM-DD>-<content_name>.md` before any generation starts.]
+[Instruction: Replace every square-bracket placeholder with real content.]
+[Instruction: After filling, delete all square-bracket instruction/placeholder text before showing the plan to the user for confirmation.]
+
+# [VIDEO_TITLE]
+
+## Meta Data
+
+[Instruction: Fill only compact metadata used for production decisions and stage sequencing.]
+- Date: [YYYY-MM-DD]
+- Content Name: [CONTENT_NAME]
+- Aspect Ratio / Resolution: [16:9 / 1920x1080]
+- Target Duration (minutes): [TARGET_DURATION_MINUTES]
+- Output Mode: [SINGLE_OR_MULTI_EPISODE]
+- Execution Sequence: [PLAN -> IMAGES -> AUDIO -> REMOTION]
+- Audio Track Plan: [GENERATE_WITH_DOCS_TO_VOICE_OR_REUSE_EXISTING]
+- Final Assembly Plan: [REMOTION_BEST_PRACTICES]
+- Remotion Workspace: [ABSOLUTE_PATH]
+
+## Reference Text
+
+[Instruction: Do not paste full long text. Only reference source locations and short purpose notes because this skill targets long-form generation.]
+1. [SOURCE_ID] - [TYPE_FILE_OR_URL] - [ABSOLUTE_PATH_OR_URL]
+   - Scope: [CHAPTER_OR_RANGE]
+   - Purpose: [HOW_THIS_SOURCE_IS_USED]
+2. [SOURCE_ID] - [TYPE_FILE_OR_URL] - [ABSOLUTE_PATH_OR_URL]
+   - Scope: [CHAPTER_OR_RANGE]
+   - Purpose: [HOW_THIS_SOURCE_IS_USED]
+
+## Images Needed To Be Generated
+
+[Instruction: List only images that still need generation for this run. Do not reuse previously generated storyboard images. If none, write `None`.]
+1. [SCENE_ID_OR_ORDER] - [IMAGE_PROMPT_OR_DESCRIPTION]
+   - Usage: [INTENDED_USAGE_IN_LONG_VIDEO]
+   - Generation Policy: [FRESH_GENERATION]
+2. [SCENE_ID_OR_ORDER] - [IMAGE_PROMPT_OR_DESCRIPTION]
+   - Usage: [INTENDED_USAGE_IN_LONG_VIDEO]
+   - Generation Policy: [FRESH_GENERATION]
+
+## Animation Plan For Audience Retention
+
+[Instruction: List chapter-level animation plans used in final Remotion assembly to avoid static visuals and keep audience focus.]
+1. [CHAPTER_ID_OR_RANGE]
+   - Animation Type: [PAN_ZOOM_OR_PARALLAX_OR_CAMERA_MOVE]
+   - Motion Notes: [HOW_MOTION_IS_APPLIED]
+   - Transition: [CUT_FADE_SLIDE_OR_OTHER]
+   - Focus Goal: [WHY_THIS_MAINTAINS_ATTENTION]
+2. [CHAPTER_ID_OR_RANGE]
+   - Animation Type: [PAN_ZOOM_OR_PARALLAX_OR_CAMERA_MOVE]
+   - Motion Notes: [HOW_MOTION_IS_APPLIED]
+   - Transition: [CUT_FADE_SLIDE_OR_OTHER]
+   - Focus Goal: [WHY_THIS_MAINTAINS_ATTENTION]