@laitszkin/apollo-toolkit 3.12.0 → 3.13.0

package/optimise-skill/SKILL.md

@@ -12,19 +12,19 @@ description: Use prompt engineering to optimise agent skill. Use it when you nee
 
 ## 工作流程
 
-1. 識別交付物
+### 1. 識別交付物
 完整閱讀整個技能的 `SKILL.md` 文檔，以及其引用的所有額檔案，包括但不限於 `references/` , `scripts/` 。基於獲取到的技能上下文資訊，總結出該技能的最終交付產物。
 
-2. 制定驗收條件
+### 2. 制定驗收條件
 制定驗收條件，從而確保LLM能夠穩定、可復現地按照驗收條件產出符合要求高質量最終交付物
 
-3. 重寫技能
+### 3. 重寫技能
 將整個技能的 `SKILL.md` 重寫。重寫後的技能應該只包含以下幾個關鍵組成部分：
-- 技能目標
-- 技能驗收條件
-- 技能工作流程
-- 技能使用範例
-- 技能參考資料索引
+- 目標
+- 驗收條件
+- 工作流程
+- 範例
+- 參考資料
 對於技能有幫助的內但不符合上述技能架構規範，則應該被分類放置在 `references/` 下的markdown檔案。
 
 ## 範例

package/optimise-skill/references/definition.md

@@ -26,6 +26,7 @@
 
 ## 範例
 範例是一個技能之中讓效果達到預期的重要基礎。其本質上是通過**對比交付產物在執行工作流程前及執行工作流程後的狀態**，讓agent在調用工作流程自行工作的時候對目標有著清晰的認知，從而避免在執行時成為無頭蒼蠅並在上下文之中迷失。
+並非所有技能都需要範例。只有非常複雜的任務需要通過範例提示來確保 agent 理解工作流程。
 
 **建議實踐**：
 用一個用於優化提示詞技能的技能作為示例：

package/optimise-skill/references/example_skill.md

@@ -12,19 +12,19 @@ description: Use prompt engineering to optimise agent skill. Use it when you nee
 
 ## 工作流程
 
-1. 識別交付物
+### 1. 識別交付物
 完整閱讀整個技能的 `SKILL.md` 文檔，以及其引用的所有額檔案，包括但不限於 `references/` , `scripts/` 。基於獲取到的技能上下文資訊，總結出該技能的最終交付產物。
 
-2. 制定驗收條件
+### 2. 制定驗收條件
 制定驗收條件，從而確保LLM能夠穩定、可復現地按照驗收條件產出符合要求高質量最終交付物
 
-3. 重寫技能
+### 3. 重寫技能
 將整個技能的 `SKILL.md` 重寫。重寫後的技能應該只包含以下幾個關鍵組成部分：
-- 技能目標
-- 技能驗收條件
-- 技能工作流程
-- 技能使用範例
-- 技能參考資料索引
+- 目標
+- 驗收條件
+- 工作流程
+- 範例
+- 參考資料
 對於技能有幫助的內但不符合上述技能架構規範，則應該被分類放置在 `references/` 下的markdown檔案。
 
 ## 範例

package/package.json

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

package/review-spec-related-changes/SKILL.md

@@ -1,47 +1,39 @@
 ---
 name: review-spec-related-changes
-description: >-
-  面向spec合規性的只讀審查技能。先唯一確定本次變更受哪一套 `docs/plans/...` 規劃文件約束，再按業務目標逐條判定 `Met`、`Partially met`、`Not met` 或 `Deferred/N/A`；`tasks.md` 的勾選不算證據。若範圍涉及代碼實作，完成業務結論後還必須對同一範圍追加 `review-change-set`、`discover-edge-cases` 與 `discover-security-issues`，並保持固定報告順序。
+description: 當你需要審查規格文檔相關變更時，調用此技能
 ---
 
 ## 目標
-輸出一份只讀的spec合規審查報告，先回答「這次變更是否真的滿足規劃中的業務要求」，再補充邊界、安全與代碼審查發現。報告需要對每條關鍵需求給出可追溯的狀態判定、證據來源、缺口說明、通過證據與剩餘不確定性；本技能不負責修改代碼或更新規劃文件。
+
+輸出一份 spec 相關變更審查報告，先回答「這次變更是否真的滿足規劃中的業務要求」，再補充邊界、安全與代碼審查發現。每條關鍵需求需給出可追溯的狀態判定、證據來源、缺口說明與剩餘不確定性；不負責修改代碼或更新規劃文件。
 
 ## 驗收條件
-- 在給出任何合規結論前，已唯一確定 governing spec；若存在兩個同樣合理的規劃根目錄且無法由倉庫證據消歧，必須停止並報告歧義，不能猜測。
-- 每條業務目標或驗收項只能根據可驗證證據判定為 `Met`、`Partially met`、`Not met` 或 `Deferred/N/A`；證據可來自代碼、測試、命令、日誌或追蹤，`tasks.md` 勾選本身不算證據。
-- 未滿足或部分滿足的必選業務要求永遠是最高嚴重度，報告排序中不得被安全、邊界或可維護性意見壓過。
-- 若範圍涉及代碼實作，完成業務結論後必須在同一範圍追加 `review-change-set`、`discover-edge-cases` 與 `discover-security-issues`；任一依賴不可用時，不得輸出「完整通過」結論。
-- 全流程保持只讀：不得修改實作、測試、spec、archive、commit、push、tag 或 release。
-- 最終交付物固定按以下順序輸出：業務缺口 → 邊界情況 → 安全問題 → 代碼審查問題 → 已滿足要求的通過證據 → 剩餘不確定性。
+
+- 生成完整的 code review report，內容涵蓋6個維度的代碼審查結果及改進建議。
 
 ## 工作流程
-1. 確定 governing spec。
-   - 若使用者已指定具體路徑，直接以該規劃目錄為準，閱讀 `spec.md`、`tasks.md`、`checklist.md`、`contract.md`、`design.md`，以及存在時的 `coordination.md`。
-   - 若使用者未指定，需根據 `git status`、diff、相關路徑、近期提交與計劃目錄證據回推出唯一 spec；若仍有歧義，立即停止。
-2. 建立spec基線。
-   - 從 governing spec 中抽取業務目標、驗收條件、非目標、已明示的延期項與要求執行的驗證。
-   - 將「產品必須做到什麼」和「代碼寫得是否漂亮」明確分開。
-3. 蒐集實作證據並先做業務判定。
-   - 閱讀最小必要代碼路徑、相關 diff、提交與測試，必要時執行 spec 點名且安全可跑的驗證命令。
-   - 對每條需求給出 `Met`、`Partially met`、`Not met` 或 `Deferred/N/A`，並附上精確 spec 引用與代碼/測試證據。
-   - 若 spec 中存在完全獨立的需求群組，可用只讀 subagent 並行評分；但最終排序、嚴重度與跨需求衝突整理由主代理負責。
-4. 對代碼範圍追加次級審查。
-   - 若審查對象包含代碼實作，必須在同一範圍追加 `review-change-set`、`discover-edge-cases` 與 `discover-security-issues`。
-   - 優先以一個只讀 subagent 對應一個次級技能並行執行，主代理只負責聚合結果，不重跑已委派分析。
-   - 若次級審查結果反過來影響某條業務需求的判定，必須先回寫業務結論，再輸出最終報告。
-5. 生成固定順序的最終報告。
-   - 先列出 `Not met` 與 `Partially met` 的業務缺口，再依序列出邊界情況、安全問題、代碼審查問題。
-   - 接著補上所有已確認 `Met` 的通過證據。
-   - 最後列出未驗證命令、無法映射的 spec 段落、外部依賴不可驗證處與其他剩餘不確定性。
-
-## 使用範例
-- 「這個 PR 有沒有滿足 `coordination.md` 和 `spec.md`？」-> 先唯一確定 governing spec，再按業務要求逐條打分，最後補上同範圍的邊界、安全與變更集審查。
-- 「請檢查 `docs/plans/2026-05-01/foo/` 對應的實作是否完成」-> 直接以指定目錄為準做只讀合規審查，不依賴聊天上下文猜測。
-- 「`tasks.md` 都打勾了，應該算完成吧？」-> 不能直接採信，仍需用代碼、測試、命令或追蹤證據重新驗證每條要求。
-- 「先跟我講哪個 requirement 沒達成，再看程式碼好不好」-> 報告必須先輸出業務缺口，不能先用重構或風格意見掩蓋未滿足的spec要求。
-
-## 參考資料索引
-- `review-change-set`：在相同代碼範圍上補做架構與簡化審查，避免將spec合規與代碼品質混為一談。
-- `discover-edge-cases`：在相同範圍上補做可重現邊界情況審查，補齊失敗路徑、併發與可觀測性風險。
-- `discover-security-issues`：在相同範圍上補做可重現安全審查，補齊攻擊面、授權與資料外洩風險。
+
+### 1. 建立審查範圍
+
+閱讀用戶指定的 spec ，並按照 spec 之中定義的實作範圍，檢索並閱讀相關代碼。
+如果外部環境允許使用 subagents，建議通過調度 subagents 完成代碼的深度閱讀。
+
+### 2. 進行多維度審查
+
+對所有實作代碼多維度的審查，確保代碼：
+- 無幻覺代碼
+- 無冗余代碼
+- 代碼無與 spec 之間的實作偏移
+- 無 spec 實作遺漏
+- 無架構瑕疵
+- 無性能隱患
+
+如果有代碼違反了上述6個原則，將他們紀錄在案。
+如果外部環境允許使用 subagents，建議通過調度 subagents 完成對代碼的多維度審查。
+
+### 3. 生成 code review report
+
+將上一步發現的所有問題代碼總結，並按照問題嚴重程度排序，生成code review report。report需要包含以下元素：
+- 問題描述、嚴重度及影響
+- 涉及的代碼檔案、行數
+- 建議修正方案

package/ship-github-issue-fix/SKILL.md

@@ -7,7 +7,7 @@ description: Resolve a GitHub issue in an existing repository and submit the fix
 
 ## Dependencies
 
-- Required: `read-github-issue`, `enhance-existing-features`, `recover-missing-plan`, and `commit-and-push`.
+- Required: `read-github-issue`, `enhance-existing-features`, and `commit-and-push`.
 - Conditional: `systematic-debug` when the issue is primarily a bug investigation or failing behavior report.
 - Optional: none.
 - Fallback: If any required dependency is unavailable, stop and report which dependency blocked the workflow.
@@ -32,7 +32,7 @@ description: Resolve a GitHub issue in an existing repository and submit the fix
 ### 2) Explore the codebase and decide whether specs are required
 
 - After reading the issue, inspect the real entrypoints, affected modules, tests, and existing planning files.
-- If the user references an expected `docs/plans/...` path that is missing or archived unexpectedly, run `$recover-missing-plan` before treating the issue as unspecced work.
+
 - Run `$enhance-existing-features` to decide whether specs are required from the actual change surface.
 - Default to direct implementation for clearly localized bug fixes, regressions, narrow optimizations, or small workflow corrections, even when the issue wording sounds broad.
 - Require specs when the explored change touches critical money movement, permissions, high-risk concurrency, or multi-module behavior changes that need approval traceability.

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

@@ -1,58 +1,23 @@
 ---
 name: solve-issues-found-during-review
-description: >-
-  用於根據已確認的 review finding 清單逐項修復問題。必須按嚴重度排序、最小化修改、
-  每項修完立即驗證，並在結束前證明 spec 合規與相關安全 / edge-case finding 已真正清乾淨。
+description: 當你需要修復 code review report 之中發現的問題時，調用這個技能。
 ---
 
-# 修復審查發現的問題
-
-## Dependencies
-
-- Required: 使用者必須提供既有 review 報告或可重建的 finding 清單
-- Conditional: `review-spec-related-changes`、`review-change-set`、`systematic-debug`、`discover-security-issues`、`discover-edge-cases`、`commit-and-push`
-- Optional: 無
-- Fallback: 若沒有可重建的 finding 清單就必須停止；若 `review-change-set` 不可用，至少要用針對性測試與 diff 證據補足；若使用者要求提交或推送但 `commit-and-push` 不可用，也必須停止
-
-## Standards
-
-- Evidence: 每個修改都要能對應到一條已確認 finding、受影響程式碼與驗證證據
-- Execution: 依嚴重度由高到低處理，每項 finding 修完就驗證，再進入下一項；最後再做全域重驗證
-- Quality: 僅修確認問題，不夾帶順手重構或推測性 hardening；不能重現時必須留下 `Could not reproduce` 證據
-- Output: 交付逐項狀態、驗證證據、spec 合規結果、 ancillary review 清理結果，以及是否真正完成本輪修復
-
 ## 技能目標
 
-把 review 報告中的 confirmed findings 轉成一條可追蹤、可驗證、可收斂的修復流程，避免只做表面修改，並在結束前證明相關spec、安全與 edge-case 要求沒有留下實質風險。
+遵照 code review report 之中的建議方案，逐一將所有發現的代碼問題修正。
 
 ## 驗收條件
 
-- 每個程式碼改動都能對應到明確的 finding，且沒有混入無關修補
-- 所有 finding 均按嚴重度順序處理，並在每項修復後留下通過的驗證證據
-- 若此範圍受 `docs/plans/...`、`spec.md`、`tasks.md`、`checklist.md` 或 contract 約束，最終已有 spec 合規證據
-- 安全、edge-case 與其他隨附 review finding 已被修復或以可重現證據標記 `Could not reproduce`；若仍有 `Deferred`，只有在使用者明確縮 scope 時才能宣稱本輪完成
+- 所有 code review report 之中明確列出的問題都已經被完全修復。
 
 ## 工作流程
 
-1. 先完整閱讀 report 與受影響程式碼；若使用者只說「修 review finding」但沒提供內容，先嘗試從近期輸出或 diff 重建清單，重建失敗就停止
-2. 擷取每條 finding 的嚴重度、標題、證據位置與重現方式，並排除沒有被 reviewer 明確確認的猜測性項目
-3. 按 Critical -> High -> Medium -> Low 排序；只有在工作空間完全隔離且檔案不重疊時，才允許平行處理不同群組，否則一律串行
-4. 逐條處理 finding：先讀程式碼與重現路徑，再用最小修改修復，立刻執行最窄且足夠的驗證；若驗證結果不清楚，交給 `systematic-debug`
-5. 全部 finding 處理完後，對修改範圍做整體重驗證；若是 code-affecting 變更，重新跑 `review-change-set`
-6. 若存在綁定 spec 或計劃檔，使用 `review-spec-related-changes` 證明已重新符合要求；若 inbound package 含安全或 edge-case finding，使用 `discover-security-issues` 或 `discover-edge-cases` 的 rerun / scoped proof 證明該維度已清空
-7. 向使用者輸出逐項狀態、驗證命令、殘留阻塞與本輪是否真的完成；若要求提交或推送，再交給 `commit-and-push`
-
-## 使用範例
+### 1. 完整閱讀 code review report
 
-- 「修這份 review 裡的 HIGH SSRF finding」-> 只修該 finding 對應路徑，跑針對性測試與重現命令，確認通過後才處理下一條
-- 「report 裡還有 edge-case 與 security finding」-> 修完主問題後，還要補 rerun / scoped proof，不能只靠口頭說明就宣稱完成
-- 「reviewer 指的路徑現在不存在」-> 記錄檢查過的 commit 與路徑，若無法重現則標成 `Could not reproduce`，而不是虛構一個修復
+完整閱讀 code review report，並深入閱讀相關受影響代碼，理解建議修復方案。
+如果外部環境允許使用 subagents，建議通過subagents完成對代碼的深度閱讀。
 
-## 參考資料索引
+### 2. 修復發現的問題
 
-- `review-spec-related-changes`：驗證修復後仍符合 spec / plan
-- `review-change-set`：修復後的 code-affecting 差異重審
-- `systematic-debug`：修復過程中遇到不明測試或 runtime 問題時使用
-- `discover-security-issues`：清理安全 finding 時的 scoped proof
-- `discover-edge-cases`：清理 edge-case / hardening finding 時的 scoped proof
-- `commit-and-push`：使用者要求提交或推送時的最終交付流程
+按照 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`、`scheduled-runtime-health-check`
-- 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. 分析問題
+
+按照用戶給出的資訊，結合相關代碼實作片段閱讀，排查可能導致問題的原因。
 
-## 使用範例
+### 2. 滲透測試
 
-- 「這個 API 應該回 200，現在卻變成 500」-> 先確認預期契約，再重現所有合理根因，最後定位是 handler 邏輯、依賴服務還是測試 fixture 問題
-- 「測試單獨跑會過，但整個 suite 會 flaky」-> 優先排查共享狀態、鎖、暫存目錄與環境污染，而不是先改產品邏輯
-- 「bounded run 幾乎沒有事件發生」-> 先沿著 lifecycle funnel 判斷停在哪個階段，再確認是 profile 過度破壞、編排錯誤，還是實際業務邏輯問題
+整理所有可能導致問題的原因，撰寫測試案例嘗試重現該問題。
+如果你發現所有你構思的可能性均無法重現該非預期行為，你需要重新構思，直至該非預期行為被測試有效重現。
 
-## 參考資料索引
+### 3. 修復代碼
 
-- `test-case-strategy`：需要補重現測試或 drift check 時使用
-- `analyse-app-logs`：問題主要來自應用日誌時使用
-- `scheduled-runtime-health-check`：需要有界執行與執行後分析時使用
+對代碼進行修復，直至重現測試全數通過。

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: `review-change-set`、`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`、必要的 `review-change-set` 與 `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 範圍先完成 `review-change-set`，再執行 `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/discover-edge-cases/CHANGELOG.md

@@ -1,19 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-## [v0.2.1] - 2026-02-17
-
-### Changed
-- Remove `submit-changes` skill dependency from no-diff release flow while keeping the PR workflow.
-- Update skill and README guidance to use direct git commit/push before opening a PR.
-
-## [v0.2.0] - 2026-02-17
-
-### Added
-- Add no-diff workflow guidance to scan the whole codebase for actionable edge cases.
-- Add release-flow guidance for no-diff fixes: create worktree, use `submit-changes`, and open a PR.
-
-### Changed
-- Clarify scope selection logic: `git diff` path uses changed files only; no-diff path uses full-codebase scan.
-- Expand README examples to include a no-diff prompt and expected execution path.

package/discover-edge-cases/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.