@laitszkin/apollo-toolkit 3.12.1 → 3.13.1

package/spec-to-project-html/SKILL.md

@@ -1,42 +0,0 @@
----
-name: spec-to-project-html
-description: >-
-  使用 `apltk architecture --spec <spec_dir>` 將專案 HTML 架構圖同步到活躍規劃文件。單個 spec 寫入 `<spec_dir>/architecture_diff/`，批量 spec 寫入 `coordination.md` 旁的共享 overlay；每個受影響功能由一個可寫子 agent 負責功能內 overlay 更新，主 agent 必須等待全部子 agent 完成後，才能補跨功能邊、渲染並驗證。基礎 atlas 不得被此技能修改。
----
-
-# 規劃文件同步到專案 HTML 架構圖
-
-## 技能目標
-
-根據 `docs/plans/...` 下的規劃文件，為專案架構圖生成或更新 spec overlay，使評審者能夠透過 `apltk architecture diff` 直接查看 proposed-after 架構變化，同時保持基礎 atlas 不被污染。
-
-## 驗收條件
-
-- 只透過 `apltk architecture --spec <spec_dir>` 寫入 overlay；單個 spec 產物位於 `<spec_dir>/architecture_diff/`，批量 spec 則寫入 `coordination.md` 同級的共享 overlay；不得手改 `architecture_diff/**/*.html`。
-- 讀取規劃文件時遵循 `spec.md` → `design.md` → `contract.md` → `coordination.md` 的順序；所有重要宣告都能同時回溯到 spec 語句和相關程式碼或設計證據。
-- 對於程式碼尚未實作、但規劃中已經提出的結構，必須顯式使用 `planned`、`gap` 或 `TBD` 標記，而不能偽裝成已落地實作。
-- 按「每個受影響功能一個可寫子 agent」執行 overlay 更新；主 agent 必須等全部子 agent 完成後，才允許補跨功能邊、共享 `meta` 或共享 `actor`。
-- `apltk architecture validate --spec <spec_dir>` 通過，且 `apltk architecture diff` 中的頁面配對正確，沒有懸空邊、孤兒頁面或錯誤的 add/remove 配對。
-
-## 工作流程
-
-1. 先定位本次規劃目錄；使用者明確給出路徑時優先使用，否則結合 `coordination.md` 找到正確 plan 集，並整理相關需求編號用於追蹤。
-2. 執行 `apltk architecture --help` 取得最新命令形態，然後按 `spec.md`、`design.md`、`contract.md`、`coordination.md` 的順序讀取內容，確定哪些功能、子模組、邊、變數或錯誤語義會發生變化。
-3. 先只列出受影響功能，不要提前把所有原始碼塞進主 agent。除了直接變更的功能，也要納入跨功能邊另一端的功能，確保 overlay 中的跨邊界關係完整。
-4. 為每個受影響功能派發一個可寫子 agent。每個子 agent 只負責自己功能內的 overlay 寫入：子模組、函式、變數、資料流、錯誤，以及功能內邊；若規劃領先於程式碼，則在角色、用途或資料流文案中明確標註 `planned`、`gap` 或 `TBD`。
-5. 子 agent 只返回功能內變更摘要、跨功能邊界變化和待記錄的 `planned/gap` 標記；主 agent 不得重讀已委派功能原始碼，也不得重複寫功能內元件。
-6. 等全部子 agent 完成後，主 agent 統一補跨功能 `edge`、必要的共享 `meta` / `actor`，再執行 `apltk architecture validate --spec <spec_dir>`，並透過 `apltk architecture diff` 檢查 overlay 頁面是否正確映射到 before/after 視圖。
-7. 最終報告至少包含：觸及的 overlay 檔案或 CLI 變更類別、`modified` / `added` / `removed` 數量、所有子 agent 已完成後才開始跨功能連線的確認、未解決的 spec 與程式碼差距，以及後續跟進行動。
-
-## 使用範例
-
-- 「把這份新 spec 的架構變化渲染成 before/after HTML 對照。」 -> 「讀取 plan 集，按受影響功能分派子 agent，寫入 `architecture_diff/` overlay，並用 `apltk architecture diff` 驗證。」
-- 「批量規劃下多個 spec 共用一份架構 overlay。」 -> 「仍以成員 spec 路徑呼叫 `--spec`，但讓 CLI 自動彙總到 `coordination.md` 同級的共享 overlay 根目錄。」
-
-## 參考資料索引
-
-- `init-project-html/SKILL.md`：基礎語義規則、邊類型與子模組表達約束。
-- `references/TEMPLATE_SPEC.md`：overlay 模式下的欄位、列舉與 diff 配對規則速查表。
-
-- `generate-spec`、`implement-specs*`：需求編號和規劃流程的上游來源。
-- `apltk architecture --help`：`--spec` 模式命令與參數的唯一真源。

package/spec-to-project-html/agents/openai.yaml

@@ -1,11 +0,0 @@
-interface:
-  display_name: "spec-to-project-html"
-  short_description: "Sync the project HTML architecture atlas with active planning specs via `apltk architecture --spec`"
-  default_prompt: >-
-    Use $spec-to-project-html. Read docs/plans (spec → design → contract). Every overlay mutation: `apltk architecture --spec <spec_dir> …`. **Exact commands: `apltk architecture --help`** — do not trust long command lists in docs.
-    Single specs write `<spec_dir>/architecture_diff/atlas/*.yaml` + affected HTML under `<spec_dir>/architecture_diff/`. Batch member paths resolve to the shared batch-root `architecture_diff/` beside `coordination.md`, so one batch keeps one overlay + one rendered diff. Base `resources/project-architecture/` is read-only here. NEVER hand-edit `architecture_diff/**`.
-    **`apltk architecture diff`** builds a paginated viewer: scans all `docs/plans/**/architecture_diff/`, pairs overlay paths with base atlas HTML by relative path, labels modified/added/removed — use it to verify the architecture delta before hand-off.
-    **Subagents only:** dispatch ONE write-capable subagent per AFFECTED feature; each applies ALL intra-feature overlay mutations (`submodule`/`function`/`variable`/`dataflow`/`error`/`edge` within that feature). Each returns ONLY change summary + outbound boundary deltas for OTHER features.
-    **HARD GATE:** main agent MUST wait until ALL subagents finish before ANY cross-feature `edge add|remove`, overlay `meta` that stitches multiple features, or shared `actor` for cross-feature context. Then `render --spec`, `validate --spec`.
-    Sub-module pages stay self-only — cross-boundary = `edge`. For removals/renames in overlay, follow SKILL.md (`submodule remove` / remove+add pattern) so `diff` classifies correctly.
-    After work: `validate --spec` MUST be OK; run `diff` and report modified/added/removed counts. Semantic rules: $init-project-html SKILL.md.

package/spec-to-project-html/references/TEMPLATE_SPEC.md

@@ -1,113 +0,0 @@
-# Atlas component schema — reference cheat sheet (spec-to-project-html copy)
-
-> Reference material only. The binding rules (read strategy, evidence requirements, what each verb means) live in `init-project-html/SKILL.md` (atlas authority) and this skill's `SKILL.md` (spec-overlay variant). This file lists the exact fields and enum values that `apltk architecture --spec <spec_dir>` accepts; the renderer produces consistent DOM/CSS/ARIA hooks under `<spec_dir>/architecture_diff/` so agents never need to touch HTML.
-
-## State files on disk
-
-Base atlas (read-only from this skill's perspective):
-
-```
-<project>/resources/project-architecture/atlas/
-├── atlas.index.yaml
-├── features/<slug>.yaml
-├── atlas.history.log
-└── atlas.history.undo.json
-```
-
-Overlay (where this skill writes via `--spec`):
-
-```
-<spec_dir>/architecture_diff/
-├── atlas/
-│   ├── atlas.index.yaml          # optional partial override (meta / actors / cross-feature edges / feature order)
-│   ├── features/<slug>.yaml      # full proposed state of any changed feature
-│   ├── _removed.yaml             # {features: [...], submodules: [{feature, submodule}]}
-│   ├── atlas.history.log
-│   └── atlas.history.undo.json
-├── index.html                    # rendered (re-emit only when macro visibly changes)
-├── features/<slug>/index.html    # rendered (re-emit when the feature page would visibly change)
-├── features/<slug>/<sub>.html    # rendered (re-emit when the sub-module's tables/dataflow change)
-├── _removed.txt                  # auto-written by the renderer; lists removed HTML paths
-└── assets/                       # architecture.css + viewer.client.js (copied by the renderer)
-```
-
-## Components (mirrors `init-project-html/references/TEMPLATE_SPEC.md`)
-
-### `meta`
-
-| Field   | Type   | Required | Notes |
-| ------- | ------ | -------- | ----- |
-| title   | string | yes      | Macro page H1; the spec overlay typically keeps the base title. |
-| summary | string | no       | Update if the spec changes scanned roots or known omissions. |
-
-CLI: `apltk architecture meta set --spec <spec_dir> --title "..." --summary "..."`
-
-### `actor`
-
-| Field | Type | Required | Notes |
-| ----- | ---- | -------- | ----- |
-| id    | kebab-case | yes | Stable identity. |
-| label | string | yes | Display name. |
-
-CLI: `apltk architecture actor add --spec <spec_dir> --id ... --label "..."`
-
-### `feature`
-
-Same shape as base mode (`slug`, `title`, `story`, `dependsOn`, `submodules`, `edges`). `submodule add|remove`, `function add|remove`, etc. mutate the feature's full overlay snapshot under the hood — declare what you would have declared in base mode, but pass `--spec <spec_dir>`.
-
-CLI: `apltk architecture feature add --spec <spec_dir> --slug <kebab> --title "..." --story "..."`
-
-### `submodule`
-
-| Field | Type | Required | Notes |
-| ----- | ---- | -------- | ----- |
-| slug  | kebab-case | yes | The HTML filename. |
-| kind  | enum `ui` `api` `service` `db` `pure-fn` `queue` `external` | yes | Drives node colour + chip. |
-| role  | string | no | Own responsibility in one sentence. Use `planned: ...` or `gap: ...` to mark spec items the code does not yet implement. |
-| functions / variables / dataflow / errors | arrays | no | Edited through their own CLI verbs. |
-
-CLI: `apltk architecture submodule add|set|remove --spec <spec_dir> --feature X --slug Y --kind ... --role "..."`
-
-### `function`, `variable`, `dataflow`, `error`
-
-Each row uses the same fields documented in `init-project-html/references/TEMPLATE_SPEC.md`. Always pass `--spec <spec_dir>` so the write lands in the overlay.
-
-`dataflow` steps accept the same structured fields in overlay mode — `--fn` must reference a function declared in this overlay (or inherited from base) for the same sub-module; `--reads` / `--writes` must reference variables declared there. `validate --spec <spec_dir>` enforces these references against the **merged** state, so adding a step that names a function/variable the spec also introduces is fine as long as both land in the same overlay.
-
-### `edge`
-
-| Field | Type | Required | Notes |
-| ----- | ---- | -------- | ----- |
-| id    | kebab-case | recommended | Pass `--id <stable>` when adding or removing so the CLI matches unambiguously. |
-| from  | `feature/submodule` or (intra-feature) `submodule` | yes | |
-| to    | same shape | yes | |
-| kind  | enum `call` `return` `data-row` `failure` | yes | |
-| label | string | no | |
-
-CLI: `apltk architecture edge add|remove --spec <spec_dir> --from <feature>[/sub] --to <feature>[/sub] --kind ... --label "..."`
-
-## Diff classification (how `apltk architecture diff` pairs pages)
-
-`apltk architecture diff` scans every `docs/plans/**/architecture_diff/**/*.html` (skipping `assets/` and `atlas/`) and pairs by path against `resources/project-architecture/`:
-
-| Base exists? | Overlay HTML exists? | Listed in `_removed.txt`? | Classification |
-| ------------ | -------------------- | ------------------------- | -------------- |
-| yes          | yes                  | no                        | **modified** (split before/after view) |
-| no           | yes                  | no                        | **added** (single after view) |
-| yes          | no                   | yes                       | **removed** (single before view) |
-
-The renderer writes `_removed.txt` automatically from `_removed.yaml`; agents only set the YAML through `feature remove` / `submodule remove`.
-
-## Quick example: add a 2FA sub-module to an existing feature
-
-```bash
-apltk architecture --spec docs/plans/2026-05-11/add-2fa \
-  submodule add --feature register --slug 2fa --kind service \
-  --role "TOTP verification (planned: not yet implemented)"
-apltk architecture --spec docs/plans/2026-05-11/add-2fa \
-  edge add --from register/api --to register/2fa --kind call --label "verify TOTP" --id e-api-2fa
-apltk architecture --spec docs/plans/2026-05-11/add-2fa validate
-apltk architecture diff
-```
-
-The CLI writes only the affected HTML pages (`features/register/2fa.html` plus any page whose visible state changed) into `architecture_diff/`, and the diff viewer pairs them with the base atlas.

package/submission-readiness-check/SKILL.md

@@ -1,39 +0,0 @@
----
-name: submission-readiness-check
-description: >-
-  用於在 commit、push、PR 或 release 前做最後同步檢查。會確認 `CHANGELOG.md`、
-  專案文件、`AGENTS.md` / `CLAUDE.md` 與已完成的 planning artifacts 是否都已更新到可提交狀態。
----
-
-## 目標
-
-在任何提交、推送、開 PR 或發版前，先把 repository 的外部說明、內部約束與 planning artifacts 同步到一致狀態，避免把未整理完成的變更交給下一個提交流程。
-
-## 驗收條件
-
-- 已盤點真實的提交面，包括 git 狀態、staged diff、現有 docs、planning artifacts 與目標提交流程
-- 當 spec 已完成且應轉成長期文件時，已先完成 `archive-specs`，而不是把它留給後續流程猜測處理
-- `docs/`、`AGENTS.md` / `CLAUDE.md` 與必要的 `README.md` 已根據實際行為與工作流程同步
-- `CHANGELOG.md` 的 `Unreleased` 區塊已準確對應這次將提交、開 PR 或發版的真實範圍
-- 最終輸出的是明確的 ready / blocking verdict，而不是模糊警告
-
-## 工作流程
-
-1. 先讀取 git 狀態、staged / unstaged diff，並盤點 repo 是否有 `CHANGELOG.md`、`AGENTS.md`、`CLAUDE.md`、標準化 `docs/` 結構，以及任何 `docs/plans/...` 計劃集
-2. 判斷下游流程屬於 `commit-push`、`pull-request` 或 `release`，因為不同流程對 changelog 與發版資料的要求不同
-3. 檢查 planning artifacts 是否應轉檔；只要 plan set 已對應本次交付成果，或專案文件仍未標準化，就必須先跑 `archive-specs`
-4. 在 spec 歸檔判斷完成後，同步專案文件；必要時執行 `align-project-documents` 更新 `docs/`，再用 `maintain-project-constraints` 更新 `AGENTS.md` / `CLAUDE.md`
-5. 檢查 `CHANGELOG.md`：對 commit / PR 流程，要讓 `Unreleased` 精準反映這次待提交內容，同時保留其他未出貨工作；對 release 流程，`Unreleased` 必須非空且已整理成可直接切版的 release notes
-6. 彙整哪些項目已同步、哪些仍阻塞；若還有未完成的 gate，明確回報 blocking item，而不是把責任留給下一個技能
-
-## 範例
-
-- 「準備提交這批變更」-> 檢查是否有未同步 changelog、文件與已完成但尚未歸檔的 spec
-- 「準備開 PR」-> 確保 `Unreleased` 反映當前 PR 範圍，並把 `AGENTS.md` / `CLAUDE.md` 與 docs 同步好
-- 「準備發版」-> 確保 `Unreleased` 非空且可直接作為 release notes，並先完成任何必要的 spec 歸檔與文件標準化
-
-## 參考資料
-
-- `align-project-documents`：同步 `docs/features/`、`docs/architecture/`、`docs/principles/`
-- `maintain-project-constraints`：同步 `AGENTS.md` / `CLAUDE.md`
-- `archive-specs`：在符合條件時轉檔並歸檔 planning artifacts

package/submission-readiness-check/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Submission Readiness"
-  short_description: "Sync changelog and docs before submit"
-  default_prompt: "Use $submission-readiness-check to prepare repository docs, changelog, and plan archives before commit, push, or release."