@laitszkin/apollo-toolkit 2.0.0

package/lib/installer.js

@@ -0,0 +1,225 @@
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+
+const VALID_MODES = ['codex', 'openclaw', 'trae'];
+const COPY_FILES = new Set(['AGENTS.md', 'CHANGELOG.md', 'LICENSE', 'README.md', 'package.json']);
+const COPY_DIRS = new Set(['scripts']);
+
+function resolveHomeDirectory(env = process.env) {
+  return env.HOME || env.USERPROFILE || os.homedir();
+}
+
+function resolveToolkitHome(env = process.env) {
+  if (env.APOLLO_TOOLKIT_HOME) {
+    return path.resolve(env.APOLLO_TOOLKIT_HOME);
+  }
+
+  return path.join(resolveHomeDirectory(env), '.apollo-toolkit');
+}
+
+function normalizeModes(inputModes) {
+  const modes = [];
+
+  for (const rawMode of inputModes) {
+    const mode = String(rawMode).toLowerCase();
+    if (mode === 'all') {
+      for (const candidate of VALID_MODES) {
+        if (!modes.includes(candidate)) {
+          modes.push(candidate);
+        }
+      }
+      continue;
+    }
+
+    if (!VALID_MODES.includes(mode)) {
+      throw new Error(`Invalid mode: ${rawMode}`);
+    }
+
+    if (!modes.includes(mode)) {
+      modes.push(mode);
+    }
+  }
+
+  return modes;
+}
+
+async function listSkillNames(rootDir) {
+  const entries = await fsp.readdir(rootDir, { withFileTypes: true });
+  const skillNames = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+
+    if (fs.existsSync(path.join(rootDir, entry.name, 'SKILL.md'))) {
+      skillNames.push(entry.name);
+    }
+  }
+
+  return skillNames.sort();
+}
+
+function shouldCopyEntry(sourceRoot, entry) {
+  if (entry.isFile()) {
+    return COPY_FILES.has(entry.name);
+  }
+
+  if (!entry.isDirectory()) {
+    return false;
+  }
+
+  if (COPY_DIRS.has(entry.name)) {
+    return true;
+  }
+
+  return fs.existsSync(path.join(sourceRoot, entry.name, 'SKILL.md'));
+}
+
+async function stageToolkitContents({ sourceRoot, destinationRoot, version }) {
+  const entries = await fsp.readdir(sourceRoot, { withFileTypes: true });
+  const copiedEntries = [];
+
+  await fsp.mkdir(destinationRoot, { recursive: true });
+
+  for (const entry of entries) {
+    if (!shouldCopyEntry(sourceRoot, entry)) {
+      continue;
+    }
+
+    const sourcePath = path.join(sourceRoot, entry.name);
+    const destinationPath = path.join(destinationRoot, entry.name);
+    await fsp.cp(sourcePath, destinationPath, { recursive: true, force: true });
+    copiedEntries.push(entry.name);
+  }
+
+  const metadata = {
+    version,
+    installedAt: new Date().toISOString(),
+    source: 'npm-package',
+  };
+  await fsp.writeFile(
+    path.join(destinationRoot, '.apollo-toolkit-install.json'),
+    `${JSON.stringify(metadata, null, 2)}\n`,
+    'utf8',
+  );
+
+  return copiedEntries.sort();
+}
+
+async function syncToolkitHome({ sourceRoot, toolkitHome, version }) {
+  const parentDir = path.dirname(toolkitHome);
+  const tempDir = path.join(parentDir, `.apollo-toolkit.tmp-${process.pid}-${Date.now()}`);
+
+  await fsp.rm(tempDir, { recursive: true, force: true });
+  await stageToolkitContents({ sourceRoot, destinationRoot: tempDir, version });
+
+  const stat = await fsp.lstat(toolkitHome).catch(() => null);
+  if (stat && !stat.isDirectory()) {
+    throw new Error(`Apollo Toolkit home exists but is not a directory: ${toolkitHome}`);
+  }
+
+  await fsp.rm(toolkitHome, { recursive: true, force: true });
+  await fsp.mkdir(parentDir, { recursive: true });
+  await fsp.rename(tempDir, toolkitHome);
+
+  return {
+    toolkitHome,
+    skillNames: await listSkillNames(toolkitHome),
+  };
+}
+
+async function getTargetRoots(modes, env = process.env) {
+  const homeDir = resolveHomeDirectory(env);
+  const targets = [];
+
+  for (const mode of normalizeModes(modes)) {
+    if (mode === 'codex') {
+      targets.push({
+        mode,
+        label: 'Codex',
+        root: env.CODEX_SKILLS_DIR || path.join(homeDir, '.codex', 'skills'),
+      });
+      continue;
+    }
+
+    if (mode === 'trae') {
+      targets.push({
+        mode,
+        label: 'Trae',
+        root: env.TRAE_SKILLS_DIR || path.join(homeDir, '.trae', 'skills'),
+      });
+      continue;
+    }
+
+    if (mode === 'openclaw') {
+      const openclawHome = env.OPENCLAW_HOME || path.join(homeDir, '.openclaw');
+      const entries = await fsp.readdir(openclawHome, { withFileTypes: true }).catch(() => []);
+      const workspaceNames = entries
+        .filter((entry) => entry.isDirectory() && entry.name.startsWith('workspace'))
+        .map((entry) => entry.name)
+        .sort();
+
+      if (workspaceNames.length === 0) {
+        throw new Error(`No workspace directories found under: ${openclawHome}`);
+      }
+
+      for (const workspaceName of workspaceNames) {
+        targets.push({
+          mode,
+          label: `OpenClaw (${workspaceName})`,
+          root: path.join(openclawHome, workspaceName, 'skills'),
+        });
+      }
+    }
+  }
+
+  return targets;
+}
+
+async function ensureDirectory(dirPath) {
+  await fsp.mkdir(dirPath, { recursive: true });
+}
+
+async function replaceWithSymlink(sourcePath, targetPath) {
+  await fsp.rm(targetPath, { recursive: true, force: true });
+  await ensureDirectory(path.dirname(targetPath));
+
+  const type = process.platform === 'win32' ? 'junction' : 'dir';
+  await fsp.symlink(sourcePath, targetPath, type);
+}
+
+async function installLinks({ toolkitHome, modes, env = process.env }) {
+  const skillNames = await listSkillNames(toolkitHome);
+  const targets = await getTargetRoots(modes, env);
+  const linkedPaths = [];
+
+  for (const target of targets) {
+    await ensureDirectory(target.root);
+    for (const skillName of skillNames) {
+      const sourcePath = path.join(toolkitHome, skillName);
+      const targetPath = path.join(target.root, skillName);
+      await replaceWithSymlink(sourcePath, targetPath);
+      linkedPaths.push({ target: target.label, path: targetPath, skillName });
+    }
+  }
+
+  return {
+    skillNames,
+    targets,
+    linkedPaths,
+  };
+}
+
+module.exports = {
+  VALID_MODES,
+  getTargetRoots,
+  installLinks,
+  listSkillNames,
+  normalizeModes,
+  resolveHomeDirectory,
+  resolveToolkitHome,
+  syncToolkitHome,
+};

package/maintain-project-constraints/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: maintain-project-constraints
+description: Automatically create and maintain AGENTS.md so it stays aligned with the current repository architecture, core business flow, project purpose, and coding conventions. Use when AGENTS.md is missing or may be outdated after code changes.
+---
+
+# Maintain Project Constraints
+
+## Dependencies
+
+- Required: none.
+- Conditional: none.
+- Optional: none.
+- Fallback: not applicable.
+
+## Standards
+
+- Evidence: Infer repository architecture, business flow, and conventions from current code and docs rather than assumptions.
+- Execution: Create or align `AGENTS.md` only after building a concrete inventory of implemented capabilities.
+- Quality: Keep every statement traceable, remove stale guidance, and ensure `Core business flow` stays exhaustive and concrete.
+- Output: Maintain a concise root-level `AGENTS.md` with the required sections and repository-specific wording.
+
+## Goal
+
+Keep `AGENTS.md` accurate, actionable, and synchronized with the latest state of the repository.
+
+## Trigger Conditions
+
+Invoke this skill when either condition is true:
+
+1. `AGENTS.md` does not exist and the user needs this repository to expose agent-facing guidance.
+2. `AGENTS.md` exists but may have drifted after code changes, refactors, or workflow updates.
+
+After completing any code modification task, proactively run this skill to verify `AGENTS.md` is still aligned, and update it if needed.
+
+## Required Outputs
+
+`AGENTS.md` must include these sections (use concise, repository-specific content):
+
+- Project architecture
+- Core business flow
+- Core project purpose
+- Code style and coding conventions
+
+For the `Core business flow` section, always use this format:
+
+1. One short sentence that summarizes what the repository currently enables.
+2. An exhaustive unordered list of the repository's current existing functions/capabilities.
+3. Each bullet must be a short capability statement, preferably in the style of `- Users can ...` or the repository-equivalent actor phrasing.
+
+Example:
+
+```markdown
+
+## Core Business Flow
+
+This project enables users to manage and run reusable automation workflows.
+
+- Users can create a workflow from a local template.
+- Users can update an existing workflow configuration.
+- Users can validate workflow inputs before execution.
+- Users can run the workflow and inspect the result.
+```
+
+## Workflow
+
+### 1) Build factual understanding first
+
+- Confirm whether `AGENTS.md` exists.
+- Read the repository before writing:
+  - root docs (`README`, contribution docs, design docs)
+  - key source directories and entry points
+  - user-facing features such as commands, routes, workflows, tasks, or installable modules
+  - representative modules that show coding patterns
+  - test directories and tooling/config files
+- Infer architecture and conventions from real code, not assumptions.
+- Build a concrete inventory of all currently implemented capabilities before drafting `Core business flow`.
+
+### 2) Create AGENTS.md when missing
+
+When `AGENTS.md` is absent:
+
+- Create a new root-level `AGENTS.md`.
+- Document architecture, business flow, purpose, and coding conventions from observed facts.
+- Write `Core business flow` as one summary sentence followed by unordered bullets that cover every current capability found in the repository.
+- Keep language specific to this repository; avoid generic boilerplate.
+
+### 3) Align AGENTS.md when drift is detected
+
+When `AGENTS.md` exists but is outdated:
+
+- Re-read changed or high-impact modules.
+- Update only sections that no longer match reality.
+- Expand or trim the `Core business flow` bullet list so it still covers all currently implemented capabilities.
+- Preserve correct existing content and structure where possible.
+
+### 4) Quality checks before finishing
+
+- Ensure every statement in `AGENTS.md` is traceable to current repository files.
+- Remove stale paths, renamed components, and obsolete workflows.
+- Verify the `Core business flow` section includes a one-sentence summary plus unordered bullets for all currently existing capabilities; do not leave major functions unlisted.
+- Keep instructions concise, concrete, and operational for future agents.
+
+## Writing Rules
+
+- Use clear headings and short bullet points.
+- Prefer repository terms already used in code/docs.
+- Do not include speculative architecture claims.
+- In `Core business flow`, prefer many short bullets over a few vague bullets; when the product grows, add more bullets so the list remains exhaustive.
+- Keep the document focused on how agents should understand and operate in this project.

package/maintain-project-constraints/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Maintain Project Constraints"
+  short_description: "Automatically create and maintain AGENTS.md so it stays aligned with the current repository architecture, core business flow, project purpose, and coding conventions. Use when AGENTS.md is missing or may be outdated after code changes."
+  default_prompt: "Use $maintain-project-constraints to automatically create and maintain AGENTS.md so it stays aligned with the current repository architecture, core business flow, project purpose, and coding conventions. Use when AGENTS.md is missing or may be outdated after code changes."

package/maintain-skill-catalog/README.md

@@ -0,0 +1,18 @@
+# maintain-skill-catalog
+
+Maintain a repository of installable skills by auditing skill definitions, dependency declarations, shared conventions, and catalog validation.
+
+## Core capabilities
+
+- Scans top-level skills before adding or splitting new ones to avoid duplicate scope.
+- Audits standardized `## Dependencies` sections and separates vendored, local-only, external, and alias dependencies.
+- Syncs catalog docs such as `README.md` and `AGENTS.md` with actual skill capabilities.
+- Catches catalog-wide validation issues like missing `agents/openai.yaml` files or stale prompt references.
+- Encodes user corrections into durable catalog rules so the same classification mistakes do not repeat.
+
+## Typical triggers
+
+- Standardize all skills to one dependency format.
+- Check which skills rely on external skills and document how to install them.
+- Split repeated workflow steps into a new shared skill.
+- Fix skill-catalog CI failures caused by missing metadata or agent config files.

package/maintain-skill-catalog/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: maintain-skill-catalog
+description: Audit and maintain a repository of installable skills so the catalog stays internally consistent. Use when users ask to standardize `SKILL.md` structure across many skills, classify internal vs external skill dependencies, sync skill lists and external dependency docs, extract shared workflows into new skills, or fix catalog-wide validation/agent-config issues.
+---
+
+# Maintain Skill Catalog
+
+## Dependencies
+
+- Required: none.
+- Conditional: `find-skills` when a dependency is external and the installation source is unknown.
+- Optional: `skill-creator` when splitting a repeated workflow into a new shared skill or significantly reshaping an existing skill.
+- Fallback: If an external dependency cannot be verified, leave it undocumented rather than guessing the package name or install command.
+
+## Standards
+
+- Evidence: Read the actual skill folders, validation scripts, repository docs, and local installed skill names before changing dependency classifications or catalog docs.
+- Execution: Audit first, classify findings, make focused catalog updates, then run the repo validators before finishing.
+- Quality: Avoid duplicate skills, avoid rewording behavior without checking the implementation, and distinguish aliases or local unpublished skills from true external dependencies.
+- Output: Leave the catalog with synchronized skill metadata, dependency documentation, and validation status.
+
+## Goal
+
+Keep a skill repository coherent when many top-level skills evolve together.
+
+## Workflow
+
+### 1) Inventory the catalog before editing
+
+- List the tracked top-level skill directories and read the relevant `SKILL.md` files before deciding that a new skill is needed.
+- Check whether the requested workflow already exists under another name or can be handled by a focused update.
+- Read current `README.md`, `AGENTS.md`, validator scripts, and any existing dependency notes that may need synchronization.
+- When the task involves external dependencies, inspect local installed skills under `~/.codex/skills` first to confirm the exact skill names.
+
+### 2) Audit dependency declarations and shared conventions
+
+- Use the standardized `## Dependencies` section as the source of truth for skill-to-skill relationships.
+- Classify each dependency as:
+  - vendored in this repository
+  - local/private skill that should not be documented as external
+  - external skill that needs install guidance
+  - alias/compatibility name that should be explained but not treated as a separate dependency
+- Verify exact external skill names before editing docs; do not invent pluralizations or package names.
+- If multiple skills repeat the same workflow, prefer extracting that shared portion into a dedicated skill instead of duplicating instructions.
+
+### 3) Update catalog docs and skill metadata carefully
+
+- Keep edits minimal and repo-wide only where necessary.
+- Update `README.md` skill lists and external dependency sections when the catalog actually changes.
+- Update `AGENTS.md` when the repository gains or loses a user-visible capability or a standing convention changes.
+- When creating a new shared skill, align naming, frontmatter, `agents/openai.yaml`, and any lightweight README with neighboring skills.
+- Do not treat unpublished local skills as external dependencies just because they are not yet installed elsewhere.
+
+### 4) Validate the catalog after changes
+
+- Run:
+  - `python3 scripts/validate_skill_frontmatter.py`
+  - `python3 scripts/validate_openai_agent_config.py`
+- If the change touched installer or repo-discovery behavior, verify the relevant install scripts or discovery logic as well.
+- Resolve validation failures before finishing; missing `agents/openai.yaml`, stale prompt references, and mismatched skill names are catalog bugs, not follow-up work.
+
+### 5) Record conclusions explicitly
+
+- Summarize which skills were audited, which conventions were updated, and which dependencies were confirmed as external.
+- Call out any unresolved unknowns, such as an external dependency whose install source could not be verified.
+- When a user correction changes the catalog rules, encode that rule in the skill or repository docs so the same mistake does not recur.

package/maintain-skill-catalog/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "maintain-skill-catalog"
+  short_description: "Audit and keep a skill repository consistent"
+  default_prompt: "Use $maintain-skill-catalog to audit top-level skills, classify internal versus external dependencies, sync catalog docs, extract repeated workflows into shared skills when justified, and run repository validators before finishing."

package/novel-to-short-video/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.3.1] - 2026-02-18
+
+### Changed
+- Require narration pacing target of 3-4 CJK chars/second in the short-video workflow and planning documents.
+- Add post-generation pacing validation loop for voice assets using timeline duration and character count.
+- Update README and default agent prompt so voice generation explicitly enforces short-video speech rhythm.
+
+## [0.3.0] - 2026-02-17
+
+### Changed
+- Move shared role registry path to `<project_dir>/roles/roles.json` and align workflow docs/prompt references.
+- Require pre-production plans to include beat-level audience-focus special-effect cues and intensity guardrails.
+- Expand Remotion composition workflow to load animation/light-leak guidance and apply controlled effects across hook, escalation, climax, and loop-closure beats.
+- Update README, output contract, and default agent prompt to explicitly include attention-retention special effects in final video production.
+- Update plan template with per-beat `focus effect` fields and an `Audience Focus Effects` section.
+
+## [0.2.2] - 2026-02-17
+
+### Changed
+- Add required workflow step to create `<project_dir>/pictures/<content_name>/roles.json` before image generation.
+- Require `roles.json` to store recurring character prompt skeletons with the `openai-text-to-image-storyboard` schema.
+- Require role prompt reuse: read existing `roles.json` first and reuse matched roles.
+- Only append new role prompts when required roles are missing, instead of recreating all role entries.
+- Update README, output contract, quality checklist, and default agent prompt to include roles file handling.
+
+## [0.2.1] - 2026-02-16
+
+### Changed
+- Strengthen selection criteria to require a standalone mini-story arc plus lingering-question potential.
+- Update plan template with standalone-story basis, lingering question, and story satisfaction checks.
+- Update README and default agent prompt to explicitly enforce "complete yet still curiosity-inducing" narrative outcomes.
+
+## [0.2.0] - 2026-02-16
+
+### Changed
+- Replace 3-scene extraction with single highlight-segment extraction for stronger short-video focus.
+- Update planning template to a single-segment structure with beat-level timing and asset planning.
+- Align skill workflow, quality gate checklist, README, and agent default prompt with the 50-60 second single-segment pipeline.
+
+## [0.1.0] - 2026-02-16
+
+### Added
+- Require a pre-production plan markdown before generation, including scenes, per-scene scripts, and image lists.
+- Add `references/plan-template.md` as the canonical plan template with bracketed placeholders.
+- Add workflow gate requiring explicit user approval of the plan before image, voice, and render steps.
+
+### Changed
+- Update skill workflow numbering and quality checks to enforce plan-first execution.
+- Update README and default agent prompt to match the new plan approval flow.

package/novel-to-short-video/LICENSE

@@ -0,0 +1,21 @@
+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/novel-to-short-video/README.md

@@ -0,0 +1,63 @@
+# novel-to-short-video
+
+A Codex skill that converts novel content into a 50-60 second loopable short video.
+
+This skill will:
+
+- Select exactly one highest-impact, high-tension core segment from the novel
+- Ensure the selected segment forms a complete mini-story that works standalone
+- Keep one meaningful unresolved hook at the end to sustain curiosity
+- Create a pre-production plan first using `references/plan-template.md` (`docs/plans/<date>-<chapter>.md`)
+- Start image/voice/render steps only after explicit user approval of the plan
+- Generate a loop-closure narration script (opening and ending call back to each other)
+- Ensure `<project_dir>/roles/roles.json` exists before prompt generation; reuse existing roles and append only missing roles (schema in `references/roles-json.md`)
+- Generate scene images via text-to-image
+- Generate narration audio and subtitles
+- Enforce narration pacing to 3-4 CJK chars per second
+- Assemble and render with Remotion, apply beat-level focus effects, and keep the Remotion project for further edits
+
+## Dependency skills
+
+- `openai-text-to-image-storyboard`
+- `docs-to-voice`
+- `remotion-best-practices`
+
+## Repository layout
+
+```text
+novel-to-short-video/
+├── SKILL.md
+├── agents/
+│   └── openai.yaml
+├── references/
+│   ├── plan-template.md
+│   └── roles-json.md
+├── README.md
+└── LICENSE
+```
+
+## Usage
+
+1. Place this folder under your Codex skills directory.
+2. Trigger it in chat with `$novel-to-short-video`.
+3. Provide `project_dir`, `content_name`, and novel content.
+4. The skill first generates a plan markdown under `docs/plans/` and waits for your approval.
+5. After approval, it generates images, narration, subtitles, and the final short video.
+
+## Output guarantees
+
+- Each short video stays within **50-60 seconds**
+- Narration pacing remains **3-4 chars/sec** (validated by char count ÷ audio duration)
+- Exactly **one** highest-impact core segment is selected
+- One segment maps to one full video (segment-to-video 1:1)
+- Story is standalone (clear setup/conflict/turn/outcome) with one unresolved ending question
+- Plan file is created first: `<project_dir>/docs/plans/<YYYY-MM-DD>-<chapter_slug>.md`
+- Plan uses `references/plan-template.md`, and all placeholders are removed after filling
+- Role registry file: `<project_dir>/roles/roles.json` (shared between short-form and long-form workflows, reuses existing roles, appends only missing roles; schema in `references/roles-json.md`)
+- Ending line and final visuals tie back to the opening for loop closure
+- Beat-level effects are applied (`hook / escalation / climax / loop-closure`) with controlled intensity to avoid harming subtitle readability
+- Remotion project is preserved by default for manual refinement
+
+## License
+
+This project is licensed under the [MIT License](./LICENSE).