@laitszkin/apollo-toolkit 2.0.0

package/text-to-short-video/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: text-to-short-video
+description: Generate 30-60 second short videos by directly calling an OpenAI-compatible video generation API from text. Keep role consistency by using roles.json as role prompt source and only updating role descriptions.
+---
+
+# Text to Short Video
+
+## Dependencies
+
+- Required: none.
+- Conditional: none.
+- Optional: none.
+- Fallback: not applicable.
+
+## Standards
+
+- Evidence: Use `roles.json` as the authoritative role source and collect only the minimal prompt, duration, and sizing inputs.
+- Execution: Stay API-only: resolve roles, build one prompt, submit the video job, poll until completion, and download one final MP4.
+- Quality: Keep duration in the 30-60 second range, preserve role identity fields, and do not route through storyboard or Remotion skills.
+- Output: Save the prompt package, API records, and final short-video artifacts under the project video workspace.
+
+## Overview
+
+This skill is **API-only**:
+
+1. Resolve role consistency from `roles.json`.
+2. Build one short-video prompt from text + roles.
+3. Call an OpenAI-compatible video generation API.
+4. Poll until the job is finished.
+5. Download one final MP4.
+6. Optionally run aspect-ratio/size post-processing.
+
+Do not use `openai-text-to-image-storyboard` or `remotion-best-practices` in this skill.
+
+## Required Inputs
+
+Collect only what is required:
+
+- `project_dir` (absolute path)
+- `content_name` (output folder/file name)
+- source text or user-locked prompt
+- target size (`width x height`, default `1080x1920`)
+- target duration seconds (default `50`, keep in `30-60` range)
+
+If critical inputs are missing, ask concise follow-up questions.
+
+## Role Definition (Required)
+
+Always use:
+
+- `<project_dir>/pictures/<content_name>/roles.json`
+
+Required JSON format:
+
+```json
+{
+  "characters": [
+    {
+      "id": "lin_xia",
+      "name": "Lin Xia",
+      "appearance": "short black hair, amber eyes, slim build",
+      "outfit": "dark trench coat, silver pendant, leather boots",
+      "description": "standing calmly, observant expression"
+    }
+  ]
+}
+```
+
+Consistency rules:
+
+- Use `roles.json` as the role prompt source.
+- Keep `id`, `name`, `appearance`, `outfit` unchanged for existing roles.
+- Only modify `description` to reflect this clip's action/emotion.
+- If a new role is required, append a new role entry; never rewrite identity fields of existing roles.
+- If no recurring roles exist yet, initialize with:
+
+```json
+{"characters": []}
+```
+
+## Environment Setup
+
+Use this template:
+
+- `/Users/tszkinlai/.codex/skills/text-to-short-video/.env.example`
+
+Copy to:
+
+- `/Users/tszkinlai/.codex/skills/text-to-short-video/.env`
+
+Required keys:
+
+- `OPENAI_API_URL`
+- `OPENAI_API_KEY`
+
+Optional keys:
+
+- `OPENAI_VIDEO_MODEL`
+- `OPENAI_VIDEO_DURATION_SECONDS`
+- `OPENAI_VIDEO_ASPECT_RATIO`
+- `OPENAI_VIDEO_SIZE`
+- `OPENAI_VIDEO_POLL_SECONDS`
+- `TEXT_TO_SHORT_VIDEO_WIDTH`
+- `TEXT_TO_SHORT_VIDEO_HEIGHT`
+
+## Workflow
+
+### 1) Resolve `roles.json` before prompt generation
+
+- Target path: `<project_dir>/pictures/<content_name>/roles.json`.
+- If file exists, load and reuse role identities.
+- If file does not exist, create it with the required schema.
+- For existing roles, update only `description` when clip-specific motion/emotion is needed.
+
+### 2) Build one generation prompt from text + roles
+
+- If the user already gives an exact prompt, reuse it directly.
+- Otherwise extract one concise visual prompt from source text.
+- Keep the prompt focused on one coherent short narrative beat.
+- Ensure all role identity details come from `roles.json` and only `description` is clip-specific.
+- Save prompt package under:
+  - `<project_dir>/video/<content_name>/shorts/api/prompt_input.json`
+
+Suggested local `prompt_input.json` structure:
+
+```json
+{
+  "roles_file": "<project_dir>/pictures/<content_name>/roles.json",
+  "description_overrides": {
+    "lin_xia": "running through rain, breathing hard, determined"
+  },
+  "final_prompt": "..."
+}
+```
+
+### 3) Submit video generation request
+
+- Endpoint: `${OPENAI_API_URL%/}/videos/generations`
+- Send model/prompt/duration/size (or aspect ratio) in JSON payload.
+- Save request and response records under:
+  - `<project_dir>/video/<content_name>/shorts/api/`
+
+Example request fields (provider-compatible variants are allowed):
+
+```json
+{
+  "model": "${OPENAI_VIDEO_MODEL}",
+  "prompt": "...",
+  "duration": 50,
+  "size": "1080x1920",
+  "aspect_ratio": "9:16"
+}
+```
+
+### 4) Poll job status until terminal state
+
+- Read job ID from the create response.
+- Poll `${OPENAI_API_URL%/}/videos/generations/<job_id>` every `OPENAI_VIDEO_POLL_SECONDS` seconds.
+- Stop only on terminal state:
+  - success: download output video URL/file
+  - failure/cancelled: report provider error and stop
+
+### 5) Download final MP4
+
+Save to:
+
+- `<project_dir>/video/<content_name>/shorts/<content_name>_important.mp4`
+
+If provider returns multiple outputs, keep the best one that matches requested size/duration closest.
+
+### 6) Enforce final aspect ratio and size (optional but recommended)
+
+When output ratio or resolution differs from target, run:
+
+```bash
+python /Users/tszkinlai/.codex/skills/text-to-short-video/scripts/enforce_video_aspect_ratio.py \
+  --input-video "<downloaded_video_path>" \
+  --output-video "<final_output_video_path>" \
+  --env-file /Users/tszkinlai/.codex/skills/text-to-short-video/.env \
+  --force
+```
+
+Behavior:
+
+- aspect ratio mismatch: center-crop then scale
+- same ratio but different size: scale
+- already matching: no-op/copy
+
+## Output Contract
+
+Return absolute paths for:
+
+- `roles.json` used for role consistency
+- prompt input JSON (if saved)
+- API request payload JSON (if saved)
+- API create response JSON (if saved)
+- final downloaded `.mp4`
+- post-processed `.mp4` (if post-processing executed)
+
+Also report:
+
+- role reuse summary (reused/added roles)
+- which role descriptions were modified for this clip
+- final prompt text source (user-locked or agent-extracted)
+- job ID and final status
+- duration check (`30-60` seconds)
+- final render size check (`width x height`)
+- whether center crop was applied
+
+## Quality Gate Checklist
+
+Before finishing, verify:
+
+- generation path is API-only (no storyboard/remotion orchestration)
+- `roles.json` uses required schema and is used as prompt source
+- existing role identity fields (`id/name/appearance/outfit`) were not modified
+- only role `description` was changed for clip-specific behavior
+- job reached a successful terminal state
+- output file exists at returned absolute path
+- output duration is within `30-60` seconds (or user-approved exception)
+- output size matches requested target (after post-processing if needed)

package/text-to-short-video/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Text to Short Video"
+  short_description: "Turn text into 30-60s short videos via API"
+  default_prompt: "Use $text-to-short-video to convert my text into one 30-60 second short video using an API-only workflow. Before building the final prompt, load <project_dir>/pictures/<content_name>/roles.json as the role source and keep role consistency: do not modify existing role id/name/appearance/outfit, only update role descriptions for clip-specific actions. Then call an OpenAI-compatible /videos/generations endpoint with settings from /Users/tszkinlai/.codex/skills/text-to-short-video/.env, poll until completion, download the MP4, and run post-process crop/resize only when output aspect ratio or size mismatches."

package/text-to-short-video/scripts/enforce_video_aspect_ratio.py

@@ -0,0 +1,350 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+SKILL_DIR = Path(__file__).resolve().parent.parent
+DEFAULT_ENV_FILE = SKILL_DIR / ".env"
+SIZE_PATTERN = re.compile(r"^(\d{2,5})x(\d{2,5})$")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Enforce final video aspect ratio and size. "
+            "If input aspect ratio differs from target, center-crop then scale."
+        )
+    )
+    parser.add_argument("--input-video", required=True, help="Path to rendered input video.")
+    parser.add_argument(
+        "--output-video",
+        help=(
+            "Path to processed output video. If omitted, write next to input as "
+            "<name>_aspect_fixed.mp4."
+        ),
+    )
+    parser.add_argument(
+        "--in-place",
+        action="store_true",
+        help="Overwrite input file in place (uses a temporary file then replaces input).",
+    )
+    parser.add_argument(
+        "--target-size",
+        help="Target size in WIDTHxHEIGHT format, for example 1080x1920.",
+    )
+    parser.add_argument("--target-width", type=int, help="Target width in pixels.")
+    parser.add_argument("--target-height", type=int, help="Target height in pixels.")
+    parser.add_argument(
+        "--env-file",
+        default=str(DEFAULT_ENV_FILE),
+        help=f"Path to .env file (default: {DEFAULT_ENV_FILE}).",
+    )
+    parser.add_argument("--force", action="store_true", help="Overwrite output if it exists.")
+    parser.add_argument("--ffmpeg-bin", default="ffmpeg", help="ffmpeg executable name or path.")
+    parser.add_argument("--ffprobe-bin", default="ffprobe", help="ffprobe executable name or path.")
+    return parser.parse_args()
+
+
+def parse_dotenv_line(content: str, line_no: int, file_path: Path) -> tuple[str, str] | None:
+    stripped = content.strip()
+    if not stripped or stripped.startswith("#"):
+        return None
+    if stripped.startswith("export "):
+        stripped = stripped[7:].strip()
+
+    if "=" not in stripped:
+        raise SystemExit(f"Invalid .env format at {file_path}:{line_no}: missing =")
+
+    key, value = stripped.split("=", 1)
+    key = key.strip()
+    value = value.strip()
+
+    if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", key):
+        raise SystemExit(f"Invalid .env key at {file_path}:{line_no}: {key}")
+
+    if value and value[0] in {"'", '"'}:
+        quote = value[0]
+        if len(value) >= 2 and value[-1] == quote:
+            value = value[1:-1]
+    else:
+        value = value.split(" #", 1)[0].strip()
+
+    return key, value
+
+
+def load_dotenv_file(env_file: Path, override: bool = False) -> bool:
+    if not env_file.exists():
+        return False
+
+    for line_no, line in enumerate(env_file.read_text(encoding="utf-8").splitlines(), start=1):
+        parsed = parse_dotenv_line(line, line_no, env_file)
+        if not parsed:
+            continue
+        key, value = parsed
+        if override or key not in os.environ:
+            os.environ[key] = value
+    return True
+
+
+def parse_size(value: str) -> tuple[int, int]:
+    match = SIZE_PATTERN.fullmatch(value.strip().lower())
+    if not match:
+        raise SystemExit("Invalid size format. Use WIDTHxHEIGHT, for example 1080x1920.")
+    width = int(match.group(1))
+    height = int(match.group(2))
+    if width <= 0 or height <= 0:
+        raise SystemExit("Width and height must be positive integers.")
+    return width, height
+
+
+def required_command(command: str) -> None:
+    if shutil.which(command):
+        return
+    raise SystemExit(f"Missing required command: {command}")
+
+
+def probe_video_size(video_path: Path, ffprobe_bin: str) -> tuple[int, int]:
+    cmd = [
+        ffprobe_bin,
+        "-v",
+        "error",
+        "-select_streams",
+        "v:0",
+        "-show_entries",
+        "stream=width,height",
+        "-of",
+        "json",
+        str(video_path),
+    ]
+    try:
+        result = subprocess.run(cmd, check=True, capture_output=True, text=True)
+    except subprocess.CalledProcessError as exc:
+        stderr = exc.stderr.strip()
+        raise SystemExit(f"ffprobe failed for {video_path}: {stderr}") from exc
+
+    try:
+        payload = json.loads(result.stdout)
+    except json.JSONDecodeError as exc:
+        raise SystemExit(f"Unable to parse ffprobe output for {video_path}.") from exc
+
+    streams = payload.get("streams")
+    if not isinstance(streams, list) or not streams:
+        raise SystemExit(f"No video stream found in {video_path}.")
+
+    first = streams[0]
+    if not isinstance(first, dict):
+        raise SystemExit(f"Unexpected ffprobe stream payload for {video_path}.")
+
+    width = first.get("width")
+    height = first.get("height")
+    if not isinstance(width, int) or not isinstance(height, int) or width <= 0 or height <= 0:
+        raise SystemExit(f"Invalid video dimensions from ffprobe for {video_path}.")
+    return width, height
+
+
+def even_floor(value: int, minimum: int = 2) -> int:
+    floored = value if value % 2 == 0 else value - 1
+    return max(floored, minimum)
+
+
+def build_video_filter(
+    input_width: int,
+    input_height: int,
+    target_width: int,
+    target_height: int,
+) -> tuple[str | None, bool]:
+    same_ratio = input_width * target_height == input_height * target_width
+    same_size = input_width == target_width and input_height == target_height
+
+    if same_ratio and same_size:
+        return None, False
+
+    if same_ratio:
+        return f"scale={target_width}:{target_height}", False
+
+    input_wider = input_width * target_height > input_height * target_width
+    if input_wider:
+        crop_width = input_height * target_width // target_height
+        crop_height = input_height
+    else:
+        crop_width = input_width
+        crop_height = input_width * target_height // target_width
+
+    crop_width = min(even_floor(crop_width), even_floor(input_width))
+    crop_height = min(even_floor(crop_height), even_floor(input_height))
+
+    offset_x = max((input_width - crop_width) // 2, 0)
+    offset_y = max((input_height - crop_height) // 2, 0)
+
+    return f"crop={crop_width}:{crop_height}:{offset_x}:{offset_y},scale={target_width}:{target_height}", True
+
+
+def resolve_target_size(args: argparse.Namespace) -> tuple[int, int]:
+    if args.target_size and (args.target_width is not None or args.target_height is not None):
+        raise SystemExit("Use either --target-size or --target-width/--target-height, not both.")
+
+    if args.target_size:
+        return parse_size(args.target_size)
+
+    env_width = os.getenv("TEXT_TO_SHORT_VIDEO_WIDTH", "").strip()
+    env_height = os.getenv("TEXT_TO_SHORT_VIDEO_HEIGHT", "").strip()
+
+    if args.target_width is not None:
+        width = args.target_width
+    else:
+        try:
+            width = int(env_width or "1080")
+        except ValueError as exc:
+            raise SystemExit("TEXT_TO_SHORT_VIDEO_WIDTH must be an integer.") from exc
+
+    if args.target_height is not None:
+        height = args.target_height
+    else:
+        try:
+            height = int(env_height or "1920")
+        except ValueError as exc:
+            raise SystemExit("TEXT_TO_SHORT_VIDEO_HEIGHT must be an integer.") from exc
+
+    if width <= 0 or height <= 0:
+        raise SystemExit("Target width and height must be positive integers.")
+    return width, height
+
+
+def resolve_output_path(args: argparse.Namespace, input_video: Path) -> Path:
+    if args.in_place and args.output_video:
+        raise SystemExit("Do not pass --output-video with --in-place.")
+
+    if args.in_place:
+        return input_video
+
+    if args.output_video:
+        output_video = Path(args.output_video).expanduser().resolve()
+    else:
+        output_video = input_video.with_name(f"{input_video.stem}_aspect_fixed.mp4")
+
+    if output_video == input_video:
+        raise SystemExit("Output path equals input path. Use --in-place to replace the input file.")
+
+    return output_video
+
+
+def copy_if_needed(source: Path, target: Path, force: bool) -> None:
+    if source == target:
+        return
+    if target.exists() and not force:
+        raise SystemExit(f"Output already exists: {target}. Use --force to overwrite.")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(source, target)
+
+
+def main() -> int:
+    args = parse_args()
+
+    input_video = Path(args.input_video).expanduser().resolve()
+    if not input_video.is_file():
+        raise SystemExit(f"Input video not found: {input_video}")
+
+    env_file = Path(args.env_file).expanduser()
+    if not env_file.is_absolute():
+        env_file = SKILL_DIR / env_file
+    load_dotenv_file(env_file, override=False)
+
+    target_width, target_height = resolve_target_size(args)
+    output_video = resolve_output_path(args, input_video)
+
+    required_command(args.ffmpeg_bin)
+    required_command(args.ffprobe_bin)
+
+    input_width, input_height = probe_video_size(input_video, args.ffprobe_bin)
+    filter_expression, crop_applied = build_video_filter(
+        input_width=input_width,
+        input_height=input_height,
+        target_width=target_width,
+        target_height=target_height,
+    )
+
+    if filter_expression is None:
+        print(
+            f"[INFO] Video already matches target size and aspect ratio: "
+            f"{input_width}x{input_height}."
+        )
+        copy_if_needed(input_video, output_video, args.force)
+        if input_video != output_video:
+            print(f"[OK] Copied original video to: {output_video}")
+        return 0
+
+    replace_in_place = args.in_place
+    if replace_in_place:
+        temp_fd, temp_name = tempfile.mkstemp(
+            prefix=f"{input_video.stem}_aspect_tmp_",
+            suffix=".mp4",
+            dir=str(input_video.parent),
+        )
+        os.close(temp_fd)
+        temp_output = Path(temp_name)
+    else:
+        temp_output = output_video
+        if temp_output.exists() and not args.force:
+            raise SystemExit(f"Output already exists: {temp_output}. Use --force to overwrite.")
+        temp_output.parent.mkdir(parents=True, exist_ok=True)
+
+    ffmpeg_cmd = [
+        args.ffmpeg_bin,
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        "-y" if (args.force or replace_in_place) else "-n",
+        "-i",
+        str(input_video),
+        "-vf",
+        filter_expression,
+        "-map",
+        "0:v:0",
+        "-map",
+        "0:a?",
+        "-c:v",
+        "libx264",
+        "-preset",
+        "medium",
+        "-crf",
+        "18",
+        "-c:a",
+        "aac",
+        "-movflags",
+        "+faststart",
+        str(temp_output),
+    ]
+
+    try:
+        subprocess.run(ffmpeg_cmd, check=True)
+    except subprocess.CalledProcessError as exc:
+        if replace_in_place and temp_output.exists():
+            temp_output.unlink(missing_ok=True)
+        raise SystemExit(f"ffmpeg failed with exit code {exc.returncode}.") from exc
+
+    if replace_in_place:
+        temp_output.replace(input_video)
+        final_output = input_video
+    else:
+        final_output = output_video
+
+    final_width, final_height = probe_video_size(final_output, args.ffprobe_bin)
+    print(
+        f"[OK] Processed video written: {final_output}\n"
+        f"[INFO] Input size: {input_width}x{input_height}\n"
+        f"[INFO] Target size: {target_width}x{target_height}\n"
+        f"[INFO] Output size: {final_width}x{final_height}\n"
+        f"[INFO] Center crop applied: {'yes' if crop_applied else 'no'}"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/version-release/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on Keep a Changelog.
+
+## [0.3.0] - 2026-02-22
+
+### Changed
+
+- Added a default `commit+push only` workflow when users do not explicitly request versioning.
+- Restricted version bump recommendations to explicit user requests instead of proactive suggestions.
+- Updated workflow docs to make release-specific steps conditional on explicit version/tag/release intent.
+
+## [0.2.0] - 2026-02-15
+
+### Changed
+
+- Added an explicit dependency contract requiring `edge-case-test-fixer` then `code-simplifier` for code-affecting releases.
+- Added a docs-only classification path so documentation-only changes can skip both dependency skills.
+- Reordered the submit workflow to run dependency checks before version/changelog/readme/agent document updates.
+
+## [0.1.3] - 2026-02-10
+
+### Changed
+
+- Added explicit guidance to infer and share a preferred semver bump before user confirmation.
+- Required submit prompts to include a recommended target version with a brief rationale.
+- Updated README workflow description to reflect recommendation-first version selection.
+
+## [0.1.2] - 2026-02-07
+
+### Changed
+
+- Unified submit behavior into a single workflow without a mode-selection step.
+- Standardized release scope analysis to always use the last version tag to `HEAD`.
+- Moved `AGENTS.md` synchronization to run before commit and push, aligned with README sync timing.
+- Updated commit staging guidance to include optional `AGENTS.md` changes when applicable.
+
+## [0.1.1] - 2026-02-07
+
+### Changed
+
+- Added a brief introduction section to improve skill onboarding guidance.
+- Clarified submit workflow rules so commit messages are derived from staged diff intent.
+- Prohibited version-only commit subjects such as `feat: vX.Y.Z`.
+- Added release-only commit message guidance and examples in commit message references.
+
+[0.1.1]: https://github.com/LaiTszKin/submit-changes/compare/v0.1.0...v0.1.1
+[0.1.2]: https://github.com/LaiTszKin/submit-changes/compare/v0.1.1...v0.1.2
+[0.1.3]: https://github.com/LaiTszKin/submit-changes/compare/v0.1.2...v0.1.3
+[0.2.0]: https://github.com/LaiTszKin/submit-changes/compare/v0.1.3...v0.2.0
+[0.3.0]: https://github.com/LaiTszKin/submit-changes/compare/v0.2.0...v0.3.0

package/version-release/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lai Tsz Kin
+
+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/version-release/README.md

@@ -0,0 +1,28 @@
+# version-release
+
+A Codex skill for explicit release workflows: code/documentation alignment, version bump, changelog update, tagging, and push.
+
+## What this skill does
+
+`version-release` helps agents perform release work in a repeatable flow:
+
+1. Inspect the release scope from git history.
+2. Run quality gates for code-affecting changes.
+3. Run `specs-to-project-docs` when the release scope contains new completed spec files.
+4. Align project code and categorized project docs.
+5. Resolve version and tag details.
+6. Update version files and changelog.
+7. Commit release metadata.
+8. Create and push the release tag.
+
+## Scope
+
+Use this skill only when the user explicitly asks for:
+
+- release preparation
+- version bumping
+- tag creation/publishing
+
+If the release includes new completed specs, convert them into categorized project docs first and let `specs-to-project-docs` remove or archive the superseded spec files.
+
+If the user only wants commit + push, use `commit-and-push`.