@laitszkin/apollo-toolkit 2.11.4 → 2.12.0

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.12.0] - 2026-03-28
+
+### Added
+- Add `agents` mode to install scripts for copying skills into `~/.agents/skills` directory, supporting agent-skill-compatible software.
+
+### Changed
+- Strengthen `production-sim-debug` so simulation investigations must verify protocol-sensitive blame against official docs or upstream source, distinguish liquidation pipeline stages precisely, and explain quote-budget counts as attempts versus unique opportunities.
+
 ## [v2.11.4] - 2026-03-27
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "2.11.4",
+  "version": "2.12.0",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",

package/production-sim-debug/SKILL.md

@@ -8,7 +8,7 @@ description: Investigate production or local simulation runs for runtime-toolcha
 ## Dependencies
 
 - Required: `systematic-debug` for evidence-first root-cause analysis when a simulation shows failing or missing expected behavior.
-- Conditional: `scheduled-runtime-health-check` when the user wants a bounded production/local simulation run executed and observed; `read-github-issue` when the requested simulation work is driven by a remote issue; `open-github-issue` when confirmed toolchain gaps should be published.
+- Conditional: `scheduled-runtime-health-check` when the user wants a bounded production/local simulation run executed and observed; `read-github-issue` when the requested simulation work is driven by a remote issue; `marginfi-development` when liquidation, health, receivership, or instruction-order conclusions depend on official marginfi docs/source; `jupiter-development` when swap, quote, routing, or rate-limit conclusions depend on official Jupiter docs; `open-github-issue` when confirmed toolchain gaps should be published.
 - Optional: none.
 - Fallback: If the relevant simulation entrypoint, preset, logs, or run artifacts cannot be found, stop and report the missing evidence instead of inferring behavior from stale docs or memory.
 
@@ -63,6 +63,13 @@ 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.
+- For every major blocker, explicitly classify the result as one of:
+  - production bot problem
+  - simulation environment problem
+  - both
+- Treat "both" as a first-class result when a bot bug and a local-harness realism gap are stacked in the same flow.
+
 - Classify each blocker into one of these buckets:
   - preset design mismatch
   - runtime scheduling or budget behavior
@@ -75,6 +82,31 @@ 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.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.
+- Reconstruct the stage explicitly, such as:
+  - candidate discovery
+  - local estimate
+  - solver candidate quote
+  - verification or pre-submit re-quote
+  - simulation
+  - execution
+- When logs or event rows expose `stage`, `bucket`, `reason`, or similar structured fields, use them to explain exactly where the attempt stopped.
+- When the user is confused by counts, distinguish:
+  - unique positions
+  - candidate attempts
+  - quote attempts
+  - verification attempts
+  - executed liquidations
+
+### 4.2) Audit quote-budget behavior before calling the strategy broken
+
+- Check whether a high quote count reflects many unique positions or repeated coarse/refinement exploration on the same few positions.
+- Trace how the runtime reserves verification capacity versus non-verification capacity, and explain which bucket was exhausted.
+- If the strategy relies on local oracle estimates before quoting, verify whether the admission threshold is merely "positive estimate" or something stricter before assuming those candidates were all strong.
+- When quote pressure appears unreasonable, tie the explanation back to the actual solver-step count, coarse/refinement selection logic, and the number of cross-mint candidates in the run.
+
 ### 5) Trace the full decision tree for missed liquidations or remediations
 
 - Follow the candidate from discovery through:
@@ -117,12 +149,17 @@ Use this skill to debug simulation workflows where the repository exposes a prod
 - **Overloaded “unknown” failures**: logs contain structured reasons, but the first-pass analysis never decomposes them.
 - **Continuous-mode self-sabotage**: a stress regime intended to stale pull oracles instead makes the runtime’s own primary feeds unusable.
 - **Quote budget starvation**: local filtering improves behavior but still lets low-value cross-mint candidates consume scarce quote capacity before higher-value paths can finish.
+- **Blame assigned too early**: the first visible error gets labeled as either bot or tooling before official docs, upstream source, and run artifacts confirm that attribution.
+- **Phase confusion**: event counts are interpreted as verification or execution attempts even though the run stopped much earlier in candidate quote or pre-submit simulation.
+- **Quote-count misread**: a large total quote count is mistaken for many distinct opportunities when the runtime actually spent repeated exploration quotes on a smaller set of positions.
 
 ## Output checklist
 
 - Name the exact scenario, preset, duration, and run directory.
 - State whether the root cause was product logic, toolchain realism, or both.
+- For protocol-sensitive issues, name the official docs or upstream source used to justify that attribution.
 - Cite the artifact types used: preset, logs, SQLite tables, and code paths.
+- 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.
 

package/scripts/install_skills.ps1

@@ -9,18 +9,20 @@ $ErrorActionPreference = "Stop"
 function Show-Usage {
   @"
 Usage:
-  ./scripts/install_skills.ps1 [codex|openclaw|trae|all]...
+  ./scripts/install_skills.ps1 [codex|openclaw|trae|agents|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
 
 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
 "@
@@ -126,8 +128,9 @@ function Resolve-Modes {
     Write-Host "1) codex (~/.codex/skills)"
     Write-Host "2) openclaw (~/.openclaw/workspace*/skills)"
     Write-Host "3) trae (~/.trae/skills)"
-    Write-Host "4) all"
-    $inputValue = Read-Host "Enter choice(s) [1-4]"
+    Write-Host "4) agents (~/.agents/skills)"
+    Write-Host "5) all"
+    $inputValue = Read-Host "Enter choice(s) [1-5]"
 
     foreach ($rawChoice in ($inputValue -split ",")) {
       $choice = $rawChoice.Trim()
@@ -135,10 +138,12 @@ function Resolve-Modes {
         "1" { Add-ModeOnce -Selected $selected -Mode "codex" }
         "2" { Add-ModeOnce -Selected $selected -Mode "openclaw" }
         "3" { Add-ModeOnce -Selected $selected -Mode "trae" }
-        "4" {
+        "4" { Add-ModeOnce -Selected $selected -Mode "agents" }
+        "5" {
           Add-ModeOnce -Selected $selected -Mode "codex"
           Add-ModeOnce -Selected $selected -Mode "openclaw"
           Add-ModeOnce -Selected $selected -Mode "trae"
+          Add-ModeOnce -Selected $selected -Mode "agents"
         }
         default {
           throw "Invalid choice: $choice"
@@ -152,10 +157,12 @@ function Resolve-Modes {
         "codex" { Add-ModeOnce -Selected $selected -Mode "codex" }
         "openclaw" { Add-ModeOnce -Selected $selected -Mode "openclaw" }
         "trae" { Add-ModeOnce -Selected $selected -Mode "trae" }
+        "agents" { Add-ModeOnce -Selected $selected -Mode "agents" }
         "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"
         }
         default {
           Show-Usage
@@ -256,6 +263,22 @@ function Install-Trae {
   }
 }
 
+function Install-Agents {
+  param([string[]]$SkillPaths)
+
+  $target = if ($env:AGENTS_SKILLS_DIR) {
+    $env:AGENTS_SKILLS_DIR
+  }
+  else {
+    Join-Path $HOME ".agents/skills"
+  }
+
+  Write-Host "Installing to agents: $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
@@ -269,6 +292,7 @@ foreach ($mode in $selectedModes) {
     "codex" { Install-Codex -SkillPaths $skillPaths }
     "openclaw" { Install-OpenClaw -SkillPaths $skillPaths }
     "trae" { Install-Trae -SkillPaths $skillPaths }
+    "agents" { Install-Agents -SkillPaths $skillPaths }
     default { throw "Unknown mode: $mode" }
   }
 }

package/scripts/install_skills.sh

@@ -4,18 +4,20 @@ set -euo pipefail
 usage() {
   cat <<"USAGE"
 Usage:
-  ./scripts/install_skills.sh [codex|openclaw|trae|all]...
+  ./scripts/install_skills.sh [codex|openclaw|trae|agents|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
 
 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
   APOLLO_TOOLKIT_REPO_URL Override git repository URL used in curl/pipe mode
 USAGE
@@ -135,6 +137,16 @@ install_trae() {
   done
 }
 
+install_agents() {
+  local agents_skills_dir
+  agents_skills_dir="${AGENTS_SKILLS_DIR:-$HOME/.agents/skills}"
+
+  echo "Installing to agents: $agents_skills_dir"
+  for src in "${SKILL_PATHS[@]}"; do
+    replace_with_copy "$src" "$agents_skills_dir"
+  done
+}
+
 add_mode_once() {
   local mode="$1"
   local existing
@@ -153,13 +165,14 @@ parse_mode() {
   local mode="$1"
 
   case "$mode" in
-    codex|openclaw|trae)
+    codex|openclaw|trae|agents)
       add_mode_once "$mode"
       ;;
     all)
       add_mode_once "codex"
       add_mode_once "openclaw"
       add_mode_once "trae"
+      add_mode_once "agents"
       ;;
     *)
       echo "Invalid mode: $mode" >&2
@@ -195,8 +208,9 @@ choose_modes_interactive() {
   echo "1) codex (~/.codex/skills)"
   echo "2) openclaw (~/.openclaw/workspace*/skills)"
   echo "3) trae (~/.trae/skills)"
-  echo "4) all"
-  choice="$(read_choice_from_user 'Enter choice(s) [1-4]: ')"
+  echo "4) agents (~/.agents/skills)"
+  echo "5) all"
+  choice="$(read_choice_from_user 'Enter choice(s) [1-5]: ')"
 
   IFS=',' read -r -a choices <<< "$choice"
   for raw_choice in "${choices[@]}"; do
@@ -205,7 +219,8 @@ choose_modes_interactive() {
       1) add_mode_once "codex" ;;
       2) add_mode_once "openclaw" ;;
       3) add_mode_once "trae" ;;
-      4) add_mode_once "codex"; add_mode_once "openclaw"; 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" ;;
       *)
         echo "Invalid choice: $raw_choice" >&2
         exit 1
@@ -249,6 +264,7 @@ main() {
       codex) install_codex ;;
       openclaw) install_openclaw ;;
       trae) install_trae ;;
+      agents) install_agents ;;
       *)
         usage
         exit 1