@laitszkin/apollo-toolkit 3.12.1 → 3.13.1

package/optimise-skill/SKILL.md

@@ -1,36 +1,44 @@
 ---
 name: optimise-skill
-description: Use prompt engineering to optimise agent skill. Use it when you need to optimise a `SKILL.md`
+description: 當你需要優化 agent skills 的 `SKILL.md` 時，調用這個技能。
 ---
 
 ## 目標
+
 在不影響被優化技能整體流程前提下，利用提示詞工程，對技能進行優化，減少冗余表達，增強agent對技能的理解能力以及實際工作中的使用效率。
 
 ## 驗收條件
+
 - 被優化技能的最終交付產物不受影響
 - 被優化技能有顯著冗余削減，且具備精確提示能力，盡最大可能釋放LLM的性能
 
 ## 工作流程
 
 ### 1. 識別交付物
+
 完整閱讀整個技能的 `SKILL.md` 文檔，以及其引用的所有額檔案，包括但不限於 `references/` , `scripts/` 。基於獲取到的技能上下文資訊，總結出該技能的最終交付產物。
 
 ### 2. 制定驗收條件
+
 制定驗收條件，從而確保LLM能夠穩定、可復現地按照驗收條件產出符合要求高質量最終交付物
 
 ### 3. 重寫技能
+
 將整個技能的 `SKILL.md` 重寫。重寫後的技能應該只包含以下幾個關鍵組成部分：
 - 目標
 - 驗收條件
 - 工作流程
-- 範例
+- 範例（選用）
 - 參考資料
+
 對於技能有幫助的內但不符合上述技能架構規範，則應該被分類放置在 `references/` 下的markdown檔案。
 
 ## 範例
+
 - "一個專注在提示LLM agent進行自我迭代，並為repo帶來性能優化的技能需要被優化" -> "定義驗收條件為優化後性能相較優化前至少提升X個百分比，並且項目之中不存在任何O(n^2)級別時間複雜度的函式和邏輯，並按照標準架構重寫技能。"
 - "一個有大量前端開發範例被包含在 `SKILL.md` 之中的前端開發技能需要被優化" -> "定義驗收條件為前端頁面 `reference` 之中提供的大量建議範例重寫且不包含任何建議示例之中明確拒絕的設計，然後按照技能優化流程對技能進行全面的重寫。"
 
 ## 參考資料
+
 - `references/example_skill.md` - 優化後的技能範例，在進行技能優化時必須閱讀並嚴格遵照當中格式 **（必讀）**
 - `references/definition.md` - 技能之中各個區塊的定義 **（必讀）**

package/optimise-skill/references/example_skill.md

@@ -1,36 +1,44 @@
 ---
 name: optimise-skill
-description: Use prompt engineering to optimise agent skill. Use it when you need to optimise a `SKILL.md`
+description: 當你需要優化 agent skills 的 `SKILL.md` 時，調用這個技能。
 ---
 
 ## 目標
+
 在不影響被優化技能整體流程前提下，利用提示詞工程，對技能進行優化，減少冗余表達，增強agent對技能的理解能力以及實際工作中的使用效率。
 
 ## 驗收條件
+
 - 被優化技能的最終交付產物不受影響
 - 被優化技能有顯著冗余削減，且具備精確提示能力，盡最大可能釋放LLM的性能
 
 ## 工作流程
 
 ### 1. 識別交付物
+
 完整閱讀整個技能的 `SKILL.md` 文檔，以及其引用的所有額檔案，包括但不限於 `references/` , `scripts/` 。基於獲取到的技能上下文資訊，總結出該技能的最終交付產物。
 
 ### 2. 制定驗收條件
+
 制定驗收條件，從而確保LLM能夠穩定、可復現地按照驗收條件產出符合要求高質量最終交付物
 
 ### 3. 重寫技能
+
 將整個技能的 `SKILL.md` 重寫。重寫後的技能應該只包含以下幾個關鍵組成部分：
 - 目標
 - 驗收條件
 - 工作流程
-- 範例
+- 範例（選用）
 - 參考資料
+
 對於技能有幫助的內但不符合上述技能架構規範，則應該被分類放置在 `references/` 下的markdown檔案。
 
 ## 範例
+
 - "一個專注在提示LLM agent進行自我迭代，並為repo帶來性能優化的技能需要被優化" -> "定義驗收條件為優化後性能相較優化前至少提升X個百分比，並且項目之中不存在任何O(n^2)級別時間複雜度的函式和邏輯，並按照標準架構重寫技能。"
 - "一個有大量前端開發範例被包含在 `SKILL.md` 之中的前端開發技能需要被優化" -> "定義驗收條件為前端頁面 `reference` 之中提供的大量建議範例重寫且不包含任何建議示例之中明確拒絕的設計，然後按照技能優化流程對技能進行全面的重寫。"
 
 ## 參考資料
+
 - `references/example_skill.md` - 優化後的技能範例，在進行技能優化時必須閱讀並嚴格遵照當中格式 **（必讀）**
 - `references/definition.md` - 技能之中各個區塊的定義 **（必讀）**

package/package.json

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

package/solve-issues-found-during-review/SKILL.md

@@ -20,4 +20,4 @@ description: 當你需要修復 code review report 之中發現的問題時，
 
 ### 2. 修復發現的問題
 
-按照 code review report之中的嚴重度排序，從最高嚴重度的問題開始建議方案修復。
+按照 code review report 之中的嚴重度排序，從最高嚴重度的問題開始建議方案修復。

package/systematic-debug/SKILL.md

@@ -1,55 +1,28 @@
 ---
 name: systematic-debug
-description: >-
-  用於系統化排查程式問題。先釐清預期與實際行為，再對所有合理原因做可重現驗證，
-  找出真正根因並以最小修復完成驗證；凡是出現 observed-vs-expected mismatch 都應優先使用。
+description: 當你需要系統性排查用戶指出的非預期行為時，調用這個技能。 
 ---
 
-# 系統化除錯
-
-## Dependencies
-
-- Required: 無
-- Conditional: 視情況可搭配 `test-case-strategy`、`analyse-app-logs`
-- Optional: 無
-- Fallback: 無
-
-## Standards
-
-- Evidence: 先收集預期與實際行為、程式碼路徑、測試輸出與單一可信 runtime artifact，再判斷原因
-- Execution: 為每個合理假設建立可重現證據，定位最後一個成功階段，再區分工具鏈、測試契約、測試隔離與產品邏輯問題
-- Quality: 修復只針對真實根因；不能重現的假設必須明確排除；不得混用不同執行批次的證據
-- Output: 產出根因候選、重現方式、最終分類、最小修復、驗證結果，以及在 runtime 問題中使用的 canonical evidence
-
 ## 技能目標
 
-把「它應該做 X，實際卻做了 Y」這類問題轉成可驗證的除錯流程，避免靠猜測改碼，並確保最後交付的是已被重現、已被證明、已被驗證的修復。
+用流程化的方式重現用戶發現的非預期行為，並通過回歸測試避免該問題再次出現。
 
 ## 驗收條件
 
-- 已清楚記錄預期行為、實際行為、受影響路徑，以及 runtime 問題使用的單一 canonical 證據來源
-- 所有合理根因都已被重現、驗證或明確排除，而不是只修第一個看起來像的原因
-- 已區分問題屬於工具鏈 / 平台、測試契約過期、測試干擾、流程編排，還是真正的產品邏輯缺陷
-- 最終修復是最小且聚焦的，並由失敗後轉成功的測試或 bounded rerun 證明有效
+- 非預期行為被修復。
+- 相關回歸測試被建立。
 
 ## 工作流程
 
-1. 先整理使用者回報、測試輸出、日誌與程式碼路徑，明確寫出預期與實際差異；若問題涉及 runtime artifact，先指定一個 canonical run 或輸出目錄
-2. 把流程拆成具體階段，例如 setup、startup、readiness、steady-state、persistence、shutdown，找出最後一個已確定成功的階段
-3. 為每個合理根因建立重現方式；能用測試重現就優先用測試，涉及真實執行流程時則用相同模式的 bounded rerun，而不是中途切換到不同 fidelity 的環境
-4. 若失敗只在平行執行、共享 shell-out、共享暫存路徑或舊報告路徑下出現，先調查測試隔離、共享狀態與 artifact routing 問題
-5. 用重現證據確認真正根因，並明確排除非原因；若測試失敗其實來自 stale assertion 或 fixture drift，先修正測試契約，不要反向削弱產品行為
-6. 實作最小修復並反覆驗證，直到所有重現案例、相關測試或 bounded rerun 都通過
-7. 向使用者回報根因清單、最終分類、修復摘要、驗證結果，以及任何仍受限於執行環境或資料品質的部分
+### 1. 分析問題
 
-## 使用範例
+按照用戶給出的資訊，結合相關代碼實作片段閱讀，排查可能導致問題的原因。
 
-- 「這個 API 應該回 200，現在卻變成 500」-> 先確認預期契約，再重現所有合理根因，最後定位是 handler 邏輯、依賴服務還是測試 fixture 問題
-- 「測試單獨跑會過，但整個 suite 會 flaky」-> 優先排查共享狀態、鎖、暫存目錄與環境污染，而不是先改產品邏輯
-- 「bounded run 幾乎沒有事件發生」-> 先沿著 lifecycle funnel 判斷停在哪個階段，再確認是 profile 過度破壞、編排錯誤，還是實際業務邏輯問題
+### 2. 滲透測試
 
-## 參考資料索引
+整理所有可能導致問題的原因，撰寫測試案例嘗試重現該問題。
+如果你發現所有你構思的可能性均無法重現該非預期行為，你需要重新構思，直至該非預期行為被測試有效重現。
 
-- `test-case-strategy`：需要補重現測試或 drift check 時使用
-- `analyse-app-logs`：問題主要來自應用日誌時使用
+### 3. 修復代碼
 
+對代碼進行修復，直至重現測試全數通過。

package/test-case-strategy/SKILL.md

@@ -1,56 +1,29 @@
 ---
 name: test-case-strategy
-description: >-
-  為實作工作選擇最小且足夠的測試組合。當 spec、功能開發、功能增強、重構或 bug 修復
-  需要明確決定單元、回歸、property、integration、E2E、對抗性測試或 drift check 時使用。
+description: 當你需要設計測試策略時，調用這個技能。
 ---
 
-# 測試案例策略
-
-## Dependencies
-
-- Required: 無
-- Conditional: 無
-- Optional: 無
-- Fallback: 無
-
-## Standards
-
-- Evidence: 只根據需求、風險、受影響模組、依賴形態與現有覆蓋情況選擇測試，不為了湊數加測試
-- Execution: 先盤點風險與 oracle，再選最小可證明風險的測試層級，必要時才升級到更重的測試
-- Quality: 每個測試都要有可重現、可驗證的明確 oracle，而不是從新寫出的實作反推
-- Output: 產出可直接執行的測試決策，包含測試 ID、目標、層級、oracle、fixture/mock 策略、驗證命令與 `N/A` 理由
-
 ## 技能目標
 
-提供一套統一的測試決策流程，讓spec技能與實作技能都能用一致的方法挑出高價值測試，並用最快、最聚焦的檢查及早發現實作偏移。
+基於當前需求，規劃完整的測試策略。
 
 ## 驗收條件
 
-- 每個非平凡變更都已建立風險清單，並明確指出需求或風險來源
-- 每個測試決策都選擇了最小但足以證明風險的測試層級，而不是預設往大測試堆
-- 每個測試都有明確 oracle、fixture 或 mock 策略，以及可執行的驗證方式
-- 若某種測試層級不適用，已留下具體 `N/A` 理由而非含糊跳過
+- 所有需求及實作任務存在關鍵性驗證測試
 
 ## 工作流程
 
-1. 先盤點變更行為、需求編號、受影響模組與風險，至少涵蓋 boundary、regression、authorization、invalid transition、idempotency、concurrency、data integrity、external failure、partial write 與 adversarial abuse
-2. 先重用現有測試，再決定新增哪些測試；只有在能說出既有 suite、case 與它覆蓋的風險時，才算真的能重用
-3. 依風險選擇最窄的有效測試層級：局部邏輯用 unit 或 regression；可描述不變量的邏輯用 property；跨模組與受控外部狀態用 integration；只有在關鍵使用者流程無法被較低層級證明時才使用 E2E；惡意輸入、重播、偽造、越界與異常組合用 adversarial
-4. 在實作前先定義 oracle，來源只能是 `spec.md`、`design.md`、`contract.md`、官方文件或既有正確行為，不能從新實作反推
-5. 對每個非平凡原子任務補上 unit drift check；若做不到，必須記錄最小替代檢查與具體原因
-6. 用統一格式記錄測試決策，讓後續技能可以直接執行與驗證
+### 1. 理解用戶需求並閱讀相關代碼
+
+理解用戶需求。同時，閱讀相關代碼實作，了解可用測試方式。
 
-## 使用範例
+### 2. 設計測試策略
 
-- 「修改驗證器的邊界規則」-> 優先選 unit test，加一個 drift check 驗證邊界值、錯誤類型與無副作用
-- 「新增排序與去重邏輯」-> 使用 property-based tests 驗證單調性、資料保留與重播不變量
-- 「改動 repository、service 與 API handler 的協作」-> 使用 integration tests 驗證跨模組資料流與錯誤處理
-- 「高價值結帳流程可能被權限與狀態機影響」-> 僅在 unit / integration 不足以證明風險時才加最小 E2E
+閱讀相關參考資料，了解在不同場景下常見的測試策略，並由此設計用戶需求及實作任務的驗證測試。
 
-## 參考資料索引
+## 參考資料
 
 - `references/unit-tests.md`：單元測試與 drift check 設計
 - `references/property-based-tests.md`：property tests 的選擇與 oracle 設計
 - `references/integration-tests.md`：整合測試與外部狀態場景設計
-- `references/e2e-tests.md`：E2E 決策與替代規則
+- `references/e2e-tests.md`：E2E 決策與替代規則

package/update-project-html/SKILL.md

@@ -1,40 +1,35 @@
 ---
 name: update-project-html
-description: >-
-  使用 `apltk architecture` 按真實程式碼 diff 刷新基礎專案 HTML 架構圖譜。先確定 diff 範圍並過濾出真正影響執行時行為的變更，再按受影響功能分派可寫子 agent 處理功能內更新；主 agent 必須等待全部子 agent 完成後，才能補跨功能邊並執行 `render` 與 `validate`。該技能只更新基礎 atlas，不使用 `--spec`。
+description: 當你發現項目架構圖過時，與實際代碼實作脫節，需要更新時，調用這個技能。
 ---
 
-# 更新專案 HTML 架構圖
-
-## 技能目標
+## 目標
 
 根據目前分支、工作區或指定提交範圍內的真實程式碼變更，增量刷新 `resources/project-architecture/` 下的基礎 atlas 與渲染 HTML，使圖譜持續和實際程式碼保持一致。
 
 ## 驗收條件
 
-- 只透過 `apltk architecture` 更新基礎 atlas；不得手改 `resources/project-architecture/**/*.html`，也不得寫入任何 `--spec` overlay 產物。
-- 在讀取原始碼前就明確本次 diff 範圍，並在報告中保留所執行的原始命令；過濾掉純文件、靜態資源、鎖檔、生成物和純格式化變更，同時記錄被跳過的類別與原因。
-- 選定範圍內每個真正影響行為的 hunk，都要麼體現在功能內元件更新或跨功能邊變化上，要麼在交付報告中明確標註「對圖譜無影響」及原因。
-- 按「每個受影響功能一個可寫子 agent」執行；主 agent 必須等全部子 agent 完成後，才允許修改跨功能 `edge`、共享 `meta` 或補充跨功能上下文。
-- 更新後的圖譜繼續滿足 `init-project-html` 的語義要求，且 `apltk architecture validate` 通過。
+- 所有架構圖已經貼合最新的代碼實作狀態。
 
 ## 工作流程
 
-1. 先確認基礎 atlas 已存在，並執行 `apltk architecture --help` 取得最新 CLI 用法；如果倉庫還沒有 atlas，改用 `init-project-html`；如果需求針對規劃文件 overlay，改用 `spec-to-project-html`。
-2. 在讀取原始碼前先決定 diff 範圍。預設同時檢查未暫存與已暫存改動；若使用者明確指定基線、提交或區間，則按使用者指定範圍執行。
-3. 僅保留真正影響程式碼行為的變更，並把這些路徑映射到受影響功能；此階段只做結構映射，不深讀函式實作。
-4. 為每個受影響功能派發一個可寫子 agent。每個子 agent 只讀取自己負責功能的現有 atlas 與變更檔案，完成全部功能內更新：子模組、函式、變數、資料流、錯誤以及功能內邊，並返回子模組變更摘要與跨功能邊界增量。
-5. 主 agent 不得重讀已委派功能的原始碼，也不得重複宣告子 agent 已處理的功能內元件；只能在全部子 agent 完成後，統一補跨功能邊、必要的共享 `meta`，再執行 `apltk architecture render` 與 `apltk architecture validate`。
-6. 最終報告至少包含：diff 範圍命令、受影響功能列表、各功能更新摘要、跨功能邊變化、被跳過的 diff 類別及原因、驗證結果，以及渲染輸出位置。
+### 1. 查看現有架構圖
+
+閱讀現有架構圖，整理當前功能模塊之間的關係、子模塊之間的關係等重要資訊。
+
+### 2. 對照代碼庫及當前架構圖
+
+閱讀當前 repo，驗證當前架構圖是否存在錯誤、遺漏。
+如果外部環境允許使用 subagents，建議通過調度 subagents 完成代碼與架構圖的對照任務。
 
-## 使用範例
+### 3. 通過 `apltk` cli 工具更新當前架構圖
 
-- 「把目前分支的程式碼變化同步到基礎架構圖。」 -> 「按分支 diff 識別受影響功能，分別更新功能內宣告，再統一補跨功能連接並重新渲染。」
-- 「刷新這次 PR 的專案 HTML atlas。」 -> 「先鎖定 PR 的 diff 基線，再僅處理有執行時影響的變更，避免無關文件改動污染圖譜。」
+使用 `apltk` cli工具，協助完成整個架構圖的更新，確保架構圖完全描述了：
+- 功能模塊之間的關係
+- 子模塊之間的關係
+- 項目資料庫、錯誤處理
 
-## 參考資料索引
+## 參考資料
 
-- `init-project-html/SKILL.md`：基礎 atlas 的語義規則、子模組表達約束與總體驗收標準。
-- `spec-to-project-html/SKILL.md`：當需求針對 `docs/plans/...` overlay 而非基礎 atlas 時使用。
-- `README.md`：本技能的簡要用途說明。
-- `apltk architecture --help`：命令、參數和子命令的唯一真源。
+- `references/definition.md` - 功能模塊與子模塊的定義
+- `apltk architecture --help` - cli 工具的指引

package/update-project-html/references/definition.md

@@ -0,0 +1,12 @@
+## 功能模塊
+
+功能模塊是直接面向用戶的功能，如：
+- 登陸功能
+- 註冊功能
+- 邀請碼功能
+
+功能模塊由子模塊的合作、交互實現
+
+## 子模塊
+
+子模塊是功能模塊的關鍵組成部分。具體定義依照代碼的實作邊界得出。

package/version-release/SKILL.md

@@ -1,53 +1,33 @@
 ---
 name: version-release
-description: >-
-  用於明確的 semver 發版流程。必須先完成 `commit-and-push` 共用 gate 與
-  `submission-readiness-check`，再決定版本、更新 changelog、建立 tag、推送並發布 GitHub Release。
+description: 當你需要協助用戶完成版本發佈時，使用這個技能。
 ---
 
-# 版本發佈
-
-## Dependencies
-
-- Required: `commit-and-push`、`submission-readiness-check`
-- Conditional: `archive-specs`
-- Optional: 無
-- Fallback: 缺少必需技能時必須停止，不能憑印象手動補一個發版流程
-
-## Standards
-
-- Evidence: 以版本檔、`CHANGELOG.md`、本地/remote tag、既有 GitHub Release 與使用者明確的 bump 意圖作為依據
-- Execution: 先確認這真的是 release 請求，再完成所有 gate，之後才更新版本、切 changelog、打 tag、推送與發布 Release
-- Quality: 不猜版本、不重複發版、不用原始 diff 臨時拼 release notes；所有版本入口必須同步一致
-- Output: 交付可驗證的版本發佈結果，包含版本號、tag、remote驗證與 GitHub Release URL
-
 ## 技能目標
 
-把明確的發版需求轉成一條完整、可驗證、可追溯的 semver 流程，確保版本檔、changelog、git tag、remote狀態與 GitHub Release 彼此一致。
+幫用戶完成自動化版本發佈流程
 
 ## 驗收條件
 
-- 已先確認這是明確的 release / semver 請求；若只是 commit 或 push，必須改走 `commit-and-push`
-- 在修改任何版本相關檔案前，已清楚說出 current -> next 版本與將建立的 tag 字串
-- `submission-readiness-check` 與必要的 `archive-specs` 都已完成，且 `CHANGELOG.md` 的 `Unreleased` 內容足以支撐本次發版
-- 最終已同步版本檔、發布說明、commit、tag、remote refs 與 GitHub Release；若使用者明確要求不發布 Release，需在結果中清楚註明
+- `CHANGELOG.md`, `docs/` 下所有項目文檔已經被同步到最新狀態
+- Github release, Github version tag 被完成創建
 
 ## 工作流程
 
-1. 先確認使用者是否真的要求 release、publish、tag、patch、minor、major 或其他明確 semver 動作；若沒有，改用 `commit-and-push`
-2. 檢查目前 git 狀態、版本檔、既有 tag、本地與remote是否已有同版本 tag，以及 GitHub 上是否已有同版本 Release，避免重複發版
-3. 對 code-affecting 範圍執行 `submission-readiness-check`；若它要求 `archive-specs` 或 changelog/文件同步，必須先完成
-4. 根據版本檔、repo 歷史與使用者指示決定 current -> next 版本與 tag 格式；若語意不明，優先選較小 bump 並請使用者確認
-5. 一致更新所有版本入口，並把 `CHANGELOG.md` 的 `Unreleased` 移到新的版本區塊；release notes 只能來自整理過的 changelog 內容
-6. 建立 release commit 與 tag；若是 prerelease retarget，保留版本號不變，只把 tag / Release 移到新的 commit
-7. 推送分支與 tag，並驗證remote commit 與 tag 都已正確存在
-8. 使用 `gh release create` 或 repo 慣用工具建立或更新 GitHub Release，最後回報版本號、tag 與 release URL
+### 1. 檢查並確認 repo 狀態
+
+閱讀目前的 repo 狀態。查看是否依然存在未提交變更。如有，使用 `commit-and-push` 技能將目前為提交的變更暫存並提交。推送到 remote。
+
+### 2. 更新項目文檔狀態
+
+完整閱讀上一次發佈版本至今的所有變更，並檢查文檔之中的表述是否存在錯誤或遺漏。如有，使用 `align-project-documents`, `maintain-project-constraints` 這兩個技能將所有項目文檔同步到最新狀態。
+如果外部環境允許使用 subagents，建議通過調度subagents完成變更的逐行深度閱讀。
 
-## 使用範例
+### 3. 發佈版本
 
-- 「發 patch release」-> 先確認目前版本與 changelog，再更新到下一個 patch、建立 tag 並發布 Release
-- 「把 prerelease tag 移到最新修正」-> 不增加版本號，只重新對準 tag 與對應 Release
-- 「幫我 commit 然後 push」-> 不使用本技能，改走 `commit-and-push`
+確認所有文檔都已經被更新之後，更新 repo 的版本文件（如 pyproject.toml, cargo.toml）。
+使用 `commit-and-push` 技能將所有變更提交並推送到 remote。
+最後，將用戶要求的版本所對應的 version tag 推送到 remote 並建立 github release。
 
 ## 參考資料索引
 
@@ -56,4 +36,3 @@ description: >-
 - `references/branch-naming.md`：分支命名慣例
 - `references/changelog-writing.md`：`CHANGELOG.md` 與 `Unreleased` 維護規則
 - `references/readme-writing.md`：README 只在必要時同步更新
-- `commit-and-push`：共享的 git 檢查、提交與推送 discipline

package/iterative-code-performance/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 LaiTszKin
-
-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/iterative-code-performance/README.md

@@ -1,34 +0,0 @@
-# iterative-code-performance
-
-Improve an existing repository through a strict three-step loop of full-codebase performance scan, module-scoped optimization, and final documentation/constraint sync while preserving intended business behavior and the system's top-level macro architecture.
-
-## Core capabilities
-
-- Runs a repository-wide performance scan before every optimization round and refreshes a concrete bottleneck backlog.
-- Uses a strict three-step loop: scan the codebase, choose this round's jobs and optimize, then update docs/constraints only when no actionable gap remains.
-- Builds a module inventory and coverage ledger so every in-scope module receives a performance-oriented deep-read iteration before completion.
-- Defines deep-read as a job-oriented scan across measurement, algorithmic complexity, repeated work, IO, batching, query behavior, caching, allocation churn, hot loops, concurrency, and staged unlock opportunities.
-- Prioritizes measured or clearly complexity-backed bottlenecks over speculative micro-optimizations.
-- Adds or updates benchmark, characterization, regression, load, or integration guardrails when optimization risk requires them.
-- Requires confidence decisions to combine the agent's self-assessed ability, task complexity, guardrail strength, rollback or repair paths, and whether strong tests or benchmarks can safely drive broken optimizations back to green.
-- Reduces avoidable repeated computation, unnecessary serialization/parsing, allocation churn, IO round trips, inefficient query patterns, and unbounded concurrency.
-- Introduces caching or memoization only when ownership, invalidation, size bounds, and failure behavior are clear.
-- Treats large coupled hot paths as staged unlock problems, not as automatic stop signals.
-- Re-scans the full repository after every iteration and repeats while any known in-scope actionable performance issue or unvisited in-scope module remains.
-- Synchronizes project docs and `AGENTS.md/CLAUDE.md` through `align-project-documents` and `maintain-project-constraints` after implementation.
-
-## Repository structure
-
-- `SKILL.md`: Main three-step loop, dependencies, guardrails, and output contract.
-- `agents/openai.yaml`: Agent interface metadata and default prompt.
-- `references/`: Focused guides for scanning, module coverage, job selection, measurement, algorithmic complexity, IO, caching, hot loops, concurrency, unlock work, and iteration gates.
-
-## Typical usage
-
-```text
-Use $iterative-code-performance to improve this repository's speed end to end without changing business behavior or macro architecture.
-```
-
-## License
-
-MIT. See `LICENSE`.

package/iterative-code-performance/SKILL.md

@@ -1,116 +0,0 @@
----
-name: iterative-code-performance
-description: >-
-  Improve an existing codebase through repeated evidence-based repository-wide
-  performance scans, module-by-module deep-read coverage, and behavior-safe
-  speed optimizations until no known in-scope actionable bottleneck or unvisited
-  in-scope module remains: measure hot paths, reduce algorithmic complexity,
-  remove avoidable repeated work, optimize IO and batching, control allocation
-  churn, improve caching only where invalidation is clear, and add benchmark or
-  regression guardrails while preserving intended business behavior and the
-  system's macro architecture. Use when users ask for comprehensive speed,
-  latency, throughput, CPU, memory-allocation, query, batching, or hot-path
-  optimization across a repository.
----
-
-# Iterative Code Performance
-
-## Dependencies
-
-- Required: `align-project-documents` and `maintain-project-constraints` after the repository is truly iteration-complete.
-- Conditional: `systematic-debug` when a performance test, benchmark, load run, or production trace exposes a real business-logic defect that must be fixed at the true owner; `improve-observability` when profiling signals are missing or measurement requires durable logs, metrics, or traces.
-- Optional: `improve-observability` for profiling signals or durable metrics needed during optimization.
-- Fallback: If required completion dependencies are unavailable, finish performance work and validation first, then report exactly which documentation, constraint-sync, or observability action could not run.
-
-## Standards
-
-- Evidence: Read repository docs, project constraints, source, tests, logs, benchmarks, profiler output, build scripts, entrypoints, and nearby abstractions before editing; every optimization must be justified by measured evidence or clear complexity analysis tied to a plausible hot path.
-- Execution: Run a continuous three-step loop of full-codebase performance scan → choose this round's jobs and optimize → if and only if the latest full-codebase scan is clear, update docs and constraints; otherwise return to scanning immediately. Maintain a module inventory and coverage ledger so every in-scope module receives a performance-oriented deep-read iteration before completion. Do not treat jobs as workflow steps. Do not produce a completion report while any known in-scope actionable bottleneck or unvisited in-scope module remains.
-- Quality: Resolve as many inherited performance problems as safely possible without changing intended behavior or the system's macro architecture. Do not optimize by guessing, weakening correctness, adding stale caches, hiding failures, or moving cost to another critical path without evidence.
-- Output: Return iteration-by-iteration decisions, selected jobs, module coverage status, changed files, speedup or complexity evidence, behavior-preservation evidence, benchmark and regression guardrails, validation results, and docs/constraint sync status only after the latest scan shows no remaining known actionable in-scope bottleneck and no unvisited in-scope module.
-
-## Mission
-
-Leave the repository materially faster by continuously scanning the whole codebase, landing the highest-value safe performance optimizations available at each moment, and repeating until there is no known in-scope actionable performance gap left to fix.
-
-For this skill, `macro architecture` means the system's top-level runtime shape and overall operating logic: major subsystems, top-level execution model, deployment/runtime boundaries, persistence model, service boundaries, and the end-to-end way the whole system works. Ordinary module interactions, helper extraction, local data-structure changes, internal batching, query shaping, memoization inside an owner, and local hot-path decomposition do not count as macro-architecture changes by themselves.
-
-## Three-Step Loop
-
-### 1) Scan the repository
-
-- Read root guidance first: `AGENTS.md/CLAUDE.md`, `README*`, package manifests, task runners, CI/test config, benchmark tooling, profiler setup, and major project docs.
-- Map runtime entrypoints, domain modules, external integrations, persistence/query boundaries, queue or job workers, request paths, hot loops, and current performance guardrails.
-- Exclude generated, vendored, lock, build-output, fixture, snapshot, or minified files unless evidence shows they are human-maintained source.
-- Build or refresh a concrete repository-wide backlog of known actionable performance issues.
-- Build or refresh a module inventory and coverage ledger; every in-scope module starts as unvisited until it has received a performance-oriented deep-read iteration with callers, callees, tests, logs, benchmarks, relevant contracts, and each available job lens inspected.
-- Re-scan the full codebase after every landed iteration, not only the files just changed.
-- Load `references/repository-scan.md` for the scan checklist and performance-backlog shaping rules.
-- Load `references/module-coverage.md` for module inventory, performance deep-read coverage, easy-first ordering, and completion rules.
-
-### 2) Choose this round's jobs and optimize
-
-- Choose jobs only after the latest full-codebase performance scan. Jobs are optional execution directions, not ordered workflow steps.
-- Treat module scanning and job choice as one linked activity: inspect the selected module through every available performance job lens before deciding which jobs actually land in this round.
-- Select the smallest set of jobs that can safely improve the currently selected module or module cluster under current correctness and measurement guardrails.
-- Before choosing or deferring an optimization, explicitly assess implementation confidence as a combination of the agent's own ability to understand and complete the change, the objective safety net from tests, benchmarks, and other guardrails, the clarity of rollback or repair paths, and the task's inherent difficulty. Do not treat difficulty alone as low confidence; when strong tests and benchmarks guard the behavior, use them to support bolder changes because failures can be driven back to green.
-- Prefer evidence-first ordering: start with bottlenecks that are measured, user-visible, high-frequency, or have clear algorithmic waste; use easy-first module ordering when it builds profiling context, tests, benchmarks, or seams that make harder hot paths safer later.
-- Do not keep revisiting familiar modules while other in-scope modules remain unvisited unless the familiar module blocks the next unvisited module's safe performance deep read.
-- Prefer smaller, high-confidence optimizations that reduce latency, CPU, memory churn, IO round trips, or repeated work without broad behavior risk.
-- If a desired optimization is high-risk and weakly guarded, make benchmark, characterization, or regression guardrail-building part of this round instead of stopping.
-- If a file feels too coupled, too central, or too risky for a direct hot-path rewrite, do staged unlock work rather than declaring the area blocked.
-- Read all directly affected callers, tests, interfaces, logs, persistence/query contracts, cache invalidation rules, and concurrency assumptions before editing.
-- Validate from narrow to broad after each bounded round, then perform a full-codebase stage-gate decision:
-  - if any known in-scope actionable bottleneck still remains or any in-scope module has not received a deep-read iteration, return to Step 1;
-  - only continue to Step 3 when the latest scan is clear.
-
-Load references for this step only as needed:
-
-- `references/module-coverage.md` for choosing the next module and proving every in-scope module has been deeply read through the available performance-job lenses.
-- `references/job-selection.md` for next-job choice conditions and tie-breakers.
-- `references/measurement-and-benchmarking.md` for profiling, benchmark, baseline, and before/after comparison rules.
-- `references/algorithmic-complexity.md` for complexity, data-structure, and repeated-work optimization.
-- `references/io-batching-and-queries.md` for database, network, filesystem, external API, and batching optimization.
-- `references/caching-and-memoization.md` for safe cache introduction, cache removal, and invalidation rules.
-- `references/allocation-and-hot-loops.md` for CPU loops, allocation churn, serialization, parsing, and memory-pressure cleanup.
-- `references/concurrency-and-pipelines.md` for bounded parallelism, async pipelines, backpressure, and queue throughput.
-- `references/coupled-hot-path-strategy.md` for staged unlock work on large coupled or apparently core hot-path files.
-- `references/iteration-gates.md` for validation cadence, stage-gate rules, and stop criteria.
-
-### 3) Update project documents and constraints
-
-Only enter this step when the latest full-codebase scan confirms there is no remaining known actionable in-scope performance issue and every in-scope module has received a deep-read iteration, except items explicitly classified as blocked, unsafe, speculative, low-value, excluded, approval-dependent, or requiring production-only measurement that is unavailable.
-
-- Run `align-project-documents` when README, architecture notes, setup docs, benchmark docs, performance budgets, operational docs, or test guidance may have drifted.
-- Run `maintain-project-constraints` to verify `AGENTS.md/CLAUDE.md` still matches the repository's real architecture, business flow, commands, and conventions.
-- Update only the documentation and constraints that changed in reality because of the optimization.
-
-## Hard Guardrails
-
-- Do not change intended business logic while optimizing, except to fix a real defect exposed by tests and verified at the true owner.
-- Do not change the system's macro architecture unless the user explicitly expands scope.
-- Do not optimize from vibes alone; require measurement, traces, logs, benchmark baselines, complexity analysis, or repeatable workload evidence.
-- Do not add caches without explicit ownership, invalidation, size bounds, failure behavior, and tests or equivalent validation.
-- Do not improve one metric by silently worsening a more important user-visible path, correctness invariant, memory ceiling, or operator workflow.
-- Do not use one-off scripts to rewrite product code.
-- Do not stop early just because a hot path is large, central, or historically fragile; if a safe unlock step exists, that is the next job.
-- Do not stop before every in-scope module has been inventoried, deeply read, and either improved, validated as clear, or explicitly deferred/excluded with evidence.
-- Do not weaken tests, benchmarks, timeouts, or assertions to make an optimization pass; fix the real defect, stabilize the benchmark, or update stale expectations to stable invariants.
-- Do not add micro-optimizations that make code harder to maintain unless evidence shows the path is hot enough to justify the tradeoff.
-
-## Completion Report
-
-Only report completion after Step 3 is done, the latest Step 1 scan is clear, and the module coverage ledger has no unvisited in-scope module.
-
-Return:
-
-1. Iterations completed and the jobs selected in each iteration.
-2. Stage-gate verdict after each full-codebase re-scan.
-3. Module coverage ledger summary: modules deep-read, improved, validated-clear, deferred, or excluded.
-4. Key files changed and the performance issue each change resolved.
-5. Speedup evidence, complexity change, or bottleneck-removal evidence, including baseline and after measurements where available.
-6. Business behavior preservation evidence.
-7. Benchmarks, regression tests, or other guardrails added or updated, including property/integration/E2E/load-test `N/A` reasons where relevant.
-8. Validation commands and results.
-9. Documentation and `AGENTS.md/CLAUDE.md` synchronization status.
-10. Remaining blocked, production-measurement-only, or approval-dependent items, if any.

package/iterative-code-performance/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Iterative Code Performance"
-  short_description: "Optimize latency, throughput, CPU, IO, caching, and hot paths in repeated safe passes"
-  default_prompt: "Use $iterative-code-performance as a strict three-step loop. Step 1: scan the full repository for performance evidence, refresh the actionable bottleneck backlog, and maintain a module inventory plus performance coverage ledger. Step 2: choose this round's module or bounded module cluster, scan it through every available performance job lens, and only then decide which jobs actually land now; prioritize measured or clearly complexity-backed hot paths, jobs are selectable directions rather than workflow steps, and assess optimization confidence from your own ability to understand and complete the change, task complexity, guardrail strength, rollback or repair paths, and whether tests or benchmarks can drive accidental breakage back to green. If a high-risk hot path is weakly guarded add benchmarks, characterization tests, or other guardrails instead of stopping; if strong tests and benchmarks guard the behavior, use them to justify bolder safe optimizations rather than avoiding the work. If a file is too coupled or too central for direct optimization, switch to staged unlock work and keep progressing. After validation, run a full-codebase stage-gate; if any known in-scope actionable bottleneck remains or any in-scope module has not received a performance-oriented deep-read iteration, go back to Step 1 immediately. Step 3: only when the latest full-codebase performance scan is clear and every in-scope module is deeply read through the available-job lenses, run $align-project-documents and $maintain-project-constraints to synchronize docs and AGENTS.md/CLAUDE.md. Preserve intended business behavior and the system's macro architecture, keep correctness guardrails green, and do not write a completion report while actionable bottlenecks or unvisited modules still exist."