@laitszkin/apollo-toolkit 3.12.1 → 3.13.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this repository are documented in this file.
 
+## [Unreleased]
+
+### Changed
+
+- Further tighten SKILL.md files (`archive-specs`, `commit-and-push`, `generate-spec`, `init-project-html`, `maintain-project-constraints`, `merge-changes-from-local-branches`, `solve-issues-found-during-review`, `systematic-debug`, `test-case-strategy`, `update-project-html`, `version-release`) by removing inline examples, standardizing section headings, and simplifying descriptions.
+
+### Added
+
+- `generate-spec/references/definition.md`, `init-project-html/references/definition.md`, `update-project-html/references/definition.md` with shared terminology for feature modules and sub-modules.
+
+### Removed
+
+- Remove `iterative-code-performance`, `iterative-code-quality`, `merge-conflict-resolver`, `spec-to-project-html`, and `submission-readiness-check` skills that are no longer part of the curated catalog.
+
 ## [v3.12.1] - 2026-05-14
 
 ### Changed

package/archive-specs/SKILL.md

@@ -23,12 +23,6 @@ description: 將已完成的spec歸檔到 `docs/archive/` 下。當你需要將s
 
 使用 `align-project-documents`, `maintain-project-constraints` 技能，按照這兩個技能之中的指引，更新項目文檔。並將完成的spec全部移動到 `docs/archive/`。
 
-## 使用範例
-
-- "這批 spec 已經實作完成，幫我整理成正式文件並歸檔" -> "先同步 `docs/` 與 `AGENTS.md` / `CLAUDE.md`，再把已完成的 spec 移到 archive"
-- "只有批次中的兩個子 spec 做完，另外一個還在進行" -> "只歸檔完成的子目錄，保留仍在使用的 `coordination.md`"
-- "spec 寫了未來計畫，但 repo 還沒實作" -> "不把該內容當成正式文件，只在需要時標成 `TBD` 或保留在 active planning"
-
 ## 參考資料索引
 
 - `references/templates/readme.md`：README.md 模板

package/commit-and-push/SKILL.md

@@ -23,20 +23,14 @@ description: 提供提交指引以及作為提交前的必要品控閘門。當
 
 ### 3. 同步項目文檔
 
-使用 `submission-readiness-check` 並遵照當中的指引，同步更新項目文檔，確保項目文檔時刻與repo保持一致。
+使用 `align-project-documents`, `maintain-project-constraints` 這兩個技能，並遵照當中的指引，同步更新項目文檔，確保項目文檔時刻與repo保持一致。
 
 ### 4. 提交及推送變更
 
 依使用者的 staging 邊界建立 commit，提交訊息遵循 `references/commit-messages.md`。
-只有在使用者明確要求更新remote時才 push。
+只有在使用者明確要求更新 remote 時才 push。
 
-## 範例
-
-- 「只把已 staged 的 `foo.ts` 提交」-> 只能提交已暫存內容，不能順手把未 staged 的 `bar.ts` 一起帶進來
-- 「幫我 push 這個 branch」-> 先完成 review 與 readiness gate，再 push，最後用 hash 證明remote已同步
-- 「順便幫我發版」-> 不使用本技能，改走 `version-release`
-
-## 參考資料索引
+## 參考資料
 
 - `references/commit-messages.md`：提交訊息格式
 - `references/branch-naming.md`：分支命名慣例

package/generate-spec/SKILL.md

@@ -4,18 +4,23 @@ description: 當你需要將用戶模糊的複雜需求拆解成有嚴格實作
 ---
 
 ## 目標
+
 將用戶需求轉化為明確、有清晰完成條件的spec。
 
 ## 驗收條件
+
 - 已經產出了嚴格遵循模板格式的spec。
 - 為spec當中的需求制定了明確的驗收條件及測試策略
 
 ## 工作流程
-1. 理解用戶需求並閱讀repo
+
+### 1. 理解用戶需求並閱讀repo
+
 分析用戶需求，並在 repo 之中搜索、列出可能相關的內容。完成搜索之後，深入閱讀相關代碼，識別變更範圍。
 如果外部環境存在 subagents 功能，建議通過調度 subagents 來完成深入閱讀 repo 的任務。
 
-2. 拆分用戶需求及設計業務架構
+### 2. 拆分用戶需求及設計業務架構
+
 將用戶需求轉化、拆分為明確、存在邊界的工程需求。結合現有代碼，設計業務架構。在設計的過程中，你需要考慮包括但不限於以下設計事項：
 - 錯誤處理
 - 測試策略
@@ -23,22 +28,35 @@ description: 當你需要將用戶模糊的複雜需求拆解成有嚴格實作
 - 資料流
 在這個階段，如果用戶有任何不清晰的需求，且該需求會影響你的設計方案，你需要紀錄並在稍後填入spec，等待用戶的回答。
 
-3. 將整個設計方案拆分成可執行任務
+### 3. 將整個設計方案拆分成可執行任務
+
 將上一步之中你構思的完整設計方案拆分為精確到函式或檔案級別的任務。你必須確保每一個任務都是可以直接執行，且沒有歧義的。以此確保執行設計方案的開發者不會偏離設計方案。
 
-4. 制定驗收條件
-為任務制定基於測試的驗收條件，確保每一個任務在完成之後都能夠被驗證。
+### 4. 制定驗收條件
+
+使用 `test-case-strategy` 這個技能，為任務制定基於測試的驗收條件，確保每一個任務在完成之後都能夠被驗證。
 同時，為需求制定驗收條件，確保用戶需求能夠被測試清晰地驗收、檢驗成果。
 
-5. 使用 `apltk` cli工具協助完成spec及spec相關架構圖
-使用 cli 工具，產生 spec 的模板。將你的完整計劃填入到模板之中，並通過 cli 工具生成完整的 architecture diff 讓用戶審閱本次spec的架構設計。
+### 5. 使用 `apltk` cli 工具協助完成 spec
+
+使用 cli 工具，產生 spec 的模板。將你的完整計劃填入到模板之中。
 如果該 spec 設計超過三個模塊，則需要創建 batch spec。
 
+### 6. 使用 `apltk` cli 工具協助完成 spec architecture diff
+
+通過 cli 工具生成完整的 architecture diff 讓用戶審閱本次 spec 的架構設計。
+
+架構圖需要清楚描述：
+- 功能模塊之間的關係變動、設計、交互。
+- 子模塊之間的關係變動、設計、交互。
+
 ## 範例
+
 - "製作一個網頁德州撲克小遊戲" -> "拆分成多個模塊：遊戲本體邏輯、前端頁面渲染、前端頁面交互邏輯；制定單元測試、整合測試等策略，並製作一份單一的spec指導實作工作。"
 - "提升現有系統的性能" -> "識別目前 repo 之中拖累性能的代碼。製作 batch spec 文檔，將 repo 的全量優化拆分為以三個模塊為一組的優化。對於必須改動業務邏輯才可以做到的性能提升，填寫 clarification questions，並等待用戶回答之後更新 spec。"
 
 ## 參考資料
+
 - `scripts/create-specs` - `apltk create-specs` 背後使用的模板產生器。
 - `references/templates/spec.md` - `spec.md` 的綁定模板。
 - `references/templates/tasks.md` - `tasks.md` 的綁定模板。
@@ -48,6 +66,6 @@ description: 當你需要將用戶模糊的複雜需求拆解成有嚴格實作
 - `references/templates/coordination.md` - batch root 的 coordination 模板。
 - `references/templates/preparation.md` - batch root 的前置工作模板。
 - `references/TEMPLATE_SPEC.md` - `apltk` cli工具相關格式指引。
-- `test-case-strategy/SKILL.md` - 測試策略選擇技能。
 - `apltk create-specs --help` - spec生成相關cli工具的指引命令
-- `apltk architecture --help` - 架構圖生成相關cli工具的指引命令
+- `apltk architecture --help` - 架構圖生成相關cli工具的指引命令
+- `references/definition.md` - 架構圖之中功能模塊及子模塊的具體定義

package/generate-spec/references/definition.md

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

package/init-project-html/SKILL.md

@@ -1,40 +1,36 @@
 ---
 name: init-project-html
-description: >-
-  使用 `apltk architecture` 初始化專案 HTML 架構圖譜，生成基礎 atlas YAML 與渲染後的 HTML 頁面。所有宣告基於倉庫證據；每個功能模組由一個可寫子 agent 負責，主 agent 必須等待全部子 agent 完成後，才能補跨功能連接並執行 render 與 validate。
+description: 當你需要為項目初始化架構圖時，使用此技能。
 ---
 
 ## 技能目標
 
-透過 `apltk architecture` 為目前倉庫建立基礎專案架構圖譜，產出受 CLI 管理的 atlas 狀態檔與渲染後的 HTML 頁面。
+在 `apltk` cli 的幫助下製作項目架構圖，幫助用戶理解項目的軟件架構
 
 ## 驗收條件
 
-- 只透過 `apltk architecture` 修改圖譜；不得手改 `resources/project-architecture/**/*.html`。
-- 所有宣告可追溯到真實程式碼、設定、SQL 或外部邊界；無法確認的部分用 `TBD` 或在 `meta.summary` 記錄遺漏原因。
-- 宏觀圖完整表達功能與子模組關係；所有跨邊界互動使用 `call`、`return`、`data-row`、`failure` 邊表達。
-- 每個非平凡子模組具備足夠內部結構：已宣告 `function`、`variable`、有序 `dataflow`、必要時的 `error`，且引用可通過校驗。
-- 採用「每個功能一個可寫子 agent」分工；主 agent 等所有子 agent 完成後才補跨功能邊，且 `apltk architecture validate` 通過。
+- 架構圖清楚描述了功能模塊之間的關係及子模塊之間的關係
 
 ## 工作流程
 
-1. 執行 `apltk architecture --help`，以 CLI 說明為唯一命令真源。
-2. 做整倉淺層盤點，列出功能模組的 slug、使用者視角職責、入口點與主要邊界資源。
-3. 為每個功能派發一個可寫子 agent，負責宣告該功能的全部子模組、函式、變數、資料流、本地錯誤與功能內邊。子 agent 返回子模組摘要及需要主 agent 補上的跨功能邊界資訊。
-4. 主 agent 不得重讀已委派功能的原始碼，也不得重複宣告子 agent 已處理的功能內元件。
-5. 全部子 agent 完成後，主 agent 統一補齊跨功能 edge、必要時補共享 meta 或 actor，然後執行 `apltk architecture render` 與 `apltk architecture validate`。
-6. 抽查渲染結果，確認宏觀圖和至少一個代表性子模組頁滿足驗收條件，彙報功能數、子模組數、邊數量、未覆蓋路徑與原因。
+### 1. 閱讀並理解代碼庫
 
-## 使用範例
+按照功能模塊的定義，全面檢索並將代碼庫拆分為單個或多個功能模塊。接著，開始對功能模塊下的子模塊進行識別及深度閱讀。
+如果外部環境允許使用 subagents ，建議為每一個功能模塊分配一個 subagents 進行深度閱讀，並要求 subagents 完整列出：
+- 該功能模塊與其他功能模塊之間是否存在交互；如有，如何交互。
+- 該功能模塊內部存在哪些子模塊，這些子模塊之間如何交互並實現功能模塊的功能。
+- 該功能模塊及下屬子模塊的資料流、錯誤處理。
 
-- 「替這個倉庫首次生成 HTML 架構圖」→ 梳理功能模組，按功能分派子 agent，彙總跨功能邊，生成基礎 atlas 與渲染頁面。交付物為 `resources/project-architecture/` 下的完整 atlas 狀態檔與通過驗證的 HTML 頁面。
-- 「把系統的資料流、呼叫關係和回滾路徑視覺化」→ 使用 `call` / `return` / `data-row` / `failure` 邊表達跨邊界關係，為每個關鍵子模組補齊內部 `dataflow`。
+### 2. 使用 `apltk` cli 工具協助生成架構圖
 
-## 參考資料索引
+將前一步獲取到的代碼庫只是通過 cli 工具轉化為清晰的架構圖。
+完成之後，驗證架構圖格式正確、可渲染。
+
+## 參考資料
 
 - `references/TEMPLATE_SPEC.md`：atlas 欄位、列舉和 CLI 寫入形狀速查表。
-- `lib/atlas/cli.js`：`apltk architecture` 的實作入口。
-- `lib/atlas/schema.js`：圖譜資料結構與校驗規則。
+- `references/definition.md`: 功能模塊和子模塊的詳細定義。
+- `references/architecture-page.template.html`: 模板html。
+- `references/architecture.css`: 風格模板。
 - `sample-demo/`：完整示例輸出，用於理解基礎 atlas 的最終形態。
-- `spec-to-project-html/SKILL.md`：面向規劃文件的 overlay 版本。
-- `update-project-html/SKILL.md`：面向已存在基礎 atlas 的增量刷新版本。
+- `apltk architecture --help` - cli 工具的指引指令。

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

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

package/maintain-project-constraints/SKILL.md

@@ -1,35 +1,27 @@
 ---
 name: maintain-project-constraints
-description: >-
-  依據倉庫現況刷新根目錄 `AGENTS.md` / `CLAUDE.md`，只保留 Common Development Commands、Project Business Goals、Project Documentation Index 三個可追溯區塊。
+description: 當你需要更新 `CLAUDE.md` 或 `AGENTS.md` 這兩份項目規範文檔的時候，調用這個技能。
 ---
 
 ## 技能目標
 
-基於當前倉庫證據，產出或刷新根目錄 `AGENTS.md` 與 `CLAUDE.md`，使其準確反映開發命令、專案商業目標與文件索引，不捏造任何內容。
+基於當前 repo 的最新文檔和及代碼，維護項目規範文檔。
 
 ## 驗收條件
 
-- 最終文件正文只包含三個區塊，順序固定：`Common Development Commands` → `Project Business Goals` → `Project Documentation Index`。
-- `Common Development Commands` 中每條命令可追溯到 `package.json`、`Makefile`、`bin/`、`scripts/` 或 CI 設定等真實入口。
-- `Project Business Goals` 只描述專案層級目的、服務對象與交付結果，不展開為功能清單。
-- `Project Documentation Index` 覆蓋現存 `docs/features/`、`docs/architecture/`、`docs/principles/` 與重要根目錄文件，每項對應真實路徑。
-- 過時路徑、虛構命令與多餘區塊已被移除。
-- 若 `AGENTS.md` 與 `CLAUDE.md` 同時存在且未聲明故意分歧，兩者三個區塊內容一致。
+- `CLAUDE.md`, `AGENTS.md` 已經被更新到最新狀態
 
 ## 工作流程
 
-1. 從倉庫現況收集可驗證的命令入口、專案目的與現有文件清單，不以舊約束文件作為唯一真相。
-2. 根據證據生成三個必需區塊，確保每條命令、商業目標與文件索引可被直接追溯。
-3. 按專案慣例更新或補齊 `AGENTS.md` / `CLAUDE.md`，正文限制在三個規定區塊內。
-4. 完成前逐項校驗命令來源、文件路徑與雙文件一致性，清除所有陳舊或多餘內容。
+### 1. 閱讀 repo
 
-## 使用範例
+深入閱讀當前項目文檔及實作代碼，並建立對於項目的全面認知。
+如果外部環境允許使用 subagents，建議通過調度 subagents 完成對 repo 代碼的深入閱讀。
 
-- 「重建 `docs/` 後，請同步刷新 `AGENTS.md` 和 `CLAUDE.md`」→ 根據當前腳本、入口與文件樹重寫兩個根目錄約束文件，只保留三個規定區塊並確保索引完整。
-- 「這個專案的 `CLAUDE.md` 已經過時，請補一份對應的 `AGENTS.md`」→ 依據現有命令與文件結構建立缺失文件，讓兩份約束文件在預期一致時保持同構。
-- 「請清理根目錄約束文件裡的舊命令與失效路徑」→ 驗證每條命令與索引路徑是否仍成立，只保留能被倉庫證據支持的內容。
+### 2. 更新項目規範文檔
 
-## 參考資料索引
+按照模板當中給出的格式，更新或創建 `CLAUDE.md`, `AGENTS.md`。
 
-- `references/constraint-file-reference.md`：三區塊契約、撰寫規則、核對清單與輸出模板。
+## 參考資料
+
+- `references/constraint-file-reference.md`：三區塊契約、撰寫規則、核對清單與輸出模板。

package/merge-changes-from-local-branches/SKILL.md

@@ -1,40 +1,27 @@
 ---
 name: merge-changes-from-local-branches
-description: >-
-  將使用者指定的本地分支合併回當前分支，依序完成衝突處理、驗證、安全清理與最終提交準備；除非本次對話明確要求，否則不推送遠端。
+description: 當你需要將 spec 相關的本地實作分支合併回當前所在分支時，調用這個技能。
 ---
 
 ## 技能目標
 
-在工作開始時的當前本地分支上，整合使用者指定的本地分支（或由 spec / batch 規劃可無歧義對應出的分支），完成合併、驗證、清理，並讓整合結果可安全交由 `commit-and-push` 收尾。
+將 spec 相關的本地實作分支合併回當前所在分支。
 
 ## 驗收條件
 
-- 所有合併變更落在流程開始時的原始當前分支，不會未經允許改換目標分支。
-- 合併範圍只包含使用者明確指定，或可由 `coordination.md` / spec 無歧義映射出的分支；若映射不清楚則停止並回報。
-- 當 batch 規劃存在 `Merge order` / landing order 時，實際整合順序與規劃一致；順序衝突或不明確時不猜測執行。
-- 所有衝突以保留正確行為為原則解決，並在刪除來源分支或交給 `commit-and-push` 前完成驗證。
-- 只清理已成功合併且已驗證的來源分支或 worktree；不強制刪除尚未真正合入的來源。
-- 最終交付是原始當前分支上的整合結果與簡潔摘要；只有使用者於本次對話明確要求時才推送遠端。本技能不單獨執行 `archive-specs`。
+- 分支的變更被合併，且所有潛在衝突代碼被解決。
 
 ## 工作流程
 
-1. 以流程開始時的當前分支為唯一目標分支，確認合併範圍（使用者明確指定的分支，或由 spec / `coordination.md` 無歧義映射出的分支與整合順序）。
-2. 確認工作樹適合執行合併：若存在干擾整合的未提交變更，停止並回報，不自行 stash 或切換分支。
-3. 依既定順序逐一合併 in-scope 分支。對已合入或無新增內容的分支，跳過並記錄原因。發生衝突時閱讀雙方內容編輯出正確結果；無法在不猜測意圖的前提下解決時停止並回報。必要時使用 `merge-conflict-resolver`。
-4. 先對衝突區域或高風險改動執行針對性驗證，再對整體整合結果執行倉庫慣用的標準驗證。驗證失敗先在當前分支修正。
-5. 僅清理已完成合併且通過驗證的來源分支與對應 worktree；安全刪除被拒絕時保留來源並回報，不使用強制刪除。
-6. 交由 `commit-and-push` 完成必要審查、submission-readiness gate 與本地提交。若 `commit-and-push` 不可用則停止並回報，不走裸 `git commit`。
-7. 總結已合併與跳過的分支、順序依據、衝突處理原則、驗證結果，以及流程最終停在本地 `HEAD` 還是包含遠端推送。
+### 1. 建立規格文檔基線認知
 
-## 使用範例
+閱讀目前用戶指定的 spec，並查看目前分支狀態，找到與 spec 相關的分支。
 
-- 「把 `feature/api-layer` 和 `feature/cli-wrapper` 合回目前分支」→ 以目前分支為唯一目標，依指定順序完成整合、驗證與安全清理，再交給 `commit-and-push` 做本地提交。
-- 「根據 batch 的 `coordination.md` 把各 worktree 分支合回來，但先不要 push」→ 從 batch 規劃確認無歧義分支映射與 landing order，依序合併、驗證、清理，只做到本地提交。
-- 「把那幾個應該相關的分支一起合一下」→ 若無法從使用者輸入或規劃文件明確判定分支集合與順序，停止並回報需要補充資訊。
+### 2. 合併分支及處理衝突
 
-## 參考資料索引
+按照 `coordination.md` 的建議順序，對分支進行合併。
+在解決分支衝突時，必須確保 spec 要求的功能沒有被破壞。
 
-- `commit-and-push/SKILL.md`：最終提交、submission-readiness 與是否允許推送的權威流程。
-- `merge-conflict-resolver/SKILL.md`：衝突需要精確合成時的輔助技能。
-- `docs/plans/**/coordination.md`：batch 規劃存在時的 landing order 與分支映射依據。
+### 3. 提交變更
+
+使用 `commit-and-push` 這個技能，將變更提交到當前分支上，不需要 push 到 remote。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "3.12.1",
+  "version": "3.13.0",
   "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 @@
+## 功能模塊
+
+功能模塊是直接面向用戶的功能，如：
+- 登陸功能
+- 註冊功能
+- 邀請碼功能
+
+功能模塊由子模塊的合作、交互實現
+
+## 子模塊
+
+子模塊是功能模塊的關鍵組成部分。具體定義依照代碼的實作邊界得出。