@laitszkin/apollo-toolkit 3.11.7 → 3.12.0

package/implement-specs/SKILL.md

@@ -1,83 +1,48 @@
 ---
 name: implement-specs
-description: >-
-  Land approved `docs/plans/{YYYY-MM-DD}/{change}` (or batch member path) on the current branch: resolve path by user pointer or evidence-backed latest (no guesses); read spec→design→contract→checklist then run every `tasks.md` line and all `checklist.md` wrap-up; multi-directory work follows `coordination.md`—one directory fully done before the next; backfill plans; **`commit-and-push`** for final commit (no branch/worktree unless user rescopes). Isolation: **`implement-specs-with-worktree`**; delegation: **`implement-specs-with-subagents`**.
+description: 當你需要在當前分支之中實作spec時，使用這個技能。
 ---
 
-# Implement Specs
+## 技能目標
 
-## Dependencies
+實作用戶指定的spec。確保所有任務都被完成，用戶所有需求都被滿足。
 
-- Required: **`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; `recover-missing-plan` if the requested plan path is missing from the current checkout.
-- Optional: none.
-- Fallback: If **`commit-and-push`** is unavailable, **MUST** stop immediately and report the missing dependency. Do not improvise substitute standards or ungated `git commit`.
+## 驗收條件
 
-## Non-negotiables
+- 在所有被用戶要求實作的spec之中，所有的 `checklist.md`, `tasks.md`, `spec.md` 當中所有非用戶填寫的任務相關checkboxes全部被勾選為完成狀態
 
-- **MUST** read and understand the full in-scope planning set and the parent `coordination.md` when its path applies, **before** editing product code or tests for this spec. Read for meaning in this order: **`spec.md`** (requirements / intent), **`design.md`** (high-level architecture + coarse `INT-###` anchors—**guidance for structuring work**), **`contract.md`** (cite-backed external facts/constraints + `EXT-###` anchors), **`checklist.md`**, then treat **`tasks.md`** as **the authoritative ordered runnable checklist**. **MUST NOT** start coding until that read pass is complete for the current in-scope directory.
-- **MUST** execute **every** **`tasks.md`** line in listed order—the **executable source of truth** for what to ship. **`design.md` / `contract.md`** **inform** decomposition and forbid contradictions (**`INT-###` / `EXT-###`** when present are **constraints/anchors referenced from tasks**, not a second queue). **MUST NOT** silently wire alternate module flows or vendor surfaces that conflict with approved **`design`** / **`contract`**; resolve conflicts via **`generate-spec`** / explicit approved plan edits first.
-- **MUST** when multiple spec directories apply to one request, follow parent **`coordination.md`** merge / sequencing guidance (or the user’s explicit order if coordination is absent or defers to them) and **complete** one directory end-to-end—**all** of its `tasks.md` lines **and** **all** of its `checklist.md` wrap-up / acceptance work—**before** starting implementation work in the next directory. **MUST NOT** interleave partial implementation across sibling specs.
-- **MUST NOT** create a branch, switch branches, or add or use a `git worktree` for this work unless the user explicitly changes the request in the same conversation.
-- **`tasks.md` completeness (hard stop)**: **MUST** execute **every** actionable item listed in the in-scope `tasks.md` for this request—**no exceptions** for perceived size, duration, file count, refactor depth, or session length. **MUST NOT** stop early, “defer” unchecked tasks while claiming the spec is done, collapse multiple task lines into a partial summary, or substitute narrative progress for completing a remaining line. If a line is truly impossible under written contracts, **MUST** stop with evidence and **MUST NOT** treat the implementation pass as complete until the plan is amended through the governing planning workflow (`generate-spec` / user-approved update) and the revised `tasks.md` is then fully satisfied.
-- **`checklist.md` wrap-up / acceptance (hard stop for “spec complete”)**: **MUST** complete **all** `checklist.md` obligations that constitute **wrap-up, acceptance, verification, release-prep, doc or index sync, or other closing/hand-off** work tied to this change—**same no-exemption bar as `tasks.md`** (workload, duration, or breadth **do not** waive checklist-only items). The **entire** in-scope spec is **not** **complete** until those checklist items are **actually satisfied** and truthfully marked. **MUST NOT** treat “implementation done” or proceed to final **`commit-and-push`** / completion reporting while checklist-defined closing work remains open or is waved away with narrative. If a checklist item is impossible under contracts or facts on the ground, **MUST** stop with evidence and **MUST NOT** declare the spec complete until the plan is amended through the governing workflow and the revised `checklist.md` is then fully satisfied.
-- **MUST** treat the approved `tasks.md`, `checklist.md`, and contracts as the scope boundary: on top of the rules above, run the relevant checklist-backed verifications and tests, and **MUST** backfill the planning documents with factual completion status (no aspirational checkboxes).
-- **MUST NOT** expand scope to unrelated sibling spec directories solely because they share a batch folder.
-- **MUST** finalize the implementation through **`commit-and-push`** after staging the intended change set (shared readiness, reviews per that skill’s classification, conventional commit message); **MUST NOT** complete the deliverable with a bare `git commit`, IDE-only commit, or other shortcut that skips **`submission-readiness-check`** / mandated gates.
-- **MUST NOT** `git push`, tag, or perform release steps **outside** **`commit-and-push`** (unless **`version-release`** / **`open-source-pr-workflow`** explicitly applies per user request).
-- If the plan path is missing or ambiguous: **MUST** use `recover-missing-plan` or other verifiable repository evidence to locate the authoritative plan; **MUST NOT** substitute a nearby path by guess. After recovery, **MUST** re-read the recovered files before coding so implementation and backfill target the same snapshot.
+## 工作流程
 
-## Standards (summary)
+### 1. 定位實作範圍
 
-- **Evidence**: Same as Non-negotiables: no coding until the spec set is fully read; no guessed plan paths.
-- **Execution**: Current checkout only; **`tasks.md`** defines runnable order and file targets; **`spec`/`design`/`contract`** constrain meaning and forbid contradictory wiring—implement and test until obligations are met—no parallel branch or worktree (unless the user rescopes to another skill).
-- **Quality**: **All** `tasks.md` lines **and** **all** `checklist.md` wrap-up / acceptance obligations for this scope satisfied (see Non-negotiables—workload is not an excuse); tests and checklist verifications executed as required; docs reflect reality; no scope creep into sibling specs.
-- **Output**: Current branch contains a clean, reviewable implementation of this spec only.
+閱讀用戶指定的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:** Before advancing each numbered step, answer the **`Pause →`** questions (even if only internally). A “no” or “unknown” answer **MUST** be resolved or surfaced as a blocker before continuing.
+按照以上文件，閱讀repo，理解本次spec的實作範圍。
 
-1. **Locate and read** — Resolve `docs/plans/{YYYY-MM-DD}/{change_name}/` or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` using the path the **user** gave **or**, when none is given, the **most recent** plan location proven by repository evidence (issue links, manifests, `docs/plans` listing—**MUST NOT** pick a sibling folder by guess). Read parent `coordination.md` when present (merge order, parallelism rules, collisions). For **each** in-scope directory, before any code edits, read the five core files for substance in this order: `spec.md` → `design.md` → `contract.md` → `checklist.md` → `tasks.md` (execution list). If multiple directories are in scope, establish their **sequence** from `coordination.md` (or the user) and plan to implement **one directory at a time** to full completion (Non-negotiables).
-   - **Pause →** Is this directory the **exact** scope—or ordered list—the user (or coordination) requires, verified by listing or viewing those five files—not a sibling “similar” folder?
-   - **Pause →** Have I explicitly linked each material requirement / task to evidence I understood from **spec** / **design** / **contract** (still no code edits)?
-   - **Pause →** If the path were missing or wrong, what **verifiable** step would locate the authoritative plan—and have I executed it?
+### 2. 實作spec任務
 
-2. **Branch sanity** — Run `git status -sb`. Do not modify unrelated dirty files; surface blockers. Confirm the current branch is where this work should land.
-   - **Pause →** Would creating or switching branches or a worktree right now **violate** the Non-negotiables—and am I resisting that temptation?
-   - **Pause →** What dirty paths are **out of scope**, and how will I avoid touching them inadvertently?
-   - **Pause →** Is the integration target branch (where the user expects work) identical to what `git status -sb` shows?
+嚴格按照 `tasks.md` 之中定義的任務，逐項完成實作。如果有多份 `tasks.md` 存在於多份spec之中，則依照 `coordination.md` 之中建議的merge順序進行實作。
+在確認完成所有任務之後，將 `tasks.md` 之中的所有checkboxes勾選為完成。
 
-3. **Implement** — Execute **the entire** approved `tasks.md` (every line) for the **current** in-scope directory only, honoring requirements and design you read in step 1; do not close this step until **no** applicable unchecked tasks remain **for that directory**. Run relevant tests and **any** verification commands or artifact steps that `checklist.md` already assigns to the implementation phase (do not postpone checklist-only closing items that belong here). When the request spans multiple directories, **repeat** steps 3–4 **per directory** in the coordination order **after** the previous directory’s tasks **and** checklist obligations are satisfied.
-   - **Pause →** Have I listed **every** remaining `tasks.md` line—and is the count **zero** before I leave this step?
-   - **Pause →** For the next task item, what is the **single** concrete change and its **single** primary verification—before I type code?
-   - **Pause →** Am I about to touch a file that belongs to a **sibling** spec or an unrelated module without an in-scope task line?
-   - **Pause →** After this chunk of work, which test command **proves** I did not break the contract’s stated behavior?
+如果實作的spec是batch spec，且有 `preparation.md`，在開始實作之前需要先完成 `preparation.md` 之中所規定的任務內容，並在驗收條件滿足之後回填 `preparation.md`。
 
-4. **Backfill** — Update `checklist.md` / `tasks.md` (and any other plan files your standards require) so completion status matches what you actually did. **MUST NOT** advance to **Submit** until **every** checklist item that defines wrap-up or acceptance for this spec is **done** or the batch is an honest documented halt per Non-negotiables.
-   - **Pause →** If I checked a box, can I point to **commit + test run** (or equivalent) that makes that check true—no wishful checking?
-   - **Pause →** Are **zero** checklist obligations that mean “before spec complete” still open—validated by re-reading `checklist.md`, not from memory?
-   - **Pause →** Did any scope shrink or shift during implementation; if so, is the plan text updated **honestly**?
+### 3. 驗證實作
 
-5. **Submit** — Stage the intended implementation/backfill diff. Run **`commit-and-push`** through commit using that staged intent (and **push** only when the user explicitly requested remote update). Keep scope to this spec only; split into multiple submission passes only when an unavoidable checkpoint requires separate commits. **Only** reach this step when **both** `tasks.md` and `checklist.md` Non-negotiable closures are satisfied.
-   - **Pause →** Does `git diff --cached` (or the equivalent staged view) show only this spec’s intended surface, or do I need to unstage/revert noise first?
-   - **Pause →** Am I on the **same** branch I named in step 2, without a silent branch switch?
+按照 `checklist.md` 之中定義的驗收標準，逐項驗收並檢查任務是否完成。對於未達到驗收標準的任務，必須重新實作及重新驗收，並在完成驗收之後將所有 `checklist.md` 之中的checkboxes勾選為完成。
 
-6. **Report** — State current branch, commit hash, tests run, which plan files were backfilled, and explicit confirmation that **`tasks.md` and checklist-defined wrap-up work are complete** for this in-scope spec (or cite the documented blocker).
-   - **Pause →** Would another engineer **reproduce** my conclusion from the branch name, commit hash, and test commands I listed alone?
+### 4. 回填spec
 
-If this skill directory contains `references/implement-specs-common.md`, treat it as an optional extension to the steps above; if it is absent, the Workflow section here is authoritative.
+確保所有實作任務完成並通過驗收之後，更新 `spec.md` 之中的需求checkboxes反應實際代碼實作狀態。
 
-## Sample hints
+## 範例
 
-- **Resolve path**: user says “implement `oauth-scope`”; read `docs/plans/2026-05-01/oauth-scope/` first, **not** a sibling folder like `docs/plans/2026-05-01/batch/oauth-scope/` unless that is where the five files actually live per user or manifest.
-- **Read order**: keep the mandated sequence (**spec → design → contract → checklist → tasks**); use **`checklist.md`** after **spec/design/contract** so acceptance checks map to stated requirements and boundaries.
-- **Multi-directory batch (same branch)**: `coordination.md` says merge order `api-layer` then `cli-wrapper` — finish **`api-layer`** `tasks.md` **and** **`api-layer`** `checklist.md` completely, then start **`cli-wrapper`**; do not split half of each.
-- **Branch sanity excerpt**: expect `git status -sb` like `## feature/x …` plus a dirty `README.md` you do **not** own — leave that file untouched; implement only paths from `tasks.md`.
-- **Completion report sketch**: `Branch: feature/x · Commit: a1b2c3d · Tests: npm test -- lib/auth.test.js · Backfill: tasks.md (done), checklist.md (R1.3 → passed).`
-- **Anti-pattern**: `git checkout -b impl/oauth-scope` for this skill — **wrong** unless the user changed scope mid-conversation.
-
-## References
-
-- `recover-missing-plan`: missing or mismatched plan recovery
-- **`commit-and-push`**: final commit/readiness (push only when user requests remote update)
+- "用戶指定了一份有四份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。"

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

@@ -1,92 +1,49 @@
 ---
 name: implement-specs-with-subagents
-description: >-
-  Coordinator-only workflow for multispec batches: ingest `coordination.md`/`preparation.md`, run prerequisite work yourself, derive topological phases, launch **`implement-specs-with-worktree`** workers (one `{change}` each; **full** `tasks.md` + **full** `checklist.md` wrap-up—no partial handoff), **`merge-changes-from-local-branches`** after every phase succeeds, ledger every branch/test/merge—not for solo specs unless user explicitly insists on delegation overload. **Multi-phase: do not declare done until every non-blocked spec is merged across all phases** (or pipeline stopped on explicit blocker).
-  Wrong tool for one directory without parallel mandate—pick **`implement-specs-with-worktree`** / **`implement-specs`** depending on isolation. Publication/versioning stays outside this orchestration layer unless another skill attaches.
-  Ledger sample: `oauth-scope | phase=1 | merged | npm test ✅`.
+description: 當有多份規格文檔需要被實作時，且環境允許使用subagents，建議使用本技能調度subagents完成任務
 ---
 
-# Implement Specs with Subagents (Multi-Phase)
+## 目標
 
-## Dependencies
+調度多個subagents完成規格文檔的實作。
 
-- Required: `implement-specs-with-worktree` (every implementation subagent **MUST** follow this skill for its assigned directory); `merge-changes-from-local-branches` (phase integration **MUST NOT** skip this between phases); **`commit-and-push`** (integration-branch **preparation** commits and **any** post-merge submission the user expects on that branch—**MUST NOT** bypass for bare `git commit` / ungated push when this skill owns the branch).
-- Conditional: `generate-spec` if the batch is not implementation-ready; `review-change-set` only when the user asks for post-merge review.
-- Fallback: If independent subagents cannot run, **MUST** report that limitation. Serial `implement-specs-with-worktree` across specs is allowed **only** after the user explicitly approves that fallback.
+## 驗收條件
 
-## Non-negotiables
+- 在所有被用戶要求實作的spec之中，所有的 `checklist.md`, `tasks.md`, `spec.md` 當中所有非用戶填寫的checkboxes全部被勾選為完成狀態
+- 所有變更已經從各個subagents的工作分支合併回當前所在分支
+- 所有subagents創建的工作分支及工作樹已經被清理
 
-- **MUST NOT** delegate until `coordination.md`, when present, explicitly allows parallel implementation—or when absent, until you have verified no contradiction to parallel work.
-- **MUST** enumerate exact in-scope spec directories **before** any subagent starts; **MUST NOT** delegate archived, sibling, or “nearest guess” directories unless the user explicitly includes them.
-- **MUST** verify each delegated directory contains `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` before launch.
-- **MUST** complete, verify, and **finalize** documented shared preparation on the integration branch **through `commit-and-push`** before any implementation subagent starts when `preparation.md` exists or specs mandate pre-work; the coordinating agent **MUST NOT** delegate that preparation. Subagents **MUST NOT** start until this branch is clean at the preparation commit (or there is no required preparation).
-- **MUST** build a directed dependency graph from `coordination.md` plus each spec’s `spec.md` / `design.md` (edges: *provider spec must merge before consumer spec*). **MUST** partition specs into phases by topological **layers**: Phase 1 = specs with **no** in-batch prerequisites; for *k* ≥ 2, Phase *k* = specs whose in-batch prerequisites all appear in phases before *k*. **MUST NOT** start phase *k* until phase *k − 1* is fully merged into the integration branch (or you have an explicit user override). If the graph has a cycle, **MUST** stop and report it.
-- **MUST** assign **exactly one** spec directory per implementation subagent; **MUST NOT** assign multiple directories to one implementation subagent.
-- **`tasks.md` + `checklist.md` completeness (hard stop)**: Every implementation subagent **MUST** finish **all** actionable items in its assigned directory’s `tasks.md` **and** **all** `checklist.md` wrap-up, acceptance, verification, and closing obligations before reporting success—**no** partial completion, **no** “good enough” stops for large batches, **no** deferrals disguised as done. The coordinating agent **MUST NOT** merge a phase branch, advance the ledger to **`merged`**, or treat a spec as complete while **any** in-scope `tasks.md` line **or** checklist-defined closing item remains undone unless the batch is explicitly **`blocked`** with documented user/contract halt. **MUST** repeat this mandate in **every** subagent envelope so workers cannot interpret scope loosely.
-- **MUST** give each subagent only task-local context (repo root, exact spec path, `coordination.md` path if relevant, instruction to run `implement-specs-with-worktree`, explicit **`tasks.md` full-completion** and **`checklist.md` wrap-up full-completion** requirements, baseline commit when preparation exists, requirement to read the full bundle before edits, worktree isolation, tests, backfill, local commit, and reporting branch/worktree/commit/tests/blockers). **MUST NOT** leak unrelated reasoning or other subagents’ private diffs unless resolving a concrete conflict.
-- After each phase: **MUST** merge every **completed** spec branch from that phase into the integration branch via `merge-changes-from-local-branches` before starting the next phase; **MUST** resolve conflicts using spec contracts as the correctness tie-breaker; **MUST** record merge result in the ledger; if merge is blocked, **MUST** stop the pipeline and report.
-- **Multi-phase completion**: When the planned ledger has **more than one** phase, **MUST** loop steps **5→6→7** until **every** in-scope spec is either **`merged`** on the integration branch or explicitly **`blocked`** with a documented stop (user abort, irresolvable conflict, failed dependency, etc.). **MUST NOT** yield, summarize as “phase complete”, or imply the batch is finished while **any** phase still has a successful, unmerged branch or **`pending`** / **`in_progress`** rows for specs that should run—unless the coordinating agent is halted by a preceding Non-negotiable blocker **and** that halt is stated plainly.
-- Model: If the user names a model, **MUST** use it for implementation subagents when the platform allows; if not supported, **MUST** state that fact and continue only if the default is acceptable to the user’s intent.
+## 工作流程
 
-## Standards (summary)
+### 1. 定位實作範圍
 
-- **Evidence**: Batch read (`coordination.md`, `preparation.md`, every in-scope `spec.md` / `design.md`) before scheduling; ledger stays live.
-- **Execution**: Preparation → dependency graph → **repeat** (run phase *k* → merge phase *k*) until all phases reconciled on the integration branch; never skip merges between dependent phases; **multi-phase ⇒ no early “done” narrative** until ledger proves full merge-set (or documented blockers).
-- **Quality**: No duplicate delegation; subagents base on the branch that already contains preparation (and prior phases); **every** spec lands with **complete** `tasks.md` execution **and** **complete** `checklist.md` wrap-up, or a documented **blocked** state—workload is never a merge excuse; pause on shared file collisions, batch-wide defects, or rate-limit pressure.
-- **Output**: Concise ledger: per spec → phase, depends-on, subagent id/label, branch/worktree, commit or blocker, tests, merge status.
+閱讀用戶指定的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:** After **each** numbered step below, briefly answer **`Pause →`** items; escalate to halt or revise the plan whenever the answer violates Non-negotiables or exposes a blocker.
+按照以上文件，閱讀repo，理解本次spec的實作範圍。
 
-1. **Batch intake** — Resolve `docs/plans/{YYYY-MM-DD}/{batch_name}/`. Read `coordination.md` (first) and `preparation.md` when present. List only in-scope spec directories; verify the five required files each. If coordination blocks parallel work, **stop** and report. If preparation is required, go to step 2; else go to step 3.
-   - **Pause →** Can I quote **verbatim** why each enumerated directory is in scope—not “probably related”?
-   - **Pause →** What **exact sentence** from `coordination.md` gates parallel readiness, if any—or what absence did I infer from—and is that justified?
+### 2. 完成前置準備工作（如有）
 
-2. **Preparation (blocking when required)** — Coordinating agent executes shared prep only: read tasks/outputs/verification hooks, satisfy scope, run listed checks, **finalize on the integration branch through `commit-and-push`** (push only if the user requested remote update), record prep commit hash in ledger, leave working tree clean. If prep fails, **stop** (no subagents).
-   - **Pause →** Am I silently delegating preparation to a **subagent** when the coordinating agent owns it—is that happening?
-   - **Pause →** What **commit hash** and **clean-tree** confirmation will subagents inherit as baseline?
+如果實作的batch spec 有 `preparation.md`，你需要在開始實作之前需要先完成 `preparation.md` 之中所規定的任務內容，並在驗收條件滿足之後回填 `preparation.md`。使用 `commit-and-push` 技能並遵守當中的流程將前置準備工作提交，不需要推送到remote。
 
-3. **Dependency graph** — Extract ordering obligations; assign each spec a phase index via topological layering. Persist `depends-on` / `depended-by` in the ledger. Cycles ⇒ **stop**.
-   - **Pause →** For each edge (A must land before B), what **sentence** from spec/design/coordination supports it?
-   - **Pause →** If I flattened phases wrong, which later spec would start **without** its merged predecessor—how do I detect that now?
+### 3. 規劃subagents調度順序
 
-4. **Plan launches** — For each phase, queue one item per spec. Ledger fields: phase, paths, deps, planned branch/worktree basename, status (`pending` / `in_progress` / `merged` / `blocked`), commit, tests, blockers, prep-commit baseline note. Fix model policy per Non-negotiables.
-   - **Pause →** Is there **exactly one** spec directory per queued subagent—never two in one prompt?
-   - **Pause →** What will I **repeat** in every subagent envelope so they cannot “improvise” the wrong skill or wrong path?
+識別各份spec之間的依賴關係，並建立調度順序。將多份spec的實作切分為多個實作批次。每一個實作批次內部的spec之間沒有互相依賴。完成實作批次的建立之後，為每一個subagents分配僅一份spec，並且開始實作。
 
-5. **Run phase *k*** — Launch subagents for each spec in the phase with task-local payloads (see Non-negotiables). Monitor ledger; pause new launches on shared blockers; on conflicting edits to shared files, resolve ownership using `coordination.md` before more launches; if one spec fails and others depend on it, **MUST NOT** start those dependents until resolved; batch-wide planning failure ⇒ stop all scheduling.
-   - **Pause →** Does every active subagent have a **distinct** spec directory assignment—no duplicate or overlapping paths?
-   - **Pause →** Did two running subagents report **overlapping** paths; if yes, did I stop launching until ownership is clear?
+在開始實作一個新的實作批次之前，你需要使用 `merge-changes-from-local-branches` 技能，遵守當中的流程，將前一個實作批次的變更從本地其他分支合併回來。
 
-6. **Merge phase *k*** — When every item in phase *k* is **done or explicitly blocked**, merge **each successful** branch via `merge-changes-from-local-branches`; rerun critical tests if your standards say so; update ledger. Merge failure ⇒ **stop** before phase *k+1*. **“Done”** here **requires** full `tasks.md` completion **and** full `checklist.md` wrap-up / acceptance per Non-negotiables—not merely a subagent “looks finished” report.
-   - **Pause →** For **each** spec I am about to merge, can I cite **evidence** (branch + `tasks.md` **and** `checklist.md` state) that **zero** applicable task lines **and** **zero** outstanding checklist closing items remain—or is this a documented **`blocked`** outcome instead?
-   - **Pause →** Has **every** successful branch in this phase been merged into the **same** integration branch I will use to **start** phase *k+1*?
-   - **Pause →** If a merge conflict touches a **contract** field, which spec’s `contract.md` / `design.md` is the tie-breaker I will apply?
+### 4. 驗收工作
 
-7. **Repeat until batch reconciled** — After step 6, if **any** later phase still has specs not yet run or not yet merged: **MUST** increment *k* and **return to step 5** on the **same** integration branch (now including phase *k* merges). Next phase starts only on that branch. **MUST NOT** end the coordinator run with a “wrapped up” message if the ledger still shows remaining phases or unmerged successful work. **Only** when every in-scope spec is **`merged`** or explicitly **`blocked`** may you treat implementation coordination as **complete** (then optional handoff to submit/review skills per user).
-   - **Pause →** How many phases remain after this merge—is the count **zero**? If not, **immediately** plan step 5 for *k+1*.
-   - **Pause →** Before launching phase *k+1*, can I **name** the merge commit or branch state that contains **all** prerequisites for every spec in that phase?
-   - **Pause →** Can I cite **ledger lines** proving **merged** for every non-blocked spec in **every** phase?
+完成所有實作批次的合併之後，你需要閱讀所有spec之中的 `checklist.md`, `tasks.md`, `spec.md`，並確保當中非用戶填寫的任務相關checkboxes都被勾選為完成。
 
-## Out of scope
+## 範例
 
-- **MUST NOT** use this skill for a single spec unless the user explicitly requests subagent delegation.
-
-**Repository regression check:** The coordinating agent must complete and commit explicitly documented prerequisite preparation on the integration branch before launching implementation subagents when `preparation.md` or equivalent mandates it.
-
-## Sample hints (subagent scheduling)
-
-- **Parallel batch (independent specs)** — The batch has multiple member directories and `coordination.md` allows parallel implementation with **no** in-batch prerequisites. Treat them as **one phase**: assign **exactly one** spec per subagent, launch one **`implement-specs-with-worktree`** worker per spec, each finishing **all** of its directory’s **`tasks.md`** and **`checklist.md`** before reporting success; when **every** branch in the phase is green, run **`merge-changes-from-local-branches`** to bring **every** member into the integration branch **before** declaring the batch done or starting a follow-on phase.
-
-- **Preparation plus A → {B, C}** — Specs **A**, **B**, and **C** share a batch with **`preparation.md`**; `coordination.md` / design shows **B** and **C** depend on merged work from **A**. Coordinating agent: (1) complete **preparation** on the integration branch and **`commit-and-push`** (push only if the user asked); (2) **Phase 1**: launch **one** subagent for **A** only; **`merge-changes-from-local-branches`** for **A** when it passes; (3) **Phase 2**: launch **two** subagents for **B** and **C** from the branch that already contains **A**’s merge; (4) merge **B** and **C** when both finish. **MUST NOT** start **B** or **C** until **A** is merged into the baseline they branch from.
-
-- **Ledger reminder** — One row per spec remains mandatory (`phase`, `depends-on`, branch/worktree, `merged` / `blocked`, tests); see Non-negotiables for full fields.
-
-## References
-
-- `implement-specs-with-worktree`: per-spec execution environment
-- `merge-changes-from-local-branches`: phase merge integration (and downstream submit flow when that skill is invoked)
-- `generate-spec`: repair planning when the batch is not ready
-- `coordination.md`, `preparation.md`: batch-level ordering and prerequisites
-- `review-change-set`: optional post-merge review
+- "用戶要求實作一份batch spec。該batch spec有5份spec。spec 2依賴於 spec 1，spec 4依賴於spec 3，spec 5依賴於spec 2, spec 4。" -> "將batch spec切分為3個實作批次。第一批，先派發兩個subagents各自實作spec 1, spec 3，並將變更合併回當前分支；第二批派發兩個subagents個字實作spec 2, spec 4，並將變更合併回當前分支；第三批派發subagent實作spec 5，並將變更合併回當前分支。完成驗證工作之後向用戶回報成果。"
+- "用戶要求實作一份batch spec。該batch spec有3份spec，並且存在 `preparation.md`。3份spec之間各自無依賴關係。" -> "先完成 `preparation.md` 的實作並提交。然後啟動三個subagents並行完成三份spec的任務。完成之後，將變更合併回當前分支。完成驗證工作之後向用戶回報結果。"

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,152 +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.
-
-## How to use `apltk architecture`
-
-**Authoritative command tree:** run **`apltk architecture --help`** (same output as `apltk architecture help`). **MUST** use that output for every verb, subverb (`add` / `set` / `remove` / `reorder`), and required flag. This skill describes **semantics and constraints** only so documentation does not drift when the CLI adds flags or synonyms.
-
-**Typical global flags** (confirm in `--help`): `--project <root>`, `--spec <spec_dir>` (overlay under `<spec_dir>/architecture_diff/` — see `spec-to-project-html`), `--no-render`, `--no-open`, `--out` (for `diff`). Pass `--no-render` while batching mutations, then **`render`** once before `validate` if you batched.
-
-**Groupings — what each family is for:**
-
-| Family | Purpose | Key constraints |
-| --- | --- | --- |
-| **`open` / `diff` / `render` / `validate` / `undo` / `help`** | View, regenerate, check, revert, discover verbs | **`validate`** before “done”. **`diff`** after spec overlays to compare base vs proposed-after under `docs/plans/**/architecture_diff/`. |
-| **`meta` / `actor`** | Macro title, summary, optional top-level actors | Summary is the right place for scanned roots and omissions. |
-| **`feature` / `submodule`** | Feature modules and their sub-modules | **Remove** cascades references; in spec overlay mode, rename is usually **remove + add** so `diff` classifies correctly. |
-| **`function` / `variable` / `dataflow` / `error`** | Tables + ordered internal flow + local errors | Declare symbols **before** referencing them from `dataflow`. Use **`remove`** (see `--help`) to delete mistaken rows or steps. |
-| **`edge`** | Cross- **or** intra-feature seams | **`kind`** ∈ `call` \| `return` \| `data-row` \| `failure`. Intra-feature endpoints land in the feature file; cross-feature endpoints land in the index. Prefer stable **`--id`** on edges you may remove later in spec mode. |
-
-**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:**
-
-```bash
-apltk architecture meta set --title "..." --summary "..." --no-render
-# only when an actor is shared across multiple features:
-apltk architecture actor add --id <id> --label "..." --no-render
-# one edge per cross-feature interaction reported by the subagents:
-apltk architecture edge add --from <featA>/<subA> --to <featB>/<subB> --kind call|return|data-row|failure --label "..." --no-render
-apltk architecture render
-apltk architecture validate
-```
-
-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 的增量刷新版本。