@laitszkin/apollo-toolkit 3.11.8 → 3.12.0

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

@@ -1,114 +1,51 @@
 ---
 name: merge-changes-from-local-branches
 description: >-
-  Read changes from local branches identified by branch name and merge them back into the current local branch. Resolve conflicts by composing correct behavior (prefer the more recent change on the same line or the variant that preserves working behavior), using **`merge-conflict-resolver`** when needed. Verify after merges; remove successfully merged source branches and detached worktrees only after merge + verification succeed. Finalize through **`commit-and-push`** for submission-readiness gates and the **final local commit** on the same branch—**do not** push unless the user explicitly requested remote update in this thread (**`commit-and-push`** step 7). **Does not** run **`archive-specs`** as part of this skill.
-  Use when consolidating named local branch work into the current branch or preparing integration on that branch.
+  將使用者指定的本地分支合併回當前分支，按既定順序完成衝突處理、驗證、
+  安全清理與最終提交準備；除非本次對話中有明確要求，否則不推送遠端。
 ---
 
-# Merge Changes from Local Branches
+## 目標
+在工作開始時的當前本地分支上，整合使用者指定的本地分支，或由現有 spec / batch
+規劃可無歧義對應出的本地分支，完成合併、驗證、清理與提交流程銜接，並確保整合結果
+可安全交由 `commit-and-push` 收尾。
 
-## Dependencies
+## 驗收條件
+- 所有實際合併的變更都落在流程開始時的原始當前分支，且不會未經使用者允許改換目標分支。
+- 合併範圍只包含使用者明確指定，或可由 `coordination.md` / spec 上下文無歧義映射出的分支；若映射不清楚，流程會停止並回報。
+- 當 batch 規劃存在 `Merge order` / landing order 時，實際整合順序與規劃一致；若順序衝突或不明確，不會猜測執行。
+- 所有衝突都以保留正確行為為原則完成解決，並在刪除來源分支或交給 `commit-and-push` 前完成必要驗證。
+- 只清理已成功合併且已驗證的來源分支或 worktree；不會強制刪除尚未真正合入目標分支的來源。
+- 最終交付是原始當前分支上的整合結果與簡潔摘要，並只在使用者於本次對話明確要求時才推送遠端；本技能不單獨執行 `archive-specs`。
 
-- Required: **`commit-and-push`** for submission-readiness, mandated reviews, and the **final** commit on the original current branch (push **only** when the user explicitly asked for remote update in this thread—otherwise stop after commit).
-- Conditional: **`merge-conflict-resolver`** when merge conflicts require deterministic resolution.
-- Optional: none.
-- Fallback: If **`commit-and-push`** is unavailable, **MUST** stop and report—**MUST NOT** improvise readiness or use a bare `git commit` shortcut. If git merge operations fail irreparably, stop and report.
+## 工作流程
+1. 確認目標分支與合併範圍  
+將流程開始時的當前分支視為唯一權威目標分支。優先使用使用者明確提供的分支名稱建立合併集合；只有在 spec 或 batch `coordination.md` 能無歧義對應時，才可從規劃文件補足分支映射與整合順序。
 
-## Non-negotiables
+2. 確認可安全開始整合  
+在原始目標分支上確認工作樹適合執行合併。若存在會干擾整合的未提交變更，停止並回報；不要自行 stash、丟棄變更，或切換到其他目標分支。
 
-- **MUST** treat the branch that was current at workflow start as the **authoritative merge target** for the whole workflow; **MUST NOT** silently switch the destination to **`main`** or another branch unless the user explicitly rescopes.
-- **MUST** determine in-scope branches from **explicit branch names** the user gives **or** from unambiguous mappings from active spec / `coordination.md` context—**MUST NOT** infer the merge set from ancestry heuristics alone when names already define intent.
-- **MUST** read active batch **`coordination.md`** when present and honor a documented **`Merge order` / landing order**; if multiple batches conflict or branch-to-spec mapping is ambiguous, **MUST** stop and report instead of guessing order.
-- **MUST** resolve conflicts by reading both sides and editing merged results that preserve shipped behavior—**MUST NOT** rely on blanket **`-X ours` / `-X theirs`** or timestamp guesses as the primary strategy.
-- **`archive-specs`**: **MUST NOT** invoke **`archive-specs`** from this skill. Any archival or doc-sync routing belongs to **`commit-and-push`** (via **`submission-readiness-check`**) when that workflow’s gates require it—not a separate mandated step immediately after merges here.
-- **MUST** verify the merged tree (targeted checks after conflictful merges; broader **`npm test` / equivalent** when the repo provides a standard command) before deleting source branches or handing off to **`commit-and-push`**.
-- **MUST NOT** **`git push`**, tag, or release **from this skill**; **`commit-and-push`** owns push **only** when the user explicitly requested remote publication in this thread (**same rule as **`commit-and-push`** step 7**).
-- **MUST** finalize through **`commit-and-push`** after staging the post-merge intent—**MUST NOT** bypass **`submission-readiness-check`** / mandated gates with a stray local commit path.
-- **MUST NOT** force-delete merged branches (**`-D`**) when **`-d`** refuses; **MUST** stop and report branches that are not actually merged into the target.
+3. 依既定順序逐一合併  
+按照使用者指定順序，或 `coordination.md` 中明確記錄的 landing order，逐一整合 in-scope 分支。對沒有新增內容或已經合入的分支，跳過並記錄原因。發生衝突時，閱讀雙方內容並編輯出能保留正確行為的結果；必要時使用 `merge-conflict-resolver`。若衝突無法在不猜測意圖的前提下解決，停止並回報。
 
-## Standards (summary)
+4. 驗證整合結果  
+先對衝突區域或高風險改動執行對應驗證，再對整體整合結果執行倉庫慣用的標準驗證。任何驗證失敗都必須先在當前分支修正，之後才能進入清理或提交階段。
 
-- **Evidence**: `git branch`, `git log` / diff stats vs current branch, conflict file contents, `coordination.md` merge order when present.
-- **Execution**: Inventory → clean target branch → sequential merges → verify → prune merged branches/worktrees → **`commit-and-push`** through local commit (push only if user asked).
-- **Quality**: Scope strictly to named / mapped branches; no unrelated branch sweeps; no push-by-default from this workflow.
-- **Output**: Integrated current branch ready for **`commit-and-push`**; concise report of merged/skipped branches, conflicts resolved, verification commands.
+5. 清理已成功整合的來源  
+僅清理已完成合併且已通過驗證的來源分支與對應 worktree。若安全刪除被拒絕，保留來源並回報，不使用強制刪除。
 
-## Workflow
+6. 交給 `commit-and-push` 完成收尾  
+整理合併後的最終提交意圖，並交由 `commit-and-push` 執行必要審查、submission-readiness gate 與最終本地提交。若 `commit-and-push` 不可用，必須停止並回報，不可改走裸 `git commit`。本技能不負責 push、tag、release，也不另外觸發 `archive-specs`；只有使用者在本次對話中明確要求遠端更新時，才允許後續推送。
 
-**Chain-of-thought:** Before each numbered step, answer the **`Pause →`** prompts. Validator or verification red **blocks** advancing to pruning or **`commit-and-push`**.
+7. 回報結果  
+總結已合併與跳過的分支、使用的順序依據、衝突處理原則、驗證結果，以及流程最終停在本地 `HEAD` 還是包含遠端推送。
 
-### 1) Inventory the current branch and in-scope named branches
+## 範例
+- 「把 `feature/api-layer` 和 `feature/cli-wrapper` 合回目前分支」 -> 以目前分支為唯一目標，依指定順序完成整合、驗證與安全清理，再交給 `commit-and-push` 做最終本地提交。
+- 「根據這個 batch 的 `coordination.md` 把各 worktree 分支合回來，但先不要 push」 -> 先從 batch 規劃確認無歧義分支映射與 landing order，再依序合併、驗證、清理，最後只做到本地提交。
+- 「把那幾個應該相關的分支一起合一下」 -> 若無法從使用者輸入或規劃文件明確判定分支集合與順序，停止並回報需要補充資訊，而不是依 ancestry 或名稱猜測。
 
-- Run `git branch`; capture `git branch --show-current` and `git status -sb`.
-- Inspect `docs/plans/` for active batch roots that include **`coordination.md`**; read merge-order guidance **before** choosing sequence.
-- Build the merge set from **user branch names**, else from unambiguous spec-name / **`coordination.md`** mappings—if a required name cannot be matched, stop and report.
-- For each candidate: `git log --oneline <current>..<candidate>` and `git diff --stat <current>...<candidate>` (or equivalent); skip empty / already-up-to-date branches and record why.
-- Per branch, note: name, match rationale, commits ahead, `git log -1 --oneline`.
-  - **Pause →** Is every in-scope branch matched **unambiguously**, not by “probably related” ancestry?
-  - **Pause →** If **`coordination.md`** gives a merge order, does my sequence match it literally?
-
-### 1.5) Resolve merge order from active batch specs
-
-- When **`coordination.md`** defines **`Merge order` / landing order**, merge **only** in that order after mapping branch names to specs/worktrees without guessing.
-- When multiple active batches disagree or mapping is unclear, stop and report.
-- When no explicit order exists, use the user’s branch list order sequentially.
-  - **Pause →** Would merging in a different order violate a written batch plan?
-
-### 2) Ensure clean state on the original current branch
-
-- Inspect `git status`. If unrelated uncommitted changes block a safe merge, stop and report—**MUST NOT** stash or discard without user direction.
-  - **Pause →** Am I still on the **same** authoritative target branch I started with?
-
-### 3) Merge branches sequentially in the resolved order
-
-For each in-scope branch:
-
-1. `git checkout <current-branch>`
-2. `git merge <branch-name> --no-ff -m "Merge branch '<branch-name>' into <current-branch>"`
-3. On conflicts: use **`merge-conflict-resolver`**; then `git add` resolved paths.
-4. If resolution is ambiguous, prefer behavior that preserves tests, documented intent, and minimal semantic drift.
-5. Complete the merge commit if Git did not auto-complete.
-
-### 4) Verify merged state
-
-- After conflictful merges, run the most relevant targeted tests or builds for touched areas.
-- After all merges, run the repo’s usual validation (`npm test`, `cargo test`, etc.) when applicable.
-  - **Pause →** Did verification fail? **MUST** fix on the current branch before pruning or **`commit-and-push`**—**do not** hide red tests behind a merge report.
-
-### 5) Prune merged sources (after verified success only)
-
-- `git worktree list`; remove worktrees for successfully merged branches when safe.
-- `git branch -d <branch-name>` only for verified merges; refuse **`-D`** when **`-d`** fails—report instead.
-- **Never** delete the original target branch, the checked-out branch, or branches that failed / were skipped.
-
-### 6) Submit via **`commit-and-push`** (local commit; push optional)
-
-- Stage the post-merge / fix-up intent per user scope.
-- Run **`commit-and-push`** through **commit**: inspect, classify gates, mandated reviews where applicable, **`submission-readiness-check`**, then commit with conventional message—**omit push** unless the user explicitly requested remote update in this thread ( **`commit-and-push`** step **7**).
-- **MUST NOT** reintroduce **`archive-specs`** as a sibling step controlled by **this** skill; if **`submission-readiness-check`** routes archival work, **`commit-and-push`** owns that decision.
-  - **Pause →** Am I about to push without an explicit user request for remote publication?
-  - **Pause →** Does `git diff --cached` match intended merge scope—no stray unrelated paths?
-
-### 7) Report
-
-- List merged vs skipped branches and why.
-- Current branch name; confirmation merges landed on original target.
-- Conflicts resolved and brief rationale.
-- Verification commands executed.
-- State whether completion stopped at **local HEAD** (**no push**) or included push per explicit user ask.
-
-## Sample hints
-
-- **Skip**: candidate shows no commits ahead of current—record “already merged / empty”.
-- **`coordination.md`**: landing order **`api-layer`** then **`cli-wrapper`** ⇒ merge matching branches in that sequence even if creation dates differ.
-- **`commit-and-push` without push**: user said “merge and commit locally”—run **`commit-and-push`** gates and commit; report `HEAD` hash; **no** **`git push`**.
-
-## Working Rules
-
-- Never force-push from this workflow.
-- Preserve functionality over winning either branch’s raw diff verbatim.
-- Do not merge ambiguously matched or unrelated branches.
-- Do not delete merged sources until merge commit **and** verification succeed.
-- When batch merge-order documentation applies, follow it unless you stop with evidence it is stale.
-
-Resolve conflicts using **`merge-conflict-resolver`**.
+## 參考資料
+- `commit-and-push/SKILL.md`：最終提交、submission-readiness 與是否允許推送的權威流程。
+- `merge-conflict-resolver/SKILL.md`：衝突需要精確合成時的輔助技能。
+- `docs/plans/**/coordination.md`：batch 規劃存在時的 landing order 與分支映射依據。

package/optimise-skill/SKILL.md

@@ -28,7 +28,7 @@ description: Use prompt engineering to optimise agent skill. Use it when you nee
 對於技能有幫助的內但不符合上述技能架構規範，則應該被分類放置在 `references/` 下的markdown檔案。
 
 ## 範例
-- "一個專注在提示LLM agent進行自我迭代，並為代碼庫帶來性能優化的技能需要被優化" -> "定義驗收條件為優化後性能相較優化前至少提升X個百分比，並且項目之中不存在任何O(n^2)級別時間複雜度的函式和邏輯，並按照標準架構重寫技能。"
+- "一個專注在提示LLM agent進行自我迭代，並為repo帶來性能優化的技能需要被優化" -> "定義驗收條件為優化後性能相較優化前至少提升X個百分比，並且項目之中不存在任何O(n^2)級別時間複雜度的函式和邏輯，並按照標準架構重寫技能。"
 - "一個有大量前端開發範例被包含在 `SKILL.md` 之中的前端開發技能需要被優化" -> "定義驗收條件為前端頁面 `reference` 之中提供的大量建議範例重寫且不包含任何建議示例之中明確拒絕的設計，然後按照技能優化流程對技能進行全面的重寫。"
 
 ## 參考資料

package/optimise-skill/references/definition.md

@@ -3,11 +3,11 @@
 
 **建議實踐**：
 - "嚴格遵守風格規範的前端頁面"
-- "嚴格遵從模板生成的規格文檔"
+- "嚴格遵從模板生成的spec"
 - "代碼審查的完整報告總結及改進建議"
 
 **錯誤實踐**：
-- "完成所有規格文檔的閱讀，並理解用戶需求。" - 規格的閱讀是執行步驟，而不是最終的交付產物。
+- "完成所有spec的閱讀，並理解用戶需求。" - spec的閱讀是執行步驟，而不是最終的交付產物。
 - "所有風格規範已經被閱讀。" - 同上
 - "所有代碼已經被仔細審查" - 這看似是驗收條件，但實際上因為不可量化，並不是一個好的驗收條件。代碼審查的報告和改進建議是能夠被直觀衡量的交付產物。
 
@@ -17,19 +17,19 @@
 **建議實踐**：
 - "按照本次變更的實際內容，創建符合通用開發規範的git分支並在分支上提交變更。"
 - "在結束任務之前閱讀並確認所有檢查項目是否被勾選為完成。"
-- "閱讀規格文檔之中的 `spec.md` 來完整理解用戶需求"
+- "閱讀spec之中的 `spec.md` 來完整理解用戶需求"
 
 **錯誤實踐**：
 - "使用 `git diff --stat` 閱讀目前變更。然後使用 `git branch -b <branch_name>` 來創建專屬分支。最後通過 `git commit -m "<commit_message>"` 完成提交。"
 - "在結束任務之前，使用 `cd completion-criteria/` 進入檢查項目所處目錄，通過 `cat checklist.md` 來閱讀整個檢查項目清單，並確認當中的markdown checkboxes是否被勾選為完成。"
-- "使用 `ls` 找到規格文檔目錄，並使用 `cd spec/` 進入規格文檔所出目錄。然後使用 `cat spec.md` 來理解用戶的需求。"
+- "使用 `ls` 找到spec目錄，並使用 `cd spec/` 進入spec所出目錄。然後使用 `cat spec.md` 來理解用戶的需求。"
 
 ## 範例
 範例是一個技能之中讓效果達到預期的重要基礎。其本質上是通過**對比交付產物在執行工作流程前及執行工作流程後的狀態**，讓agent在調用工作流程自行工作的時候對目標有著清晰的認知，從而避免在執行時成為無頭蒼蠅並在上下文之中迷失。
 
 **建議實踐**：
 用一個用於優化提示詞技能的技能作為示例：
-- "一個專注在提示LLM agent進行自我迭代，並為代碼庫帶來性能優化的技能需要被優化" -> "定義驗收條件為優化後性能相較優化前至少提升X個百分比，並且項目之中不存在任何O(n^2)級別時間複雜度的函式和邏輯，並按照標準架構重寫技能。"
+- "一個專注在提示LLM agent進行自我迭代，並為repo帶來性能優化的技能需要被優化" -> "定義驗收條件為優化後性能相較優化前至少提升X個百分比，並且項目之中不存在任何O(n^2)級別時間複雜度的函式和邏輯，並按照標準架構重寫技能。"
 - "一個有大量前端開發範例被包含在 `SKILL.md` 之中的前端開發技能需要被優化" -> "定義驗收條件為前端頁面 `reference` 之中提供的大量建議範例重寫且不包含任何建議示例之中明確拒絕的設計，然後按照技能優化流程對技能進行全面的重寫。"
 
 **錯誤實踐**：

package/optimise-skill/references/example_skill.md

@@ -28,7 +28,7 @@ description: Use prompt engineering to optimise agent skill. Use it when you nee
 對於技能有幫助的內但不符合上述技能架構規範，則應該被分類放置在 `references/` 下的markdown檔案。
 
 ## 範例
-- "一個專注在提示LLM agent進行自我迭代，並為代碼庫帶來性能優化的技能需要被優化" -> "定義驗收條件為優化後性能相較優化前至少提升X個百分比，並且項目之中不存在任何O(n^2)級別時間複雜度的函式和邏輯，並按照標準架構重寫技能。"
+- "一個專注在提示LLM agent進行自我迭代，並為repo帶來性能優化的技能需要被優化" -> "定義驗收條件為優化後性能相較優化前至少提升X個百分比，並且項目之中不存在任何O(n^2)級別時間複雜度的函式和邏輯，並按照標準架構重寫技能。"
 - "一個有大量前端開發範例被包含在 `SKILL.md` 之中的前端開發技能需要被優化" -> "定義驗收條件為前端頁面 `reference` 之中提供的大量建議範例重寫且不包含任何建議示例之中明確拒絕的設計，然後按照技能優化流程對技能進行全面的重寫。"
 
 ## 參考資料

package/package.json

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

package/review-change-set/SKILL.md

@@ -1,96 +1,46 @@
 ---
 name: review-change-set
 description: >-
-  Unbiased **git diff** review: architecture (boundaries, duplication, ownership) then simplification (real deletes/flattening, not churn)—discard conversation bias. For diffs spanning multiple files/modules, **prefer dispatching one read-only subagent per scope cluster** (each owns its files end-to-end), then aggregate confirmed findings on the main agent without re-reading delegated files.
-  Use for pre-commit/pre-PR review, refactor/abstraction second opinion, “review my branch” **STOP** greenfield feature design from scratch—use planning skills… BAD style-only nits… GOOD evidence + named abstraction target…
+  面向當前 `git diff` 的只讀審查技能。先從架構與模組邊界切入，再檢查是否存在真正能降低複雜度的簡化機會；忽略對話偏見，不做 style-only 評論。當變更跨多個檔案或模組時，優先按 scope cluster 派發只讀 subagent，各自讀完整個責任區後回傳結構化發現，由主代理統一去重與彙總。
 ---
 
-# Review Change Set
-
-## Dependencies
-
-- Required: none.
-- Conditional: none.
-- Optional: none.
-- Fallback: If a downstream consumer (e.g. `commit-and-push`) needs additional safety checks (security, edge cases), invoke those skills explicitly there — this skill no longer chains them automatically.
-
-## Non-negotiables
-
-- Read the **full** active change set (staged **and** unstaged when both exist—label which finding hits which).
-- **MUST** discard authorship bias; burden of proof on the code.
-- Prefer **architecture** and **maintainability** over style-only.
-- Abstraction only when it cuts duplication, clarifies ownership, or stabilizes boundaries.
-- Simplification only when behavior-preserving and genuinely simpler—**MUST NOT** shuffle complexity.
-- For non-trivial diffs (multiple files, multiple modules, or large per-file changes), **SHOULD** dispatch **read-only subagents** — one per coherent scope cluster (e.g. one feature/package, one layer, or one logical concern). Each subagent reads its assigned files end-to-end and returns ONLY structured findings (architecture + simplification with `path:line` evidence). The main agent **MUST NOT** re-read delegated files; it aggregates confirmed findings, deduplicates cross-cluster overlaps, and writes the final report. Tiny one-file diffs may be reviewed inline without subagents.
-- **MUST NOT** fabricate findings the diff does not actually contain; subagent reports stay confined to architecture and simplification.
-
-## Standards (summary)
-
-- **Evidence**: Full diff + minimum context reads to understand behavior; subagent reports cite `path:line` per finding.
-- **Execution**: Git state → baseline → (subagent fan-out for multi-cluster diffs OR inline read for tiny diffs) → architecture → simplification → aggregate → report.
-- **Quality**: Actionable, outsider perspective; subagent fan-out keeps each context window small; no duplicated findings across clusters.
-- **Output**: Scope, architecture findings, simplification findings, residual uncertainty.
-
-## Workflow
-
-**Chain-of-thought:** **`Pause →`** after each block—no verdicts from partial file reads.
-
-### 1) Inspect git state
-
-- `git status -sb`, `git diff --stat`, `git diff --cached --stat`; cover staged vs unstaged explicitly.
-- No diff → `No active git change set to review` and stop.
-   - **Pause →** Am I about to review **only** unstaged while staged also ships?
-
-### 2) Plan the read pattern
-
-- **Tiny diff** (one file or a handful of small hunks in one module) → read inline; skip subagents.
-- **Multi-file or multi-module diff** → cluster the changed files into coherent scopes (one feature/package, one layer, one logical concern). Dispatch **one read-only subagent per cluster**. Hand each subagent: the cluster file list, its slice of `git diff`/`git diff --cached`, and the structured-report contract below. The main agent **MUST NOT** read the delegated files itself.
-
-> **Cluster `<scope>` subagent contract**
-> - Read every file in this cluster E2E plus the minimum callers/callees/config needed to interpret behavior.
-> - Discard authorship bias; behavior comes from code/tests/config, not chat memory.
-> - Return ONLY a structured findings block:
->   - `Architecture`: list of `{ title, evidence (path:line), abstraction target, why current shape is weaker }`.
->   - `Simplification`: list of `{ title, evidence (path:line), candidate change, behavior-preserving benefit }`.
->   - `Outbound concerns`: any boundary issue that touches another cluster (so the orchestrator can deduplicate).
-> - No source dumps, no opinions about tasks outside this cluster, no security/edge-case fabrication.
-
-   - **Pause →** Did I cluster correctly so that one subagent owns each coherent boundary, or am I about to split a duplicated helper across two subagents and miss the dedup signal?
-
-### 3) Baseline (inline path) or aggregate (subagent path)
-
-- Inline: read every changed file E2E; pull in minimal callers/callees/config to interpret moves and interfaces.
-- Subagent: wait for **every** cluster subagent to return. Aggregate their findings, then deduplicate any architecture finding two clusters reported via their `Outbound concerns` block.
-- Behavior from **code, tests, config, execution**—not from chat memory.
-   - **Pause →** Can I quote **one concrete behavior** change this diff introduces—not intent?
-
-### 4) Architecture first
-
-Flag only if evidence-backed: duplicated workflows, cross-layer leakage, wrong helper ownership, repeated condition trees, unstable interfaces.
-Each finding **MUST** name abstraction target **and** why current shape is weaker.
-   - **Pause →** Is this “different style” or a real **boundary** problem?
-
-### 5) Simplification second
-
-Redundant branches/wrappers, deep nesting, duplicated validation, oversize functions, dead compat—**only** if it truly reduces complexity.
-   - **Pause →** Would this refactor just **move** lines between files?
-
-### 6) Report
-
-1. **Scope** — staged/unstaged; extra context paths read; cluster list when subagents were used.
-2. **Architecture** — title, evidence (`path:line`), candidate, why weaker.
-3. **Simplification** — title, evidence, candidate, benefit.
-4. **Residual uncertainty** — hypotheses / follow-up checks.
-
-If nothing actionable: `No actionable abstraction or simplification finding identified`.
-
-## Sample hints
-
-- **Staged only**: User ran `git add -p` → findings tagged **staged** vs **unstaged** separately.
-- **Rename-heavy**: Read old→new path mapping before calling “duplication.”
-- **Tiny diff**: One-file guard clause → architecture section may be empty; reviewed inline without subagents.
-- **Wide refactor across packages**: cluster by package; one read-only subagent per package; dedupe duplicated-helper findings on the main agent.
-
-## References
-
-- Downstream consumers (e.g. `commit-and-push`, `version-release`, `review-spec-related-changes`) decide independently when to add security or edge-case passes; this skill no longer wires them.
+## 目標
+輸出一份針對活躍變更集的審查報告，聚焦真正有價值的架構問題與可維護性簡化機會，而不是風格雜訊。報告需要標明審查範圍、staged/unstaged 狀態、已確認的架構問題、已確認的簡化建議，以及剩餘不確定性。
+
+## 驗收條件
+- 已完整覆蓋本次活躍變更集；若 staged 與 unstaged 同時存在，必須明確區分哪些發現命中哪一部分。
+- 每個發現都基於完整 diff 與最小必要上下文，並附帶 `path:line` 證據；不得只靠對話記憶、作者意圖或主觀風格偏好下結論。
+- 架構與責任邊界問題優先於 style-only 建議；抽象必須能消除重複、釐清歸屬或穩定邊界。
+- 簡化建議必須是行為等價且真正降低複雜度的改動，不能只是把複雜度搬到別處。
+- 對於跨多檔、多模組或大變更，應按 coherent scope cluster 使用只讀 subagent；主代理只負責聚合、去重與整理，不重讀已委派檔案。
+- 若沒有可操作發現，最終需明確輸出 `No actionable abstraction or simplification finding identified`。
+
+## 工作流程
+1. 檢查 git 狀態。
+   - 先確認 `git status`、staged diff 與 unstaged diff，避免只審其中一半。
+   - 若目前沒有活躍變更集，直接輸出 `No active git change set to review`。
+2. 決定閱讀策略。
+   - 單檔或很小的同模組變更可直接 inline 審查。
+   - 多檔、多模組或跨層變更需先按功能、套件、層級或邏輯關切點切成 scope cluster，並優先以一個只讀 subagent 對應一個 cluster。
+3. 建立基線並收斂上下文。
+   - Inline 路徑下，讀完整個變更檔案與最小必要的 caller、callee、配置。
+   - Subagent 路徑下，等待所有 cluster 結果返回，再根據共享邊界與 outbound concerns 做去重。
+   - 所有判斷都必須回到代碼、測試、配置與可觀察行為本身。
+4. 先做架構審查。
+   - 只報告有明確證據支撐的問題，例如跨層洩漏、重複工作流、錯誤 helper 歸屬、重複條件樹、脆弱介面或責任模糊。
+   - 每條架構發現都要指出候選抽象或責任落點，以及當前寫法為何更弱。
+5. 再做簡化審查。
+   - 只在確定不改變行為的前提下，指出多餘分支、包裝層、深巢狀、重複驗證、過大函式或歷史相容殘骸。
+   - 若建議只是把複雜度移位，則不應作為有效簡化發現。
+6. 輸出報告。
+   - 先交代審查範圍、staged/unstaged 區分、補讀的上下文與 cluster 情況。
+   - 再依序輸出架構發現、簡化發現與剩餘不確定性。
+
+## 使用範例
+- 「幫我 review 這次 branch 的變更」-> 先完整覆蓋 staged 與 unstaged diff，再按架構問題與簡化機會輸出報告。
+- 「我想知道這次重構有沒有真正變簡單」-> 聚焦行為等價的簡化空間，而不是風格偏好。
+- 「這次改動跨很多 package，請不要漏看邊界」-> 先按 package 或邏輯責任分 cluster，用只讀 subagent 分治後再由主代理去重彙總。
+- 「如果沒有值得改的地方，直接講沒有」-> 若無可操作發現，明確輸出 `No actionable abstraction or simplification finding identified`。
+
+## 參考資料索引
+- 下游工作流如 `commit-and-push`、`version-release`、`review-spec-related-changes` 會自行決定是否追加安全或邊界情況審查；本技能只負責變更集的架構與簡化分析。

package/review-codebases/SKILL.md

@@ -1,103 +1,46 @@
 ---
 name: review-codebases
-description: Repository-wide code review workflow that requires reading the full codebase before judging, prioritizes architecture findings over implementation details, and publishes one GitHub issue per confirmed finding through open-github-issue. Use when users ask for a code review, repository audit, architecture review, maintainability review, or complete codebase inspection.
+description: >-
+  面向整個倉庫的只讀代碼審查技能。要求先讀完整個人類編寫的repo，再按「架構 → 代碼品質 → 邊界情況」的優先順序做判斷；一旦在更高層級發現已確認問題，就停止下探。若需要對外追蹤，為每個已確認且非重複的發現建立 GitHub issue，否則至少輸出可直接發布的草稿內容。
 ---
 
-# Review Codebases
-
-## Dependencies
-
-- Required: none.
-- Conditional: `read-github-issue` when issue publication requires duplicate checks; `open-github-issue` when confirmed findings should be tracked as GitHub issues.
-- Optional: none.
-- Fallback: If publication is needed and `open-github-issue` is unavailable, return draft issue bodies instead of inventing another publisher.
-
-## Standards
-
-- Evidence: Read the full human-authored repository before judging and cite concrete files for every finding.
-- Execution: Review architecture first, code quality second, and edge cases last, stopping when a higher-priority tier has confirmed findings.
-- Quality: Prefer root-cause findings over scattered symptoms, merge duplicates, and keep hypotheses out of published results.
-- Output: Return coverage, review tier reached, confirmed findings, publication status, and deferred lower-tier follow-up.
-
-## Core rules
-
-- Read the full repository before judging any design or implementation choice.
-- Inspect every human-authored file that affects behavior: source code, tests, build scripts, configuration, migrations, and key docs.
-- For generated, vendored, or snapshot files, verify what they are first; exclude them from deep review only when that status is clear, and list those exclusions explicitly.
-- Do not speculate. Every finding must cite concrete files and causal reasoning.
-- Prefer root-cause findings over scattered symptoms or style nits.
-- Merge duplicate symptoms into one finding when they come from the same underlying issue.
-
-## Workflow
-
-1. Map the repository
-   - List top-level directories and identify entrypoints, domain modules, test suites, configuration, scripts, and generated/vendor areas.
-   - Record any files or folders excluded from deep review and why.
-2. Read the whole codebase
-   - Read all relevant human-authored files end to end.
-   - Build a repository-wide model of boundaries, data flow, ownership, invariants, and failure handling.
-3. Review architecture first
-   - Check module boundaries, layering, hidden coupling, circular dependencies, duplicated workflows, leaky abstractions, ownership confusion, and inconsistent domain models.
-   - If any confirmed architecture findings exist, stop the lower-level review and report only architecture findings.
-4. Review code quality second
-   - Run this step only when there are no architecture findings.
-   - Check readability, duplication, dead code, error handling, unsafe state changes, unclear contracts, missing tests around critical logic, and maintainability risks.
-   - If any confirmed code-quality findings exist, stop before edge-case review and report only these findings.
-5. Review edge cases last
-   - Run this step only when there are no architecture or code-quality findings.
-   - Check null or empty inputs, boundary values, partial failures, retries, concurrency, ordering assumptions, idempotency, and invalid state transitions.
-6. Check for duplicate issues before publication
-   - When findings will be published, use `read-github-issue` to search the target repository for open and recently closed issues that match the same module, failure mode, or architectural boundary.
-   - Treat an existing issue as a duplicate when the underlying root cause, affected boundary, and requested outcome materially overlap, even if the wording differs.
-   - If a duplicate exists, cite it in the final report and do not publish a new issue for that finding.
-7. Publish each confirmed non-duplicate finding
-   - Invoke `open-github-issue` once per finding.
-   - Use a tier-specific title prefix:
-     - `[Architecture] <short finding>`
-     - `[Code Quality] <short finding>`
-     - `[Edge Case] <short finding>`
-   - Pass these fields to the dependency skill:
-     - `title`
-     - `problem-description`: symptom, impact, and repository evidence
-     - `suspected-cause`: file references, causal chain, and confidence
-     - `reproduction`: concrete trigger or conditions when known; otherwise leave empty
-     - `repo`: target repository in `owner/repo` format when known
-   - If invoking the publisher CLI directly, pass finding details through `apltk open-github-issue --payload-file <json>` or `@file` inputs rather than inline shell arguments so code snippets and backticks survive unchanged.
-
-## Evidence standard
-
-Each finding must include:
-
-- affected files or modules
-- why the current design or code is problematic
-- impact on correctness, maintenance, performance, or future change safety
-- confidence level with a short reason
-
-If evidence is incomplete, keep it as a hypothesis and do not publish a GitHub issue for it.
-
-## Output format
-
-Use this structure in responses:
-
-1. Codebase coverage
-   - reviewed areas
-   - explicit exclusions
-2. Review tier reached
-   - architecture / code quality / edge cases
-   - why lower tiers were skipped, if applicable
-3. Confirmed findings
-   - title
-   - affected files
-   - evidence and reasoning
-   - impact
-   - confidence
-4. GitHub issue publication status
-   - duplicate-check status and any matching existing issue URLs
-   - publication mode (`gh-cli` / `github-token` / `draft-only`)
-   - created issue URL or draft output per finding
-5. Deferred follow-up
-   - list lower-tier checks that were intentionally not performed because a higher-tier issue already exists
-
-## Resources
-
-- Dependency skill: `open-github-issue` for deterministic GitHub issue publication with auth fallback and README language detection.
+## 目標
+輸出一份面向整個倉庫的審查報告，先交付最有價值的根因級問題，而不是零散表象。報告需要說明覆蓋範圍、實際審查到的層級、已確認發現、是否已檢查重複 issue、是否已發布 issue，以及因高優先級問題而延後的後續檢查。
+
+## 驗收條件
+- 在做任何設計或實作判斷前，已完整閱讀所有會影響行為的人類編寫檔案，包括原始碼、測試、配置、建置腳本、遷移與關鍵文檔。
+- 對生成檔、vendor 檔與 snapshot 檔先確認其性質；只有在性質明確時才可排除深讀，且必須在報告中明確列出排除項與原因。
+- 每個發現都附帶具體檔案與因果說明，不做無證據推測；同一根因導致的多個症狀必須合併成一條發現。
+- 審查順序固定為「架構 → 代碼品質 → 邊界情況」；若在較高層級已確認問題，必須停止更低層級審查並在報告中說明原因。
+- 若需要發布 issue，必須先做重複檢查；每個已確認且非重複的發現都要有發布結果，若無法發布則提供可直接使用的草稿內容。
+- 最終交付物必須包含覆蓋範圍、審查層級、已確認發現、issue 發布狀態與延後檢查項。
+
+## 工作流程
+1. 映射倉庫。
+   - 先識別頂層目錄、入口點、核心模組、測試區、配置、腳本與疑似生成/vendor 區域。
+   - 同時記錄哪些內容會被排除深讀，以及排除理由。
+2. 完整閱讀repo。
+   - 逐個讀完所有相關的人類編寫檔案。
+   - 建立全倉視角的模組邊界、資料流、責任歸屬、不變式與失敗處理模型。
+3. 先做架構審查。
+   - 優先尋找模組邊界錯位、跨層洩漏、循環依賴、重複工作流、抽象滲漏、責任混亂與領域模型不一致。
+   - 若已確認任何架構問題，直接停止後續較低層級審查，專注輸出架構發現。
+4. 若架構層沒有問題，再做代碼品質審查。
+   - 檢查可讀性、重複代碼、死碼、錯誤處理、危險狀態變更、契約不清與關鍵邏輯缺少測試保護等問題。
+   - 若已確認任何代碼品質問題，停止邊界情況審查。
+5. 僅在前兩層都沒有問題時，才審查邊界情況。
+   - 檢查空值、邊界值、部分失敗、重試、併發、順序假設、冪等性與非法狀態轉移。
+6. 需要發布時，先做重複檢查再逐條發布。
+   - 使用 `read-github-issue` 檢查是否已有相同根因、相同邊界或相同結果導向的 open / recently closed issue。
+   - 對每個已確認且非重複的發現，使用 `open-github-issue` 發布；若發布依賴不可用，改為返回對應 issue 草稿。
+   - issue 標題前綴遵循審查層級，例如 `[Architecture]`、`[Code Quality]`、`[Edge Case]`。
+
+## 使用範例
+- 「幫我做一次整倉 code review」-> 先讀完整個人類編寫的repo，再按架構、代碼品質、邊界情況的順序輸出審查報告。
+- 「幫我做 maintainability audit，找到最值得開 issue 的問題」-> 聚焦根因級問題，必要時先做 duplicate check，再為每個非重複發現準備或發布 issue。
+- 「請做 architecture review，不要陷入 style nit」-> 先完成全倉閱讀，只報告有明確邊界與責任證據的架構問題。
+- 「如果 issue 發布不了，也要把內容整理好」-> 仍然完成重複檢查，並輸出可直接發布的 issue 草稿，而不是臨時改用其他未定義發佈方式。
+
+## 參考資料索引
+- `read-github-issue`：在發布前檢查目標倉庫中是否已存在相同根因的 issue，避免重複建單。
+- `open-github-issue`：為每個已確認且非重複的發現建立 GitHub issue；若不可用，則返回 issue 草稿內容。