@laitszkin/apollo-toolkit 3.11.7 → 3.12.0

package/discover-security-issues/SKILL.md

@@ -1,88 +1,54 @@
 ---
 name: discover-security-issues
 description: >-
-  Discovery-only adversarial audit: map trust boundaries, run module catalogs (`agent-system`, `financial-program`, `software-system`, `combined`), reproduce exploitable behavior with payloads/commands and `path:line` evidence; prioritize impact × exploitability—**no code edits, no PRs, no auto-remediation**.
-  Use for security review, vuln hunting, SQLi/XSS/auth/IDOR checks, agent prompt-injection/tool abuse, money-path races **STOP** when user wants patches shipped—hand off findings… BAD single vague “looks fine”… GOOD two-pass repro, hypothesis vs confirmed…
+  面向選定範圍的只讀安全審查技能。先界定信任邊界，再依 `agent-system`、`financial-program`、`software-system` 或 `combined` 攻擊目錄執行可重現的對抗性驗證，要求以 payload、請求形狀、命令或運行結果配合 `path:line` 證據支撐結論；不允許修改代碼、提交 PR 或直接修復漏洞。
 ---
 
-# Discover Security Issues
-
-## Dependencies
-
-- Required: none.
-- Conditional: none.
-- Optional: none.
-- Fallback: not applicable.
-
-## Non-negotiables
-
-- **Discovery-only**: **MUST NOT** edit code, apply patches, open PRs, or run “fix workflows.”
-- **MUST** keep only **reproducible** issues with exploit evidence; separate **hypotheses** from **confirmed** findings.
-- **MUST** reproduce each confirmed exploit **at least twice** on the same path; use nearby payload variants for high-risk sinks.
-- **MUST** discard authorship bias—treat all code as untrusted until evidence proves behavior.
-
-## Standards (summary)
-
-- **Evidence**: Payload/precondition, observable failure, `path:line`, commands or requests that reproduce.
-- **Execution**: Pick modules → boundaries → scenarios from references → validate → prioritize → report only.
-- **Quality**: Rank by impact, exploitability, reach; unknowns listed under residual risk.
-- **Output**: Findings (severity-ordered), attack evidence, risk notes, hardening **advice** (not patches), residual risk.
-
-## Workflow
-
-**Chain-of-thought:** After each step, satisfy **`Pause →`** before continuing; halt on missing scope or contradictory module choice.
-
-### 1) Scope and modules
-
-- Choose one or more of: `agent-system`, `financial-program`, `software-system`, `combined` (cross-boundary chains).
-- List untrusted inputs, privileged actions, and protected assets; state invariants that must hold.
-   - **Pause →** Which module catalogs did I **open** (file names)—not guessed from memory?
-
-### 2) Execute scenarios from references
-
-- **Agent**: `references/agent-attack-catalog.md`; optional `references/security-test-patterns-agent.md` (prompt injection, tool abuse, memory/exfil paths).
-- **Financial**: `references/red-team-extreme-scenarios.md`, `references/risk-checklist.md`; optional `references/security-test-patterns-finance.md` (authz, replay/race, idempotency, precision, lifecycle).
-- **Software**: `references/common-software-attack-catalog.md` (SQL/NoSQL/command injection, XSS, CSRF, SSRF, traversal, upload, session/JWT, IDOR/BOLA, deserialization, misconfig).
-- **Combined**: relevant subsets **plus** chains (e.g. injection → privileged API).
-   - **Pause →** Did I record **payload + preconditions + observed behavior** for each candidate—not just “maybe vulnerable”?
-
-### 3) Validate reproducibility
-
-- Re-run each confirmed path twice; add encoding/casing/delimiter variants on hot sinks.
-   - **Pause →** Is anything still “likely” without a second repro—downgrade to hypothesis?
-
-### 4) Prioritize
-
-- Order Critical/High → Medium → Low using impact, exploitability, blast radius (multi-tenant / cross-tenant called out).
-
-### 5) Report only
-
-Deliver (see **Output shape** below): findings, attack evidence, prioritization, hardening guidance (advisory), residual risk.
-
-## Minimum coverage (apply per selected module)
-
-- **Core**: trust boundaries, authn/authz, input → dangerous sink paths, secrets/sensitive data handling.
-- **Agent**: prompt/indirect injection, unauthorized tools/actions, exfil, memory poisoning resistance.
-- **Financial**: object-level authz, replay/race/idempotency, precision, oracle/side-effect safety, failure consistency.
-- **Software**: injection families, XSS/CSRF/SSRF, traversal/upload, session/JWT, brute-force/rate limits, debug/CORS/secrets exposure.
-- **Combined**: module checks + realistic cross-boundary chains.
-
-## Output shape
-
-1. **Findings** (high → low): title, severity, evidence (`path:line`), reproduction steps/payload, impacted invariant/asset.
-2. **Attack evidence**: preconditions, commands/requests, observed insecure behavior, variant results.
-3. **Risk prioritization**: impact, exploitability, reach; why it matters in **this** system.
-4. **Hardening guidance** (advice only): fix direction, validation focus post-remediation.
-5. **Residual risk**: hypotheses, assumptions, follow-up probes.
-
-## Sample hints
-
-- **Module**: Web API + Claude tool-use → `combined` (software + agent); deposits/withdrawals → include `financial-program`.
-- **Evidence**: “SQLi possible” without two runs + exact parameter → stays **hypothesis** until repro’d.
-- **Stop line**: User says “patch it now” → finish report; hand off to implementation skills—**do not** self-patch here.
-
-## References
-
-- `references/agent-attack-catalog.md`, `references/security-test-patterns-agent.md`
-- `references/red-team-extreme-scenarios.md`, `references/risk-checklist.md`, `references/security-test-patterns-finance.md`
-- `references/common-software-attack-catalog.md`, `references/test-snippets.md` (optional snippets)
+## 目標
+輸出一份只讀的安全審查報告，僅保留可重現、可利用、可定位的安全問題。報告需要包含攻擊前提、攻擊步驟、觀察到的不安全行為、`path:line` 證據、嚴重度排序、建議性加固方向與剩餘風險；本技能不負責修補漏洞。
+
+## 驗收條件
+- 審查開始前已明確定義範圍：所選模組目錄、信任邊界、不可信輸入、受保護資產、特權操作與必須成立的安全不變式。
+- 每個已確認問題都包含 payload 或請求形狀、前置條件、實際觀察到的不安全行為，以及精確的 `path:line` 證據。
+- 每個已確認漏洞都在同一路徑下成功重現至少兩次；對高風險熱點還要補做相鄰變體驗證。無法穩定重現者只能作為假設或剩餘風險。
+- 問題排序基於影響、可利用性與波及範圍，並對資金流、權限提升、跨租戶資料暴露與破壞性操作給予更高權重。
+- 最終交付物是按嚴重度排序的安全報告，只包含已確認發現、攻擊證據、風險解釋、建議性加固方向與剩餘風險。
+- 全流程保持只讀：不得修改代碼、補丁、測試、PR 或直接執行修復工作流。
+
+## 工作流程
+1. 先定義安全審查範圍。
+   - 根據目標選擇 `agent-system`、`financial-program`、`software-system` 或 `combined`。
+   - 列出所有不可信輸入、受保護資產、特權操作與關鍵安全不變式。
+   - 在挑選攻擊場景前，先打開對應參考資料，不依賴記憶臆測。
+2. 選擇合適的攻擊目錄。
+   - `agent-system`：聚焦提示注入、間接注入、工具濫用、記憶污染、資料外洩與 agent handoff 攻擊。
+   - `financial-program`：聚焦授權繞過、重放、競態、精度、生命週期、外部依賴與資金流濫用。
+   - `software-system`：聚焦注入、XSS、CSRF、SSRF、路徑穿越、檔案上傳、Session/Token、存取控制與配置錯誤。
+   - `combined`：合併多個目錄，驗證跨邊界的真實攻擊鏈。
+3. 執行可確定的攻擊驗證。
+   - 對每條候選路徑記錄 payload、前置條件、入口點、可觀察結果與能解釋結果的代碼路徑。
+   - 只保留有證據支撐的候選；「看起來像漏洞」不能直接進報告。
+4. 確認或降級。
+   - 對每個候選問題做同路徑二次重現。
+   - 對 parser 邊界、授權檢查、查詢構造、命令執行、資金流與 prompt/tool 路由等熱點補做相鄰變體。
+   - 若第二次重現失敗或證據鏈不足，將其降級為假設或剩餘風險。
+5. 按嚴重度排序並只輸出報告。
+   - 依影響、可利用性與波及範圍從高到低排序。
+   - 交付內容只包含已確認問題、攻擊證據、排序理由、建議性加固方向與剩餘風險。
+   - 若使用者要求修復，先完成本技能報告，再交由實作型技能處理。
+
+## 使用範例
+- 「審查這個 Web API 是否有 SQLi、IDOR、SSRF 和 token 問題」-> 選擇 `software-system`，圍繞輸入邊界、查詢構造與授權控制執行可重現驗證。
+- 「審查這個帶 retrieval、memory 和 tool call 的 agent」-> 選擇 `agent-system`，聚焦提示注入、間接注入、工具濫用、資料外洩與記憶污染。
+- 「審查結算、清算或餘額流程是否能被 replay、race 或 precision abuse 利用」-> 選擇 `financial-program`，優先驗證資金守恆、生命週期原子性與精度邊界。
+- 「幫我看 prompt injection 能不能一路打到特權 API」-> 選擇 `combined`，設計跨 agent 與後端邊界的真實攻擊鏈。
+- 「這裡可能有 SQLi，但我只有模糊直覺」-> 若沒有二次重現與精確參數路徑，只能在報告中標記為假設，不能算作已確認漏洞。
+
+## 參考資料索引
+- `references/agent-attack-catalog.md`：AI agent 安全攻擊目錄，涵蓋直接/間接注入、工具濫用、記憶污染、資料外洩與 handoff 攻擊。
+- `references/security-test-patterns-agent.md`：AI agent 安全測試模式，用於描述驗證思路與後續補強方向。
+- `references/red-team-extreme-scenarios.md`：金融與高風險系統的極端攻擊場景，聚焦重放、競態、生命週期、預言機與安全開關濫用。
+- `references/risk-checklist.md`：金融系統風險檢查清單與嚴重度規則，涵蓋授權、資金完整性、依賴風險與運維控制。
+- `references/security-test-patterns-finance.md`：金融系統安全測試模式，涵蓋 replay、授權、精度、陳舊資料與狀態機失敗。
+- `references/common-software-attack-catalog.md`：通用軟體與 Web/API 攻擊目錄，涵蓋主流注入、瀏覽器端與存取控制問題。
+- `references/test-snippets.md`：可重現 payload 與測試模板範例，用於補充報告中的攻擊形狀與驗證描述。

package/docs-to-voice/SKILL.md

@@ -44,41 +44,14 @@ description: Convert text and document content into audio files and sentence-lev
 6. Return completion details.
    - Report absolute output audio path.
 
-## Script Reference
+## CLI reference
 
-`apltk docs-to-voice` flags:
-
-- `--project-dir` (required)
-- `--project-name` (optional)
-- `--text` or `--input-file` (exactly one required)
-- `--env-file` (optional, default: `skill_dir/.env`)
-- `--mode` (`say|api`, optional)
-- `--voice` (optional, say mode)
-- `--rate` (optional, say mode)
-- `--speech-rate` (optional, post-process speed multiplier)
-- `--api-endpoint` (optional, api mode)
-- `--api-model` (optional, api mode)
-- `--api-voice` (optional, api mode)
-- `--max-chars` (optional, auto chunking threshold for long text)
-- `--output-name` (optional)
-- `--no-auto-prosody` (optional, say mode)
-- `--force` (optional)
-
-Environment variables:
-
-- `DOCS_TO_VOICE_MODE`
-- `DOCS_TO_VOICE_VOICE`
-- `DOCS_TO_VOICE_API_ENDPOINT`
-- `DOCS_TO_VOICE_API_MODEL`
-- `DOCS_TO_VOICE_API_VOICE`
-- `DOCS_TO_VOICE_MAX_CHARS`
-- `DOCS_TO_VOICE_SPEECH_RATE`
-- `DASHSCOPE_API_KEY`
+Use `apltk docs-to-voice --help` as the live command reference for required inputs, mode-specific flags, environment variables, examples, and expected output paths.
 
 ## Troubleshooting
 
 - `say` mode: confirm `command -v say` and `command -v python3`.
 - `api` mode: confirm `command -v python3` and valid `DASHSCOPE_API_KEY`.
 - Long-text chunk merge (especially AIFF output): recommend `command -v ffmpeg`.
-- If output exists, use `--force` or a new `--output-name`.
+- If output exists, use the overwrite or rename options shown in `apltk docs-to-voice --help`.
 - `scripts/docs_to_voice.sh` is kept as a compatibility wrapper for existing workflows, but prefer `apltk docs-to-voice`.

package/enhance-existing-features/SKILL.md

@@ -1,77 +1,56 @@
 ---
 name: enhance-existing-features
 description: >-
-  Extend brownfield systems only after reading the real modules involved: choose **`generate-spec`**/`recover-missing-plan` when user-visible scope, ambiguity, coordination, or sensitive flows demand written approval; otherwise implement directly but still run **`test-case-strategy`** on every non-trivial delta (property/adversarial/integration as risk dictates) and never check off plans without commit+test evidence.
-  Use for backlog work that mutates production behavior; reroute pure regressions, copy/style-only tweaks, or single-pocket config nits that restore documented intent without new surface area.
-  Bad: multi-service permission change with zero spec… Good: contract captures external API limits + property tests cover invariants… Single-file pagination fix matching README → targeted regression only…
+  用於在既有系統上增強或調整產品行為。必須先讀懂實際受影響的模組，再決定是直接實作，
+  還是先走 `generate-spec` / `recover-missing-plan`；所有非平凡變更都要經過 `test-case-strategy`。
 ---
 
-# Enhance Existing Features
+# 增強既有功能
 
 ## Dependencies
 
-- Required: `test-case-strategy` for risk selection, oracles, drift checks.
-- Conditional: **`generate-spec`** when spec triggers below fire; **`recover-missing-plan`** when user-named `docs/plans/...` is missing/archived/mismatched; **`commit-and-push`** when the user requests **git commit** and/or **push** to persist completed work—**MUST** delegate final submission to **`commit-and-push`** (often via **`implement-specs`** / **`implement-specs-with-worktree`** when a spec path is active).
-- Optional: none.
-- Fallback: **`test-case-strategy`** unavailable ⇒ **stop**. Spec path required but **`generate-spec`** unavailable ⇒ **stop**. If the user requested **commit/push** and **`commit-and-push`** is unavailable, **MUST** stop and report.
+- Required: `test-case-strategy`
+- Conditional: `generate-spec`、`recover-missing-plan`、`commit-and-push`
+- Optional: 無
+- Fallback: `test-case-strategy` 不可用時必須停止；需要spec但 `generate-spec` 或 `recover-missing-plan` 不可用時也必須停止；若使用者要求提交或推送但 `commit-and-push` 不可用，必須說明後停止
 
-## Non-negotiables
+## Standards
 
-- **MUST** explore relevant code (entrypoints, flows, integrations) **before** deciding process or editing—**MUST NOT** spec-dump or code-dump from titles alone.
-- Spec path **when** any: new/changed **user-visible** behavior (not mere restore of old intent); ambiguity needing approval; multi-module alignment; critical/sensitive/irreversible/migration risk; traceability materially reduces error.
-- **MUST NOT** open **`generate-spec`** for clearly tiny/localized work: pure regression to prior intent; polish-only UI copy/style; one-area config/constant/flag; narrow CRUD/validation tweak; internal refactor/observability **without** behavior change—**implement + `test-case-strategy` directly**.
-- If specs: **MUST** complete **`generate-spec`** lifecycle (approval before code; backfill after); **≤3 modules** per spec set—split independent non-dependent sets + batch `coordination.md` when coordinated parallelism; **MUST NOT** code pre-approval.
-- **MUST NOT** yield with approved in-scope **`tasks.md`/`checklist.md`** undone except user deferral or documented external blocker (record in plans).
-- **`test-case-strategy` required** for non-trivial deltas—property/adversarial/integration etc. per risk; meaningful oracles; drift check or explicit **`N/A`** with reason per non-trivial logic task.
-- External deps: **`contract.md`** records official-backed obligations when material.
+- Evidence: 先閱讀實際程式碼、整合點與外部文件，再決定流程與修改方案
+- Execution: 探索範圍 -> 判斷是否需要 spec -> 查官方資料 -> 最小實作 -> 測試 -> 回填或總結
+- Quality: 不因怕麻煩而跳過 spec，也不為小改動硬開 spec；只做與需求直接相關的修改
+- Output: 交付符合需求的行為變更、可追溯的測試結果，以及在需要時保持誠實的計劃文件狀態
 
-## Standards (summary)
+## 技能目標
 
-- **Evidence**: Code exploration + official docs/APIs where touched.
-- **Execution**: Explore → decide specs → docs/officials → implement → test → backfill/summary.
-- **Quality**: No speculative scope expansion; reuse patterns.
-- **Output**: Behavior matches ask; traceable tests; plans honest if specs used.
+在不打亂既有系統邊界的前提下，為 brownfield 專案安全地增強功能或調整行為，並用合適的spec流程與測試策略把風險控制在可驗證範圍內。
 
-## Workflow
+## 驗收條件
 
-**Chain-of-thought:** **`Pause →`** after explorations and spec decision—wrong classification wastes days.
+- 在動手前已讀懂受影響模組、入口點、整合邊界與變更爆炸半徑
+- 已正確判斷這次工作是直接實作還是必須先走 `generate-spec` / `recover-missing-plan`
+- 每個非平凡變更都經過 `test-case-strategy`，並留下清楚的 oracle、驗證方式與 `N/A` 理由
+- 若使用了 spec，則批准、實作、回填與真實狀態同步全部完成；若未使用 spec，則最終摘要足以說明風險、測試與限制
 
-### 1) Explore codebase
+## 工作流程
 
-- Map modules, integrations, blast radius.
-  - **Pause →** Can I state **one paragraph** concrete change surface before editing?
+1. 先完整閱讀相關模組、資料流、整合點與現有測試，明確界定這次變更會影響哪些地方
+2. 判斷是否需要spec流程；若涉及新的或改變後的使用者可見行為、跨模組協調、高風險敏感流程、重大歧義，則走 `generate-spec`；如果使用者指定的 plan 路徑缺失或不一致，先用 `recover-missing-plan`
+3. 若不需要 spec，明確說出不開 spec 的理由；若需要 spec，必須等批准後才能改產品程式碼
+4. 查閱變更所依賴的官方文件、API spec或工具文件，尤其是外部整合與契約邏輯
+5. 以最小差異實作需求，不順手做額外重構或範圍擴張
+6. 使用 `test-case-strategy` 選擇單元、回歸、property、integration、E2E 或 adversarial 測試，跑測試並修正失敗
+7. 若使用了 spec，回填 `spec.md`、`tasks.md`、`checklist.md`、`contract.md`、`design.md` 與任何 `coordination.md`；若未使用 spec，輸出簡潔的結果摘要、測試證據與剩餘限制
 
-### 2) Decide specs
+## 使用範例
 
-- Apply Non-negotiable triggers above; if doubt favors **implement-only** **only when** genuinely low-risk localized.
-- If specs: broken path ⇒ **`recover-missing-plan`** then **`generate-spec`** (templates, clarification loop, approval). Parallel batch rules per **`generate-spec`**. If **not** specs: complete step 2 with “no specs” rationale, then continue with steps 3–6 (still run official-doc pass when external surfaces change).
-  - **Pause →** Am I dodging specs just to avoid bureaucracy while scope is multi-team/critical?
+- 「新增一套影響 API、資料庫與 UI 的權限模型」-> 先走 `generate-spec`，批准後再實作，並補上跨層測試
+- 「修正分頁 off-by-one，讓行為回到 README 描述」-> 不開 spec，直接修復並加回歸測試
+- 「目前指定的 `docs/plans/...` 不見了，但使用者要沿著它繼續做」-> 先用 `recover-missing-plan` 還原或重建，再繼續
 
-### 3) Authoritative docs
+## 參考資料索引
 
-- Official docs / Context7 / web for libs used in change.
-
-### 4) Implement
-
-- Minimal diffs preserving behavior unless tasked otherwise; specs ⇒ every in-scope unchecked item delivered; intermediate milestones ≠ user’s final asked outcome unless rescoped.
-
-### 5) Testing (always for non-trivial)
-
-- **`test-case-strategy`**: inventory risk → tests with oracles → run/fix.
-
-### 6) Completion
-
-- With specs: backfill **`spec.md`/`tasks.md`/`checklist.md`/`contract.md`/`design.md`** (+ **`coordination.md`** if batch truth moved). **`spec.md`** requirement status honest. Strip template noise / `N/A` properly.
-- Without specs: concise summary citing tests/results/`N/A` reasons.
-
-## Sample hints
-
-- **Spec yes**: Adds new permission model affecting API+DB+UI—the blast radius crosses layers.
-- **Spec no**: Off-by-one in existing pagination restoring documented behavior—fix + regression test.
-- **Split**: Touches auth, billing, infra—**three plans** capped modules, **`coordination.md`** collision map.
-
-## References
-
-- **`generate-spec`**: planning/backfill lifecycle
-- **`test-case-strategy`**: tests + drift philosophy
-- **`recover-missing-plan`**: heal missing dirs
+- `generate-spec`：需要書面批准時的spec流程
+- `recover-missing-plan`：修復缺失或不一致的計劃檔
+- `test-case-strategy`：非平凡變更的測試選型與 oracle 設計
+- `commit-and-push`：使用者要求提交或推送時的最終交付流程

package/generate-spec/SKILL.md

@@ -1,135 +1,56 @@
 ---
 name: generate-spec
 description: >-
-  Author docs/plans trees: run `apltk create-specs`, fill `spec/tasks/checklist/contract/design`
-  (+ `coordination.md`/`preparation.md` for batches), cite official docs, plan tests via
-  **`test-case-strategy`**, and block code edits until approval. Architecture deltas use
-  `apltk architecture --spec <spec_dir> …`: single specs write under `<spec_dir>/architecture_diff/`,
-  while batch member paths resolve to the shared batch-root `architecture_diff/` beside
-  `coordination.md`; `apltk architecture diff` renders the before/after viewer. Use for
-  drafting/refreshing specs or restructuring batches, not execution. Reject vague `tasks.md`
-  rows and split scope beyond 3 modules.
+  Create or refresh approval-gated planning docs under `docs/plans/...` with
+  `apltk create-specs`, `test-case-strategy`, and optional batch coordination or
+  preparation files. Use for drafting or restructuring specs, not implementation.
 ---
 
-# Generate Spec
-
-## Dependencies
-
-- Required: `test-case-strategy` for risk-driven test selection, oracles, and unit drift-check planning.
-- Conditional: none.
-- Optional: none.
-- Fallback: If `test-case-strategy` is unavailable, **MUST** stop and report it. **MUST NOT** invent local coverage heuristics as a substitute.
-
-## Non-negotiables
-
-- **MUST** read relevant code, config, and authoritative external documentation before writing requirements, contracts, or test plans. When the change depends on frameworks, libraries, SDKs, APIs, CLIs, or hosted services, **MUST** consult **official** documentation during spec creation (required evidence step, not optional).
-- **MUST** generate new or refreshed files from this skill’s **`references/templates/*.md`** via `apltk create-specs` (paths `scripts/...` and `references/...` in this document are **under this skill folder**, not the target project). **MUST NOT** let older `docs/plans/...` layouts override current template headings or required fields; old plans are scope evidence only.
-- **MUST NOT** overwrite or repurpose a neighboring plan directory just because topics overlap; adjacent scope **MUST** get a new `change_name` unless it is the **same** issue/change.
-- **MUST** keep each spec set to **at most three modules** that will be touched. If broader, **MUST** split into multiple spec sets (each ≤3 modules), each independently valid; **MUST NOT** ship one oversized coupled plan.
-- **MUST** use batch-root `preparation.md` **only** for minimal shared prerequisite work that must land before parallel implementation; keep that preparation minimal and free of core business logic or target outcomes (see Working Rules). **`preparation.md` content boundary**: enabling scaffolds, shared fixtures, stubs, mechanical migrations, compatibility surfaces—**no** core business logic, **no** target user-visible outcomes (those stay in normal specs). Exclude core business logic, target business outcomes, user-visible behavior changes, and member-spec implementation guidance; those belong in normal spec files.
-- **`tasks.md` checklist items**: **every** `- [ ]` **MUST** specify (a) concrete file/function target, (b) specific modification and expected outcome, (c) a verification hook—**no** vague rows (`Implement integration`, `Add tests`). Forbidden vague items **MUST** be rewritten before approval.
-- **MUST** use `test-case-strategy` when planning non-trivial logic tests and checklist mapping (test IDs, drift checks). Every **non-trivial** `tasks.md` implementation item **MUST** name a focused unit drift check, another concrete verification hook, or **`N/A`** with a concrete reason.
-- **MUST NOT** modify implementation code before **explicit user approval** of the spec set. Clarifications **MUST** sync across affected files and **MUST** re-trigger approval. If scope becomes a **different issue**, **MUST** stop editing the old set and create a **new** `change_name`.
-- **MUST** when the proposed change touches the architecture surface (feature / sub-module add / rename / remove, edge add / remove, variable rows, function I/O rows, internal dataflow / error deltas), declare the proposed-after state **only** through `apltk architecture --spec <spec_dir> …` using the exact verbs, subverbs, and flags from **`apltk architecture --help`** (this file must not be treated as the command list). The CLI writes overlay YAML to `<spec_dir>/architecture_diff/atlas/` and renders only the affected proposed-after HTML pages under `<spec_dir>/architecture_diff/` for single-spec plans. For batch plans, passing any member spec path to `--spec` resolves to the shared batch-root overlay beside `coordination.md`, so the whole batch maintains **one** `architecture_diff/atlas/` and **one** rendered architecture diff. **`apltk architecture diff`** then builds a paginated **before/after viewer**: it walks every `docs/plans/**/architecture_diff/` tree, pairs each overlay HTML path with the matching file under `resources/project-architecture/` when it exists, and labels pages **modified**, **added**, or **removed** (via `_removed.txt` / removal manifests) so reviewers can scroll the whole architecture delta without opening files by hand. **MUST NOT** hand-author anything under `architecture_diff/**` — the renderer owns layout, DOM, CSS, ARIA, and pan/zoom. Use this skill’s `references/TEMPLATE_SPEC.md` for field/enum schema; use `init-project-html/SKILL.md` for semantic rules (**subagent gate** + edge kinds + dataflow integrity). When using subagents to draft atlas overlay, the authoring agent **MUST** wait until **all** feature subagents finish before declaring cross-feature **`edge`** (or overlay **`meta`** / **`actor`** that only exists to stitch features), matching `init-project-html` / `spec-to-project-html`.
-- Write prose in the **user’s language** by default; keep requirement/task/test IDs traceable across `spec.md`, `tasks.md`, and `checklist.md`.
-- **MUST** use **kebab-case** `change_name`; **MUST NOT** use spaces or arbitrary special characters in names.
-
-## Standards (summary)
-
-- **Evidence**: Official docs when externally constrained; record cites in `spec.md` / `contract.md`.
-- **Execution**: Scaffold → fill templates in place → clarification loop → approval gate → (later) backfill after implementation.
-- **Quality**: Synchronized artifacts; **`tasks.md`** is unique runnable granularity; **`design.md`/`contract.md`** constrain and orient without mirroring checklist rows—**`TBD`/honest `None`** when facts missing.
-- **Output**: `docs/plans/{YYYY-MM-DD}/{change_name}/` or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/`; batch root `coordination.md` when intentionally parallel; `preparation.md` only when prerequisite batch work is required first.
-
-## Workflow
-
-**Chain-of-thought:** For every subsection **`N)`**, answer **`Pause →`** prompts before scaffolding or authoring the next subsection; unanswered external constraints or ambiguous scope mean **stop** or **loop** clarifications—not silent drafting.
-
-### 1) Inputs and evidence
-
-Confirm workspace root, feature title, kebab-case `change_name`. Review minimal code/config. **Mandatory** official-doc pass when external systems apply; note sources for `spec.md` / `contract.md`. Inspect existing `docs/plans/`—reuse a set **only** when it matches **this** issue; otherwise create a new directory.
-   - **Pause →** Which **official** URLs or docs did I actually consult for each external dependency I plan to cite—URLs not opened are not citations?
-   - **Pause →** Is the user ask the **same** issue as an existing nearby plan—or only **adjacent**, requiring a **new** `change_name`?
-   - **Pause →** What is the smallest set of repo paths whose behavior I **must** read before writing requirements truthfully?
-
-### 2) Scaffold planning files
-
-Identify concrete modules (≤3 per set; split if needed). Resolve shared collision: merge spec sets, additive-only ownership rules in `coordination.md`, or `preparation.md` when one-time shared prep is the only safe path.
-
-Run from this skill’s context (templates resolved from this skill dir):
-
-```bash
-WORKSPACE_ROOT=<target_project_root>
-apltk create-specs "<feature_name>" --change-name <kebab-case> --output-dir "$WORKSPACE_ROOT/docs/plans"
-```
-
-Multi-spec parallel batch: add `--batch-name <kebab-case>` and `--with-coordination`. **Only** if parallel safety needs prior shared work: add `--with-preparation`.
-
-Always materialize: `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md` from `references/templates/`. Add `coordination.md` / `preparation.md` at batch root only when flags require. Save under `docs/plans/{YYYY-MM-DD}/...`. After generation, fill in place **without** stripping section headings unless truly N/A (document inline); drop unused repeatable blocks (extra component or dependency stubs). Run a **template-drift pass** before approval: required fields covered, placeholders removed or justified.
-   - **Pause →** List the **module names** (≤3) this spec set will touch; if more, where is my **split plan**?
-   - **Pause →** For every shared file two specs might touch, where is the **named** resolution in `coordination.md` or why is `preparation.md` required instead?
-   - **Pause →** Did I run `apltk create-specs` from the **skill** context so template paths resolve correctly?
-
-### 3) Author content (fill templates)
-
-- **`spec.md`**: Concrete scope; BDD (`GIVEN` / `WHEN` / `THEN` / `AND` / `Requirements`); testable requirements; boundaries, auth, failure, idempotency/concurrency/integrity where relevant; doc references; `3-5` clarification questions or `None`.
-- **`tasks.md`**: `## **Task N: [Title]**` with Purpose, Requirements, Scope, Out of scope; atomic `- N [ ]` triple (path · change · verify). **Derive sequencing and decomposition from** **`spec.md` + `design.md` + `contract.md`**; **`tasks.md` stays the only enumerated runnable checklist**. Optionally cite **`INT-###` / `EXT-###`** on rows an anchor constrains—and **keep design/contract coarser**, never a second copy of checklist lines. Integrate `test-case-strategy` for drift checks where needed.
-- **`contract.md`**: Cite-backed **external facts / limits / failure semantics / security**, plus **`EXT-###`** integration **anchors** (typically fewer rows than **`tasks.md` items)—**constraints and anti-hallucination context**, **not** a parallel implementation runbook (`TBD` instead of guesses; **`Dependencies` → None** when genuinely no externals).
-- **`design.md`**: **High-level architectural context for composing `tasks.md`**—baseline/target shape, boundaries, modules, **`INT-###`** coarse coupling/order hints (`task` granularity lives only in **`tasks.md`**). No file-level chores; batches defer ownership grids to **`coordination.md`**; **`preparation.md`** assumed done—don't replay prep execution here.
-- **`coordination.md`** (batch root, parallel only): **Business Goals** (outcome, member specs, parallel readiness, exclusions, blockers → `preparation.md` or list); **Design Principles** (baseline, shared invariants, compat, cleanup—high level); **Spec Boundaries** → **Ownership Map** (allowed/forbidden touchpoints per spec) and **Collisions & Integration** (shared-file rules, freeze owners, merge order, checkpoints, re-coordination trigger)—**every** collision candidate **MUST** have a named resolution.
-- **`preparation.md`** (batch root, only if required): Preparation Goal (why, no core business logic, dependents, start condition); **Task P[N]** like `tasks.md` (atomic triple items); **Validation**; **Handoff** (assumptions, must-not-change, if prep changes later). Strip duplicate prep from member specs.
-- **`checklist.md`**: `- [ ]` adapted to scope; map behaviors to requirement/test IDs via `test-case-strategy`; behavior lines `[CL-xx]: … — R?.? → [Test IDs] — Result: …`; property-based logic **required** unless `N/A` + reason; honest execution/completion records—**no** checking unused examples or unchosen options.
-   - **Pause →** Pick one **random** `tasks.md` checkbox: does it still fail the triple rule (target, change, verify)—if yes, rewrite now?
-   - **Pause →** Does every **R** requirement ID I care about appear in `tasks.md` or `checklist.md` with a test or explicit `N/A`?
-   - **Pause →** Do **`design.md` / `contract.md`** stay **coarser than `tasks.md`** (no mirrored checkbox choreography / file paths)—yet still constrain ordering and forbidden hallucinations?
-   - **Pause →** For parallel batches, does `design.md` **avoid** duplicating batch ownership grids already locked in **`coordination.md`**?
-
-### 3.5) Architecture overlay + diff viewer (only when the proposal touches the architecture surface)
-
-When the spec changes a feature module, sub-module, edge, variable row, function I/O row, internal dataflow, or error row:
-
-**Completion standard:** the overlay is not complete until every intended cross-feature **edge**, every feature-to-feature dependency or call/return relationship, and every sub-module-to-sub-module relationship inside the affected scope has been declared precisely through the CLI. It is **not** acceptable to leave relationship structure implied only by prose in `spec.md` / `design.md`; the architecture diff must explicitly express the real proposed-after topology.
-
-1. **Discover commands:** run **`apltk architecture --help`** in the target workspace; use that output for every `add` / `set` / `remove` / `reorder` spelling and required flag. Do not copy long command tables from skills — they go stale.
-2. **Declare proposed-after state** with `apltk architecture --spec <spec_dir> …` for each mutation (pass `--no-render` while batching if you prefer a single render at the end). In a batch, keep using the member spec path; the CLI resolves writes to the batch-root `architecture_diff/` beside `coordination.md`.
-3. **`apltk architecture render --spec <spec_dir>`** — emits/updates only the HTML files touched by this overlay plus assets. In a batch, this updates the shared batch-root render.
-4. **`apltk architecture validate --spec <spec_dir>`** — **MUST** return OK before the spec is approval-ready (resolve dangling edges, unknown enums, bad dataflow references). In a batch, this validates the shared batch-root overlay.
-5. **`apltk architecture diff`** — **MUST** run before hand-off when atlas changed; confirm the paginated viewer shows sensible **modified** / **added** / **removed** counts and that each interesting path pairs correctly (base `resources/project-architecture/…` vs the spec or batch-root `architecture_diff/…`). Use this pass to verify that the rendered graph actually contains the full intended relationship set: all relevant feature-level seams, all required sub-module seams, and no missing edge that the design prose depends on. A page appearing as **remove + add** instead of **modified** usually means a **slug rename** was split wrong — fix with intentional remove+add or a single coherent mutation sequence.
-
-**Where files land:** single-spec plans write overlay YAML under `<spec_dir>/architecture_diff/atlas/` and rendered proposed-after HTML under `<spec_dir>/architecture_diff/`. Batch plans write both under the batch root beside `coordination.md`, even when the CLI call uses a member spec path. Cross-feature edges whose far endpoint exists only in the **base** atlas still resolve when merged — but you **must** `validate` to catch mistakes.
-
-**Subagent coordination:** if multiple features are drafted in parallel, **do not** declare cross-feature **`edge`** (or overlay **`meta` / `actor`** used only to stitch features) until **all** feature workers report done — see `init-project-html/SKILL.md` Rule 3 and `spec-to-project-html`.
-
-**Do not hand-edit** any file under `architecture_diff/`.
-
-- **Pause →** Did I touch any file under `architecture_diff/` by hand? Revert and re-run the CLI verb instead.
-- **Pause →** Does `apltk architecture validate --spec <spec_dir>` return OK?
-- **Pause →** Does `apltk architecture diff` pair the spec’s pages correctly?
-- **Pause →** Have I explicitly declared every intended edge, feature-to-feature relationship, and sub-module relationship in the CLI output, or am I still relying on prose to imply missing structure?
-
-### 4) Clarifications and approval
-
-On answers: update clarification/approval section in `checklist.md` first, then any of `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md`; **MUST** obtain approval again after material edits. **MUST NOT** touch product code pre-approval.
-   - **Pause →** Am I about to “just fix a small bug” in product code before explicit approval—**why is that not a hard stop**?
-   - **Pause →** After the last edit, does the user still owe an **explicit** approval token, or did I assume silence means yes?
-
-### 5) Backfill after implementation
-
-When implementation exists: mark `tasks.md`; sync `checklist.md` outcomes/`N/A`; fix `contract.md` / `design.md` if reality diverged; update `coordination.md` / `preparation.md` if ownership or prep status changed. Checklist complete **only** for work actually done or decisions actually taken; separate rows for divergent flows; remove stale placeholders.
-   - **Pause →** For each checked item, what **evidence** (commit, test log) would a reviewer use to agree it is true?
-   - **Pause →** Did implementation reality change **shared** ownership or prep assumptions—if so, which batch file records that?
-
-## Sample hints
-
-- **`tasks.md` line — bad**: `- [ ] Add tests` → **reject** (no path, change, verifier).
-- **`tasks.md` line — ok (with ledger wiring)**:
-  `- [ ] 2 src/api/handlers/oauth.rs — implement handler path for POST /oauth/token satisfying INT-003, INT-004 · EXT-001 client config loaded from env per contract · Verify: cargo test oauth::handlers::token_exchange`
-- **Batch scaffold** (three member specs): `WORKSPACE_ROOT=... apltk create-specs "OAuth batch" --change-name oauth-api --batch-name oauth-may-batch --with-coordination --output-dir "$WORKSPACE_ROOT/docs/plans"` (then repeat or use generator rules for additional `change-name` dirs as your tooling permits).
-- **`checklist.md` behavior row sketch**: `[CL-01]: invalid token rejected — R2.1 → TU-Scope-01,TU-Scope-02 — Result: pending`
-- **Split-trigger**: change touches `src/auth/*`, `src/cli/*`, `src/db/*`, `infra/terraform/*` (four modules) ⇒ **minimum two spec sets**, not one.
-
-## References
-
-- `test-case-strategy`: test design and drift checks
-- `scripts/create-specs` / `apltk create-specs`: generator
-- `references/templates/spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md`, `coordination.md`, `preparation.md`: binding templates
+## 目標
+將用戶需求轉化為明確、有清晰完成條件的spec。
+
+## 驗收條件
+- 已經產出了嚴格遵循模板格式的spec。
+- 為spec當中的需求制定了明確的驗收條件及測試策略
+
+## 工作流程
+1. 理解用戶需求並閱讀repo
+分析用戶需求，並在repo之中搜索、列出可能相關的內容。完成搜索之後，深入閱讀相關代碼，識別變更範圍。
+如果外部環境存在subagents功能，建議通過調度subagents來完成深入閱讀repo的任務。
+
+2. 拆分用戶需求及設計業務架構
+將用戶需求轉化、拆分為明確、存在邊界的工程需求。結合現有代碼，設計業務架構。在設計的過程中，你需要考慮包括但不限於以下設計事項：
+- 錯誤處理
+- 測試策略
+- 模塊之間的呼叫、回傳
+- 資料流
+在這個階段，如果用戶有任何不清晰的需求，且該需求會影響你的設計方案，你需要紀錄並在稍後填入spec，等待用戶的回答。
+
+3. 將整個設計方案拆分成可執行任務
+將上一步之中你構思的完整設計方案拆分為精確到函式或檔案級別的任務。你必須確保每一個任務都是可以直接執行，且沒有歧義的。以此確保執行設計方案的開發者不會偏離設計方案。
+
+4. 制定驗收條件
+為任務制定基於測試的驗收條件，確保每一個任務在完成之後都能夠被驗證。
+同時，為需求制定驗收條件，確保用戶需求能夠被測試清晰地驗收、檢驗成果。
+
+5. 使用 `apltk` cli工具協助完成spec
+使用cli工具，產生spec的模板。將你的完整計劃填入到模板之中，並通過cli工具生成完整架構圖讓用戶審閱。
+如果該spec設計超過三個模塊，則需要創建batch spec。
+
+## 範例
+- "製作一個網頁德州撲克小遊戲" -> "拆分成多個模塊：遊戲本體邏輯、前端頁面渲染、前端頁面交互邏輯；制定單元測試、整合測試等策略，並製作一份單一的spec指導實作工作。"
+- "提升現有系統的性能" -> "識別目前repo之中拖累性能的代碼。製作batch spec文檔，將repo的全量優化拆分為以三個模塊為一組的優化。對於必須改動業務邏輯才可以做到的性能提升，填寫clarification questions，並等待用戶回答之後更新spec。"
+
+## 參考資料
+- `scripts/create-specs` - `apltk create-specs` 背後使用的模板產生器。
+- `references/templates/spec.md` - `spec.md` 的綁定模板。
+- `references/templates/tasks.md` - `tasks.md` 的綁定模板。
+- `references/templates/checklist.md` - `checklist.md` 的綁定模板。
+- `references/templates/contract.md` - `contract.md` 的綁定模板。
+- `references/templates/design.md` - `design.md` 的綁定模板。
+- `references/templates/coordination.md` - batch root 的 coordination 模板。
+- `references/templates/preparation.md` - batch root 的前置工作模板。
+- `references/TEMPLATE_SPEC.md` - `apltk` cli工具相關格式指引。
+- `test-case-strategy/SKILL.md` - 測試策略選擇技能。
+- `apltk create-specs --help` - spec生成相關cli工具的指引命令
+- `apltk architecture --help` - 架構圖生成相關cli工具的指引命令

package/generate-spec/references/templates/coordination.md

@@ -9,7 +9,6 @@
 
 - Batch members: [[spec-name-1], [spec-name-2]]
 - Shared outcome: [what the batch delivers when all spec sets land]
-- Parallel readiness: [Yes / No; if No, list blocking items or link to preparation.md]
 - Out of scope: [shared exclusions for the batch]
 
 ## Design Principles