@laitszkin/apollo-toolkit 2.0.0

package/open-source-pr-workflow/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: open-source-pr-workflow
+description: PR-focused workflow for open-source repositories. Use when the user asks to prepare a PR branch from existing changes, draft/open/update a PR, or push a ready contribution branch. Do not use this skill for implementing product features or editing business logic; use it after code changes are already prepared. Enforce branch naming as codex/{change_type}/{changes}, open PRs directly by default without waiting for draft confirmation, show drafts only when the user explicitly asks to review them first, default forked repositories to open PRs against the upstream parent repository unless the user explicitly requests the fork, and write PR content in English by default with required sections for related issues or motivation, engineering decisions with rationale, and test results with commands. For code-affecting changes, run discover-edge-cases first, resolve any confirmed findings, and run code-simplifier before opening the PR.
+---
+
+# Open Source PR Workflow
+
+## Dependencies
+
+- Required: none.
+- Conditional: `discover-edge-cases` and `code-simplifier` for code-affecting PRs before opening the PR.
+- Optional: none.
+- Fallback: If a required code-affecting dependency is unavailable, stop and report the missing dependency instead of bypassing the quality gate.
+
+## Standards
+
+- Evidence: Assume implementation is already prepared, then verify PR scope, repository constraints, and validation commands from the actual change set.
+- Execution: Create a compliant `codex/{change_type}/{changes}` branch, run the required quality gates for code changes, then draft and open the PR.
+- Quality: Target the upstream parent repository by default for forks, keep PR content in English unless requested otherwise, and exclude internal workflow details.
+- Output: Produce a review-ready PR body with motivation, engineering rationale, test commands, and any required issue linkage.
+
+## Overview
+
+Use this workflow to prepare open-source contributions and open review-ready pull requests with consistent branch naming and PR content quality.
+
+## Scope Guardrails
+
+- This skill is for PR preparation and PR creation only.
+- Do not use this skill as the primary workflow for implementing features or fixing code.
+- If code changes are still needed, finish implementation in another workflow first, then return to this skill for PR handling.
+
+## Workflow
+
+### 1) Clarify PR scope
+
+- Identify related issue links/IDs and summarize the motivation for the change.
+- Confirm target base branch and contribution constraints from the repository.
+- Detect whether the current repository is a fork (for example with `gh repo view --json isFork,parent,nameWithOwner`).
+- If it is a fork, default the PR destination repository to the upstream parent repository.
+- Only target the fork repository when the user explicitly asks for it.
+
+### 2) Create a compliant branch name
+
+- Always use this pattern for PR branches: `codex/{change_type}/{changes}`.
+- Convert both `{change_type}` and `{changes}` to lowercase kebab-case (`[a-z0-9-]` only).
+- If the current branch name does not match, create a new compliant branch from current HEAD before opening PR.
+
+Example:
+
+```bash
+git checkout -b codex/fix/add-rate-limit-retry
+```
+
+### 3) Run dependent skills for code-affecting changes
+
+- If the PR includes code changes, run `discover-edge-cases` first to discover unresolved edge-case risks.
+- Resolve any confirmed findings before continuing.
+- Then run `code-simplifier` on the updated changes.
+- Keep both passes minimal and focused on the current PR scope.
+- Use these skills as internal quality gates only; do not include skill/tool names in PR content.
+- If the PR has no code changes, explicitly note that these two skills were not required in internal notes only.
+
+### 4) Verify existing changes (no feature implementation in this skill)
+
+- Assume code/documentation changes are already prepared before entering this workflow.
+- Do not add new feature implementation in this skill.
+- After the dependent skills step (when required), run relevant checks (lint/test/build) based on repository conventions.
+- Record exact test commands and outcomes for PR content.
+
+### 5) Prepare PR content (show draft only on request)
+
+- Draft the PR title and full PR body before creating the PR.
+- Keep PR content strictly about the PR itself (motivation, changes, rationale, tests).
+- Do not include internal workflow details such as skill names, tool names, or agent process notes.
+- By default, proceed directly to PR creation after the title/body are ready.
+- Show the draft only when the user explicitly asks to review it before creating the PR.
+- If the user asks for draft edits, revise accordingly and get final confirmation before creating the PR.
+
+### 6) Open the PR
+
+- Prefer `gh pr create` to open the PR.
+- If the repository is a fork, target the upstream parent repository by default (for example `gh pr create --repo <upstream-owner>/<upstream-repo> --head <fork-owner>:<branch>`).
+- Use the fork as the PR destination only when the user explicitly requests it.
+- Ensure PR title/body are in English by default.
+- Switch language only when the user explicitly requests another language.
+
+## Required PR Body Structure
+
+Use this structure (or equivalent headings) every time:
+
+```markdown
+
+## Related Issues / Motivation
+- Related: #<issue-id> (or link)
+- Why this change is needed
+
+## Engineering Decisions and Rationale
+- Key implementation choices
+- Why each choice was made
+- Trade-offs considered (if applicable)
+
+## Test Results and Commands
+- ✅ `command 1`
+- ✅ `command 2`
+- Summary of outcomes
+
+### Test Cases (for complex changes)
+- Case 1: input/scenario -> expected result
+- Case 2: input/scenario -> expected result
+```
+
+If tests cannot run locally, state why and provide the closest available validation evidence.
+
+## Pre-PR Checklist
+
+- Branch name matches `codex/{change_type}/{changes}`.
+- If the user asked to review the draft, they confirmed the final draft before PR creation.
+- If the repository is a fork, PR destination is the upstream parent unless the user explicitly requested the fork.
+- PR body includes all required sections and focuses only on PR-related context.
+- If code changes exist, run `discover-edge-cases`, resolve confirmed findings, and then run `code-simplifier` before opening the PR.
+- PR body does not mention internal skills/tools or agent workflow notes.
+- Test commands and results are explicitly listed.
+- Language defaults to English unless user requests otherwise.

package/open-source-pr-workflow/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Open Source PR Workflow"
+  short_description: "Prepare and open high-quality OSS PRs"
+  default_prompt: "Use $open-source-pr-workflow to prepare a pull request for an open-source repository from existing changes, ensure branch names follow codex/{change_type}/{changes}, and default forked repositories to open PRs against the upstream parent repository unless the user explicitly asks for the fork. Open PRs directly by default without waiting for draft confirmation, and only show a draft when the user explicitly asks to review it first. Include related issues or motivation, engineering decisions with rationale, and test results with commands. If code changes are involved, run discover-edge-cases first, resolve any confirmed findings, and run code-simplifier before opening the PR. Keep PR content strictly about the PR itself and do not include internal skill or tool process notes. Do not implement new features in this workflow."

package/openai-text-to-image-storyboard/.env.example

@@ -0,0 +1,10 @@
+OPENAI_API_URL=https://api.openai.com/v1
+OPENAI_API_KEY=
+OPENAI_IMAGE_MODEL=gpt-image-1
+OPENAI_IMAGE_RATIO=4:3
+# Optional
+# OPENAI_IMAGE_RATIO=16:9
+# OPENAI_IMAGE_ASPECT_RATIO=16:9
+# OPENAI_IMAGE_SIZE=1024x768
+# OPENAI_IMAGE_QUALITY=medium
+# OPENAI_IMAGE_STYLE=vivid

package/openai-text-to-image-storyboard/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.3.0] - 2026-02-15
+
+### Added
+- Added structured `--prompts-file` object mode with top-level `characters` and `scenes` for recurring character consistency.
+- Added per-scene character description overrides (`character_descriptions`) that only replace the `description` field while keeping a stable character skeleton.
+- Added support for multi-character scene composition by injecting multiple character skeletons in one generated scene prompt.
+
+### Changed
+- Updated skill docs, README, and default agent prompt to require character JSON skeleton workflow for recurring novel characters.
+- CLI values now take precedence over environment variables, including `--api-url` and `--api-key` overrides for API credentials.
+
+## [0.2.0] - 2026-02-14
+
+### Added
+- Added aspect-ratio center-crop post-processing so outputs match the configured ratio even when providers ignore ratio parameters.
+- Added `source_width` and `source_height` metadata in `storyboard.json` when post-processing changes image dimensions.
+
+### Changed
+- Updated docs to clarify ratio-based post-processing behavior and size guidance.
+
+## [0.1.1] - 2026-02-14
+
+### Added
+- Added `--image-size`/`--size` CLI options and `OPENAI_IMAGE_SIZE` env support for providers that require explicit pixel size.
+- Added generated image dimension metadata (`width`, `height`) and optional `image_size` to `storyboard.json`.
+
+### Changed
+- Updated README, SKILL docs, and `.env.example` with size-based guidance when aspect-ratio controls are ignored by a provider.
+
+### Fixed
+- Added post-generation aspect-ratio mismatch detection and warning to highlight when providers ignore `aspect_ratio`.
+
+## [0.1.0] - 2026-02-14
+
+### Added
+- Initial release of the OpenAI text-to-image storyboard skill and generation script.
+- Support for generating ordered storyboard images and `storyboard.json` from direct prompts or a JSON prompts file.
+- OpenAI-compatible image generation support via `/images/generations` with configurable model, ratio, quality, and style.
+
+### Changed
+- Clarified skill workflow so the agent starts image generation immediately after receiving article or chapter content.
+- Updated usage docs and agent default prompt to reflect the expected execution flow.
+
+### Fixed
+- Default `.env` loading now points to this skill folder instead of the target project directory.

package/openai-text-to-image-storyboard/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tszkinlai
+
+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/openai-text-to-image-storyboard/README.md

@@ -0,0 +1,99 @@
+# OpenAI Text to Image Storyboard
+
+Generate storyboard images in batch via an OpenAI-compatible Image Generation API.
+
+Workflow: the agent first decides which prompts are needed, then this tool sends prompts to `/images/generations` and writes outputs to `pictures/<content_name>/`.
+
+## Agent execution rules
+
+- As soon as article/chapter content is available, split scenes and run the script immediately.
+- Do not stop in suggestion-only mode unless mandatory inputs are missing (for example output project path or content name).
+- Always provide prompts via `--prompts-file` in JSON format.
+- Define `roles.json` schemas in `video-production` or `novel-to-short-video`; do not duplicate role-schema docs in this skill.
+
+## Features
+
+- Reads `.env` from the skill folder by default (override with `--env-file`)
+- CLI parameters always override environment variables (including `--api-url`, `--api-key`)
+- Loads JSON prompts in one pass via `--prompts-file`
+- Outputs images in order: `01_*.png`, `02_*.png`, ...
+- Generates `storyboard.json` as input/output record
+- Auto-appends `_2`, `_3`, ... when filename collisions exist
+
+## Requirements
+
+- Python 3.9+
+- Access to an OpenAI-compatible API endpoint
+
+## Quick start
+
+1. Copy env template in the skill folder
+
+```bash
+cp .env.example .env
+```
+
+2. Edit `.env`
+
+```dotenv
+OPENAI_API_URL=https://api.openai.com/v1
+OPENAI_API_KEY=your_api_key_here
+OPENAI_IMAGE_MODEL=gpt-image-1
+# Optional
+# OPENAI_IMAGE_RATIO=16:9
+# OPENAI_IMAGE_ASPECT_RATIO=16:9
+# OPENAI_IMAGE_SIZE=1024x768
+# OPENAI_IMAGE_QUALITY=medium
+# OPENAI_IMAGE_STYLE=vivid
+```
+
+> Both `OPENAI_IMAGE_RATIO` and `OPENAI_IMAGE_ASPECT_RATIO` are supported; `OPENAI_IMAGE_RATIO` is preferred.  
+> If a ratio is provided, the script performs center-crop post-processing to match it.  
+> If provider ignores `aspect_ratio`, use `OPENAI_IMAGE_SIZE` (for example `1024x768`).  
+> By default, the script reads `/Users/tszkinlai/.codex/skills/openai-text-to-image-storyboard/.env`.
+
+3. Run with JSON prompt file
+
+```bash
+python scripts/generate_storyboard_images.py \
+  --project-dir /path/to/project \
+  --env-file /Users/tszkinlai/.codex/skills/openai-text-to-image-storyboard/.env \
+  --content-name "1_chapter_title" \
+  --prompts-file /path/to/prompts.json
+```
+
+Example `prompts.json`:
+
+```json
+[
+  {
+    "title": "Rain Chase",
+    "prompt": "cinematic rain-soaked alley, tense running pose, blue neon reflections, dramatic rim light"
+  },
+  {
+    "title": "Underground Archive",
+    "prompt": "ancient underground library, floating dust in warm volumetric light, mysterious atmosphere"
+  }
+]
+```
+
+If you need multi-character continuity with `roles.json` and structured JSON role specs, refer to `video-production` or `novel-to-short-video`.
+
+## Important parameters
+
+- `--aspect-ratio`: overrides ratio in `.env` (for example `16:9`, `4:3`) and applies center-crop before output
+- `--image-size` / `--size`: explicit pixel size (for example `1024x768`); useful for providers that only support `size`
+- `--api-url` / `--api-key`: directly override `OPENAI_API_URL` / `OPENAI_API_KEY`
+- If no ratio is provided, model/provider default size is used
+
+## Output
+
+Output paths:
+
+- `pictures/<content_name>/01_<title>.png`
+- `pictures/<content_name>/02_<title>.png`
+- `pictures/<content_name>/storyboard.json`
+
+## License
+
+MIT, see [LICENSE](LICENSE).

package/openai-text-to-image-storyboard/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: openai-text-to-image-storyboard
+description: Generate storyboard images by using agent-decided prompts and calling an OpenAI-compatible image generation API. Use when users want chapters, novels, articles, or scripts converted into image sets under pictures/{content_name}, with API URL and API key loaded from this skill folder's .env by default.
+---
+
+# OpenAI Text to Image Storyboard
+
+## Dependencies
+
+- Required: none.
+- Conditional: none.
+- Optional: none.
+- Fallback: not applicable.
+
+## Standards
+
+- Evidence: Generate prompts from the supplied content and require only the minimal mandatory inputs such as project path and content name.
+- Execution: Convert scenes into valid JSON prompts, load the skill-local `.env`, and call the storyboard generator in the same turn whenever possible.
+- Quality: Keep prompts and outputs in narrative order, use only `/images/generations`, and leave role-schema management to the video orchestration skills.
+- Output: Write images plus `storyboard.json` under `pictures/<content_name>/` without overwriting existing filenames.
+
+## Overview
+
+Let the agent decide which images are needed from the text, then call only `/images/generations` to render them.
+Always save outputs in `pictures/<content_name>/` (example: `pictures/1_chapter_title/`).
+
+## Workflow
+
+1. Read user text and decide the target scenes in the agent.
+2. Convert scene prompts into a JSON prompt file (`prompts.json`).
+3. As soon as article/chapter content is available, directly run the script (do not stop at suggestion-only mode).
+4. Use this skill folder's `.env` first, then call `/images/generations` to render images.
+5. Save files in narrative order and write `storyboard.json`.
+
+## Agent Execution Requirement
+
+- After receiving article/chapter/script content, immediately enter generation flow.
+- Convert content into scene prompts and execute the Python script in the same turn whenever possible.
+- Only ask follow-up questions when mandatory inputs are missing (for example: no output project path or no content name).
+- Always provide prompts through `--prompts-file` with valid JSON.
+- Do not define `roles.json` schema in this skill; role schema details belong to `video-production` or `novel-to-short-video`.
+
+## Environment Configuration
+
+Create `.env` in this skill folder (default path used by script):
+
+- `/Users/tszkinlai/.codex/skills/openai-text-to-image-storyboard/.env`
+
+You can still override via `--env-file` when needed.
+All CLI parameters take priority over environment variables.
+
+- `OPENAI_API_URL` (required)
+- `OPENAI_API_KEY` (required)
+- `OPENAI_IMAGE_MODEL` (optional, default `gpt-image-1`)
+- `OPENAI_IMAGE_RATIO` (optional, e.g. `16:9` / `4:3`; recommended)
+- `OPENAI_IMAGE_ASPECT_RATIO` (optional fallback alias)
+- `OPENAI_IMAGE_SIZE` (optional, e.g. `1024x768`, for providers that expect `size`)
+- `OPENAI_IMAGE_QUALITY` (optional)
+- `OPENAI_IMAGE_STYLE` (optional)
+
+A template is provided at:
+- `/Users/tszkinlai/.codex/skills/openai-text-to-image-storyboard/.env.example`
+
+## Command
+
+Use JSON prompt file:
+
+```bash
+python /Users/tszkinlai/.codex/skills/openai-text-to-image-storyboard/scripts/generate_storyboard_images.py \
+  --project-dir /path/to/project \
+  --env-file /Users/tszkinlai/.codex/skills/openai-text-to-image-storyboard/.env \
+  --content-name "1_chapter_title" \
+  --prompts-file /path/to/prompts.json
+```
+
+`prompts.json` format:
+
+```json
+[
+  {
+    "title": "Rain Chase",
+    "prompt": "cinematic rain-soaked alley, tense running pose, blue neon reflections, dramatic rim light"
+  },
+  {
+    "title": "Underground Archive",
+    "prompt": "ancient underground library, floating dust in warm volumetric light, mysterious atmosphere"
+  }
+]
+```
+
+Notes:
+
+- `prompts.json` must be valid JSON.
+- For role-related schema (`roles.json` and recurring-role definitions), follow `video-production` or `novel-to-short-video`.
+- If the provider ignores `aspect_ratio`, pass `--image-size 1024x768` or set `OPENAI_IMAGE_SIZE=1024x768`.
+- You can pass `--api-url` and `--api-key` to override `OPENAI_API_URL` and `OPENAI_API_KEY`.
+- When an aspect ratio is set, the script applies center-crop post-processing so outputs still match the target ratio.
+
+## Output Convention
+
+Generated files:
+
+- `pictures/1_chapter_title/01_rain_chase.png`
+- `pictures/1_chapter_title/02_underground_archive.png`
+- `pictures/1_chapter_title/storyboard.json`
+
+If a filename already exists, the script appends `_2`, `_3`, etc. to avoid overwriting.

package/openai-text-to-image-storyboard/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "OpenAI Text to Image Storyboard"
+  short_description: "Generate image sets from agent-decided prompts"
+  default_prompt: "Use $openai-text-to-image-storyboard to decide scene prompts from text and generate images into pictures/{content_name}/ as soon as content is available. Always provide prompts through a JSON prompts file and run image generation directly when required inputs are present. Load API settings from /Users/tszkinlai/.codex/skills/openai-text-to-image-storyboard/.env by default."