@laitszkin/apollo-toolkit 2.12.5 → 2.12.7

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.12.7] - 2026-04-02
+
+### Added
+- Add `claude-code` install mode for copying skills into `~/.claude/skills`, with `CLAUDE_CODE_SKILLS_DIR` environment override support.
+
+### Changed
+- Move `codex-memory-manager` and `learn-skill-from-conversations` into `codex/` subdirectory to clarify agent-specific skill boundaries.
+- Update codex install mode to include skills from both root directory and the `codex/` subdirectory.
+
+## [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

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/installer.js

@@ -3,7 +3,7 @@ const fsp = require('node:fs/promises');
 const os = require('node:os');
 const path = require('node:path');
 
-const VALID_MODES = ['codex', 'openclaw', 'trae'];
+const VALID_MODES = ['codex', 'openclaw', 'trae', 'claude-code'];
 const COPY_FILES = new Set(['AGENTS.md', 'CHANGELOG.md', 'LICENSE', 'README.md', 'package.json']);
 const COPY_DIRS = new Set(['scripts']);
 
@@ -61,7 +61,7 @@ function normalizeModes(inputModes) {
   return modes;
 }
 
-async function listSkillNames(rootDir) {
+async function listSkillNames(rootDir, modes = []) {
   const entries = await fsp.readdir(rootDir, { withFileTypes: true });
   const skillNames = [];
 
@@ -75,6 +75,19 @@ async function listSkillNames(rootDir) {
     }
   }
 
+  // For codex mode, also include codex-specific skills
+  if (modes.includes('codex')) {
+    const codexDir = path.join(rootDir, 'codex');
+    if (fs.existsSync(codexDir)) {
+      const codexEntries = await fsp.readdir(codexDir, { withFileTypes: true });
+      for (const entry of codexEntries) {
+        if (entry.isDirectory() && fs.existsSync(path.join(codexDir, entry.name, 'SKILL.md'))) {
+          skillNames.push(entry.name);
+        }
+      }
+    }
+  }
+
   return skillNames.sort();
 }
 
@@ -125,10 +138,10 @@ async function stageToolkitContents({ sourceRoot, destinationRoot, version }) {
   return copiedEntries.sort();
 }
 
-async function syncToolkitHome({ sourceRoot, toolkitHome, version }) {
+async function syncToolkitHome({ sourceRoot, toolkitHome, version, modes = [] }) {
   const parentDir = path.dirname(toolkitHome);
   const tempDir = path.join(parentDir, `.apollo-toolkit.tmp-${process.pid}-${Date.now()}`);
-  const previousSkillNames = await listSkillNames(toolkitHome).catch(() => []);
+  const previousSkillNames = await listSkillNames(toolkitHome, modes).catch(() => []);
 
   await fsp.rm(tempDir, { recursive: true, force: true });
   await stageToolkitContents({ sourceRoot, destinationRoot: tempDir, version });
@@ -145,7 +158,7 @@ async function syncToolkitHome({ sourceRoot, toolkitHome, version }) {
   return {
     toolkitHome,
     previousSkillNames,
-    skillNames: await listSkillNames(toolkitHome),
+    skillNames: await listSkillNames(toolkitHome, modes),
   };
 }
 
@@ -197,6 +210,18 @@ async function getTargetRoots(modes, env = process.env) {
           root: path.join(openclawHome, workspaceName, 'skills'),
         });
       }
+      continue;
+    }
+
+    if (mode === 'claude-code') {
+      targets.push({
+        mode,
+        label: 'Claude Code',
+        root: env.CLAUDE_CODE_SKILLS_DIR
+          ? path.resolve(expandUserPath(env.CLAUDE_CODE_SKILLS_DIR, env))
+          : path.join(homeDir, '.claude', 'skills'),
+      });
+      continue;
     }
   }
 
@@ -214,8 +239,9 @@ async function replaceWithCopy(sourcePath, targetPath) {
 }
 
 async function installLinks({ toolkitHome, modes, env = process.env, previousSkillNames = [] }) {
-  const skillNames = await listSkillNames(toolkitHome);
-  const targets = await getTargetRoots(modes, env);
+  const normalizedModes = normalizeModes(modes);
+  const skillNames = await listSkillNames(toolkitHome, normalizedModes);
+  const targets = await getTargetRoots(normalizedModes, env);
   const copiedPaths = [];
   const staleSkillNames = previousSkillNames.filter((skillName) => !skillNames.includes(skillName));
 
@@ -225,7 +251,13 @@ async function installLinks({ toolkitHome, modes, env = process.env, previousSki
       await fsp.rm(path.join(target.root, staleSkillName), { recursive: true, force: true });
     }
     for (const skillName of skillNames) {
-      const sourcePath = path.join(toolkitHome, skillName);
+      // For codex skills, use the ./codex/ subdirectory as source
+      let sourcePath;
+      if (normalizedModes.includes('codex') && fs.existsSync(path.join(toolkitHome, 'codex', skillName))) {
+        sourcePath = path.join(toolkitHome, 'codex', skillName);
+      } else {
+        sourcePath = path.join(toolkitHome, skillName);
+      }
       const targetPath = path.join(target.root, skillName);
       await replaceWithCopy(sourcePath, targetPath);
       copiedPaths.push({ target: target.label, path: targetPath, skillName });

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "2.12.5",
+  "version": "2.12.7",
   "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
 

package/scripts/install_skills.ps1

@@ -9,22 +9,24 @@ $ErrorActionPreference = "Stop"
 function Show-Usage {
   @"
 Usage:
-  ./scripts/install_skills.ps1 [codex|openclaw|trae|agents|all]...
+  ./scripts/install_skills.ps1 [codex|openclaw|trae|agents|claude-code|all]...
 
 Modes:
-  codex     Copy skills into ~/.codex/skills
-  openclaw  Copy skills into ~/.openclaw/workspace*/skills
-  trae      Copy skills into ~/.trae/skills
-  agents    Copy skills into ~/.agents/skills (for agent-skill-compatible software)
-  all       Install all supported targets
+  codex       Copy skills into ~/.codex/skills (includes ./codex/ agent-specific skills)
+  openclaw    Copy skills into ~/.openclaw/workspace*/skills
+  trae        Copy skills into ~/.trae/skills
+  agents      Copy skills into ~/.agents/skills (for agent-skill-compatible software)
+  claude-code Copy skills into ~/.claude/skills
+  all         Install all supported targets
 
 Optional environment overrides:
-  CODEX_SKILLS_DIR   Override codex skills destination path
-  OPENCLAW_HOME      Override openclaw home path
-  TRAE_SKILLS_DIR    Override trae skills destination path
-  AGENTS_SKILLS_DIR  Override agents skills destination path
-  APOLLO_TOOLKIT_HOME Override local install path used when repo root is unavailable
-  APOLLO_TOOLKIT_REPO_URL Override git repository URL used when repo root is unavailable
+  CODEX_SKILLS_DIR         Override codex skills destination path
+  OPENCLAW_HOME            Override openclaw home path
+  TRAE_SKILLS_DIR          Override trae skills destination path
+  AGENTS_SKILLS_DIR        Override agents skills destination path
+  CLAUDE_CODE_SKILLS_DIR   Override claude-code skills destination path
+  APOLLO_TOOLKIT_HOME       Override local install path used when repo root is unavailable
+  APOLLO_TOOLKIT_REPO_URL   Override git repository URL used when repo root is unavailable
 "@
 }
 
@@ -109,6 +111,8 @@ else {
 }
 
 function Get-SkillPaths {
+  param([string[]]$SelectedModes)
+
   $dirs = Get-ChildItem -Path $RepoRoot -Directory | Sort-Object Name
   $skills = @()
 
@@ -118,6 +122,19 @@ function Get-SkillPaths {
     }
   }
 
+  # For codex mode, also include codex-specific skills
+  if ($SelectedModes -contains "codex") {
+    $codexDir = Join-Path $RepoRoot "codex"
+    if (Test-Path -LiteralPath $codexDir -PathType Container) {
+      $codexDirs = Get-ChildItem -Path $codexDir -Directory | Sort-Object Name
+      foreach ($dir in $codexDirs) {
+        if (Test-Path -LiteralPath (Join-Path $dir.FullName "SKILL.md") -PathType Leaf) {
+          $skills += $dir.FullName
+        }
+      }
+    }
+  }
+
   if ($skills.Count -eq 0) {
     throw "No skill folders found in: $RepoRoot"
   }
@@ -145,12 +162,13 @@ function Resolve-Modes {
     Show-Banner
     Write-Host ""
     Write-Host "Select install options (comma-separated):"
-    Write-Host "1) codex (~/.codex/skills)"
+    Write-Host "1) codex (~/.codex/skills, includes ./codex/ agent-specific skills)"
     Write-Host "2) openclaw (~/.openclaw/workspace*/skills)"
     Write-Host "3) trae (~/.trae/skills)"
     Write-Host "4) agents (~/.agents/skills)"
-    Write-Host "5) all"
-    $inputValue = Read-Host "Enter choice(s) [1-5]"
+    Write-Host "5) claude-code (~/.claude/skills)"
+    Write-Host "6) all"
+    $inputValue = Read-Host "Enter choice(s) [1-6]"
 
     foreach ($rawChoice in ($inputValue -split ",")) {
       $choice = $rawChoice.Trim()
@@ -159,11 +177,13 @@ function Resolve-Modes {
         "2" { Add-ModeOnce -Selected $selected -Mode "openclaw" }
         "3" { Add-ModeOnce -Selected $selected -Mode "trae" }
         "4" { Add-ModeOnce -Selected $selected -Mode "agents" }
-        "5" {
+        "5" { Add-ModeOnce -Selected $selected -Mode "claude-code" }
+        "6" {
           Add-ModeOnce -Selected $selected -Mode "codex"
           Add-ModeOnce -Selected $selected -Mode "openclaw"
           Add-ModeOnce -Selected $selected -Mode "trae"
           Add-ModeOnce -Selected $selected -Mode "agents"
+          Add-ModeOnce -Selected $selected -Mode "claude-code"
         }
         default {
           throw "Invalid choice: $choice"
@@ -178,11 +198,13 @@ function Resolve-Modes {
         "openclaw" { Add-ModeOnce -Selected $selected -Mode "openclaw" }
         "trae" { Add-ModeOnce -Selected $selected -Mode "trae" }
         "agents" { Add-ModeOnce -Selected $selected -Mode "agents" }
+        "claude-code" { Add-ModeOnce -Selected $selected -Mode "claude-code" }
         "all" {
           Add-ModeOnce -Selected $selected -Mode "codex"
           Add-ModeOnce -Selected $selected -Mode "openclaw"
           Add-ModeOnce -Selected $selected -Mode "trae"
           Add-ModeOnce -Selected $selected -Mode "agents"
+          Add-ModeOnce -Selected $selected -Mode "claude-code"
         }
         default {
           Show-Usage
@@ -299,13 +321,29 @@ function Install-Agents {
   }
 }
 
+function Install-ClaudeCode {
+  param([string[]]$SkillPaths)
+
+  $target = if ($env:CLAUDE_CODE_SKILLS_DIR) {
+    Expand-UserPath $env:CLAUDE_CODE_SKILLS_DIR
+  }
+  else {
+    Join-Path $HOME ".claude/skills"
+  }
+
+  Write-Host "Installing to claude-code: $target"
+  foreach ($src in $SkillPaths) {
+    Copy-Skill -Source $src -TargetRoot $target
+  }
+}
+
 if ($Modes.Count -gt 0 -and ($Modes[0] -eq "-h" -or $Modes[0] -eq "--help")) {
   Show-Usage
   exit 0
 }
 
 $selectedModes = Resolve-Modes -Requested $Modes
-$skillPaths = Get-SkillPaths
+$skillPaths = Get-SkillPaths -SelectedModes $selectedModes
 
 foreach ($mode in $selectedModes) {
   switch ($mode) {
@@ -313,6 +351,7 @@ foreach ($mode in $selectedModes) {
     "openclaw" { Install-OpenClaw -SkillPaths $skillPaths }
     "trae" { Install-Trae -SkillPaths $skillPaths }
     "agents" { Install-Agents -SkillPaths $skillPaths }
+    "claude-code" { Install-ClaudeCode -SkillPaths $skillPaths }
     default { throw "Unknown mode: $mode" }
   }
 }

package/scripts/install_skills.sh

@@ -4,21 +4,23 @@ set -euo pipefail
 usage() {
   cat <<"USAGE"
 Usage:
-  ./scripts/install_skills.sh [codex|openclaw|trae|agents|all]...
+  ./scripts/install_skills.sh [codex|openclaw|trae|agents|claude-code|all]...
 
 Modes:
-  codex     Copy skills into ~/.codex/skills
-  openclaw  Copy skills into ~/.openclaw/workspace*/skills
-  trae      Copy skills into ~/.trae/skills
-  agents    Copy skills into ~/.agents/skills (for agent-skill-compatible software)
-  all       Install all supported targets
+  codex       Copy skills into ~/.codex/skills (includes ./codex/ agent-specific skills)
+  openclaw    Copy skills into ~/.openclaw/workspace*/skills
+  trae        Copy skills into ~/.trae/skills
+  agents      Copy skills into ~/.agents/skills (for agent-skill-compatible software)
+  claude-code Copy skills into ~/.claude/skills
+  all         Install all supported targets
 
 Optional environment overrides:
-  CODEX_SKILLS_DIR   Override codex skills destination path
-  OPENCLAW_HOME      Override openclaw home path
-  TRAE_SKILLS_DIR    Override trae skills destination path
-  AGENTS_SKILLS_DIR  Override agents skills destination path
-  APOLLO_TOOLKIT_HOME Override local install path used in curl/pipe mode
+  CODEX_SKILLS_DIR    Override codex skills destination path
+  OPENCLAW_HOME       Override openclaw home path
+  TRAE_SKILLS_DIR     Override trae skills destination path
+  AGENTS_SKILLS_DIR   Override agents skills destination path
+  CLAUDE_CODE_SKILLS_DIR Override claude-code skills destination path
+  APOLLO_TOOLKIT_HOME  Override local install path used in curl/pipe mode
   APOLLO_TOOLKIT_REPO_URL Override git repository URL used in curl/pipe mode
 USAGE
 }
@@ -87,6 +89,18 @@ collect_skills() {
     fi
   done < <(find "$REPO_ROOT" -mindepth 1 -maxdepth 1 -type d | sort)
 
+  # For codex mode, also include codex-specific skills
+  if [[ " ${SELECTED_MODES[*]} " =~ " codex " ]]; then
+    local codex_dir="$REPO_ROOT/codex"
+    if [[ -d "$codex_dir" ]]; then
+      while IFS= read -r dir; do
+        if [[ -f "$dir/SKILL.md" ]]; then
+          SKILL_PATHS+=("$dir")
+        fi
+      done < <(find "$codex_dir" -mindepth 1 -maxdepth 1 -type d | sort)
+    fi
+  fi
+
   if [[ ${#SKILL_PATHS[@]} -eq 0 ]]; then
     echo "No skill folders found in: $REPO_ROOT" >&2
     exit 1
@@ -164,6 +178,16 @@ install_agents() {
   done
 }
 
+install_claude_code() {
+  local claude_code_skills_dir
+  claude_code_skills_dir="$(expand_user_path "${CLAUDE_CODE_SKILLS_DIR:-$HOME/.claude/skills}")"
+
+  echo "Installing to claude-code: $claude_code_skills_dir"
+  for src in "${SKILL_PATHS[@]}"; do
+    replace_with_copy "$src" "$claude_code_skills_dir"
+  done
+}
+
 add_mode_once() {
   local mode="$1"
   local existing
@@ -182,7 +206,7 @@ parse_mode() {
   local mode="$1"
 
   case "$mode" in
-    codex|openclaw|trae|agents)
+    codex|openclaw|trae|agents|claude-code)
       add_mode_once "$mode"
       ;;
     all)
@@ -190,6 +214,7 @@ parse_mode() {
       add_mode_once "openclaw"
       add_mode_once "trae"
       add_mode_once "agents"
+      add_mode_once "claude-code"
       ;;
     *)
       echo "Invalid mode: $mode" >&2
@@ -222,12 +247,13 @@ choose_modes_interactive() {
   show_banner
   echo
   echo "Select install options (comma-separated):"
-  echo "1) codex (~/.codex/skills)"
+  echo "1) codex (~/.codex/skills, includes ./codex/ agent-specific skills)"
   echo "2) openclaw (~/.openclaw/workspace*/skills)"
   echo "3) trae (~/.trae/skills)"
   echo "4) agents (~/.agents/skills)"
-  echo "5) all"
-  choice="$(read_choice_from_user 'Enter choice(s) [1-5]: ')"
+  echo "5) claude-code (~/.claude/skills)"
+  echo "6) all"
+  choice="$(read_choice_from_user 'Enter choice(s) [1-6]: ')"
 
   IFS=',' read -r -a choices <<< "$choice"
   for raw_choice in "${choices[@]}"; do
@@ -237,7 +263,8 @@ choose_modes_interactive() {
       2) add_mode_once "openclaw" ;;
       3) add_mode_once "trae" ;;
       4) add_mode_once "agents" ;;
-      5) add_mode_once "codex"; add_mode_once "openclaw"; add_mode_once "trae"; add_mode_once "agents" ;;
+      5) add_mode_once "claude-code" ;;
+      6) add_mode_once "codex"; add_mode_once "openclaw"; add_mode_once "trae"; add_mode_once "agents"; add_mode_once "claude-code" ;;
       *)
         echo "Invalid choice: $raw_choice" >&2
         exit 1
@@ -282,6 +309,7 @@ main() {
       openclaw) install_openclaw ;;
       trae) install_trae ;;
       agents) install_agents ;;
+      claude-code) install_claude_code ;;
       *)
         usage
         exit 1