@laitszkin/apollo-toolkit 3.11.7 → 3.12.0

package/maintain-project-constraints/SKILL.md

@@ -1,93 +1,39 @@
 ---
 name: maintain-project-constraints
 description: >-
-  Maintain root `AGENTS.md` / `CLAUDE.md` with exactly three mirrored sections (unless the repo documents deliberate divergence): Common Development Commands traced to real scripts/Makefile targets, Project Business Goals capturing macro why/who/outcome, Project Documentation Index enumerating every standardized `docs/features`, `docs/architecture`, `docs/principles` file plus important root docs—purge invented commands, prune deleted paths, forbid stuffing feature lists into Goals.
-  Invoke after missing files, drift after refactors, or once `align-project-documents` reshapes `docs/`.
-  Bad: documenting `npm run magic` absent from `package.json`. Good: cite `npm test` with file reference. Bad: ten micro-features listed under Goals instead of the docs index…
+  依據倉庫現況刷新根目錄 `AGENTS.md` / `CLAUDE.md`，只保留
+  `Common Development Commands`、`Project Business Goals`、
+  `Project Documentation Index` 三個可追溯區塊。
 ---
 
-# Maintain Project Constraints
+# 維護專案約束文件
 
-## Dependencies
+## 技能目標
 
-- Required: none.
-- Conditional: none.
-- Optional: none.
-- Fallback: not applicable.
+基於當前倉庫證據，產出或刷新根目錄 `AGENTS.md` 與 `CLAUDE.md`，使其準確反映開發命令、專案商業目標與文件索引，且不捏造任何內容。
 
-## Non-negotiables
+## 技能驗收條件
 
-- **MUST** derive commands and business purpose from **current** repo artifacts (`package.json`, `Makefile`, `bin/`, `scripts/`, `README`, `docs/features/`, code entrypoints)—**MUST NOT** invent flags, task names, or CLI paths.
-- **`AGENTS.md` / `CLAUDE.md` content** is **exactly three sections**—no extra tutorials, architecture essays, or style guides (those belong in `docs/`):
-  1. **Common Development Commands**
-  2. **Project Business Goals**
-  3. **Project Documentation Index**
-- **MUST** list **every** file under `docs/features/`, `docs/architecture/`, `docs/principles/` plus notable root docs (`README.md`, `CONTRIBUTING.md`, …) that exist; paths **MUST** exist on disk—**MUST NOT** stale links.
-- If **both** `AGENTS.md` and `CLAUDE.md` exist, the three sections **MUST** be **identical** between them unless the repo documents an intentional divergence (otherwise keep parity).
-- **Project Business Goals** = macro **why/for whom/outcome**—**MUST NOT** duplicate the feature inventory (index already points there).
+- 最終交付為根目錄 `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` 同時存在且未聲明故意分歧，兩者的三個區塊內容保持一致。
 
-## Standards (summary)
+## 技能工作流程
 
-- **Evidence**: Scripts and docs on disk drive command list and index—no memory.
-- **Execution**: Inventory → draft three sections → verify paths → prune stray sections.
-- **Quality**: Scannable; no speculative architecture.
-- **Output**: Fresh root constraint files aligned with repo.
+1. 先從倉庫現況收集可驗證的命令入口、專案目的與現有文件清單，不以舊約束文件作為唯一真相。
+2. 根據證據生成三個必需區塊，讓命令、商業目標與文件索引都能被直接追溯。
+3. 按專案慣例更新或補齊 `AGENTS.md` / `CLAUDE.md`，並將正文限制在三個規定區塊內。
+4. 完成前逐項校驗命令來源、文件路徑與雙文件一致性，清除所有陳舊或多餘內容。
 
-## Triggers
+## 技能使用範例
 
-- Missing `AGENTS.md`/`CLAUDE.md`, post-change drift suspected, or after `align-project-documents` reshapes `docs/`.
+- "重建 `docs/` 後，請同步刷新 `AGENTS.md` 和 `CLAUDE.md`。" -> "根據當前腳本、入口與文件樹重寫兩個根目錄約束文件，只保留三個規定區塊並確保索引完整。"
+- "這個專案的 `CLAUDE.md` 已經過時，請補一份對應的 `AGENTS.md`。" -> "依據現有命令與文件結構建立缺失文件，並讓兩份約束文件在預期一致時保持同構。"
+- "請清理根目錄約束文件裡的舊命令與失效路徑。" -> "驗證每條命令與每個索引路徑是否仍然成立，只保留仍可被倉庫證據支持的內容。"
 
-## Workflow
+## 技能參考資料索引
 
-**Chain-of-thought:** **`Pause →`** before writing each section—if a command is uncertain, grep config before committing text.
-
-### 1) Inventory
-
-- Parse command surfaces (`package.json` scripts, `Makefile`, CI, CLIs).
-- Enumerate `docs/features/`, `docs/architecture/`, `docs/principles/`; note root docs.
-  - **Pause →** Can I cite the **source line** (script name, target) for every command I plan to list?
-
-### 2) Business goals
-
-- Prefer `README` + `docs/features/` tone; else infer from user-facing entrypoints—still **product-level sentences**, not file lists.
-
-### 3) Write / update files
-
-- Create or overwrite **only** the three sections per file conventions (create missing file among `AGENTS.md`/`CLAUDE.md` per repo habit).
-  - **Pause →** Did any stray `## Installation` creep in—must delete if not part of repo’s mandated format?
-
-### 4) Documentation index
-
-- One line per file: `path — short purpose`. Mirror reality; drop deleted; add new.
-
-### 5) Verification
-
-- Each command reproducible from declared config; every indexed path exists; both files match if both present; strip extra sections.
-
-## Sample hints
-
-- **Command bad**: “`npm run magic` — deploy” when no script `magic` in `package.json`.
-- **Command OK**: `` `npm test` — runs Node test suite (see `package.json`) ``.
-- **Goals bad**: Listing ten micro-features → belongs in features index + separate files.
-- **Goals OK**: “This repo ships X for Y operators; primary outcome Z.”
-- **Index**: If `docs/features/auth.md` deleted, **remove** line same run.
-
-## Template sketch
-
-```markdown
-## Common Development Commands
-- `…` — …
-
-## Project Business Goals
-…
-
-## Project Documentation Index
-### Features (`docs/features/`)
-- `…` — …
-### Architecture (`docs/architecture/`)
-- …
-### Principles (`docs/principles/`)
-- …
-### Root Documents
-- `README.md` — …
-```
+- `references/constraint-file-reference.md` - 三區塊契約、撰寫規則、核對清單與輸出模板。

package/maintain-project-constraints/references/constraint-file-reference.md

@@ -0,0 +1,58 @@
+# 約束文件參考
+
+## 三區塊契約
+
+根目錄 `AGENTS.md` 與 `CLAUDE.md` 的正文只應包含以下三個區塊，且順序固定：
+
+1. `Common Development Commands`
+2. `Project Business Goals`
+3. `Project Documentation Index`
+
+若專案未明確說明兩者應有差異，這三個區塊的內容應保持一致。
+
+## 撰寫規則
+
+### `Common Development Commands`
+
+- 只收錄能被當前倉庫驗證的命令。
+- 優先從 `package.json`、`Makefile`、`bin/`、`scripts/`、CI 設定或其他真實入口提取。
+- 每條命令附上一句簡短用途說明，避免捏造不存在的工作流。
+
+### `Project Business Goals`
+
+- 只描述專案層級的目的、服務對象與最終價值。
+- 保持宏觀，不展開成細碎功能列表。
+- 若存在產品說明文件，僅在能被當前倉庫內容支撐時採納。
+
+### `Project Documentation Index`
+
+- 覆蓋現存 `docs/features/`、`docs/architecture/`、`docs/principles/` 下的所有文件。
+- 補充重要且實際存在的根目錄文件，例如 `README.md`、`CONTRIBUTING.md`、`SECURITY.md`。
+- 每個條目都應包含檔案路徑與一句用途說明。
+
+## 核對清單
+
+- [ ] 只保留三個規定區塊，且順序正確。
+- [ ] 每條命令都能回溯到真實入口。
+- [ ] 商業目標沒有退化成功能清單。
+- [ ] 文件索引覆蓋所有現存標準化文檔。
+- [ ] 已刪除失效路徑、舊命令與額外區塊。
+- [ ] 若 `AGENTS.md` 與 `CLAUDE.md` 都存在，已確認它們在預期情況下保持一致。
+
+## 輸出模板
+
+```markdown
+# <專案名稱或標題>
+
+## Common Development Commands
+
+- `<command>` - <用途說明>
+
+## Project Business Goals
+
+- <專案存在的原因、服務對象與交付結果>
+
+## Project Documentation Index
+
+- `<path>` - <文件用途說明>
+```

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/open-github-issue/SKILL.md

@@ -52,104 +52,13 @@ Designed to be reusable by other skills that know the issue title and evidence b
 5. Return publication result
    - Always return publication mode, issue URL when created, rendered issue body, and any publish error.
 
-## Deterministic command
-
-Use the bundled command. Prefer `--payload-file` for all rich issue content because inline shell arguments can corrupt Markdown code spans such as `` `symbol` `` before the script starts.
-
-Safe problem issue payload:
-
-```bash
-cat > /tmp/open-github-issue-payload.json <<'JSON'
-{
-  "issue_type": "problem",
-  "title": "[Log] <short symptom>",
-  "problem_description": "Expected Behavior (BDD)\nGiven ...\nWhen ...\nThen `literal_code_span` should remain unchanged\n\nCurrent Behavior (BDD)\nGiven ...\nWhen ...\nThen ...\n\nBehavior Gap\n- Expected: ...\n- Actual: ...\n- Difference/Impact: ...\n\nEvidence\n- symptom: ...\n- impact: ...\n- key evidence: ...",
-  "suspected_cause": "<path:line + causal chain + confidence>",
-  "reproduction": "<steps/conditions or leave empty>"
-}
-JSON
-
-apltk open-github-issue --payload-file /tmp/open-github-issue-payload.json --repo <owner/repo>
-```
-
-Safe feature proposal payload:
-
-```bash
-cat > /tmp/open-github-issue-payload.json <<'JSON'
-{
-  "issue_type": "feature",
-  "title": "[Feature] <short proposal>",
-  "proposal": "<what should be added or changed>",
-  "reason": "<why this matters now, user value, constraints>",
-  "suggested_architecture": "<modules, boundaries, implementation direction>"
-}
-JSON
-
-apltk open-github-issue --payload-file /tmp/open-github-issue-payload.json --repo <owner/repo>
-```
-
-Safe individual field files are also supported:
-
-```bash
-apltk open-github-issue --repo <owner/repo> \
-  --issue-type problem \
-  --title "[Log] <short symptom>" \
-  --problem-description @/tmp/problem-description.md \
-  --suspected-cause @/tmp/suspected-cause.md
-```
-
-Performance issue:
-
-```bash
-apltk open-github-issue \
-  --issue-type performance \
-  --title "[Performance] Slow dashboard query under large tenants" \
-  --problem-description @/tmp/performance-problem.md \
-  --impact @/tmp/performance-impact.md \
-  --evidence @/tmp/performance-evidence.md \
-  --suggested-action @/tmp/performance-action.md \
-  --repo <owner/repo>
-```
-
-Security issue:
-
-```bash
-apltk open-github-issue \
-  --issue-type security \
-  --title "[Security] Missing authorization check on admin export" \
-  --problem-description @/tmp/security-risk.md \
-  --severity high \
-  --affected-scope "/admin/export endpoint and exported customer data" \
-  --impact @/tmp/security-impact.md \
-  --evidence @/tmp/security-evidence.md \
-  --suggested-action @/tmp/security-action.md \
-  --repo <owner/repo>
-```
-
-Docs issue:
-
-```bash
-apltk open-github-issue \
-  --issue-type docs \
-  --title "[Docs] Deployment guide omits required Redis configuration" \
-  --problem-description @/tmp/docs-gap.md \
-  --evidence @/tmp/docs-evidence.md \
-  --suggested-action @/tmp/docs-action.md \
-  --repo <owner/repo>
-```
-
-Observability issue:
-
-```bash
-apltk open-github-issue \
-  --issue-type observability \
-  --title "[Observability] Missing request identifiers in payment retry logs" \
-  --problem-description @/tmp/observability-gap.md \
-  --impact @/tmp/observability-impact.md \
-  --evidence @/tmp/observability-evidence.md \
-  --suggested-action @/tmp/observability-action.md \
-  --repo <owner/repo>
-```
+## CLI reference
+
+Run `apltk open-github-issue --help` for the live flag reference, examples, expected results, and issue-type-specific payload rules.
+
+- Prefer the bundled `apltk` command over calling the Python helper directly.
+- Prefer payload files or `@file` inputs for rich Markdown so shell quoting cannot corrupt the content before Python receives it.
+- Keep one confirmed issue or one accepted proposal per invocation.
 
 ## Output contract
 

package/optimise-skill/SKILL.md

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

package/optimise-skill/references/definition.md

@@ -0,0 +1,38 @@
+## 驗收條件
+驗收條件是一個技能的**宏觀目標**。其描述的必須是agent完成所有任務之後，交付產物的狀態，如：
+
+**建議實踐**：
+- "嚴格遵守風格規範的前端頁面"
+- "嚴格遵從模板生成的spec"
+- "代碼審查的完整報告總結及改進建議"
+
+**錯誤實踐**：
+- "完成所有spec的閱讀，並理解用戶需求。" - spec的閱讀是執行步驟，而不是最終的交付產物。
+- "所有風格規範已經被閱讀。" - 同上
+- "所有代碼已經被仔細審查" - 這看似是驗收條件，但實際上因為不可量化，並不是一個好的驗收條件。代碼審查的報告和改進建議是能夠被直觀衡量的交付產物。
+
+## 工作流程
+工作流程是一個技能核心要素。需要專注在告訴agent **「做什麼」**，而不是 **「如何去做」**。
+
+**建議實踐**：
+- "按照本次變更的實際內容，創建符合通用開發規範的git分支並在分支上提交變更。"
+- "在結束任務之前閱讀並確認所有檢查項目是否被勾選為完成。"
+- "閱讀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` 找到spec目錄，並使用 `cd spec/` 進入spec所出目錄。然後使用 `cat spec.md` 來理解用戶的需求。"
+
+## 範例
+範例是一個技能之中讓效果達到預期的重要基礎。其本質上是通過**對比交付產物在執行工作流程前及執行工作流程後的狀態**，讓agent在調用工作流程自行工作的時候對目標有著清晰的認知，從而避免在執行時成為無頭蒼蠅並在上下文之中迷失。
+
+**建議實踐**：
+用一個用於優化提示詞技能的技能作為示例：
+- "一個專注在提示LLM agent進行自我迭代，並為repo帶來性能優化的技能需要被優化" -> "定義驗收條件為優化後性能相較優化前至少提升X個百分比，並且項目之中不存在任何O(n^2)級別時間複雜度的函式和邏輯，並按照標準架構重寫技能。"
+- "一個有大量前端開發範例被包含在 `SKILL.md` 之中的前端開發技能需要被優化" -> "定義驗收條件為前端頁面 `reference` 之中提供的大量建議範例重寫且不包含任何建議示例之中明確拒絕的設計，然後按照技能優化流程對技能進行全面的重寫。"
+
+**錯誤實踐**：
+用一個專門用於前端開發的提示詞技能作為示例：
+- "前端頁面非常混亂。" -> "找到前端頁面所出目錄，列出所有前端頁面檔案，並對前端頁面進行整理" - 前面的找到目錄、列出檔案，這些都是隱含前提，不需要額外列出。我們需要關注並對比的是執行工作流程前後交付物的狀態。
+- "測試覆蓋率低。" -> "執行工作流程補全測試" - 這裏沒有描述好最終的狀態，應該是 `補齊低測試覆蓋率模塊的高價值測試，確保業務邏輯正確無誤。` ，這樣能夠更清晰展現輸入輸出之間的對應關係。

package/optimise-skill/references/example_skill.md

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

package/package.json

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

package/read-github-issue/SKILL.md

@@ -33,44 +33,16 @@ description: Read and search remote GitHub issues via GitHub CLI (`gh`). Use whe
 
 ### 2) Find candidate issues with the bundled CLI
 
-- Preferred command:
-
-```bash
-apltk find-github-issues --limit 50 --state open
-```
-
-- Optional filters:
-  - `--repo owner/name`
-  - `--label bug`
-  - `--search "panic in parser"`
+- Use `apltk find-github-issues --help` as the live command reference for filters, output modes, and examples.
 - Raw `gh` fallback when the script is missing or broken:
-
-```bash
-gh issue list --limit 50 --state open
-```
-
-- Add `--repo <owner>/<repo>`, `--label <label>`, or `--search "<text>"` as needed.
+- `gh issue list --limit 50 --state open`
 - If the issue target is still unclear, present top candidates and ask which issue number or URL should be inspected next.
 
 ### 3) Read a specific issue in detail
 
-- Preferred command:
-
-```bash
-apltk read-github-issue 123 --comments
-```
-
-- Optional flags:
-  - `--repo owner/name`
-  - `--json`
-  - `--comments`
+- Use `apltk read-github-issue --help` as the live command reference for issue selection, comments, JSON output, and examples.
 - Raw `gh` fallback when the script is missing or broken:
-
-```bash
-gh issue view 123 --comments
-```
-
-- Use `--repo <owner>/<repo>` when targeting a different repository.
+- `gh issue view 123 --comments`
 - Use the returned title, body, labels, assignees, state, timestamps, and comments to summarize the issue precisely.
 
 ### 4) Summarize gaps before any follow-up action
@@ -78,18 +50,6 @@ gh issue view 123 --comments
 - Identify missing acceptance criteria, repro details, affected components, or environment context.
 - If issue text and comments are insufficient, state exactly what is missing instead of inventing a fix plan.
 
-## Included CLI
-
-### `apltk find-github-issues`
-
-- Purpose: consistent remote issue listing via `gh issue list`.
-- Outputs a readable table by default, or JSON with `--output json`.
-- Uses only GitHub CLI so it reflects remote GitHub state.
-- Treat it as a convenience wrapper, not a hard dependency.
-
-### `apltk read-github-issue`
+## CLI reference
 
-- Purpose: deterministic issue detail retrieval via `gh issue view`.
-- Outputs either a human-readable summary or full JSON for downstream automation.
-- Can include issue comments so the agent can read the latest discussion before taking any other step.
-- Treat it as a convenience wrapper, not a hard dependency.
+Use `apltk find-github-issues --help` and `apltk read-github-issue --help` as the authoritative command references. This skill keeps the retrieval workflow and fallback rules, not the flag catalog.