@laitszkin/apollo-toolkit 3.11.8 → 3.12.0

package/implement-specs-with-worktree/SKILL.md

@@ -1,84 +1,60 @@
 ---
 name: implement-specs-with-worktree
-description: >-
-  Like **`implement-specs`** (same read order, full `tasks.md`/`checklist.md`, sequential multi-spec per `coordination.md`) but all writes in a dedicated worktree+feature branch; `pwd` must match `git rev-parse --show-toplevel`; parent checkout read-only for deliverables; honor `preparation.md` and `coordination.md` collision rules. Use when isolation is required; otherwise **`implement-specs`**.
+description: 當你需要在獨立分支和工作樹之中實作spec時，使用這個技能。
 ---
 
-# Implement Specs with Worktree
+## 技能目標
 
-## Dependencies
+在獨立分支及工作樹實作用戶指定的spec。確保所有任務都被完成，用戶所有需求都被滿足。
 
-- Required: `implement-specs` for the shared discovery / implementation / backfill / **submit** / reporting lifecycle; **`commit-and-push`** for the **final** implementation commit (and push when the user explicitly requests remote update).
-- Conditional: `generate-spec` if spec files need clarification or updates.
-- Fallback: If any required dependency skill is unavailable, **MUST** stop and report it.
+## 驗收條件
 
-## Non-negotiables
+- 在所有被用戶要求實作的spec之中，所有的 `checklist.md`, `tasks.md`, `spec.md` 當中所有非用戶填寫的任務相關checkboxes全部被勾選為完成狀態
 
-- **MUST** perform every write (product code, tests, and spec-document backfill) inside the active worktree: after each `cd`, **MUST** confirm `pwd` equals `git rev-parse --show-toplevel` for that worktree before editing.
-- **MUST NOT** edit implementation files from the parent checkout except for creating or listing worktrees and read-only inspection; the parent checkout is write-prohibited for this spec’s deliverables.
-- **MUST** follow the **`implement-specs` Workflow** for discovery, implementation, backfill, commit discipline, and completion reporting—**except** that branch/worktree restrictions in `implement-specs` Non-negotiables are replaced by this skill’s worktree rules.
-- **MUST** create the implementation branch from the **same parent branch** the user/session identified as the baseline (often the branch that will receive the merge—not necessarily `main` unless that branch is verified as the base).
-- **MUST** use the spec directory name (`change_name`) as the canonical basename for the worktree path and branch stem; branch **`type`/name** must follow `references/branch-naming.md`.
-- **MUST** use `git show-ref` and `git worktree list --porcelain` (not shell guesses) when checking whether a branch or worktree already exists; if creation fails ambiguously, **MUST** re-query those commands before retrying.
-- When `preparation.md` exists: **MUST** treat it as an already-committed shared baseline for parallel work; **MUST NOT** redo its tasks inside the member spec unless the preparation commit is missing or the document states the prerequisite is still blocked. If baseline assumptions break, **MUST** update `preparation.md` or stop for coordination—**MUST NOT** silently move prerequisite work into the member spec.
-- **`tasks.md` completeness (hard stop)**: **MUST** satisfy the **`implement-specs` Non-negotiable** on **`tasks.md`**: execute **every** actionable line in the in-scope `tasks.md`, with **no** early exit for workload, duration, or breadth; partial task lists are **not** a mergeable or committable state. If a line cannot be met under contracts, **MUST** halt with evidence and resolve the plan through approved planning updates before claiming completion.
-- **`checklist.md` wrap-up / acceptance (hard stop for “spec complete”)**: **MUST** satisfy the **`implement-specs` Non-negotiable** on **`checklist.md`**: the spec is **not** **complete** and **must not** be merged or treated as finished until **all** checklist-defined wrap-up, acceptance, and closing obligations for the change are **done** and honestly recorded—**no** workload exemption.
-- **MUST** complete the same quality bar as `implement-specs`: on top of full `tasks.md` and **complete checklist wrap-up**, relevant tests, honest backfill, no sibling-spec scope creep, revert formatter-only noise outside owned files before commit.
-- **MUST NOT** `git push` **outside** **`commit-and-push`** unless the user explicitly requests remote update through that workflow (or a release/PR skill the user named).
-- For targeted Rust tests: **MUST** pass at most one positional `cargo test` filter per invocation; use separate commands or a broader confirmed filter when multiple selectors are needed.
+## 工作流程
 
-## Standards (summary)
+### 1. 定位實作範圍
 
-- **Evidence**: Read full spec set plus `coordination.md` and `preparation.md` when present; verify whether the spec is already implemented on the baseline before opening a new worktree; if the plan is missing in the worktree, sync the authoritative copy and re-read before coding.
-- **Execution**: Isolated worktree only; branch naming per `references/branch-naming.md`; check sibling worktrees before editing shared boundaries in a parallel batch.
-- **Quality**: Same as `implement-specs` (including **all** `tasks.md` items **and** **all** `checklist.md` wrap-up obligations—no workload excuse), plus collision awareness with sibling worktrees per `coordination.md`.
-- **Output**: Clean local branch in the worktree with intended commits only; parent working tree unchanged by this implementation.
+閱讀用戶指定的spec：
 
-## Workflow
+- `spec.md` 定義了用戶的需求
+- `tasks.md` 定義了詳細的實作任務
+- `checklist.md` 定義了任務的完成和驗收條件
+- `contract.md` 定義了spec的外部依賴
+- `design.md` 定義了相關業務鏈路的架構設計
+- `coordination.md`（如有）定義了batch spec之中各份spec各自的實作邊界
+- `preparation.md`（如有）定義了實作batch spec之前各spec的共用準備工作
 
-**Chain-of-thought:** Answer each **`Pause →`** question before leaving the phase; if any answer conflicts with Non-negotiables, fix state first (right directory, right root, right baseline).
+按照以上文件，閱讀repo，理解本次spec的實作範圍。
 
-### A) Specs and baseline
+### 2. 創建子分支及worktree
 
-- Run **`implement-specs` Workflow steps 1–2** in spirit: resolve paths, read all core files and `coordination.md`; run `git status` / `git worktree list` as needed. If the plan files are absent in the target worktree, sync them in, then re-read in that tree.
-- Read `preparation.md` when present; apply the Non-negotiable baseline rule above.
-  - **Pause →** Where will authoritative plan text live **for this session**—parent tree, worktree after sync—and have I opened that copy end-to-end?
-  - **Pause →** Does `coordination.md` / `preparation.md` imply **anything** I must not redo or must assume stable before coding?
+從當前分支創建子分支及worktree。分支以規格文檔的實際變更命名，並且需要符合通用開發規範(e.g. feat/event-bus-backend)
 
-### B) Worktree and branch
+### 3. 實作spec任務
 
-- If the requested scope is already implemented and verified on the baseline, **MUST** report `no-op` with evidence instead of creating duplicate work.
-- Otherwise: ensure the shell is in the correct worktree (create one if required):
-  - Derive `change_name`; branch pattern `<type>/<spec-name>` per `references/branch-naming.md`; worktree directory `../<spec-name>` (or an equivalent path the user approves).
-  - `git branch <branch-name> <parent-branch>` then `git worktree add <path> <branch-name>`; `cd` into it; verify `pwd` vs `git rev-parse --show-toplevel`.
-- Before editing shared modules in a batch, check `git worktree list --porcelain` and `coordination.md` for sibling ownership; read sibling diffs when the same file is touched.
-  - **Pause →** Why is **`parent-branch`** definitely the correct baseline—not an unexamined assumption that `main` is default?
-  - **Pause →** Could this work duplicate an **already-merged** implementation; what **evidence** (`git log`, tests, code search) did I use to rule that in or out?
-  - **Pause →** After `cd`, do `pwd` and `git rev-parse --show-toplevel` **match**; if not, why am I not stopping before any write?
-  - **Pause →** Which sibling worktree might already own the shared file I am about to touch, and did I inspect their diff?
+嚴格按照 `tasks.md` 之中定義的任務，逐項完成實作。如果有多份 `tasks.md` 存在於多份spec之中，則依照 `coordination.md` 之中建議的merge順序進行實作。
+在確認完成所有任務之後，將 `tasks.md` 之中的所有checkboxes勾選為完成。
 
-### C) Implement, backfill, commit, report
+如果實作的spec是batch spec，且有 `preparation.md`，在開始實作之前需要先完成 `preparation.md` 之中所規定的任務內容，並在驗收條件滿足之後回填 `preparation.md`。
 
-- Execute **`implement-specs` Workflow steps 3–6** (implement—including **full** `tasks.md` and checklist-backed work per Non-negotiables—backfill—including **complete** `checklist.md` wrap-up before submit—**submit via `commit-and-push`**, report) **entirely from the worktree root**, honoring the same **`spec.md` / `design.md` / `contract.md` / `checklist.md` / `tasks.md`** read-and-execute rules as **`implement-specs`** (including **one directory at a time** to completion when the request spans multiple member specs on the same integration cadence—typically **one worktree lifecycle per directory** unless the user batches otherwise).
-- In the report, **MUST** include branch name, worktree path, commit hash, tests run, backfilled docs, and an explicit statement that the parent checkout was not modified for implementation files.
-  - **Pause →** Am I honoring **implement-specs** step 3–6 **constraints** literally while respecting that all writes happen **only** under this worktree root?
-  - **Pause →** If I used Rust `cargo test` filters, did I violate the **single positional filter** rule; how would I split the commands?
+### 4. 驗證實作
 
-## Sample hints
+按照 `checklist.md` 之中定義的驗收標準，逐項驗收並檢查任務是否完成。對於未達到驗收標準的任務，必須重新實作及重新驗收，並在完成驗收之後將所有 `checklist.md` 之中的checkboxes勾選為完成。
 
-- **Root check** (must print the same path twice before edits):
-  ```bash
-  pwd && git rev-parse --show-toplevel
-  ```
-- **Skeleton commands** (`change_name` `oauth-scope`, parent `feature/x`, type `feat`):
-  ```bash
-  git branch feat/oauth-scope feature/x
-  git worktree add ../oauth-scope feat/oauth-scope
-  cd ../oauth-scope
-  ```
-- **Cargo** (two filters ⇒ two commands): run `cargo test parser::` **and separately** `cargo test cache::`, not `cargo test parser:: cache::`.
+### 5. 回填spec
 
-## References
+確保所有實作任務完成並通過驗收之後，更新 `spec.md` 之中的需求checkboxes反應實際代碼實作狀態。
 
-- `implement-specs`: shared lifecycle (locate → read bundle in order → implement → backfill → **`commit-and-push`** → report)
-- `references/branch-naming.md`: branch naming
+### 6. 提交變更
+
+使用 `commit-and-push` 將變更提交到子分支上。不需要將變更推送到remote。
+
+## 範例
+
+- "用戶指定了一份有四份spec的batch spec並要求實作這份batch spec。同時，`coordination.md` 之中建議merge順序是 spec 1 -> spec 2 -> spec 3 -> spec 4。" -> "創建子分支及工作樹；從spec 1開始進行完整的實作流程，並在完成回填spec之後再開始實作spec 2，直至4份spec都被完成"
+- "用戶指定了一份有2份spec的batch spec並要求實作這份batch spec。同時，`coordination.md` 之中的建議merge順序是spec 2 -> spec 1，並且 `preparation.md` 存在於該batch spec之中。" -> "創建子分支及工作樹；先實作 `preparation.md` 之中要求的任務並按照當中的驗收標準進行驗收。確定完成之後，從spec 2開始完整的實作流程。並在完成spec 2之後再實作 spec 1。"
+
+## 參考資料
+
+- `references/branch-naming.md` - 建議分支命名方式

package/init-project-html/SKILL.md

@@ -1,130 +1,42 @@
 ---
 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 頁面。所有宣告必須基於倉庫證據，跨模組關係只能用 `call`、`return`、`data-row`、`failure` 邊表達；每個功能模組由一個可寫子 agent 負責，主 agent 必須等待全部子 agent 完成後，才能補跨功能連接並執行 `render` 與 `validate`。
 ---
 
-# Init Project HTML
+# 初始化專案 HTML 架構圖
 
-## Dependencies
+## 技能目標
 
-- 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.
+透過 `apltk architecture` 為目前倉庫建立基礎專案架構圖譜，產出受 CLI 管理的 `resources/project-architecture/atlas/` 狀態檔與對應 HTML 頁面，而不是手寫 SVG 或 HTML。
 
-## Non-negotiables
+## 驗收條件
 
-### Rule 1 — Use the CLI; never hand-author atlas HTML
+- 只透過 `apltk architecture` 修改圖譜；不得手改 `resources/project-architecture/**/*.html`。
+- 渲染後的宏觀圖完整表達功能與子模組關係；所有跨邊界互動都必須落在 `call`、`return`、`data-row`、`failure` 邊上，不能藏在子模組頁面文案裡。
+- 每個非平凡子模組都具備足夠的內部結構：已宣告的 `function`、`variable`、有序 `dataflow`、必要時的 `error`，且 `dataflow` 中的函式與讀寫變數引用可被校驗通過。
+- 所有宣告都能追溯到真實程式碼、設定、SQL 或外部邊界；無法確認的部分用 `TBD` 或在 `meta.summary` 中明確記錄遺漏原因。
+- 採用「每個功能一個可寫子 agent」的分工；主 agent 必須等所有子 agent 完成後，才允許補跨功能邊並執行 `apltk architecture validate`，且驗證結果為通過。
 
-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.
+## 工作流程
 
-### Rule 2 — Sub-module pages describe only themselves; the internal-dataflow diagram is zoomable and structurally typed
+1. 先執行 `apltk architecture --help`，把 CLI 說明當作唯一命令真源；本技能只定義語義規則，不重複維護參數細節。
+2. 先做整倉淺層盤點，只列出功能模組的 `slug`、使用者視角職責、入口點與主要邊界資源；此階段不要深讀函式實作。
+3. 為每個待建圖功能派發一個可寫子 agent。每個子 agent 只深讀自己負責的功能，並負責宣告該功能內的全部子模組、函式、變數、資料流、本地錯誤，以及所有功能內邊。
+4. 子 agent 返回的內容只能是：子模組摘要，以及需要由主 agent 稍後補上的跨功能邊界資訊；主 agent 不得回頭重讀已委派功能原始碼，也不得重複宣告子 agent 已擁有的功能內元件。
+5. 等全部子 agent 完成後，主 agent 統一補齊跨功能 `edge`，必要時補共享 `meta` 或 `actor`，隨後執行 `apltk architecture render` 與 `apltk architecture validate`。
+6. 打開渲染結果進行抽查，確認宏觀圖和至少一個代表性子模組頁都滿足驗收條件，並在彙報中記錄功能數、子模組數、邊數量、未覆蓋路徑與原因。
 
-What the CLI emits on each sub-module page is fixed in *role* (not in exact flag names — those live in `--help`):
+## 使用範例
 
-- **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`).
+- 「替這個倉庫首次生成 HTML 架構圖。」 -> 「先梳理功能模組，再按功能分派子 agent，最後彙總跨功能邊，生成基礎 atlas 與渲染頁面。」
+- 「把系統的資料流、呼叫關係和回滾路徑視覺化。」 -> 「使用 `call` / `return` / `data-row` / `failure` 邊表達跨邊界關係，並為每個關鍵子模組補齊內部 `dataflow`。」
 
-**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/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>` - <文件用途說明>
+```