@laitszkin/apollo-toolkit 3.12.0 → 3.13.0

package/AGENTS.md

@@ -31,10 +31,10 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can turn lecture slides, past papers, and answer books into mock exams, worked solutions, study notes, or graded PDFs with KaTeX-rendered math.
 - Users can extend existing features in a brownfield codebase with required tests and approvals.
 - Users can propose product features from an existing codebase and publish accepted proposals.
-- Users can discover reproducible edge-case risks and report prioritized hardening gaps.
+
 - Users can read, filter, and inspect remote GitHub issues before planning follow-up work.
 - Users can resolve a GitHub issue end-to-end and push the fix directly to a requested branch without opening a PR.
-- Users can run evidence-first application security audits focused on confirmed vulnerabilities.
+
 - Users can run a shared submission-readiness pass that synchronizes changelog, project docs, `AGENTS.md`, and completed plan archives before commit, push, PR creation, or release.
 - Users can learn new or improved skills from recent Codex conversation history.
 - Users can audit and maintain the skill catalog itself, including dependency classification and shared-skill extraction decisions.
@@ -51,12 +51,12 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can generate storyboard image sets from chapters, novels, articles, or scripts.
 - Users can configure OpenClaw from official documentation, including `~/.openclaw/openclaw.json`, skills loading, SecretRefs, CLI edits, and validation or repair workflows.
 - Users can record multi-account spending and balance changes in monthly Excel ledgers with summary analytics and charts.
-- Users can recover missing or archived `docs/plans/...` spec sets from issue context, git history, and repository evidence before continuing feature work.
-- Users can review the current git change set from an unbiased reviewer perspective to find abstraction opportunities and simplification candidates.
+
+
 - Users can review recent or user-specified spec-backed changes against the governing planning documents, treating unmet business goals as the most severe findings before secondary edge-case, security, and code-review checks.
 - Users can process GitHub pull request review comments and resolve addressed threads.
-- Users can perform repository-wide code reviews and publish confirmed findings as GitHub issues.
-- Users can schedule a bounded project runtime window, stop it automatically, and analyze module health from captured logs.
+
+
 - Users can investigate gated or shadow LLM APIs by capturing real client request shapes, replaying verified traffic patterns, and attributing the likely underlying model through black-box fingerprinting.
 - Users can build and maintain Solana programs and Rust clients using official Solana development workflows.
 - Users can fix issues discovered during a review pass by processing findings from highest to lowest severity, with per-fix validation and full-scope re-validation.

package/CHANGELOG.md

@@ -4,11 +4,28 @@ 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
 
-### Fixed
+- Rewrite remaining shipped skills (`enhance-existing-features`, `generate-spec`, `init-project-html`, `merge-changes-from-local-branches`, `open-source-pr-workflow`, `optimise-skill`, `review-spec-related-changes`, `solve-issues-found-during-review`, `submission-readiness-check`, `commit-and-push`, `version-release`, `iterative-code-performance`, `iterative-code-quality`, `maintain-project-constraints`, `ship-github-issue-fix`, `spec-to-project-html`, `systematic-debug`) into the compact Chinese-first structure with goal, acceptance criteria, workflow, examples, and references sections.
+- Update `AGENTS.md` and `README.md` to remove references to deleted skills and simplify dependency descriptions.
+
+### Removed
+
+- Remove `discover-edge-cases`, `discover-security-issues`, `recover-missing-plan`, `review-change-set`, `review-codebases`, and `scheduled-runtime-health-check` skills that are no longer part of the curated catalog.
 
 ## [v3.12.0] - 2026-05-13
 

package/README.md

@@ -12,7 +12,7 @@ A curated skill catalog for Codex, OpenClaw, Trae, Agents, and Claude Code with
 - codex-memory-manager
 - deep-research-topics
 - develop-new-features
-- discover-edge-cases
+
 - docs-to-voice
 - exam-pdf-workflow
 - document-vision-reader
@@ -21,7 +21,7 @@ A curated skill catalog for Codex, OpenClaw, Trae, Agents, and Claude Code with
 - financial-research
 - read-github-issue
 - generate-spec
-- discover-security-issues
+
 - implement-specs
 - implement-specs-with-subagents
 - implement-specs-with-worktree
@@ -41,13 +41,13 @@ A curated skill catalog for Codex, OpenClaw, Trae, Agents, and Claude Code with
 - openai-text-to-image-storyboard
 - openclaw-configuration
 - optimise-skill
-- recover-missing-plan
+
 - record-spending
 - resolve-review-comments
-- review-change-set
-- review-codebases
+
+
 - review-spec-related-changes
-- scheduled-runtime-health-check
+
 - shadow-api-model-research
 - solana-development
 - spec-to-project-html
@@ -208,12 +208,11 @@ Compatibility note:
 
 - `generate-spec` is a local skill used by `develop-new-features` and `enhance-existing-features`, and it can produce either a single spec set under `docs/plans/{YYYY-MM-DD}/{change_name}/` or a coordinated parallel batch under `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` with shared `coordination.md`.
 - `implement-specs-with-subagents` coordinates one `implement-specs-with-worktree` subagent per spec directory for approved multi-spec batches.
-- `recover-missing-plan` is a local skill used by `enhance-existing-features` and `ship-github-issue-fix` when a referenced `docs/plans/...` spec set is missing or archived.
+
 - `read-github-issue` uses GitHub CLI (`gh`) directly for remote issue discovery and inspection, so it does not add any extra skill dependency.
-- `review-spec-related-changes` is a local skill that depends on `review-change-set`, `discover-edge-cases`, and `discover-security-issues` for secondary code-practice checks after business-goal completion is reviewed against the governing specs; it prefers running each secondary skill in its own read-only subagent in parallel.
+- `review-spec-related-changes` is a local skill that reviews spec compliance of changes against governing planning documents, assessing business goals before secondary code-practice concerns.
 - `update-project-html` is a local skill that depends on `init-project-html` for semantic rules and on the `apltk architecture` CLI to refresh the base atlas after code changes; for spec overlay diagrams use `spec-to-project-html` instead.
-- `commit-and-push` and `version-release` no longer chain `discover-edge-cases` or `discover-security-issues`; invoke those skills explicitly when the review surface needs them.
-- `review-change-set` no longer chains `discover-security-issues`; for multi-file diffs it prefers dispatching one read-only subagent per scope cluster.
+
 
 ## Release publishing
 

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

@@ -19,26 +19,18 @@ description: 提供提交指引以及作為提交前的必要品控閘門。當
 
 ### 2. 品控閘門（選用）
 
-如果變更範圍設計代碼變更，使用 `review-change`, `discover-edge-cases`, `discover-security-issues` 這三個技能，並遵從當中的任務指引，對代碼變更進行審查。
-如果外部環境允許使用subagents，建議通過調度subagents完成三個不同維度的代碼審查工作。
-如果在審查過程中發現問題，修復發現的問題並暫存。
+如果變更範圍涉及代碼變更，確認變更已通過必要的審查與驗證。如果在審查過程中發現問題，修復發現的問題並暫存。
 
 ### 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/enhance-existing-features/SKILL.md

@@ -1,56 +1,40 @@
 ---
 name: enhance-existing-features
 description: >-
-  用於在既有系統上增強或調整產品行為。必須先讀懂實際受影響的模組，再決定是直接實作，
-  還是先走 `generate-spec` / `recover-missing-plan`；所有非平凡變更都要經過 `test-case-strategy`。
+  在既有系統上增強或調整產品行為。先讀懂受影響模組，再決定直接實作或走 generate-spec；所有非平凡變更必須經過 test-case-strategy。
 ---
 
-# 增強既有功能
-
-## Dependencies
-
-- Required: `test-case-strategy`
-- Conditional: `generate-spec`、`recover-missing-plan`、`commit-and-push`
-- Optional: 無
-- Fallback: `test-case-strategy` 不可用時必須停止；需要spec但 `generate-spec` 或 `recover-missing-plan` 不可用時也必須停止；若使用者要求提交或推送但 `commit-and-push` 不可用，必須說明後停止
-
-## Standards
-
-- Evidence: 先閱讀實際程式碼、整合點與外部文件，再決定流程與修改方案
-- Execution: 探索範圍 -> 判斷是否需要 spec -> 查官方資料 -> 最小實作 -> 測試 -> 回填或總結
-- Quality: 不因怕麻煩而跳過 spec，也不為小改動硬開 spec；只做與需求直接相關的修改
-- Output: 交付符合需求的行為變更、可追溯的測試結果，以及在需要時保持誠實的計劃文件狀態
-
 ## 技能目標
 
-在不打亂既有系統邊界的前提下，為 brownfield 專案安全地增強功能或調整行為，並用合適的spec流程與測試策略把風險控制在可驗證範圍內。
+在不打亂既有系統邊界的前提下，為 brownfield 專案安全地增強功能或調整行為，以合適的 spec 流程與測試策略將風險控制在可驗證範圍內。
 
 ## 驗收條件
 
-- 在動手前已讀懂受影響模組、入口點、整合邊界與變更爆炸半徑
-- 已正確判斷這次工作是直接實作還是必須先走 `generate-spec` / `recover-missing-plan`
-- 每個非平凡變更都經過 `test-case-strategy`，並留下清楚的 oracle、驗證方式與 `N/A` 理由
-- 若使用了 spec，則批准、實作、回填與真實狀態同步全部完成；若未使用 spec，則最終摘要足以說明風險、測試與限制
+- 變更範圍明確：已讀懂受影響模組、入口點、整合邊界與變更爆炸半徑。
+- 已正確判斷直接實作或必須先走 `generate-spec`，並在不需要 spec 時給出明確理由。
+- 每個非平凡變更都經過 `test-case-strategy`，留下清楚的 oracle、驗證方式與通過證據。
+- 若使用 spec：批准、實作、回填與計劃文件狀態同步全部完成。
+- 若未使用 spec：最終摘要足以說明風險、測試結果與剩餘限制。
+- `test-case-strategy` 不可用時必須停止；需要 spec 但 `generate-spec` 不可用時必須停止。
 
 ## 工作流程
 
-1. 先完整閱讀相關模組、資料流、整合點與現有測試，明確界定這次變更會影響哪些地方
-2. 判斷是否需要spec流程；若涉及新的或改變後的使用者可見行為、跨模組協調、高風險敏感流程、重大歧義，則走 `generate-spec`；如果使用者指定的 plan 路徑缺失或不一致，先用 `recover-missing-plan`
-3. 若不需要 spec，明確說出不開 spec 的理由；若需要 spec，必須等批准後才能改產品程式碼
-4. 查閱變更所依賴的官方文件、API spec或工具文件，尤其是外部整合與契約邏輯
-5. 以最小差異實作需求，不順手做額外重構或範圍擴張
-6. 使用 `test-case-strategy` 選擇單元、回歸、property、integration、E2E 或 adversarial 測試，跑測試並修正失敗
-7. 若使用了 spec，回填 `spec.md`、`tasks.md`、`checklist.md`、`contract.md`、`design.md` 與任何 `coordination.md`；若未使用 spec，輸出簡潔的結果摘要、測試證據與剩餘限制
+1. 完整閱讀受影響模組、資料流、整合點與現有測試，明確界定變更的爆炸半徑。
+2. 判斷是否需要 spec：涉及新的或改變使用者可見行為、跨模組協調、高風險敏感流程、重大歧義時走 `generate-spec`。不需 spec 時明確說出理由。
+3. 若需要 spec，必須等批准後才能改產品程式碼。
+4. 查閱變更依賴的官方文件或 API spec，以最小差異實作需求，不順手做額外重構或範圍擴張。
+5. 使用 `test-case-strategy` 選擇測試組合，跑測試並修正失敗。
+6. 若使用 spec，回填所有計劃文件；若未使用，輸出簡潔的結果摘要、測試證據與剩餘限制。
 
 ## 使用範例
 
-- 「新增一套影響 API、資料庫與 UI 的權限模型」-> 先走 `generate-spec`，批准後再實作，並補上跨層測試
-- 「修正分頁 off-by-one，讓行為回到 README 描述」-> 不開 spec，直接修復並加回歸測試
-- 「目前指定的 `docs/plans/...` 不見了，但使用者要沿著它繼續做」-> 先用 `recover-missing-plan` 還原或重建，再繼續
+- 「新增一套影響 API、資料庫與 UI 的權限模型」→ 先走 `generate-spec`，批准後再實作，並補上跨層測試。交付物包含已批准的 spec、通過的測試證據、回填完成的計劃文件。
+- 「修正分頁 off-by-one，讓行為回到 README 描述」→ 不開 spec，直接修復並加回歸測試。交付物為修復後的代碼與測試通過證據。
+
 
 ## 參考資料索引
 
-- `generate-spec`：需要書面批准時的spec流程
-- `recover-missing-plan`：修復缺失或不一致的計劃檔
-- `test-case-strategy`：非平凡變更的測試選型與 oracle 設計
-- `commit-and-push`：使用者要求提交或推送時的最終交付流程
+- `generate-spec`：需要書面批准時的 spec 流程。
+
+- `test-case-strategy`：非平凡變更的測試選型與 oracle 設計。
+- `commit-and-push`：使用者要求提交或推送時的最終交付流程。

package/generate-spec/SKILL.md

@@ -1,24 +1,26 @@
 ---
 name: generate-spec
-description: >-
-  Create or refresh approval-gated planning docs under `docs/plans/...` with
-  `apltk create-specs`, `test-case-strategy`, and optional batch coordination or
-  preparation files. Use for drafting or restructuring specs, not implementation.
+description: 當你需要將用戶模糊的複雜需求拆解成有嚴格實作範圍的spec時，使用這個技能
 ---
 
 ## 目標
+
 將用戶需求轉化為明確、有清晰完成條件的spec。
 
 ## 驗收條件
+
 - 已經產出了嚴格遵循模板格式的spec。
 - 為spec當中的需求制定了明確的驗收條件及測試策略
 
 ## 工作流程
-1. 理解用戶需求並閱讀repo
-分析用戶需求，並在repo之中搜索、列出可能相關的內容。完成搜索之後，深入閱讀相關代碼，識別變更範圍。
-如果外部環境存在subagents功能，建議通過調度subagents來完成深入閱讀repo的任務。
 
-2. 拆分用戶需求及設計業務架構
+### 1. 理解用戶需求並閱讀repo
+
+分析用戶需求，並在 repo 之中搜索、列出可能相關的內容。完成搜索之後，深入閱讀相關代碼，識別變更範圍。
+如果外部環境存在 subagents 功能，建議通過調度 subagents 來完成深入閱讀 repo 的任務。
+
+### 2. 拆分用戶需求及設計業務架構
+
 將用戶需求轉化、拆分為明確、存在邊界的工程需求。結合現有代碼，設計業務架構。在設計的過程中，你需要考慮包括但不限於以下設計事項：
 - 錯誤處理
 - 測試策略
@@ -26,22 +28,35 @@ description: >-
 - 資料流
 在這個階段，如果用戶有任何不清晰的需求，且該需求會影響你的設計方案，你需要紀錄並在稍後填入spec，等待用戶的回答。
 
-3. 將整個設計方案拆分成可執行任務
+### 3. 將整個設計方案拆分成可執行任務
+
 將上一步之中你構思的完整設計方案拆分為精確到函式或檔案級別的任務。你必須確保每一個任務都是可以直接執行，且沒有歧義的。以此確保執行設計方案的開發者不會偏離設計方案。
 
-4. 制定驗收條件
-為任務制定基於測試的驗收條件，確保每一個任務在完成之後都能夠被驗證。
+### 4. 制定驗收條件
+
+使用 `test-case-strategy` 這個技能，為任務制定基於測試的驗收條件，確保每一個任務在完成之後都能夠被驗證。
 同時，為需求制定驗收條件，確保用戶需求能夠被測試清晰地驗收、檢驗成果。
 
-5. 使用 `apltk` cli工具協助完成spec
-使用cli工具，產生spec的模板。將你的完整計劃填入到模板之中，並通過cli工具生成完整架構圖讓用戶審閱。
-如果該spec設計超過三個模塊，則需要創建batch 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。"
+- "提升現有系統的性能" -> "識別目前 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` 的綁定模板。
@@ -51,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,42 +1,36 @@
 ---
 name: init-project-html
-description: >-
-  使用 `apltk architecture` 初始化專案 HTML 架構圖譜，生成基礎 atlas YAML 與渲染後的 HTML 頁面。所有宣告必須基於倉庫證據，跨模組關係只能用 `call`、`return`、`data-row`、`failure` 邊表達；每個功能模組由一個可寫子 agent 負責，主 agent 必須等待全部子 agent 完成後，才能補跨功能連接並執行 `render` 與 `validate`。
+description: 當你需要為項目初始化架構圖時，使用此技能。
 ---
 
-# 初始化專案 HTML 架構圖
-
 ## 技能目標
 
-透過 `apltk architecture` 為目前倉庫建立基礎專案架構圖譜，產出受 CLI 管理的 `resources/project-architecture/atlas/` 狀態檔與對應 HTML 頁面，而不是手寫 SVG 或 HTML。
+在 `apltk` cli 的幫助下製作項目架構圖，幫助用戶理解項目的軟件架構
 
 ## 驗收條件
 
-- 只透過 `apltk architecture` 修改圖譜；不得手改 `resources/project-architecture/**/*.html`。
-- 渲染後的宏觀圖完整表達功能與子模組關係；所有跨邊界互動都必須落在 `call`、`return`、`data-row`、`failure` 邊上，不能藏在子模組頁面文案裡。
-- 每個非平凡子模組都具備足夠的內部結構：已宣告的 `function`、`variable`、有序 `dataflow`、必要時的 `error`，且 `dataflow` 中的函式與讀寫變數引用可被校驗通過。
-- 所有宣告都能追溯到真實程式碼、設定、SQL 或外部邊界；無法確認的部分用 `TBD` 或在 `meta.summary` 中明確記錄遺漏原因。
-- 採用「每個功能一個可寫子 agent」的分工；主 agent 必須等所有子 agent 完成後，才允許補跨功能邊並執行 `apltk architecture validate`，且驗證結果為通過。
+- 架構圖清楚描述了功能模塊之間的關係及子模塊之間的關係
 
 ## 工作流程
 
-1. 先執行 `apltk architecture --help`，把 CLI 說明當作唯一命令真源；本技能只定義語義規則，不重複維護參數細節。
-2. 先做整倉淺層盤點，只列出功能模組的 `slug`、使用者視角職責、入口點與主要邊界資源；此階段不要深讀函式實作。
-3. 為每個待建圖功能派發一個可寫子 agent。每個子 agent 只深讀自己負責的功能，並負責宣告該功能內的全部子模組、函式、變數、資料流、本地錯誤，以及所有功能內邊。
-4. 子 agent 返回的內容只能是：子模組摘要，以及需要由主 agent 稍後補上的跨功能邊界資訊；主 agent 不得回頭重讀已委派功能原始碼，也不得重複宣告子 agent 已擁有的功能內元件。
-5. 等全部子 agent 完成後，主 agent 統一補齊跨功能 `edge`，必要時補共享 `meta` 或 `actor`，隨後執行 `apltk architecture render` 與 `apltk architecture validate`。
-6. 打開渲染結果進行抽查，確認宏觀圖和至少一個代表性子模組頁都滿足驗收條件，並在彙報中記錄功能數、子模組數、邊數量、未覆蓋路徑與原因。
+### 1. 閱讀並理解代碼庫
+
+按照功能模塊的定義，全面檢索並將代碼庫拆分為單個或多個功能模塊。接著，開始對功能模塊下的子模塊進行識別及深度閱讀。
+如果外部環境允許使用 subagents ，建議為每一個功能模塊分配一個 subagents 進行深度閱讀，並要求 subagents 完整列出：
+- 該功能模塊與其他功能模塊之間是否存在交互；如有，如何交互。
+- 該功能模塊內部存在哪些子模塊，這些子模塊之間如何交互並實現功能模塊的功能。
+- 該功能模塊及下屬子模塊的資料流、錯誤處理。
 
-## 使用範例
+### 2. 使用 `apltk` cli 工具協助生成架構圖
 
-- 「替這個倉庫首次生成 HTML 架構圖。」 -> 「先梳理功能模組，再按功能分派子 agent，最後彙總跨功能邊，生成基礎 atlas 與渲染頁面。」
-- 「把系統的資料流、呼叫關係和回滾路徑視覺化。」 -> 「使用 `call` / `return` / `data-row` / `failure` 邊表達跨邊界關係，並為每個關鍵子模組補齊內部 `dataflow`。」
+將前一步獲取到的代碼庫只是通過 cli 工具轉化為清晰的架構圖。
+完成之後，驗證架構圖格式正確、可渲染。
 
-## 參考資料索引
+## 參考資料
 
 - `references/TEMPLATE_SPEC.md`：atlas 欄位、列舉和 CLI 寫入形狀速查表。
-- `lib/atlas/cli.js`：`apltk architecture` 的實作入口。
-- `lib/atlas/schema.js`：圖譜資料結構與校驗規則。
-- `sample-demo/`：完整示例輸出，可用於理解基礎 atlas 的最終形態。
-- `spec-to-project-html/SKILL.md`：面向規劃文件的 overlay 版本。
-- `update-project-html/SKILL.md`：面向已存在基礎 atlas 的增量刷新版本。
+- `references/definition.md`: 功能模塊和子模塊的詳細定義。
+- `references/architecture-page.template.html`: 模板html。
+- `references/architecture.css`: 風格模板。
+- `sample-demo/`：完整示例輸出，用於理解基礎 atlas 的最終形態。
+- `apltk architecture --help` - cli 工具的指引指令。

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

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

package/maintain-project-constraints/SKILL.md

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

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

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

package/open-source-pr-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: open-source-pr-workflow
-description: PR-focused workflow for open-source repositories. Use when the user asks to prepare a PR branch from existing changes, draft/open/update a PR, or push a ready contribution branch. Do not use this skill for implementing product features or editing business logic; use it after code changes are already prepared. Enforce branch naming as codex/{change_type}/{changes}, open PRs directly by default without waiting for draft confirmation, show drafts only when the user explicitly asks to review them first, default forked repositories to open PRs against the upstream parent repository unless the user explicitly requests the fork, and write PR content in English by default with required sections for related issues or motivation, engineering decisions with rationale, and test results with commands. For code-affecting changes, run discover-edge-cases first, resolve any confirmed findings, and run code-simplifier before opening the PR.
+description: PR-focused workflow for open-source repositories. Use when the user asks to prepare a PR branch from existing changes, draft/open/update a PR, or push a ready contribution branch. Do not use this skill for implementing product features or editing business logic; use it after code changes are already prepared. Enforce branch naming as codex/{change_type}/{changes}, open PRs directly by default without waiting for draft confirmation, show drafts only when the user explicitly asks to review them first, default forked repositories to open PRs against the upstream parent repository unless the user explicitly requests the fork, and write PR content in English by default with required sections for related issues or motivation, engineering decisions with rationale, and test results with commands. For code-affecting changes, run code-simplifier before opening the PR.
 ---
 
 # Open Source PR Workflow
@@ -8,7 +8,7 @@ description: PR-focused workflow for open-source repositories. Use when the user
 ## Dependencies
 
 - Required: **`commit-and-push`** before publishing the contribution branch (any remaining changes **MUST** be committed/readiness-checked through that skill; **push** only when the user requested remote update—then continue to PR steps).
-- Conditional: `discover-edge-cases` and `code-simplifier` for code-affecting PRs before opening the PR.
+- Conditional: `code-simplifier` for code-affecting PRs before opening the PR.
 - Optional: none.
 - Fallback: If **`commit-and-push`** or a **required** code-affecting dependency is unavailable, stop and report the missing dependency instead of bypassing the quality gate.
 
@@ -54,10 +54,7 @@ git checkout -b codex/fix/add-rate-limit-retry
 
 ### 4) Run dependent skills for code-affecting changes
 
-- If the PR includes code changes, run `discover-edge-cases` first to discover unresolved edge-case risks.
-- Resolve any confirmed findings before continuing.
-- Then run `code-simplifier` on the updated changes.
-- Keep both passes minimal and focused on the current PR scope.
+- If the PR includes code changes, run `code-simplifier` before opening the PR.
 - Use these skills as internal quality gates only; do not include skill/tool names in PR content.
 - If the PR has no code changes, explicitly note that these two skills were not required in internal notes only.
 
@@ -118,7 +115,7 @@ If tests cannot run locally, state why and provide the closest available validat
 - If the user asked to review the draft, they confirmed the final draft before PR creation.
 - If the repository is a fork, PR destination is the upstream parent unless the user explicitly requested the fork.
 - PR body includes all required sections and focuses only on PR-related context.
-- If code changes exist, run `discover-edge-cases`, resolve confirmed findings, and then run `code-simplifier` before opening the PR.
+- If code changes exist, run `code-simplifier` before opening the PR.
 - PR body does not mention internal skills/tools or agent workflow notes.
 - Test commands and results are explicitly listed.
 - Language defaults to English unless user requests otherwise.