@laitszkin/apollo-toolkit 2.12.4 → 2.12.6

package/AGENTS.md

@@ -58,6 +58,16 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can prepare and publish versioned releases with changelog and tag workflows.
 - Users can generate long-form videos by orchestrating storyboard, voice, and Remotion-based production steps.
 
+## Common Commands
+
+- `npm test` - 執行 Node 測試套件。
+- `node bin/apollo-toolkit.js` - 直接從倉庫啟動 Apollo Toolkit CLI。
+- `node bin/apollo-toolkit.js codex openclaw trae` - 以非互動方式將技能安裝到指定目標。
+- `python3 scripts/validate_skill_frontmatter.py` - 驗證所有頂層技能 `SKILL.md` 的 frontmatter。
+- `python3 scripts/validate_openai_agent_config.py` - 驗證所有技能 `agents/openai.yaml` 設定。
+- `./scripts/install_skills.sh codex` - 用本地安裝腳本把技能安裝到 Codex 目錄。
+- `./scripts/install_skills.sh all` - 用本地安裝腳本同步安裝到所有支援目標。
+
 ## Core Project Purpose
 
 - Provide a curated set of reusable agent skills that can be installed into Codex/OpenClaw/Trae skill directories.

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.12.6] - 2026-04-02
+
+### Added
+- Add the global `apltk` CLI alias so the Apollo Toolkit installer can be launched with a shorter command after npm installation.
+
+### Changed
+- Update `develop-new-features` and `enhance-existing-features` so any spec-backed change affecting more than three modules must be split into independent, non-conflicting, non-dependent spec sets.
+- Expand `commit-and-push` with stricter worktree replay and cleanup rules so temporary worktree delivery verifies the authoritative target branch before removing the worktree.
+- Strengthen `production-sim-debug` so protocol-sensitive simulation claims must be checked against official docs or upstream source, and infeasible local-simulation designs must be collapsed quickly instead of left as pending implementation.
+- Update the Apollo Toolkit CLI so interactive global runs can start from `apltk`, check npm for newer published packages, and offer an in-place global update before continuing.
+
+### Fixed
+- Fix updater version comparison so prerelease builds such as `2.12.5-beta.1` no longer suppress available stable-release upgrade prompts.
+
+## [v2.12.5] - 2026-04-01
+
+### Changed
+- Update `maintain-project-constraints` so generated `AGENTS.md` templates must include a factual `Common Commands` section grounded in repository-owned command entry points such as CLIs, package scripts, and task runners.
+- Refresh the Apollo Toolkit root `AGENTS.md` guidance with repository-specific common commands for the local CLI, validation scripts, tests, and install flows.
+
 ## [v2.12.4] - 2026-04-01
 
 ### Added

package/README.md

@@ -70,9 +70,12 @@ The interactive installer:
 
 ```bash
 npm i -g @laitszkin/apollo-toolkit
+apltk
 apollo-toolkit
 ```
 
+Global install 後，`apltk` 與 `apollo-toolkit` 都會啟動同一個 Apollo Toolkit CLI。直接執行 `apltk` 會打開互動安裝頁，並在互動模式下先檢查 npm registry 是否有新版可用；若有，CLI 會先詢問，再自動執行全域更新。
+
 ### Non-interactive install
 
 ```bash

package/commit-and-push/SKILL.md

@@ -15,7 +15,7 @@ description: "Guide the agent to submit local changes with commit and push only
 ## Standards
 
 - Evidence: Inspect git state and classify the change set before deciding which quality gates apply, then compare the actual pending diff against root `CHANGELOG.md` `Unreleased` before committing.
-- Execution: Run the required quality-gate skills when applicable, and treat every conditional gate whose scenario is met as blocking before submission; hand the repository to `submission-readiness-check` for changelog/docs/plan finalization, preserve staging intent, honor any explicit user-specified target branch, and when the worktree is already clean inspect local `HEAD`, upstream state, and the most recent relevant commit before deciding the request is a no-op; then commit and push without release steps; run dependent git mutations sequentially and verify the remote branch actually contains the new local `HEAD` before reporting success.
+- Execution: Run the required quality-gate skills when applicable, and treat every conditional gate whose scenario is met as blocking before submission; hand the repository to `submission-readiness-check` for changelog/docs/plan finalization, preserve staging intent, honor any explicit user-specified target branch, and when the worktree is already clean inspect local `HEAD`, upstream state, and the most recent relevant commit before deciding the request is a no-op; when worktree-based delivery is involved, verify where the authoritative target branch lives before moving history, re-validate on that target branch after replay or merge, and remove the temporary worktree only after the target branch is safely updated; then commit and push without release steps; run dependent git mutations sequentially and verify the remote branch actually contains the new local `HEAD` before reporting success.
 - Quality: Re-run relevant validation for runtime changes, preserve unrelated local work safely when branch switching or post-push local sync is required, and do not bypass blocking readiness findings such as missing/stale `Unreleased` bullets or unsynchronized project docs.
 - Output: Produce a concise Conventional Commit, push it to the intended branch, and report any temporary stash/restore or local branch sync that was required.
 
@@ -51,6 +51,9 @@ Load only when needed:
    - Preserve unrelated uncommitted work safely before branch operations, for example with `git stash push`, and restore it after the target branch has been updated.
    - If the fix was committed on the wrong branch, move it to the requested branch with safe history-preserving operations such as `cherry-pick`, `merge --ff-only`, or a clean replay; do not force-push unless the user explicitly asks for it.
    - If the user asks to sync the local target branch after pushing, fast-forward or pull that branch locally and then restore any preserved worktree changes.
+   - If the implementation lives in a detached or temporary `git worktree`, inspect both the temporary worktree and the main worktree before deciding the replay method.
+   - When the main worktree already contains staged or partially overlapping copies of the same changes, compare file content and branch tips first; do not create an unnecessary merge commit when a direct replay onto the authoritative target branch is safer.
+   - When the worktree diff is broader than the requested issue, stop and separate the requested commit scope before replaying anything to the target branch.
 4. Run code-affecting dependency skills (when applicable)
    - Run `review-change-set` for every code-affecting change before continuing; treat unresolved review findings as blocking.
    - Run `discover-edge-cases` and `harden-app-security` for the same code-affecting scope when the reviewed risk profile or repository context says their coverage is needed; treat them as blocking review gates, not optional polish, whenever that condition is met.
@@ -71,6 +74,7 @@ Load only when needed:
    - After pushing, verify the remote branch tip matches the local `HEAD`, for example by comparing `git rev-parse HEAD` with the target branch hash from `git rev-parse @{u}` or `git ls-remote --heads <remote> <branch>`.
    - If the push result is ambiguous, out of order, or the hashes do not match, rerun the missing git step sequentially and re-check before reporting success.
    - Confirm the local branch state matches the user's requested destination when post-push synchronization was requested.
+   - When the user explicitly asks to merge work back from a temporary worktree and delete that worktree, do the final verification on the authoritative target branch first, then remove the temporary worktree and prune stale worktree records before reporting completion.
 
 ## Notes
 
@@ -80,6 +84,7 @@ Load only when needed:
 - Never downgrade `discover-edge-cases` or `harden-app-security` to optional follow-up when the change risk says they apply.
 - Never claim the repository is ready to commit while root `CHANGELOG.md` `Unreleased` is missing the current change or still describes superseded work.
 - Never fabricate a commit/push result when the worktree is already clean; either identify the exact existing commit/upstream state that satisfies the user's request or say that no matching new submission exists.
+- Never delete a temporary worktree before the target branch has been updated, tested, and verified to contain the intended final content.
 - If release/version/tag work is requested, use `version-release` instead.
 - If a new branch is required, follow `references/branch-naming.md`.
 - A pushed implementation can still leave an active spec set behind; commit completion and spec archival are separate decisions.

package/develop-new-features/SKILL.md

@@ -56,6 +56,10 @@ Use a shared spec-generation workflow for non-trivial new feature work, then imp
   - narrowly scoped adjustments that touch only a few files/modules and do not require cross-team alignment or approval artifacts
 - In those cases, do not create `spec.md` / `tasks.md` / `checklist.md`; instead use the appropriate direct implementation workflow (for example `enhance-existing-features` for small brownfield adjustments or `systematic-debug` for bug fixes).
 - Specs are required when the request is truly a non-trivial new feature, product behavior change, or greenfield project that needs shared planning.
+- Treat each spec set as a narrowly scoped workstream that covers at most three modules.
+- If the requested change would require edits across more than three modules, do not force it into one oversized spec set.
+- Instead, split the work into multiple independent spec sets, each covering no more than three modules.
+- Define those spec sets so they do not conflict with each other and do not depend on another spec set being implemented first in order to be valid.
 - Follow `$generate-spec` completely for:
   - generating `docs/plans/{YYYY-MM-DD}_{change_name}/spec.md`, `tasks.md`, and `checklist.md`
   - filling BDD requirements and risk-driven test plans
@@ -117,6 +121,7 @@ Rules:
 
 - By default, write planning docs in the user's language.
 - Keep implementation traceable to approved requirement IDs and planned risks.
+- Keep each spec set limited to at most three modules; split larger changes into independent, non-conflicting, non-dependent spec sets before approval.
 - Prefer realism over rigid templates: add or remove test coverage only when the risk profile justifies it.
 - Every planned test should justify a distinct risk; remove shallow duplicates that only prove the code "still runs".
 - Treat starter template alternatives as mutually exclusive options, not as boxes that all need to be checked.

package/enhance-existing-features/SKILL.md

@@ -66,6 +66,9 @@ When in doubt, prefer direct implementation for genuinely low-risk localized cha
 If triggered:
 - Run `$generate-spec` and follow its workflow completely.
 - Use it to create or update `docs/plans/{YYYY-MM-DD}_{change_name}/spec.md`, `tasks.md`, and `checklist.md`.
+- Keep each spec set scoped to at most three modules.
+- If the requested change would require edits across more than three modules, split it into multiple spec sets instead of drafting one large coupled plan.
+- Design the split spec sets so they are independently valid, do not conflict with each other, and do not require another spec set to land first.
 - Ensure planned behaviors and edge cases cover external dependency states, abuse/adversarial paths, and any relevant authorization/idempotency/concurrency/data-integrity risks.
 - After implementation and testing, update the same plan set so `spec.md` reflects requirement completion status in addition to task and checklist progress.
 - If users answer clarification questions, update the planning docs and obtain explicit approval again before implementation.
@@ -130,6 +133,7 @@ Rules:
 
 - Keep the solution minimal and executable.
 - Always decide the need for specs only after exploring the existing codebase.
+- When specs are used, keep each spec set limited to at most three modules; split broader work into independent, non-conflicting, non-dependent spec sets before approval.
 - Maintain traceability between requirements, tasks, and tests when specs are present.
 - Treat checklists as living artifacts: adjust items to match real change scope.
 - Treat mutually exclusive template choices as a decision to record, not multiple boxes to finish.

package/lib/cli.js

@@ -1,4 +1,5 @@
 const { createInterface } = require('node:readline/promises');
+const fs = require('node:fs');
 const path = require('node:path');
 
 const {
@@ -9,6 +10,7 @@ const {
   syncToolkitHome,
   getTargetRoots,
 } = require('./installer');
+const { checkForPackageUpdate } = require('./updater');
 
 const TARGET_OPTIONS = [
   { id: 'all', label: 'All', description: 'Install every supported target below' },
@@ -116,13 +118,18 @@ function buildHelpText({ version, colorEnabled }) {
     buildBanner({ version, colorEnabled }),
     '',
     'Usage:',
+    '  apltk [install] [codex|openclaw|trae|all]...',
     '  apollo-toolkit [install] [codex|openclaw|trae|all]...',
+    '  apltk --help',
     '  apollo-toolkit --help',
     '',
     'Examples:',
+    '  apltk',
+    '  apltk codex openclaw',
     '  npx @laitszkin/apollo-toolkit',
     '  npx @laitszkin/apollo-toolkit codex openclaw',
     '  npm i -g @laitszkin/apollo-toolkit',
+    '  apltk all',
     '  apollo-toolkit all',
     '',
     'Options:',
@@ -131,6 +138,10 @@ function buildHelpText({ version, colorEnabled }) {
   ].join('\n');
 }
 
+function readPackageJson(sourceRoot) {
+  return JSON.parse(fs.readFileSync(path.join(sourceRoot, 'package.json'), 'utf8'));
+}
+
 function parseArguments(argv) {
   const args = [...argv];
   const result = {
@@ -343,7 +354,7 @@ async function run(argv, context = {}) {
   const stderr = context.stderr || process.stderr;
   const stdin = context.stdin || process.stdin;
   const env = context.env || process.env;
-  const packageJson = require(path.join(sourceRoot, 'package.json'));
+  let packageJson = readPackageJson(sourceRoot);
 
   try {
     const parsed = parseArguments(argv);
@@ -352,6 +363,21 @@ async function run(argv, context = {}) {
       return 0;
     }
 
+    const updateResult = await checkForPackageUpdate({
+      packageName: packageJson.name,
+      currentVersion: packageJson.version,
+      env,
+      stdin,
+      stdout,
+      stderr,
+      exec: context.execCommand,
+      confirmUpdate: context.confirmUpdate,
+    });
+
+    if (updateResult.updated) {
+      packageJson = readPackageJson(sourceRoot);
+    }
+
     const toolkitHome = parsed.toolkitHome || resolveToolkitHome(env);
     const modes = parsed.modes.length > 0
       ? normalizeModes(parsed.modes)
@@ -401,5 +427,6 @@ module.exports = {
   buildHelpText,
   parseArguments,
   promptForModes,
+  readPackageJson,
   run,
 };

package/lib/updater.js

@@ -0,0 +1,193 @@
+const { spawn } = require('node:child_process');
+const { createInterface } = require('node:readline/promises');
+
+function normalizeVersion(version) {
+  return String(version || '')
+    .trim()
+    .replace(/^v/i, '');
+}
+
+function parseVersion(version) {
+  const normalized = normalizeVersion(version);
+  const [core, prerelease = ''] = normalized.split('-', 2);
+  const parts = core.split('.').map((part) => Number.parseInt(part, 10) || 0);
+
+  return {
+    parts,
+    prerelease,
+  };
+}
+
+function compareVersions(left, right) {
+  const leftVersion = parseVersion(left);
+  const rightVersion = parseVersion(right);
+  const leftParts = leftVersion.parts;
+  const rightParts = rightVersion.parts;
+  const length = Math.max(leftParts.length, rightParts.length);
+
+  for (let index = 0; index < length; index += 1) {
+    const delta = (leftParts[index] || 0) - (rightParts[index] || 0);
+    if (delta !== 0) {
+      return delta;
+    }
+  }
+
+  if (leftVersion.prerelease && !rightVersion.prerelease) {
+    return -1;
+  }
+
+  if (!leftVersion.prerelease && rightVersion.prerelease) {
+    return 1;
+  }
+
+  if (leftVersion.prerelease !== rightVersion.prerelease) {
+    return leftVersion.prerelease.localeCompare(rightVersion.prerelease);
+  }
+
+  return 0;
+}
+
+function shouldSkipUpdateCheck({ env = process.env, stdin = process.stdin, stdout = process.stdout }) {
+  return env.APOLLO_TOOLKIT_SKIP_UPDATE_CHECK === '1' || !stdin.isTTY || !stdout.isTTY;
+}
+
+function execCommand(command, args, { env = process.env, stdout, stderr } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    let capturedStdout = '';
+    let capturedStderr = '';
+
+    child.stdout.on('data', (chunk) => {
+      capturedStdout += chunk.toString('utf8');
+      if (stdout) {
+        stdout.write(chunk);
+      }
+    });
+
+    child.stderr.on('data', (chunk) => {
+      capturedStderr += chunk.toString('utf8');
+      if (stderr) {
+        stderr.write(chunk);
+      }
+    });
+
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code !== 0) {
+        reject(new Error(capturedStderr.trim() || `${command} exited with code ${code}`));
+        return;
+      }
+
+      resolve({
+        stdout: capturedStdout,
+        stderr: capturedStderr,
+      });
+    });
+  });
+}
+
+async function defaultConfirmUpdate({ stdin, stdout, currentVersion, latestVersion, packageName }) {
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    const answer = await rl.question(
+      `A newer ${packageName} release is available (${currentVersion} -> ${latestVersion}). Update now? [Y/n] `,
+    );
+    const normalized = answer.trim().toLowerCase();
+    return normalized === '' || normalized === 'y';
+  } finally {
+    rl.close();
+  }
+}
+
+async function getLatestPublishedVersion({
+  packageName,
+  env = process.env,
+  exec = execCommand,
+}) {
+  const result = await exec('npm', ['view', packageName, 'version', '--json'], { env });
+  const parsed = JSON.parse(result.stdout.trim());
+
+  if (Array.isArray(parsed)) {
+    return String(parsed[parsed.length - 1] || '').trim();
+  }
+
+  return String(parsed || '').trim();
+}
+
+async function checkForPackageUpdate({
+  packageName,
+  currentVersion,
+  env = process.env,
+  stdin = process.stdin,
+  stdout = process.stdout,
+  stderr = process.stderr,
+  exec = execCommand,
+  confirmUpdate = defaultConfirmUpdate,
+}) {
+  if (shouldSkipUpdateCheck({ env, stdin, stdout })) {
+    return {
+      checked: false,
+      updated: false,
+    };
+  }
+
+  try {
+    const latestVersion = await getLatestPublishedVersion({ packageName, env, exec });
+    if (!latestVersion || compareVersions(latestVersion, currentVersion) <= 0) {
+      return {
+        checked: true,
+        updated: false,
+        latestVersion,
+      };
+    }
+
+    const approved = await confirmUpdate({
+      stdin,
+      stdout,
+      currentVersion,
+      latestVersion,
+      packageName,
+    });
+
+    if (!approved) {
+      stdout.write(`Continuing with ${packageName} ${currentVersion}.\n`);
+      return {
+        checked: true,
+        updated: false,
+        latestVersion,
+      };
+    }
+
+    stdout.write(`Updating ${packageName} to ${latestVersion}...\n`);
+    await exec('npm', ['install', '-g', `${packageName}@latest`], { env, stdout, stderr });
+    stdout.write(`Update complete. Continuing with ${packageName} ${latestVersion}.\n`);
+
+    return {
+      checked: true,
+      updated: true,
+      latestVersion,
+    };
+  } catch (error) {
+    stderr.write(`Warning: unable to check or install package updates: ${error.message}\n`);
+    return {
+      checked: false,
+      updated: false,
+      error,
+    };
+  }
+}
+
+module.exports = {
+  checkForPackageUpdate,
+  compareVersions,
+  defaultConfirmUpdate,
+  execCommand,
+  getLatestPublishedVersion,
+  normalizeVersion,
+  parseVersion,
+  shouldSkipUpdateCheck,
+};

package/maintain-project-constraints/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Automatically create and maintain AGENTS.md so it stays aligned with the current repository architecture, core business flow, common commands, project purpose, and coding conventions. Use when AGENTS.md is missing or may be outdated after code changes.
 ---
 
 # Maintain Project Constraints
@@ -17,7 +17,7 @@ description: Automatically create and maintain AGENTS.md so it stays aligned wit
 - 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.
+- Output: Maintain a concise root-level `AGENTS.md` with the required sections, repository-specific wording, and a factual `Common Commands` section when the repository exposes stable command entry points.
 
 ## Goal
 
@@ -38,9 +38,18 @@ After completing any code modification task, proactively run this skill to verif
 
 - Project architecture
 - Core business flow
+- Common commands
 - Core project purpose
 - Code style and coding conventions
 
+For the `Common Commands` section, always use this format:
+
+1. Include only commands that are real, current, and useful in this repository.
+2. Prefer repository-owned entry points such as package scripts, CLIs, `bin/` programs, `scripts/`, `Makefile`, `justfile`, or other documented task runners.
+3. For each command, explain when to use it in one short phrase instead of listing bare commands with no context.
+4. Prioritize commands that help an agent inspect, validate, build, test, or operate repository-specific workflows.
+5. Do not invent commands, aliases, flags, or task names that are not traceable to the repository.
+
 For the `Core business flow` section, always use this format:
 
 1. One short sentence that summarizes what the repository currently enables.
@@ -51,6 +60,13 @@ Example:
 
 ```markdown
 
+## Common Commands
+
+- `npm test` — run the repository's automated test suite.
+- `python3 scripts/validate_skill_frontmatter.py` — validate every top-level `SKILL.md` frontmatter block.
+- `python3 scripts/validate_openai_agent_config.py` — validate every `agents/openai.yaml` interface config.
+- `./scripts/install_skills.sh codex` — install the current toolkit into the local Codex skills directory.
+
 ## Core Business Flow
 
 This project enables users to manage and run reusable automation workflows.
@@ -69,11 +85,13 @@ This project enables users to manage and run reusable automation workflows.
 - Read the repository before writing:
   - root docs (`README`, contribution docs, design docs)
   - key source directories and entry points
+  - repository command surfaces such as `package.json`, `bin/`, `scripts/`, `Makefile`, `justfile`, or equivalent task runners
   - 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`.
+- Build a separate inventory of stable, repository-specific commands before drafting `Common Commands`.
 
 ### 2) Create AGENTS.md when missing
 
@@ -81,7 +99,9 @@ When `AGENTS.md` is absent:
 
 - Create a new root-level `AGENTS.md`.
 - Document architecture, business flow, purpose, and coding conventions from observed facts.
+- Document the repository's common commands from observed command entry points and docs.
 - Write `Core business flow` as one summary sentence followed by unordered bullets that cover every current capability found in the repository.
+- Write `Common commands` as short bullets in the style of ``- `command` — when to use it.``.
 - Keep language specific to this repository; avoid generic boilerplate.
 
 ### 3) Align AGENTS.md when drift is detected
@@ -91,12 +111,15 @@ 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.
+- Expand, trim, or replace the `Common Commands` list whenever command entry points or recommended workflows have changed.
 - 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.
+- Remove stale commands, flags, or task names that no longer exist.
+- Verify every command in `Common Commands` is either documented in repository docs or directly supported by the current codebase.
 - 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.
 
@@ -106,4 +129,5 @@ When `AGENTS.md` exists but is outdated:
 - 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.
+- In `Common Commands`, prefer the smallest useful set of high-signal commands over an exhaustive dump of every helper script.
 - Keep the document focused on how agents should understand and operate in this project.

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

@@ -1,4 +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."
+  short_description: "Automatically create and maintain AGENTS.md so it stays aligned with the current repository architecture, core business flow, common commands, 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, common commands, project purpose, and coding conventions. Use when AGENTS.md is missing or may be outdated after code changes."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "2.12.4",
+  "version": "2.12.6",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",
@@ -14,7 +14,8 @@
   },
   "type": "commonjs",
   "bin": {
-    "apollo-toolkit": "bin/apollo-toolkit.js"
+    "apollo-toolkit": "bin/apollo-toolkit.js",
+    "apltk": "bin/apollo-toolkit.js"
   },
   "scripts": {
     "test": "node --test"

package/production-sim-debug/SKILL.md

@@ -14,8 +14,8 @@ description: Investigate production or local simulation runs for runtime-toolcha
 
 ## Standards
 
-- Evidence: Base conclusions on the actual preset, runtime command, logs, SQLite event store, local stub responses, and the code paths that generated them.
-- Execution: Reproduce with the exact scenario first, verify the bounded-run contract against the actual script/env implementation before launch, separate product logic failures from simulation-toolchain failures, make the smallest realistic toolchain fix, and rerun the same bounded scenario to validate.
+- Evidence: Base conclusions on the actual preset, runtime command, logs, SQLite event store, local stub responses, the code paths that generated them, and official protocol or validator documentation whenever feasibility or instruction legality is in question.
+- Execution: Reproduce with the exact scenario first, verify the bounded-run contract against the actual script/env implementation before launch, separate product logic failures from simulation-toolchain failures, verify protocol-sensitive claims against official docs or upstream source before changing code or specs, make the smallest realistic toolchain fix, and rerun the same bounded scenario to validate.
 - Quality: Prefer harness or stub fixes that improve realism over one-off scenario hacks, avoid duplicating existing workflow skills, and record reusable presets when a scenario becomes part of the regular test suite.
 - Output: Return the scenario contract, observed outcomes, root-cause chain, fixes applied, validation evidence, and any remaining realism gaps.
 
@@ -69,6 +69,7 @@ Use this skill to debug simulation workflows where the repository exposes a prod
 ### 4) Separate product failures from toolchain realism failures
 
 - When the suspected blocker touches protocol rules, instruction legality, quote semantics, or liquidation invariants, verify the claim against the relevant official docs or upstream source before assigning blame.
+- When the current spec or planned fix assumes a local-simulation capability, verify that the capability is actually supported by the validator and program ownership model before implementing it.
 - For every major blocker, explicitly classify the result as one of:
   - production bot problem
   - simulation environment problem
@@ -87,6 +88,17 @@ Use this skill to debug simulation workflows where the repository exposes a prod
 - If a local stub inflates or distorts profitability, preserve the runtime behavior and calibrate the stub.
 - If a scenario intentionally stresses one dimension, make sure the harness is not accidentally stressing unrelated dimensions.
 
+### 4.3) Collapse infeasible simulation designs quickly
+
+- If official docs or upstream source prove that the proposed local-simulation design is impossible under the current architecture, stop trying to force the implementation through.
+- Treat this as a first-class debugging outcome, not as an implementation blocker to hand-wave away.
+- Name the precise external constraint, such as:
+  - validator preload behavior only applying at genesis/startup
+  - account data mutability being restricted to the owner program
+  - protocol instruction allowlists rejecting the proposed transaction shape
+- When a live spec or plan still claims that infeasible design as in scope, update the spec artifacts immediately so they only describe the remaining feasible scope.
+- Prefer narrowing the scenario to the strongest still-valid readiness or realism checks rather than leaving impossible tasks marked as pending.
+
 ### 4.1) Map the observed failure to the real pipeline stage
 
 - Do not treat every `liquidation_event` row as evidence that the run reached verification or execution.
@@ -168,6 +180,7 @@ Use this skill to debug simulation workflows where the repository exposes a prod
 - Explain the failing stage in the liquidation pipeline and whether the key counts represent positions, attempts, quotes, or executed outcomes.
 - Summarize the narrow fix and the regression test or rerun evidence.
 - If the final scenario should be reused, state where the preset or docs were added.
+- If official docs disproved part of the planned simulation design, state which spec or plan artifacts were narrowed and why.
 
 ## Example invocation