@laitszkin/apollo-toolkit 3.11.8 → 3.12.1

package/AGENTS.md

@@ -31,10 +31,10 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can turn lecture slides, past papers, and answer books into mock exams, worked solutions, study notes, or graded PDFs with KaTeX-rendered math.
 - Users can extend existing features in a brownfield codebase with required tests and approvals.
 - Users can propose product features from an existing codebase and publish accepted proposals.
-- Users can discover reproducible edge-case risks and report prioritized hardening gaps.
+
 - Users can read, filter, and inspect remote GitHub issues before planning follow-up work.
 - Users can resolve a GitHub issue end-to-end and push the fix directly to a requested branch without opening a PR.
-- Users can run evidence-first application security audits focused on confirmed vulnerabilities.
+
 - Users can run a shared submission-readiness pass that synchronizes changelog, project docs, `AGENTS.md`, and completed plan archives before commit, push, PR creation, or release.
 - Users can learn new or improved skills from recent Codex conversation history.
 - Users can audit and maintain the skill catalog itself, including dependency classification and shared-skill extraction decisions.
@@ -51,12 +51,12 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can generate storyboard image sets from chapters, novels, articles, or scripts.
 - Users can configure OpenClaw from official documentation, including `~/.openclaw/openclaw.json`, skills loading, SecretRefs, CLI edits, and validation or repair workflows.
 - Users can record multi-account spending and balance changes in monthly Excel ledgers with summary analytics and charts.
-- Users can recover missing or archived `docs/plans/...` spec sets from issue context, git history, and repository evidence before continuing feature work.
-- Users can review the current git change set from an unbiased reviewer perspective to find abstraction opportunities and simplification candidates.
+
+
 - Users can review recent or user-specified spec-backed changes against the governing planning documents, treating unmet business goals as the most severe findings before secondary edge-case, security, and code-review checks.
 - Users can process GitHub pull request review comments and resolve addressed threads.
-- Users can perform repository-wide code reviews and publish confirmed findings as GitHub issues.
-- Users can schedule a bounded project runtime window, stop it automatically, and analyze module health from captured logs.
+
+
 - Users can investigate gated or shadow LLM APIs by capturing real client request shapes, replaying verified traffic patterns, and attributing the likely underlying model through black-box fingerprinting.
 - Users can build and maintain Solana programs and Rust clients using official Solana development workflows.
 - Users can fix issues discovered during a review pass by processing findings from highest to lowest severity, with per-fix validation and full-scope re-validation.

package/CHANGELOG.md

@@ -2,13 +2,31 @@
 
 All notable changes to this repository are documented in this file.
 
-## [Unreleased]
+## [v3.12.1] - 2026-05-14
+
+### Changed
+
+- Rewrite remaining shipped skills (`enhance-existing-features`, `generate-spec`, `init-project-html`, `merge-changes-from-local-branches`, `open-source-pr-workflow`, `optimise-skill`, `review-spec-related-changes`, `solve-issues-found-during-review`, `submission-readiness-check`, `commit-and-push`, `version-release`, `iterative-code-performance`, `iterative-code-quality`, `maintain-project-constraints`, `ship-github-issue-fix`, `spec-to-project-html`, `systematic-debug`) into the compact Chinese-first structure with goal, acceptance criteria, workflow, examples, and references sections.
+- Update `AGENTS.md` and `README.md` to remove references to deleted skills and simplify dependency descriptions.
+
+### Removed
+
+- Remove `discover-edge-cases`, `discover-security-issues`, `recover-missing-plan`, `review-change-set`, `review-codebases`, and `scheduled-runtime-health-check` skills that are no longer part of the curated catalog.
+
+## [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
 
-### Fixed
+- 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
 

package/README.md

@@ -12,7 +12,7 @@ A curated skill catalog for Codex, OpenClaw, Trae, Agents, and Claude Code with
 - codex-memory-manager
 - deep-research-topics
 - develop-new-features
-- discover-edge-cases
+
 - docs-to-voice
 - exam-pdf-workflow
 - document-vision-reader
@@ -21,7 +21,7 @@ A curated skill catalog for Codex, OpenClaw, Trae, Agents, and Claude Code with
 - financial-research
 - read-github-issue
 - generate-spec
-- discover-security-issues
+
 - implement-specs
 - implement-specs-with-subagents
 - implement-specs-with-worktree
@@ -41,13 +41,13 @@ A curated skill catalog for Codex, OpenClaw, Trae, Agents, and Claude Code with
 - openai-text-to-image-storyboard
 - openclaw-configuration
 - optimise-skill
-- recover-missing-plan
+
 - record-spending
 - resolve-review-comments
-- review-change-set
-- review-codebases
+
+
 - review-spec-related-changes
-- scheduled-runtime-health-check
+
 - shadow-api-model-research
 - solana-development
 - spec-to-project-html
@@ -208,12 +208,11 @@ Compatibility note:
 
 - `generate-spec` is a local skill used by `develop-new-features` and `enhance-existing-features`, and it can produce either a single spec set under `docs/plans/{YYYY-MM-DD}/{change_name}/` or a coordinated parallel batch under `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` with shared `coordination.md`.
 - `implement-specs-with-subagents` coordinates one `implement-specs-with-worktree` subagent per spec directory for approved multi-spec batches.
-- `recover-missing-plan` is a local skill used by `enhance-existing-features` and `ship-github-issue-fix` when a referenced `docs/plans/...` spec set is missing or archived.
+
 - `read-github-issue` uses GitHub CLI (`gh`) directly for remote issue discovery and inspection, so it does not add any extra skill dependency.
-- `review-spec-related-changes` is a local skill that depends on `review-change-set`, `discover-edge-cases`, and `discover-security-issues` for secondary code-practice checks after business-goal completion is reviewed against the governing specs; it prefers running each secondary skill in its own read-only subagent in parallel.
+- `review-spec-related-changes` is a local skill that reviews spec compliance of changes against governing planning documents, assessing business goals before secondary code-practice concerns.
 - `update-project-html` is a local skill that depends on `init-project-html` for semantic rules and on the `apltk architecture` CLI to refresh the base atlas after code changes; for spec overlay diagrams use `spec-to-project-html` instead.
-- `commit-and-push` and `version-release` no longer chain `discover-edge-cases` or `discover-security-issues`; invoke those skills explicitly when the review surface needs them.
-- `review-change-set` no longer chains `discover-security-issues`; for multi-file diffs it prefers dispatching one read-only subagent per scope cluster.
+
 
 ## Release publishing
 

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,42 @@
 ---
 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
+如果變更範圍涉及代碼變更，確認變更已通過必要的審查與驗證。如果在審查過程中發現問題，修復發現的問題並暫存。
 
-- `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。"