@laitszkin/apollo-toolkit 3.11.8 → 3.12.1

package/init-project-html/SKILL.md

@@ -1,130 +1,40 @@
 ---
 name: init-project-html
 description: >-
-  Declare the project HTML architecture atlas through `apltk architecture` instead of hand-writing SVG/HTML. Two acceptance criteria gate completion: (1) the macro diagram clearly shows feature × sub-module relationships — data flow, call/return interaction logic, error handling, rollback — all expressed as cross-sub-module edges with kinds `call`, `return`, `data-row`, and `failure`; (2) each sub-module’s internal diagram shows function-level flow (`dataflow` steps may reference a declared function plus `reads`/`writes` of declared variables). The tool owns layout, CSS, pan/zoom, and validation. **Subagents only:** one write-capable subagent per feature declares every intra-feature change; the main agent **waits until all subagents finish**, then wires **only** cross-feature seams. **Exact CLI spelling:** always `apltk architecture --help` — never treat prose in this file as the command list. Anchor every declaration to repo evidence.
+  使用 `apltk architecture` 初始化專案 HTML 架構圖譜，生成基礎 atlas YAML 與渲染後的 HTML 頁面。所有宣告基於倉庫證據；每個功能模組由一個可寫子 agent 負責，主 agent 必須等待全部子 agent 完成後，才能補跨功能連接並執行 render 與 validate。
 ---
 
-# Init Project HTML
+## 技能目標
 
-## Dependencies
+透過 `apltk architecture` 為目前倉庫建立基礎專案架構圖譜，產出受 CLI 管理的 atlas 狀態檔與渲染後的 HTML 頁面。
 
-- Required: none (the CLI ships its own layout engine, CSS, and pan/zoom client; `apltk architecture` is installed with this toolkit).
-- Conditional: `spec-to-project-html` when the same atlas needs spec-driven refresh — that skill uses the same CLI with `--spec`.
-- Optional: `align-project-documents` when `docs/features` already names the user-visible capabilities.
-- Fallback: codebase too large for one pass → use the **subagent** strategy below; document scanned roots and explicit omissions in `meta.summary`. **MUST NOT** declare components for code paths that were never read.
+## 驗收條件
 
-## Non-negotiables
+- 只透過 `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` 通過。
 
-### Rule 1 — Use the CLI; never hand-author atlas HTML
+## 工作流程
 
-The atlas state lives in `resources/project-architecture/atlas/` (`atlas.index.yaml` + per-feature YAMLs). Every change goes through the CLI (exact verbs/flags: **`apltk architecture --help`**). After any mutation, the CLI re-renders `resources/project-architecture/**/*.html` with the correct layout, CSS, pan/zoom, and ARIA — agents **MUST NOT** edit those HTML files by hand or invent additional ones.
+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. 抽查渲染結果，確認宏觀圖和至少一個代表性子模組頁滿足驗收條件，彙報功能數、子模組數、邊數量、未覆蓋路徑與原因。
 
-### Rule 2 — Sub-module pages describe only themselves; the internal-dataflow diagram is zoomable and structurally typed
+## 使用範例
 
-What the CLI emits on each sub-module page is fixed in *role* (not in exact flag names — those live in `--help`):
+- 「替這個倉庫首次生成 HTML 架構圖」→ 梳理功能模組，按功能分派子 agent，彙總跨功能邊，生成基礎 atlas 與渲染頁面。交付物為 `resources/project-architecture/` 下的完整 atlas 狀態檔與通過驗證的 HTML 頁面。
+- 「把系統的資料流、呼叫關係和回滾路徑視覺化」→ 使用 `call` / `return` / `data-row` / `failure` 邊表達跨邊界關係，為每個關鍵子模組補齊內部 `dataflow`。
 
-- **Function I/O table** — one row per declared function/side-effect entry point.
-- **Variables table** — business-purpose identifiers (`scope` enum and `purpose` text).
-- **Internal dataflow** — ordered steps inside a pan/zoom viewport (+/−/Fit), same interaction model as the macro SVG. Steps may attach a declared function name and comma-separated read/write variable names; the renderer shows them as a function pill and read/write chips so **function-to-function flow** and **variable state** are visible in one diagram.
-- **Local errors** — symbolic error rows (`when` / `means`).
+## 參考資料索引
 
-**Structural constraints** (enforced by `validate`):
-
-- Any function name referenced from a dataflow step must already exist on **that** sub-module (`function` row).
-- Any variable name in reads/writes must already exist on **that** sub-module (`variable` row).
-- Purely descriptive steps without fn/reads/writes are allowed, but non-trivial sub-modules **MUST** fill the structure so the diagram is not hollow.
-
-Cross-boundary narratives (“I call X”, “Y calls me”) **MUST** be **edges** between `feature/submodule` endpoints with a `kind` of `call`, `return`, `data-row`, or `failure` — never as extra prose on a sub-module page. There is no CLI path to smuggle cross-boundary text onto sub-module pages.
-
-### Rule 3 — Read order: subagents only; wait for all workers before cross-feature wiring
-
-Real production codebases dwarf the main agent’s context. **MUST** use this pattern only:
-
-1. Enumerate the **feature-module list** (slug + entry + boundary resources only) — **no** function-body deep reads at this stage.
-2. Dispatch **one write-capable subagent per feature** (every feature in scope that needs atlas work). Each subagent:
-   - deep-reads **only** its feature;
-   - declares **everything intra-feature** via `apltk architecture` scoped with `--feature <slug>` where the CLI allows (exact scoping flags: **`--help`**): sub-modules, per-sub-module functions / variables / ordered dataflow / errors, and **every intra-feature edge** (calls, returns, data-rows, failures, rollback/compensation **between sub-modules of the same feature**);
-   - returns **ONLY** a structured summary of (i) sub-module list (slug + kind + one-line role) and (ii) **outbound boundaries** the orchestrator must wire later (calls / data-rows / failures **to other features’** sub-modules — direction, endpoints, suggested kind/label).
-
-3. **Gate — all subagents complete:** The main agent **MUST NOT** declare any **cross-feature** `edge`, shared `meta` that encodes multi-feature narrative, nor any `actor` that exists only to stitch features together, **until every dispatched subagent has finished** (success **or** an explicit failure report). Partial summaries are for note-taking only — **not** for mutating cross-feature atlas state.
-
-4. After the gate: the main agent aggregates outbound boundary notes, declares **only** cross-feature edges (and optional shared `meta` / `actor` if needed), then runs **`apltk architecture render`** (if batched with `--no-render`) and **`apltk architecture validate`**.
-
-The main agent **MUST NOT** re-read source for a delegated feature and **MUST NOT** re-declare intra-feature components a subagent already owns.
-
-### Rule 4 — Evidence over invention
-
-- **MUST** anchor every declared feature, sub-module, function, variable, dataflow step, and edge to a concrete path / symbol / SQL / config; record scanned roots and any deliberate omissions in `meta.summary` via the CLI (`meta` verbs — flags: **`--help`**).
-- **MUST NOT** invent modules, integrations, or sub-modules just because the diagram “looks balanced”. Empty rows are valid; lies are not.
-
-## Standards (summary)
-
-- **Evidence**: every CLI declaration traces to a path/symbol/SQL/config; uncertain areas surface as `TBD` strings or are omitted with a recorded reason.
-- **Execution**: shallow feature-module list → subagent fan-out per feature → **wait for all** → cross-feature edges / meta → `validate` → handover.
-- **Quality**: macro SVG carries every cross-feature data-row edge that exists in the system; sub-module declarations are self-only; pan/zoom + Fit work in the rendered HTML; `apltk architecture validate` returns OK.
-- **Output**: `resources/project-architecture/atlas/` (YAML state) + `resources/project-architecture/**/*.html` (renderer output) — both managed by the CLI.
-
-## Acceptance criteria
-
-The atlas is only complete when both of the following are demonstrably true on the rendered HTML (open `resources/project-architecture/index.html` and one representative sub-module page to verify):
-
-1. **Macro diagram clearly shows the relationships between features and sub-modules**, including:
-   - **Data flow** — every cross-feature DB row, queue topic, or cache key hand-off is a `data-row` **edge** between producing and consuming sub-modules (not free-form prose).
-   - **Interaction logic** — synchronous request/response paths use paired **`call`** (outbound) and **`return`** edges with a label that names the call site or response shape.
-   - **Error handling and rollback** — every failure / compensation / retry path that crosses a sub-module boundary is a **`failure`** edge with a label that names what is rolled back or compensated.
-   - No cross-boundary interaction exists **only** in sub-module page prose — it **MUST** appear as an edge on the macro SVG.
-2. **Each sub-module’s internal diagram clearly shows the function-level interactions inside the sub-module**, including:
-   - **Function-to-function flow** — non-trivial steps reference a declared function on that sub-module.
-   - **Variable state transitions** — variables read or written by a step are declared first, then referenced on the step; reading top-to-bottom traces lifecycle.
-   - **Local data flow** — ordered steps read as a directed flowchart to the sub-module boundary.
-
-`apltk architecture validate` **MUST** return OK before reporting completion.
-
-## CLI reference
-
-Run **`apltk architecture --help`** and the deeper `apltk architecture <verb> [subverb] --help` pages for the authoritative command tree, required flags, examples, and expected results. This skill keeps only the semantic rules, acceptance criteria, and subagent coordination rules so the documentation does not drift when the CLI evolves.
-
-**Cross-feature work timing:** only after **all** feature subagents have returned (Rule 3).
-
-## Workflow
-
-### 1) Whole-repo inventory — list feature modules, not function bodies
-
-Scan the shipped source for **user-visible capabilities** (each one = one feature module): entry routes, CLI commands, UI pages, cron jobs, runners, event handlers, CDC streams. Record only kebab-case slug + one-line user story + boundary points (entry symbol, outbound DB tables / queue topics / external services).
-
-- **Pause →** Is the list actually complete? Note skipped roots with reason; no silent skips.
-- **Pause →** Did I dive into function bodies here? Roll back — keep only structural notes.
-
-### 2) Subagent fan-out — workers own features; orchestrator owns cross-feature seams **after** all workers finish
-
-Dispatch one **write-capable** subagent per feature. Hand each subagent: its feature slug, the feature-module list from step 1 (so it knows other features’ slugs for outbound edges), and **`apltk architecture --help`** as the flag reference.
-
-> **Feature `<slug>` subagent contract**
-> - Read every sub-module of this feature.
-> - Declare the feature and its sub-modules (`feature` / `submodule` — exact flags: **`--help`**).
-> - For every sub-module: add **function**, **variable**, ordered **dataflow**, and **error** rows as needed.
-> - For every intra-feature interaction between sub-modules, add an **edge** whose endpoints stay **inside** this feature.
-> - Run **`apltk architecture validate`** before returning (same project root; use **`--help`** for project/spec flags).
-> - **Return ONLY**: (i) sub-module list (slug + kind + one-line role), (ii) outbound boundaries to *other* features’ sub-modules (direction + edge kind + suggested label). No source dumps.
-
-**Orchestrator — after every subagent has completed:** declare only the cross-feature `apltk architecture` mutations reported by the workers, then render and validate once.
-
-The main agent **MUST NOT** re-declare a subagent’s intra-feature components, and **MUST NOT** open source files for any feature it delegated.
-
-### 3) Handover report
-
-Report: feature count, sub-module count, macro edge counts (call / return / data-row / failure), uncovered paths + reasons, confirmation that **all subagents completed before cross-feature wiring**, and the location of the rendered atlas (`resources/project-architecture/index.html`).
-
-## Sample hints
-
-- Multiple SQL paths on `service ↔ db` → one **`edge`** per SQL path so the macro shows distinct strokes.
-- Retry loops between `service ↔ generator(pure)` → **`call` / `return`** pair on the macro plus ordered **`dataflow`** steps on the service that show retry budget and persistence.
-- Cross-feature DB hand-off (A writes, B reads) → both sides declare DB-oriented functions, then a **`data-row`** edge from producer to consumer.
-- Rollback / compensation across sub-modules → **`failure`** edge with an explicit label; cleanup *inside* a single sub-module belongs in ordered **`dataflow`** steps.
-- Third-party systems → **`external`** kind sub-modules so the trust boundary is visible in styling.
-
-## References
-
-- `lib/atlas/schema.js` — fields, enums, validation. `references/TEMPLATE_SPEC.md` mirrors the schema as a cheat sheet (not a substitute for **`apltk architecture --help`**).
-- `lib/atlas/cli.js` — implementation of dispatch (`apltk architecture --help` prints usage).
-- `init-project-html/sample-demo/` — end-to-end YAML + rendered HTML for two features.
+- `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 的增量刷新版本。

package/iterative-code-performance/SKILL.md

@@ -19,7 +19,7 @@ description: >-
 
 - Required: `align-project-documents` and `maintain-project-constraints` after the repository is truly iteration-complete.
 - Conditional: `systematic-debug` when a performance test, benchmark, load run, or production trace exposes a real business-logic defect that must be fixed at the true owner; `improve-observability` when profiling signals are missing or measurement requires durable logs, metrics, or traces.
-- Optional: `discover-edge-cases` for high-risk boundary, concurrency, cache-invalidation, or load-shape exploration before changing hot paths.
+- Optional: `improve-observability` for profiling signals or durable metrics needed during optimization.
 - Fallback: If required completion dependencies are unavailable, finish performance work and validation first, then report exactly which documentation, constraint-sync, or observability action could not run.
 
 ## Standards

package/iterative-code-quality/SKILL.md

@@ -18,7 +18,7 @@ description: >-
 
 - Required: `align-project-documents` and `maintain-project-constraints` after the repository is truly iteration-complete.
 - Conditional: `systematic-debug` when a newly added or existing test exposes a real business-logic defect that must be fixed at the true owner.
-- Optional: `discover-edge-cases` for high-risk boundary exploration before adding tests; `improve-observability` for non-trivial telemetry design.
+- Optional: `improve-observability` for non-trivial telemetry design.
 - Fallback: If required completion dependencies are unavailable, finish code and validation first, then report exactly which documentation or constraint-sync action could not run.
 
 ## Standards

package/maintain-project-constraints/SKILL.md

@@ -1,93 +1,35 @@
 ---
 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
+基於當前倉庫證據，產出或刷新根目錄 `AGENTS.md` 與 `CLAUDE.md`，使其準確反映開發命令、專案商業目標與文件索引，不捏造任何內容。
 
-- Required: none.
-- Conditional: none.
-- Optional: none.
-- Fallback: not applicable.
+## 驗收條件
 
-## Non-negotiables
+- 最終文件正文只包含三個區塊，順序固定：`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` 同時存在且未聲明故意分歧，兩者三個區塊內容一致。
 
-- **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).
+## 工作流程
 
-## Standards (summary)
+1. 從倉庫現況收集可驗證的命令入口、專案目的與現有文件清單，不以舊約束文件作為唯一真相。
+2. 根據證據生成三個必需區塊，確保每條命令、商業目標與文件索引可被直接追溯。
+3. 按專案慣例更新或補齊 `AGENTS.md` / `CLAUDE.md`，正文限制在三個規定區塊內。
+4. 完成前逐項校驗命令來源、文件路徑與雙文件一致性，清除所有陳舊或多餘內容。
 
-- **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.
+## 使用範例
 
-## Triggers
+- 「重建 `docs/` 後，請同步刷新 `AGENTS.md` 和 `CLAUDE.md`」→ 根據當前腳本、入口與文件樹重寫兩個根目錄約束文件，只保留三個規定區塊並確保索引完整。
+- 「這個專案的 `CLAUDE.md` 已經過時，請補一份對應的 `AGENTS.md`」→ 依據現有命令與文件結構建立缺失文件，讓兩份約束文件在預期一致時保持同構。
+- 「請清理根目錄約束文件裡的舊命令與失效路徑」→ 驗證每條命令與索引路徑是否仍成立，只保留能被倉庫證據支持的內容。
 
-- Missing `AGENTS.md`/`CLAUDE.md`, post-change drift suspected, or after `align-project-documents` reshapes `docs/`.
+## 參考資料索引
 
-## 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,40 @@
 ---
 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
+## 技能目標
 
-## Dependencies
+在工作開始時的當前本地分支上，整合使用者指定的本地分支（或由 spec / batch 規劃可無歧義對應出的分支），完成合併、驗證、清理，並讓整合結果可安全交由 `commit-and-push` 收尾。
 
-- 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.
+## 驗收條件
 
-## Non-negotiables
+- 所有合併變更落在流程開始時的原始當前分支，不會未經允許改換目標分支。
+- 合併範圍只包含使用者明確指定，或可由 `coordination.md` / spec 無歧義映射出的分支；若映射不清楚則停止並回報。
+- 當 batch 規劃存在 `Merge order` / landing order 時，實際整合順序與規劃一致；順序衝突或不明確時不猜測執行。
+- 所有衝突以保留正確行為為原則解決，並在刪除來源分支或交給 `commit-and-push` 前完成驗證。
+- 只清理已成功合併且已驗證的來源分支或 worktree；不強制刪除尚未真正合入的來源。
+- 最終交付是原始當前分支上的整合結果與簡潔摘要；只有使用者於本次對話明確要求時才推送遠端。本技能不單獨執行 `archive-specs`。
 
-- **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.
+## 工作流程
 
-## Standards (summary)
+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` 還是包含遠端推送。
 
-- **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.
+## 使用範例
 
-## Workflow
+- 「把 `feature/api-layer` 和 `feature/cli-wrapper` 合回目前分支」→ 以目前分支為唯一目標，依指定順序完成整合、驗證與安全清理，再交給 `commit-and-push` 做本地提交。
+- 「根據 batch 的 `coordination.md` 把各 worktree 分支合回來，但先不要 push」→ 從 batch 規劃確認無歧義分支映射與 landing order，依序合併、驗證、清理，只做到本地提交。
+- 「把那幾個應該相關的分支一起合一下」→ 若無法從使用者輸入或規劃文件明確判定分支集合與順序，停止並回報需要補充資訊。
 
-**Chain-of-thought:** Before each numbered step, answer the **`Pause →`** prompts. Validator or verification red **blocks** advancing to pruning or **`commit-and-push`**.
+## 參考資料索引
 
-### 1) Inventory the current branch and in-scope named branches
-
-- 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-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.

package/optimise-skill/SKILL.md

@@ -12,23 +12,23 @@ description: Use prompt engineering to optimise agent skill. Use it when you nee
 
 ## 工作流程
 
-1. 識別交付物
+### 1. 識別交付物
 完整閱讀整個技能的 `SKILL.md` 文檔，以及其引用的所有額檔案，包括但不限於 `references/` , `scripts/` 。基於獲取到的技能上下文資訊，總結出該技能的最終交付產物。
 
-2. 制定驗收條件
+### 2. 制定驗收條件
 制定驗收條件，從而確保LLM能夠穩定、可復現地按照驗收條件產出符合要求高質量最終交付物
 
-3. 重寫技能
+### 3. 重寫技能
 將整個技能的 `SKILL.md` 重寫。重寫後的技能應該只包含以下幾個關鍵組成部分：
-- 技能目標
-- 技能驗收條件
-- 技能工作流程
-- 技能使用範例
-- 技能參考資料索引
+- 目標
+- 驗收條件
+- 工作流程
+- 範例
+- 參考資料
 對於技能有幫助的內但不符合上述技能架構規範，則應該被分類放置在 `references/` 下的markdown檔案。
 
 ## 範例
-- "一個專注在提示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,20 @@
 **建議實踐**：
 - "按照本次變更的實際內容，創建符合通用開發規範的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在調用工作流程自行工作的時候對目標有著清晰的認知，從而避免在執行時成為無頭蒼蠅並在上下文之中迷失。
+並非所有技能都需要範例。只有非常複雜的任務需要通過範例提示來確保 agent 理解工作流程。
 
 **建議實踐**：
 用一個用於優化提示詞技能的技能作為示例：
-- "一個專注在提示LLM agent進行自我迭代，並為代碼庫帶來性能優化的技能需要被優化" -> "定義驗收條件為優化後性能相較優化前至少提升X個百分比，並且項目之中不存在任何O(n^2)級別時間複雜度的函式和邏輯，並按照標準架構重寫技能。"
+- "一個專注在提示LLM agent進行自我迭代，並為repo帶來性能優化的技能需要被優化" -> "定義驗收條件為優化後性能相較優化前至少提升X個百分比，並且項目之中不存在任何O(n^2)級別時間複雜度的函式和邏輯，並按照標準架構重寫技能。"
 - "一個有大量前端開發範例被包含在 `SKILL.md` 之中的前端開發技能需要被優化" -> "定義驗收條件為前端頁面 `reference` 之中提供的大量建議範例重寫且不包含任何建議示例之中明確拒絕的設計，然後按照技能優化流程對技能進行全面的重寫。"
 
 **錯誤實踐**：