@laitszkin/apollo-toolkit 3.11.6 → 3.11.8

package/AGENTS.md

@@ -38,6 +38,7 @@ This repository enables users to install and run a curated set of reusable agent
 - 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.
+- Users can optimize existing agent skills by deriving the intended deliverable, tightening acceptance criteria, and rewriting `SKILL.md` into a leaner structure backed by extracted references.
 - Users can implement approved spec planning sets directly in the current checkout and commit them to the active branch.
 - Users can implement approved spec planning sets inside isolated git worktrees and keep the parent checkout clean.
 - Users can coordinate approved multi-spec implementation batches by assigning each spec directory to an independent worktree-backed subagent with bounded concurrency.

package/CHANGELOG.md

@@ -10,6 +10,36 @@ All notable changes to this repository are documented in this file.
 
 ### Fixed
 
+## [v3.11.8] - 2026-05-12
+
+### Added
+
+- `apltk` now provides task-oriented top-level help for bundled tools, and `apltk architecture --help` can route to action-specific help pages for the atlas CLI.
+- `optimise-skill` now ships a dedicated `references/definition.md` reference so the target skill output structure has a separate canonical definition.
+
+### Changed
+
+- Refresh the atlas-related planning docs and command guidance (`generate-spec`, `init-project-html`, `spec-to-project-html`, `update-project-html`) to rely on `apltk architecture --help` as the authoritative command tree and to better explain batch overlays plus subagent responsibilities.
+- Expand the bundled CLI help system so `apltk tools <tool> --help` shows curated purpose / use-when / examples before native script help, and align the validator / helper scripts with that layered help flow.
+- Refresh multiple shipped skills (`docs-to-voice`, `open-github-issue`, `read-github-issue`, `resolve-review-comments`, `optimise-skill`) and retire the standalone `maintain-skill-catalog` skill while keeping the validator commands available as bundled `apltk` tools.
+- Remove brittle text-level workflow assertions from the test suite so repository tests focus on executable CLI and rendering behavior instead of exact prompt wording.
+
+### Fixed
+
+- Keep the public skill inventory and bundled tool metadata consistent after removing `maintain-skill-catalog`, so validator commands no longer reference a deleted skill owner.
+
+## [v3.11.7] - 2026-05-12
+
+### Added
+
+- Add `optimise-skill`, a new catalog skill that reads a target skill and its supporting files, derives the intended deliverable and acceptance criteria, and rewrites the skill into a tighter `goal / acceptance criteria / workflow / examples / references` structure for higher-signal agent execution.
+
+### Changed
+
+- Catalog docs now include `optimise-skill`, and its bundled example reference path is normalized to match the shipped file name.
+
+### Fixed
+
 ## [v3.11.6] - 2026-05-12
 
 ### Added

package/README.md

@@ -35,12 +35,12 @@ A curated skill catalog for Codex, OpenClaw, Trae, Agents, and Claude Code with
 - learning-error-book
 - marginfi-development
 - maintain-project-constraints
-- maintain-skill-catalog
 - novel-to-short-video
 - open-github-issue
 - open-source-pr-workflow
 - openai-text-to-image-storyboard
 - openclaw-configuration
+- optimise-skill
 - recover-missing-plan
 - record-spending
 - resolve-review-comments
@@ -209,7 +209,6 @@ 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.
-- `maintain-skill-catalog` can conditionally use `find-skills`, but its install source is not verified in this repository, so it is intentionally omitted from the table.
 - `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.
 - `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.

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/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
+# 生成規格
+
+## 目標
+將用戶需求轉化為明確、有清晰完成條件的規格文檔。
+
+## 驗收條件
+- 已經產出了嚴格遵循模板格式的規格文檔。
+- 為規格文檔當中的需求制定了明確的驗收條件及測試策略
+
+## 工作流程
+1. 理解用戶需求並閱讀代碼庫
+分析用戶需求，並在代碼庫之中搜索、列出可能相關的內容。完成搜索之後，深入閱讀相關代碼，識別變更範圍。
+如果外部環境存在subagents功能，建議通過調度subagents來完成深入閱讀代碼庫的任務。
+
+2. 拆分用戶需求及設計業務架構
+將用戶需求轉化、拆分為明確、存在邊界的工程需求。結合現有代碼，設計業務架構。在設計的過程中，你需要考慮包括但不限於以下設計事項：
+- 錯誤處理
+- 測試策略
+- 模塊之間的呼叫、回傳
+- 資料流
+在這個階段，如果用戶有任何不清晰的需求，且該需求會影響你的設計方案，你需要紀錄並在稍後填入規格文檔，等待用戶的回答。
+
+3. 將整個設計方案拆分成可執行任務
+將上一步之中你構思的完整設計方案拆分為精確到函式或檔案級別的任務。你必須確保每一個任務都是可以直接執行，且沒有歧義的。以此確保執行設計方案的開發者不會偏離設計方案。
+
+4. 制定驗收條件
+為任務制定基於測試的驗收條件，確保每一個任務在完成之後都能夠被驗證。
+同時，為需求制定驗收條件，確保用戶需求能夠被測試清晰地驗收、檢驗成果。
+
+5. 使用 `apltk` cli工具協助完成規格文檔
+使用cli工具，產生規格文檔的模板。將你的完整計劃填入到模板之中，並通過cli工具生成完整架構圖讓用戶審閱。
+如果該規格文檔設計超過三個模塊，則需要創建規格批次。
+
+## 範例
+- "製作一個網頁德州撲克小遊戲" -> "拆分成多個模塊：遊戲本體邏輯、前端頁面渲染、前端頁面交互邏輯；制定單元測試、整合測試等策略，並製作一份單一的規格文檔指導實作工作。"
+- "提升現有系統的性能" -> "識別目前代碼庫之中拖累性能的代碼。製作規格批次文檔，將代碼庫的全量優化拆分為以三個模塊為一組的優化。對於必須改動業務邏輯才可以做到的性能提升，填寫clarification questions，並等待用戶回答之後更新規格文檔。"
+
+## 參考資料
+- `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` - 測試策略選擇技能。

package/init-project-html/SKILL.md

@@ -80,21 +80,9 @@ The atlas is only complete when both of the following are demonstrably true on t
 
 `apltk architecture validate` **MUST** return OK before reporting completion.
 
-## How to use `apltk architecture`
+## CLI reference
 
-**Authoritative command tree:** run **`apltk architecture --help`** (same output as `apltk architecture help`). **MUST** use that output for every verb, subverb (`add` / `set` / `remove` / `reorder`), and required flag. This skill describes **semantics and constraints** only so documentation does not drift when the CLI adds flags or synonyms.
-
-**Typical global flags** (confirm in `--help`): `--project <root>`, `--spec <spec_dir>` (overlay under `<spec_dir>/architecture_diff/` — see `spec-to-project-html`), `--no-render`, `--no-open`, `--out` (for `diff`). Pass `--no-render` while batching mutations, then **`render`** once before `validate` if you batched.
-
-**Groupings — what each family is for:**
-
-| Family | Purpose | Key constraints |
-| --- | --- | --- |
-| **`open` / `diff` / `render` / `validate` / `undo` / `help`** | View, regenerate, check, revert, discover verbs | **`validate`** before “done”. **`diff`** after spec overlays to compare base vs proposed-after under `docs/plans/**/architecture_diff/`. |
-| **`meta` / `actor`** | Macro title, summary, optional top-level actors | Summary is the right place for scanned roots and omissions. |
-| **`feature` / `submodule`** | Feature modules and their sub-modules | **Remove** cascades references; in spec overlay mode, rename is usually **remove + add** so `diff` classifies correctly. |
-| **`function` / `variable` / `dataflow` / `error`** | Tables + ordered internal flow + local errors | Declare symbols **before** referencing them from `dataflow`. Use **`remove`** (see `--help`) to delete mistaken rows or steps. |
-| **`edge`** | Cross- **or** intra-feature seams | **`kind`** ∈ `call` \| `return` \| `data-row` \| `failure`. Intra-feature endpoints land in the feature file; cross-feature endpoints land in the index. Prefer stable **`--id`** on edges you may remove later in spec mode. |
+Run **`apltk architecture --help`** and the deeper `apltk architecture <verb> [subverb] --help` pages for the authoritative command tree, required flags, examples, and expected results. This skill keeps only the semantic rules, acceptance criteria, and subagent coordination rules so the documentation does not drift when the CLI evolves.
 
 **Cross-feature work timing:** only after **all** feature subagents have returned (Rule 3).
 
@@ -119,17 +107,7 @@ Dispatch one **write-capable** subagent per feature. Hand each subagent: its fea
 > - Run **`apltk architecture validate`** before returning (same project root; use **`--help`** for project/spec flags).
 > - **Return ONLY**: (i) sub-module list (slug + kind + one-line role), (ii) outbound boundaries to *other* features’ sub-modules (direction + edge kind + suggested label). No source dumps.
 
-**Orchestrator — after every subagent has completed:**
-
-```bash
-apltk architecture meta set --title "..." --summary "..." --no-render
-# only when an actor is shared across multiple features:
-apltk architecture actor add --id <id> --label "..." --no-render
-# one edge per cross-feature interaction reported by the subagents:
-apltk architecture edge add --from <featA>/<subA> --to <featB>/<subB> --kind call|return|data-row|failure --label "..." --no-render
-apltk architecture render
-apltk architecture validate
-```
+**Orchestrator — after every subagent has completed:** declare only the cross-feature `apltk architecture` mutations reported by the workers, then render and validate once.
 
 The main agent **MUST NOT** re-declare a subagent’s intra-feature components, and **MUST NOT** open source files for any feature it delegated.