@laitszkin/apollo-toolkit 3.11.8 → 3.12.0

package/CHANGELOG.md

@@ -10,6 +10,21 @@ All notable changes to this repository are documented in this file.
 
 ### Fixed
 
+## [v3.12.0] - 2026-05-13
+
+### Added
+
+- `maintain-project-constraints` now ships `references/constraint-file-reference.md`, a shared contract/checklist/template for keeping root `AGENTS.md` / `CLAUDE.md` limited to the three required sections.
+
+### Changed
+
+- Rewrite a broad set of shipped skills into a more compact Chinese-first structure built around explicit goal, acceptance, workflow, examples, and reference sections, covering documentation alignment, submission/release, planning, implementation, review, debugging, testing, security, and architecture-atlas workflows.
+- Simplify supporting references and wording across the catalog to prefer `repo` / `spec` terminology, point `maintain-project-constraints` at its new shared reference file, and tighten example phrasing in `optimise-skill` plus the standardized docs template.
+
+### Removed
+
+- Remove the now-redundant `archive-specs` reference templates for `architecture`, `docs-index`, `features`, and `principles` after delegating standardized documentation structure guidance to `align-project-documents`.
+
 ## [v3.11.8] - 2026-05-12
 
 ### Added

package/align-project-documents/SKILL.md

@@ -1,86 +1,37 @@
 ---
 name: align-project-documents
-description: >-
-  Regenerate standardized tree `docs/features` (BDD zero code paths), `docs/architecture` (macro layer rules), `docs/principles` (evidence-backed conventions) after reading the ENTIRE production codebase—legacy scattered Markdown must migrate or be removed before finish then invoke **`maintain-project-constraints`** so AGENTS/CLAUDE indexes match disk.
-  Use for repo-wide doc realignments (“rebuild project docs from code”)—skip for single-file README nitpicks unless user explicitly requests full regeneration.
-  Violation examples: features mentioning `src/foo.ts`… acceptable feature: “Given signed-in user When export Then CSV downloads”… architecture stays stable if module renamed internally…
+description: 整理及維護項目文檔。當你需要管理項目說明文檔時，使用此技能。
 ---
 
-# Align Project Documents
+## 目標
 
-## Dependencies
+以整個生產repo為唯一主證據，建立或維護標準化的 `docs/features/`、`docs/architecture/`、`docs/principles/`，清理已失效或重複的舊文檔，並在完成後同步刷新根目錄約束文件。
 
-- Required: `maintain-project-constraints` after `docs/` work to refresh `AGENTS.md`/`CLAUDE.md` and the doc index.
-- Conditional: none.
-- Optional: none.
-- Fallback: If `maintain-project-constraints` cannot run, **MUST NOT** pretend the constraints files are refreshed—report the gap.
+## 驗收條件
 
-## Non-negotiables
+- repo的所有細節被仔細閱讀並轉化為標準化的 `docs/features/`、`docs/architecture/`、`docs/principles/`，以及同步後的 `AGENTS.md` / `CLAUDE.md`。
+- 舊的非標準文檔已被遷移、合併或移除。
 
-- **MUST** read the **entire** codebase (all meaningful source/config/test entrypoints—not a single-folder sample) **before** writing category docs; code is sole truth—existing prose is corroborating only.
-- **MUST NOT** ship `docs/features/` bullets that cite file paths, function names, or implementation detail—user-facing **BDD** only (`Given` / `When` / `Then`).
-- **`docs/architecture/`** stays **macro** (layers, boundaries, data-flow direction)—**MUST NOT** document code that will rot on every refactor.
-- **`docs/principles/`** **MUST** remain traceable to **concrete** repo patterns (with examples)—not aspirational platitudes without evidence.
-- **MUST** create or refresh `docs/features/`, `docs/architecture/`, `docs/principles/` with categorized files; **MUST** remove or migrate stale non-conforming docs (**MUST NOT** leave mixed legacy layout alongside new structure indefinitely).
-- **MUST** invoke **`maintain-project-constraints`** after category docs stabilize so `AGENTS.md`/`CLAUDE.md` indexes match disk.
-- Default doc **language**: match user preference or repo’s dominant README/docs language consistently per run.
+## 工作流程
 
-## Standards (summary)
+### 1. 建立對repo的基線認知
 
-- **Evidence**: Paths and reads logged while building claims; contradictory old docs flagged, not blindly merged.
-- **Execution**: Whole repo read → ingest old docs → write three pillars → prune → constraints refresh.
-- **Quality**: Features user-only; architecture stable abstractions; principles evidence-backed.
-- **Output**: Standardized tree + synced agent constraint files.
+閱讀項目現有文檔，建立對repo的初步理解，並將其作為對repo的基線認知，制定後續的閱讀策略
 
-## Target structure
+### 2. 比對repo及項目文檔
 
-```
-docs/
-├── features/       — User-facing capability, BDD only (no code paths)
-├── architecture/   — Layers/modules, boundaries, integration contracts (macro)
-└── principles/     — Style, tooling, conventions with codebase examples
-```
+按照上一步建立的閱讀策略，全面搜索、查找整個repo，驗證並確保現有項目文檔的描述正確、無遺漏。
+如果外部環境存在subagents功能，建議調度subagents完成對repo的閱讀。
 
-Extended rules and checklist: `references/templates/standardized-docs-template.md`.
+### 3. 制定文檔更新策略
 
-## Workflow
+根據上一步找到的所有遺漏或項目文檔與實際代碼脫節之處，制定文檔更新策略。將所有項目文檔更新為符合模板格式的標準化文檔，並移除除必要文檔（如 `CHANGELOG.md`, `CONTRIBUTION.md` ）外的舊有說明文檔。
 
-**Chain-of-thought:** **`Pause →`** after each major phase; ambiguity on “user-visible” vs “internal” ⇒ re-read callers before classifying.
+## 範例
 
-### 1) Read entire codebase
+- "根據當前repo重建整套專案文檔。" -> "完整讀碼後重建三類標準文檔，清理舊文檔並同步刷新 `AGENTS.md` / `CLAUDE.md`。"
+- "這個倉庫的 docs 很散，請重新對齊成統一結構。" -> "把可保留內容遷入 `docs/features/`、`docs/architecture/`、`docs/principles/`，移除重複或失效文件。"
+- "我要的不是 README 小修，而是整個文檔體系重整。" -> "以全倉庫證據為基礎重建標準化文檔樹，而不是只修改單一說明文件。"
 
-- Cover entrypoints (CLI/server/workers), public surfaces, boundaries, configs, integrations, tests as behavior specs.
-- Keep an **evidence notebook** (paths) for principles and architecture—not for features text.
-  - **Pause →** Did I skip generated/vendor/`node_modules`/binary blobs incorrectly included as “must read”?
-  - **Pause →** Can I name the **top five** externally visible behaviors from code alone?
-
-### 2) Read existing prose
-
-- List `README.md`, `docs/**`, `CONTRIBUTING.md`, etc.; extract facts that code confirms; flag obsolete sections.
-  - **Pause →** Where did I treat Markdown as authoritative over a contradicted implementation?
-
-### 3) Generate three pillars
-
-- **features/**: categories → one markdown per category → BDD scenarios only.
-- **architecture/**: one file per layer/module cluster → boundaries and flows, stable wording.
-- **principles/**: split files (`naming-conventions.md`, etc.) → each point ties to observable repo habit.
-  - **Pause →** Random feature paragraph: grep for `./src` or `` ` `` — if found, rewrite for user observable outcome only.
-
-### 4) Remove non-conforming legacy
-
-- Delete or migrate files fully superseded; if uncertain, **keep** file list in report as migration backlog — **do not** silently duplicate two competing truths forever.
-
-### 5) Refresh constraints
-
-- Run **`maintain-project-constraints`** so Commands / Business Goals / Doc Index mirror new files.
-
-### 6) Gates before finish
-
-- No code paths in features; architecture still macro after imagined small refactor; principles cite real examples; index lists every file under the three dirs; constraints skill executed.
-
-## Sample hints
-
-- **Feature OK**: “Given a signed-in user When they export Then a CSV download starts” — no `handlers/export.rs` references.
-- **Feature bad**: “Call `ExportService.run` …” — violates Non-negotiables (implementation leak).
-- **Architecture OK**: “API layer handles I/O only; domain module owns business rules” — stable across internal renames.
-- **Principle OK**: “TypeScript files use kebab-case — see `src/user-profile/`” — traceable pattern.
+## 參考資料
+- `references/templates/standardized-docs-template.md` - 三類文檔的目標結構、分類規則與清理檢查表。

package/align-project-documents/references/templates/standardized-docs-template.md

@@ -86,7 +86,7 @@ Every principles file must:
 
 **理由**: <為什麼採用此慣例>
 
-**範例**: <從代碼庫提取的具體範例>
+**範例**: <從repo提取的具體範例>
 ```
 
 ### Principles classification guide

package/archive-specs/SKILL.md

@@ -1,86 +1,34 @@
 ---
 name: archive-specs
-description: Convert completed project plan sets into maintainable project documentation and archive the consumed planning files. Use when users want to consolidate `spec.md`/`tasks.md`/`checklist.md`/`contract.md`/`design.md` and any batch-level `coordination.md` into the standardized docs/features/, docs/architecture/, docs/principles/ structure, then refresh AGENTS.md/CLAUDE.md via maintain-project-constraints.
+description: 將已完成的spec歸檔到 `docs/archive/` 下。當你需要將spec歸檔時，調用這個技能。
 ---
 
-# Archive Specs
+## 技能目標
 
-## Dependencies
+把已完成的規劃文件轉成專案的長期文檔資產，讓正式文件反映目前真實系統，而活動中的 planning artifacts 與已消耗完的 spec 能被清楚分離。
 
-- Required: `align-project-documents` to generate and align the standardized project documentation under `docs/features/`, `docs/architecture/`, and `docs/principles/`, and `maintain-project-constraints` to refresh `AGENTS.md`/`CLAUDE.md` with the updated business goals and documentation index after the doc update.
-- Conditional: none.
+## 驗收條件
 
-## Standards
+- `docs/plans/` 目錄下不存在任何完成但未歸檔的spec
+- 所有項目文檔已經被維護至最新狀態，對齊repo實作。
 
-- Evidence: Treat code, config, deployment files, and current spec files as evidence sources; never guess when a detail is missing.
-- Execution: Inventory all relevant specs first, reconcile them with the current repository, delegate documentation generation to `align-project-documents`, delegate `AGENTS.md`/`CLAUDE.md` refresh to `maintain-project-constraints`, then archive only the truly consumed planning artifacts.
-- Quality: Prefer source-of-truth behavior over stale plan text, align existing docs to the standardized three-category structure, and call out unknowns explicitly instead of inventing missing setup details.
-- Output: Produce synchronized standardized docs under `docs/features/`, `docs/architecture/`, and `docs/principles/`, a concise `README.md` when appropriate, and an up-to-date `AGENTS.md`/`CLAUDE.md`, then archive or remove superseded spec files after conversion is complete.
+## 工作流程
 
-## Goal
+### 1. 盤點現有spec的完成狀態
 
-Convert completed planning artifacts into the standardized project documentation structure, refresh the project constraint files, then archive the consumed specs so active planning files stay separate from durable project docs.
+在 `docs/plans/` 目錄下找到現有的所有spec。閱讀每一份spec的 `checklist.md`, `tasks.md`, `spec.md` 並檢查當中的markdown checkboxes是否被全部勾選為完成（除與任務無關的checkboxes外，比如spec的批准狀態）。
+將 `checklist.md`, `tasks.md`, `spec.md` 三份文檔checkboxes皆完成勾選的spec標記為已完成。
 
-## Workflow
+### 2. 歸檔spec並更新項目文檔
 
-### 1) Inventory documentation sources
+使用 `align-project-documents`, `maintain-project-constraints` 技能，按照這兩個技能之中的指引，更新項目文檔。並將完成的spec全部移動到 `docs/archive/`。
 
-- Find all relevant planning files such as `docs/plans/**/spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md`, and any batch-level `coordination.md`.
-- Read existing `README*`, `docs/**`, deployment scripts, manifests, env examples, infra files, CI configs, and representative source modules.
-- Build a source map for implemented features, module boundaries, external services, and configuration details.
+## 使用範例
 
-### 2) Reconcile spec claims with the current repository
+- "這批 spec 已經實作完成，幫我整理成正式文件並歸檔" -> "先同步 `docs/` 與 `AGENTS.md` / `CLAUDE.md`，再把已完成的 spec 移到 archive"
+- "只有批次中的兩個子 spec 做完，另外一個還在進行" -> "只歸檔完成的子目錄，保留仍在使用的 `coordination.md`"
+- "spec 寫了未來計畫，但 repo 還沒實作" -> "不把該內容當成正式文件，只在需要時標成 `TBD` 或保留在 active planning"
 
-- Treat source priority as:
-  1. current code, config, and deployment files
-  2. current tests and automation scripts
-  3. recent specs that still match the implementation
-  4. existing docs
-- When specs disagree with the codebase, keep the codebase truth and note the mismatch while updating docs.
-- Merge repeated or overlapping feature descriptions into one stable capability summary.
-- Use `coordination.md` to understand shared preparation, ownership boundaries, legacy cutover direction, and which old features or paths were intentionally replaced across multiple spec sets.
-- Distinguish between completed scope that should become durable docs and still-active scope that remains planning material for follow-up work.
+## 參考資料索引
 
-### 3) Delegate documentation generation to align-project-documents
-
-- Hand the full documentation rewrite/alignment work to `align-project-documents`.
-- `align-project-documents` will read the entire codebase, generate standardized documentation under `docs/features/` (BDD-described user-facing capabilities), `docs/architecture/` (macro-level design principles by module), and `docs/principles/` (code style, naming conventions, development constraints), and remove old non-conforming documentation.
-- Provide `align-project-documents` with the reconciled spec findings from step 2 as supplementary context.
-
-### 4) Refresh AGENTS.md/CLAUDE.md via maintain-project-constraints
-
-- After `align-project-documents` has completed the documentation update, invoke `maintain-project-constraints`.
-- `maintain-project-constraints` will read the updated `docs/` structure, extract macro business goals, inventory common development commands, build the project documentation index, and write or update `AGENTS.md`/`CLAUDE.md` with exactly three sections: Common Development Commands, Project Business Goals, and Project Documentation Index.
-- If both `AGENTS.md` and `CLAUDE.md` exist, `maintain-project-constraints` will keep their content consistent.
-
-### 5) Keep README short and the doc set navigable
-
-- If `README.md` does not exist or is outdated, create or update it as a short project overview with a link to the documentation index in `AGENTS.md`/`CLAUDE.md`.
-- Do not duplicate content that belongs in `docs/`.
-
-### 6) Archive superseded spec files after successful conversion
-
-- After the standardized project docs are complete and verified, archive the old source spec files that were converted.
-- Prefer moving the consumed `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md`, and when applicable their shared `coordination.md`, or the containing batch/spec plan directory, into a clearly marked archive path instead of leaving them mixed with active docs.
-- Delete converted spec files only when the repository clearly does not need historical retention.
-- Do not archive or delete any spec file that is still actively needed for unfinished implementation work.
-- Treat a spec file as active when it still records pending gaps, planned later phases, follow-up integration work, or unresolved design decisions for the same change, even if one implementation commit has already shipped.
-- If only part of a plan set is complete, convert or summarize only the truly completed scope and leave the active plan set in place unless the repository has a separate archival convention for partial phases.
-- If only part of a coordinated batch is complete, archive only the fully consumed spec subdirectories and keep the batch-level `coordination.md` active until no remaining spec set relies on it.
-
-## Working Rules
-
-- Prefer the user's language unless the repository clearly uses another documentation language.
-- Do not copy speculative roadmap items from specs into the main docs as if they already exist.
-- When a section cannot be completed from evidence, keep an explicit `Unknown` or `TBD (missing repository evidence)` marker.
-- The final repository state should not keep both standardized docs and redundant active spec files for the same completed scope.
-- Do not equate "code was committed" with "planning scope is complete"; archive only when the remaining notes no longer guide future implementation.
-- Do not archive a batch `coordination.md` while it still governs active replacement work, shared field preparation, or unresolved cross-spec merge sequencing.
-
-## References
-
-- `references/templates/readme.md`: concise project overview template.
-- `references/templates/docs-index.md`: categorized project-doc index and reference list template.
-- `references/templates/features.md`: template for `docs/features/` BDD-described feature documentation.
-- `references/templates/architecture.md`: template for `docs/architecture/` macro-level design principles.
-- `references/templates/principles.md`: template for `docs/principles/` code conventions and development constraints.
+- `references/templates/readme.md`：README.md 模板

package/commit-and-push/SKILL.md

@@ -1,72 +1,44 @@
 ---
 name: commit-and-push
-description: >-
-  Commit and push only (no semver): inspect staged vs unstaged, classify scopes, run the mandated `review-change-set` for code-affecting scope, then **`submission-readiness-check`** BEFORE the final commit honoring `CHANGELOG.md` Unreleased + `archive-specs` redirections, preserve intentional staging splits, forbid UI git stubs, VERIFY remote hashes post-push. **`version-release` elsewhere**.
-  Use for “please commit”, “submit”, “push branch” lacking explicit semver/tag language **STOP** tagging here… BAD skip readiness red… GOOD staged subset untouched unrelated dirty files changelog mirrors diff… hashes `git rev-parse HEAD` versus upstream… archive specs before commit flagged…
+description: 提供提交指引以及作為提交前的必要品控閘門。當你需要將變更提交到git repo或者是推送到remote，使用這個技能。
 ---
 
-# Commit and Push
+## 目標
 
-## Dependencies
+在不破壞使用者既有工作樹與提交邊界的前提下，安全地完成本地 commit 與可選 push，並確保所有提交前的審查、文件同步與 changelog 門檻都已真正完成。
 
-- Required: **`submission-readiness-check`** immediately before the **final** commit.
-- Conditional: **`archive-specs`** when readiness (or completed specs) requires doc conversion or categorized `docs/` alignment; **`review-change-set`** for every **code-affecting** scope.
-- Optional: none.
-- Fallback: Any **required** dependency unavailable ⇒ **MUST** stop and report—**MUST NOT** “light” commit.
+## 驗收條件
 
-## Non-negotiables
+- 所有暫存的變更已經被提交和推送到remote
 
-- **MUST** use real `git` mutations (`git add`, `git commit`, `git push`, `git stash`, etc.); **MUST NOT** treat UI tokens (`::git-commit`, IDE buttons) as proof of history.
-- **MUST** run **`submission-readiness-check`** before final commit; unresolved readiness (e.g. stale/missing `CHANGELOG.md` **Unreleased**, doc drift) **blocks** commit.
-- Code-affecting: **`review-change-set` MANDATORY**; unresolved confirmed findings **block**.
-- **`archive-specs`**: when readiness says convert/archive or `docs/` mismatch—**MUST** run **before** final commit, not as a vague follow-up.
-- **MUST** reconcile **staged vs unstaged** with user intent—**MUST NOT** broaden scope by auto-staging unrelated files when user staged a subset.
-- **`CHANGELOG.md` `Unreleased`**: for code-affecting or user-visible docs, **MUST** reflect this change before commit; reopen diff after edits to match commit scope.
-- **MUST** resolve **target branch** per user (or current if explicit) before rewriting history; protect unrelated dirty work (`stash` etc.); **no** force-push unless user explicitly requests.
-- After **push**, **MUST** verify remote tip matches local `HEAD` (`git rev-parse` / `@{u}` / `ls-remote`) before claiming success.
-- **MUST NOT** run version bump, tag, or GitHub release (**use `version-release`**).
-- Clean worktree requests: **MUST** inspect `HEAD`, upstream, last commit—**MUST NOT** fabricate “pushed” when already satisfied or impossible.
+## 工作流程
 
-**Repository regression checks (verbatim requirements):** Treat root `CHANGELOG.md` `Unreleased` coverage as mandatory for code-affecting or user-visible changes. Re-open the final `CHANGELOG.md` diff after readiness updates. **`review-change-set` is required for code-affecting changes**; Run `review-change-set` for every code-affecting change before continuing; treat unresolved review findings as blocking. Any conditional gate whose trigger is confirmed by this classification becomes mandatory before commit. Treat every scenario-matched gate as blocking before commit.
+### 1. 檢查變更狀態
 
-## Standards (summary)
+檢查目前的git變更狀態。識別變更範圍及確認目前暫存變更之中是否包含代碼變更。
 
-- **Evidence**: `git status`/`diff`; classification drives gates; changelog diff matches commit.
-- **Execution**: Inspect → classify → (deps) → readiness → commit → push verify.
-- **Quality**: No gate bypass; sequential git ops; preserve intentional commit boundaries.
-- **Output**: Conventional commit message + confirmed remote **when push ran** + note stash/scope if any.
+### 2. 品控閘門（選用）
 
-## References
+如果變更範圍設計代碼變更，使用 `review-change`, `discover-edge-cases`, `discover-security-issues` 這三個技能，並遵從當中的任務指引，對代碼變更進行審查。
+如果外部環境允許使用subagents，建議通過調度subagents完成三個不同維度的代碼審查工作。
+如果在審查過程中發現問題，修復發現的問題並暫存。
 
-- `references/commit-messages.md`
-- `references/branch-naming.md`
+### 3. 同步項目文檔
 
-## Workflow
+使用 `submission-readiness-check` 並遵照當中的指引，同步更新項目文檔，確保項目文檔時刻與repo保持一致。
 
-**Chain-of-thought:** **`Pause →`** guards skipping a gate or mis-sizing scope.
+### 4. 提交及推送變更
 
-1. **Inspect** — `git status -sb`; `git diff --stat`; `git diff --cached --stat`; `git diff --cached --name-only`. If clean: `git log -1 --stat`, upstream tracking, whether work already pushed.
-   - **Pause →** Is the user’s intended commit **exactly** the staged set, or full worktree—I must not mix them silently?
+依使用者的 staging 邊界建立 commit，提交訊息遵循 `references/commit-messages.md`。
+只有在使用者明確要求更新remote時才 push。
 
-2. **Classify** — Tag mentally: `code-affecting` | `docs-only` | `repo-specs-present` | `repo-specs-ready-for-conversion` | `project-doc-structure-mismatch` (per `archive-specs` needs). Active specs with unfinished same-change work stay active.
-   - **Pause →** Which conditional skills just became **mandatory**—did I list them explicitly?
+## 範例
 
-3. **Branch target** — Honor user branch; if switch needed, protect unrelated changes; cherry-pick/replay off wrong branch safely; worktree cases: identify authoritative target **before** replay.
-   - **Pause →** Am I about to merge noise because diff > issue scope—should I stop and narrow first?
+- 「只把已 staged 的 `foo.ts` 提交」-> 只能提交已暫存內容，不能順手把未 staged 的 `bar.ts` 一起帶進來
+- 「幫我 push 這個 branch」-> 先完成 review 與 readiness gate，再 push，最後用 hash 證明remote已同步
+- 「順便幫我發版」-> 不使用本技能，改走 `version-release`
 
-4. **Code-affecting gates** — `review-change-set` always; fix or document blockers; re-test material logic.
+## 參考資料索引
 
-5. **Readiness** — Run **`submission-readiness-check`**; if it routes to **`archive-specs`**, run that **now**; fix `Unreleased` bullets; recheck changelog vs staged intent.
-   - **Pause →** Could I commit while readiness still red—**why not**?
-
-6. **Commit** — Respect staging; separate commits if user asked; Conventional message per `references/commit-messages.md`.
-
-7. **Push** — **Only** when the user requested remote update (`push`, `publish`, PR branch sync, explicit upstream publish, or equivalent). If the user asked **only** for a **local** commit with **no** remote publish in this thread, finish after step 6, state local `HEAD`, and **do not** push.
-   - **Pause →** Did the user **explicitly** ask to update a remote, or only to record commits locally?
-   - **Pause →** What two hashes prove remote == local when push **did** run?
-
-## Sample hints
-
-- **Scope**: Staged `foo.ts` only; unstaged `bar.ts` unrelated → commit **must not** pick up `bar.ts` without user scope change.
-- **Changelog**: Code change with no `Unreleased` bullet → **blocking** until added.
-- **Push proof**: “Pushed” means e.g. local `abc123` equals `origin/feature` `abc123`, not “command sent.”
+- `references/commit-messages.md`：提交訊息格式
+- `references/branch-naming.md`：分支命名慣例

package/develop-new-features/SKILL.md

@@ -1,74 +1,29 @@
 ---
 name: develop-new-features
-description: >-
-  Net-new or materially new product behavior: **`generate-spec`** is mandatory (clarify → approve → only then code) with **`test-case-strategy`** backing every serious logic change—property tests required unless documented `N/A`, add adversarial/auth/idempotency/concurrency/mocks for external services, cap each spec at three modules and split coordinated batches via `coordination.md`, finish every approved `tasks.md`/`checklist.md` item or document deferrals.
-  Use when users ask for “new feature”, “greenfield slice”, “plan-first delivery”. Reroute typo-only UI, bug restores, or internal refactors without product impact to **`enhance-existing-features`** / **`systematic-debug`**.
-  Bad: editing `src/api.ts` before approval exists… Good: spec records risk → tests map to requirement IDs… Typo fix in footer copy → wrong skill…
+description: 用於從零開始打造新專案。當你需要從零開始打造一個新專案時，請使用這個技能。
 ---
 
-# Develop New Features
+## 技能目標
 
-## Dependencies
+把新的產品需求轉成一套可批准、可實作、可驗證的交付流程，避免在需求未定稿前直接寫產品程式碼，並確保最終功能、測試與規劃文件彼此一致。
 
-- Required: `generate-spec` for shared planning artifacts and `test-case-strategy` for risk-driven test selection, oracles, and unit drift checks before coding.
-- Conditional: **`commit-and-push`** when the user requests **git commit** and/or **push** after delivery—**MUST** delegate final submission to **`commit-and-push`** (implementation detail: often via **`implement-specs`**, which already requires it).
-- Optional: none.
-- Fallback: **`generate-spec`** **or** **`test-case-strategy`** missing ⇒ **stop** (no improvised planning/tests). If the user requested **commit/push** and **`commit-and-push`** is unavailable, **MUST** stop and report.
+## 驗收條件
 
-## Non-negotiables
+- 產生了完全符合用戶需求的spec，通過spec將用戶的需求精確定義為可實作的工程指導文檔。
+- 遵照可實作的spec，實作了用戶的需求。
 
-- This skill applies to **non-trivial new behavior / greenfield**. **MUST NOT** activate for: pure bug restore; style/copy-only tweaks; trivial one-pocket config/constants; internal-only refactors/no visible behavior—these routes belong to **`enhance-existing-features`**, **`systematic-debug`**, etc., **without** new specs here.
-- **When this skill applies**, **`generate-spec` is mandatory** before product code: create/update plans, BDD reqs, contracts, design, optional batch **`coordination.md`**, obtain **explicit approval**, then implement.
-- **≤3 modules** per spec set; wider work ⇒ multiple **independent** spec sets under batch + **`coordination.md`** (no hidden cross-deps).
-- **MUST NOT** modify product code **before** approval.
-- Post-approval: **all** in-scope **`tasks.md`/`checklist.md`** items complete unless deferral/blocker documented in artifacts.
-- **`test-case-strategy`**: risk-first; property-based logic **required** unless documented **`N/A`**; adversarial/auth/idempotency/concurrency where relevant; mocks for externals in logic chains; oracles tied to requirements.
-- Backfill all plan files + coordination when batch; no fake-completed template branches.
+## 工作流程
 
-## Standards (summary)
+### 1. 理解用戶需求
 
-- **Evidence**: Official docs + repo architecture pass before plan lock.
-- **Execution**: Route-out trivial work → spec → implement → test → backfill.
-- **Quality**: Plans trace to tests; minimal speculative code.
-- **Output**: Approved scope shipped + honest plan status.
+分析用戶需求，並使用 `generate-spec` 技能建立spec。
 
-## Workflow
+### 2. 實作spec
 
-**Chain-of-thought:** If request is maintenance-sized, **`Pause →`** “Should I reroute?” before spending tokens on **`generate-spec`**.
+在明確獲取用戶的同意之後，使用 `implement-specs` 技能實作spec。
+如果spec是batch spec（存在多份spec），且外部環境允許使用subagents，建議使用 `implement-specs-with-subagents` 技能調度subagents實作spec。
 
-### 1) Docs & routing
+## 使用範例
 
-- Stack/deps discovery; verify using official sources.
-  - **Pause →** Is this truly greenfield/feature vs fix/polish—if latter, bail to other skill?
-
-### 2) `generate-spec`
-
-- Full workflow: dirs `docs/plans/{YYYY-MM-DD}/…`, batch/coord flags, clarification, **`MUST`** approval before code.
-  - **Pause →** Did I secretly start coding “just the types”—**hard violation**?
-
-### 3) Architecture map
-
-- Reuse seams; list likely files **after** approval to stay honest to plan.
-
-### 4) Implement (post-approval)
-
-- Execute tasks/checklist exhaustively unless blocker recorded with user-visible deferrals.
-
-### 5) Testing
-
-- **`test-case-strategy`** mapping requirement IDs ↔ tests; drift checks/`N/A` discipline; run and fix reds.
-
-### 6) Completion
-
-- Backfill **`generate-spec`**-style across **`spec/tasks/checklist/contract/design`** (+ **`coordination.md`**); requirement-level status in **`spec.md`**; strip template illusions; final report with scope + tests + `N/A`.
-
-## Sample hints
-
-- **Wrong skill**: “Fix typo in footer string” ⇒ not here.
-- **Right skill**: “Add export-to-CSV for dashboard” ⇒ **`generate-spec`** then code + property tests on CSV invariants maybe.
-- **Split**: Touches CLI + server + terraform module boundaries—three modules cap ⇒ **two spec dirs** coordinated.
-
-## References
-
-- **`generate-spec`**: planning/backfill authority
-- **`test-case-strategy`**: breadth/depth of tests
+- "現有repo完全不存在任何的CSV解析、讀取、會出功能。用戶要求替 dashboard 新增 CSV 匯出功能。-> "建立spec並等待用戶批准，再實作匯出流程，並用 property tests 驗證欄位順序、編碼與內容不變量"
+- "原repo不存在任何cli功能。用戶要求同時新增 CLI、後端與基礎設施的新能力" -> "拆成多份 spec，用 `coordination.md` 管理跨模組依賴，並使用 `implement-specs-with-subagents` 技能調度subagents實作spec。"

package/discover-edge-cases/SKILL.md

@@ -1,91 +1,32 @@
 ---
 name: discover-edge-cases
-description: >-
-  Diff-first (or full-repo) discovery of **reproducible** edge-case risks: boundaries, null/empty, failure paths, concurrency, observability; evidence via code/tests/runtime—**no edits, no new tests, no PRs**. For code-affecting scope, cross-check with **`discover-security-issues`** before final report.
-  Use for edge-case review, hardening gaps, unusual inputs/error paths, pre-merge risk pass **STOP** implementation or “just fix it here”… BAD unproven alarm list… GOOD path:line + double repro…
+description: 審查代碼在邊界狀況時可能會出現的問題。當你需要進行代碼審查時，調用此技能
 ---
 
-# Discover Edge Cases
+## 目標
 
-## Dependencies
+審查代碼並輸出一份代碼邊界問題審查報告，僅保留可重現、可驗證的風險。報告需要按優先級列出問題標題、證據、重現方式、受影響不變式、風險評估、加固建議與剩餘不確定性。
 
-- Required: none.
-- Conditional: **`discover-security-issues`** on **code-affecting** scope before finalizing the report (adversarial security pass).
-- Optional: none.
-- Fallback: If that security cross-check is **required** but unavailable, **MUST** stop and report the missing dependency.
+## 驗收條件
 
-## Non-negotiables
+- 完整的代碼審查報告與建議修正。包括但不限於對代碼進行：資料完整性、靜默失敗、重試風暴、資源耗盡、部分提交/回滾失敗與跨模組傳播等審查結果。
 
-- **Discovery-only**: **MUST NOT** edit code, add/modify tests, or open PRs.
-- **MUST** keep only **reproducible** findings; label guesses as **hypotheses**.
-- **MUST** reproduce each **confirmed** issue **at least twice** (same trigger); vary neighbors (empty vs null, malformed vs wrong-type).
-- **MUST** discard authorship bias—including code from earlier in the conversation.
-- If remediation is requested: finish this pass first; hand off **confirmed** items to an implementation workflow.
+## 工作流程
 
-## Standards (summary)
+### 1. 深入閱讀相關代碼
 
-- **Evidence**: `path:line`, commands/inputs, test output, or runtime symptoms—no intent-only claims.
-- **Execution**: Scope → baseline read → focused probes (2–5 high-impact) → validate → prioritize → report.
-- **Quality**: Prefer fewer strong findings; flag data integrity, silent failure, retry storms, cross-module propagation.
-- **Output**: Prioritized findings, reproduction, risk, hardening **advice**, residual risk/hypotheses.
+通過用戶指引或目前git變更狀態，定義審查範圍。完整閱讀並閱讀相關代碼片段並理解代碼。重點關注常見邊界問題。
 
-## Workflow
+### 2. 報告整理及輸出
 
-**Chain-of-thought:** Answer **`Pause →`** each step; if scope is wrong, fix before probing.
+將發現的邊界問題按嚴重程度排序，並輸出一份完整的審查報告
 
-### 1) Determine scan scope
+## 使用範例
 
-- `git diff --name-only` first.
-- **With diff**: changed files + minimum dependency chain to validate suspected edges.
-- **No diff**: whole project, prioritizing domain logic, external boundaries, stateful/concurrent modules.
-- If nothing actionable after honest pass: report `No actionable edge-case finding identified` and stop.
-   - **Pause →** Can I name the **smallest file set** I must read—not the whole monorepo by default?
+- "幫我檢查這次 parser 改動有沒有邊界風險" -> "閱讀本次改動的相關代碼，檢查常見邊界問題是否存在，並輸出完整的驗證報告"
+- "看看這個支付狀態機還有哪些不容易被測到的問題" -> "優先檢查重試、部分提交、回滾、併發重入、順序依賴與可觀測性缺口。"
 
-### 2) Build factual baseline
+## 參考資料索引
 
-- Read end-to-end before judging; derive behavior from code, tests, runtime only.
-- Clarify contracts: types, ranges, null, ordering, retries, state transitions.
-   - **Pause →** What did I **execute** (test/command) vs only read?
-
-### 3) Focused probes (prioritize 2–5)
-
-Target high-risk patterns tied to scope:
-
-- Empty/null/malformed/unexpected types; boundaries (0, 1, min/max, overflow); duplicates/order.
-- Dependency failure: timeout, partial data, retry loops; invalid formats.
-- Concurrency/reentrancy; architecture edges: backpressure, exhaustion, partial commit/rollback.
-- **HTTP/API** (if in scope): 429/500 behavior; logging with status/id/retry/latency (no silent fails).
-
-Load as needed: `references/architecture-edge-cases.md`, `references/code-edge-cases.md`.
-   - **Pause →** Would **discover-security-issues** flag this sink if it is auth/input injection—did I schedule that pass for code changes?
-
-### 4) Confirm reproducibility
-
-- Two passes per confirmed issue; note variants tried; keep unconfirmed as hypotheses.
-
-### 5) Prioritize
-
-- User impact, frequency/exploitability, blast radius; call out integrity, state corruption, silent failure.
-
-### 6) Security cross-check (code-affecting)
-
-- Run **`discover-security-issues`** on the **same** scope; integrate **confirmed** security items (do not duplicate as edge trivia unless distinct).
-
-### 7) Report only
-
-Deliver: (1) Findings—title, severity, evidence, repro, broken invariant; (2) Edge evidence—preconditions, observation, variants; (3) Risk—impact/likelihood/scope; (4) Hardening guidance (advisory); (5) Residual risk—hypotheses, next checks.
-
-## Minimum coverage (apply what fits scope)
-
-- Input validation; boundary behavior; failure/degraded modes; state/idempotency/concurrency/rollback; actionable observability.
-
-## Sample hints
-
-- **Diff**: One new parser → empty string + max length + malformed delimiter **before** “maybe SQL.”
-- **No diff**: Start at payment/state machine module—highest consequence.
-- **Handoff**: Five confirmed edges → remediation skill gets **numbered list + repro**—not this skill patching.
-
-## References
-
-- `references/architecture-edge-cases.md` — system-level checklist.
-- `references/code-edge-cases.md` — code-level input/error/concurrency checklist.
+- `references/architecture-edge-cases.md`：常見系統級邊界情況清單，涵蓋併發、背壓、分散式一致性、超時取消、回滾與部署漂移。
+- `references/code-edge-cases.md`：常見代碼級邊界情況清單，涵蓋輸入、數值、排序、錯誤處理、狀態污染、安全驗證與性能上限。