@laitszkin/apollo-toolkit 3.12.1 → 3.13.1

package/AGENTS.md

@@ -1,107 +1,38 @@
-# AGENTS Guide
-
-## Project Architecture
-
-- This repository is a skill catalog: each top-level skill lives in its own directory and is installable when that directory contains `SKILL.md`.
-- Typical skill layout is lightweight and consistent: `SKILL.md`, `README.md`, `LICENSE`, plus optional `agents/`, `references/`, and `scripts/`.
-- The npm package exposes an `apollo-toolkit` CLI that stages a managed copy under `~/.apollo-toolkit` and copies or symlinks each skill folder into selected target directories.
-- The installer writes a `.apollo-toolkit-manifest.json` per target directory to track installed skills, historical skill names, and install mode for future uninstall and deduplication.
-- `scripts/install_skills.sh` and `scripts/install_skills.ps1` remain available for local/curl installs and mirror the managed-home install behavior with symlink/copy choice and uninstall support.
-
-## Core Business Flow
-
-This repository enables users to install and run a curated set of reusable agent skills for software delivery, research, repository maintenance, and media-generation workflows.
-
-- Users can align project documentation with the current codebase.
-- Users can consolidate completed project specs and batch-level coordination plans into a standardized README and categorized project documentation set, then archive only the truly consumed planning files.
-- Users can investigate application logs, slice them to precise time windows, search by keyword or regex, and produce evidence-backed root-cause findings.
-- Users can answer repository-backed questions with additional web research when needed.
-- Users can commit and push local changes without performing version or release work.
-- Users can manage Codex user-preference memory by reviewing the last 24 hours of chats, storing reusable preference-first memory documents under `~/.codex/memory`, and syncing a memory index into `~/.codex/AGENTS.md`.
-- Users can research a topic deeply and produce evidence-based deliverables.
-- Users can research the latest completed market week and produce a PDF watchlist of tradeable instruments for the coming week.
-- Users can turn a marked weekly finance PDF into a concise evidence-based financial event report.
-- Users can install Apollo Toolkit through npm or npx and interactively choose one or more target skill directories to populate with copied or symlinked skills, with the option to include codex-exclusive skills in non-codex targets.
-- Users can uninstall Apollo Toolkit-installed skills through an interactive target selector or specific non-interactive targets via `apltk uninstall`.
-- Users can choose between symlink mode (auto-update via git pull) and copy mode (stable snapshot) with `--symlink` / `--copy` flags.
-- Users can run bundled helper tools through `apltk tools` and direct `apltk <tool>` commands for selected packaged skill scripts.
-- Users can design and implement new features through a spec-first workflow.
-- Users can generate shared feature planning artifacts for approval-gated workflows, including parallel multi-spec batches coordinated through `coordination.md` and, only when needed, minimal non-business prerequisite work in `preparation.md`.
-- Users can convert text or documents into audio files with subtitle timelines.
-- 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 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 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.
-- Users can summarize mistakes into separate multiple-choice and long-answer error books backed by structured reference files and rendered PDFs.
-- Users can build or review marginfi protocol integrations using official SDK, CLI, protocol, and The Arena documentation.
-- Users can create or maintain `AGENTS.md` so project constraints stay aligned with the repository.
-- Users can turn novel content into a loopable short-form video with generated assets.
-- Users can publish structured GitHub issues or feature proposals with auth fallbacks.
-- Users can prepare and open open-source pull requests from existing changes.
-- 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 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 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.
-- Users can add focused observability to opaque workflows through targeted logs, metrics, traces, and tests.
-- Users can iteratively improve repository code quality through behavior-neutral naming, simplification, module-boundary, logging, and test-coverage passes.
-- Users can iteratively improve repository performance through evidence-backed module scans, safe hot-path optimization, benchmark guardrails, batching, caching, allocation, concurrency, and repeated full-codebase stage gates.
-- Users can refresh the project HTML architecture atlas to reflect the latest committed or staged code changes by dispatching one subagent per affected feature and updating the base atlas via `apltk architecture` (no spec overlay).
-- Users can select risk-driven test levels and define unit drift checks through a shared testing strategy skill.
-- Users can build against Jupiter's official Solana swap, token, price, lending, trigger, recurring, and portfolio APIs with an evidence-based development guide.
-- Users can render and embed math formulas with KaTeX using official documentation-backed guidance and reusable rendering scripts.
-- Users can debug software systematically by reproducing causes, validating fixes, and testing outcomes.
-- Users can generate 30-60 second short videos directly from text prompts.
-- Users can prepare and publish versioned releases with changelog and tag workflows.
-- Users can generate long-form videos by orchestrating storyboard, voice, and Remotion-based production steps.
-
-## Common Commands
-
-- `npm test` - 執行 Node 測試套件。
-- `node bin/apollo-toolkit.js` - 直接從倉庫啟動 Apollo Toolkit CLI。
-- `node bin/apollo-toolkit.js codex openclaw trae` - 以非互動方式將技能安裝到指定目標。
-- `node bin/apollo-toolkit.js tools` - 列出 Apollo Toolkit 內建 CLI 工具。
-- `node bin/apollo-toolkit.js filter-logs app.log --start 2026-03-24T10:00:00Z` - 透過內建工具包裝器執行技能腳本。
-- `node bin/apollo-toolkit.js architecture` - 開啟專案 `resources/project-architecture/index.html` 架構圖。
-- `node bin/apollo-toolkit.js architecture diff` - 將 `docs/plans/**/architecture_diff/` 與目前架構圖配對成分頁式 before/after viewer（輸出至 `.apollo-toolkit/architecture-diff/`）。
-- `python3 scripts/validate_skill_frontmatter.py` - 驗證所有頂層技能 `SKILL.md` 的 frontmatter。
-- `python3 scripts/validate_openai_agent_config.py` - 驗證所有技能 `agents/openai.yaml` 設定。
-- `./scripts/install_skills.sh codex` - 用本地安裝腳本把技能安裝到 Codex 目錄。
-- `./scripts/install_skills.sh codex --symlink` - 以 symlink 模式安裝（推薦）。
-- `./scripts/install_skills.sh all --copy` - 以複製模式安裝到所有支援目標。
-- `./scripts/install_skills.sh uninstall` - 從所有目標移除已安裝的技能。
-- `./scripts/install_skills.sh uninstall codex` - 只從 codex 目標移除。
-- `node bin/apollo-toolkit.js uninstall` - 透過 CLI 互動選擇要移除的 agent target 技能。
-- `node bin/apollo-toolkit.js uninstall codex --yes` - 以非互動方式移除指定 target 的已安裝技能。
-
-## Core Project Purpose
-
-- Provide a curated set of reusable agent skills that can be installed into Codex/OpenClaw/Trae skill directories.
-- Keep skills focused, composable, and easy to reuse across workflows.
-- Prefer splitting shared capabilities into dedicated skills when multiple workflows can depend on them.
-
-## Code Style And Conventions
-
-- Follow existing skill naming: kebab-case folder names and matching `name` values in `SKILL.md` frontmatter.
-- Keep documentation concise, operational, and evidence-based; avoid speculative guidance.
-- Reuse existing patterns from neighboring skills before introducing new structures.
-- Use a standardized `## Dependencies` section in every `SKILL.md` with `Required`, `Conditional`, `Optional`, and `Fallback` bullets whenever skill-to-skill orchestration matters.
-- Use a standardized `## Standards` section in every `SKILL.md` with `Evidence`, `Execution`, `Quality`, and `Output` bullets to summarize skill-specific constraints.
-- Keep helper scripts small and deterministic, and update repository docs when adding or moving a top-level skill.
+# Apollo Toolkit
+
+## Common Development Commands
+
+- `npm test` - 執行 Node 測試套件（`node --test`）。
+- `node bin/apollo-toolkit.js [mode...]` - 直接從倉庫啟動 CLI，將技能安裝至指定目標（codex/openclaw/trae/agents/claude-code/all）。
+- `node bin/apollo-toolkit.js uninstall [mode...]` - 從指定目標移除已安裝的 Apollo Toolkit 技能。
+- `node bin/apollo-toolkit.js tools` - 列出所有內建 CLI 工具及其分類。
+- `node bin/apollo-toolkit.js <tool> [args...]` - 執行內建工具（如 `filter-logs`、`search-logs`、`architecture`、`create-specs` 等）。
+- `node bin/apollo-toolkit.js architecture [diff]` - 開啟專案 HTML 架構圖，或搭配 `diff` 產生分頁式 before/after 檢視器。
+- `python3 scripts/validate_skill_frontmatter.py` - 驗證所有頂層技能 `SKILL.md` 的 frontmatter 格式與命名規範。
+- `python3 scripts/validate_openai_agent_config.py` - 驗證所有技能 `agents/openai.yaml` 的設定完整性。
+- `./scripts/install_skills.sh [mode...]` - 透過本地 shell 腳本安裝技能（非 npm 安裝方式）。
+
+## Project Business Goals
+
+- Provide a curated set of reusable agent skills installable into Codex, OpenClaw, Trae, Agents, and Claude Code skill directories.
+- Enable spec-first software delivery: feature planning, implementation (including parallel subagents and worktree isolation), code review, systematic debugging, and release management.
+- Support evidence-based research (deep research, financial analysis, API fingerprinting), media generation (video, audio, storyboard), and educational content (PDF exams, error books, KaTeX rendering).
+- Automate platform workflows: GitHub issue/PR operations, blockchain development (Solana, Jupiter, Marginfi), and OpenClaw configuration.
+- Keep skills focused, composable, and easy to reuse; split shared capabilities into dedicated skills when multiple workflows can depend on them.
+
+## Project Documentation Index
+
+- `docs/features/skill-installation.md` - 安裝、解除安裝與使用內建工具
+- `docs/features/software-development.md` - spec 驅動的開發生命週期
+- `docs/features/research-and-content.md` - 研究、媒體與教育內容生成
+- `docs/features/platform-automation.md` - GitHub、區塊鏈與 OpenClaw 自動化
+- `docs/features/catalog-maintenance.md` - 技能優化、記憶管理、記帳與驗證
+- `docs/architecture/cli-architecture.md` - CLI 設計：命令調度、工具註冊、更新檢查
+- `docs/architecture/installer-architecture.md` - 安裝器設計：原子同步、manifest 追蹤、連結模式
+- `docs/architecture/skill-structure.md` - 技能目錄佈局、frontmatter 規範、選擇性擴充
+- `docs/principles/naming-conventions.md` - 命名慣例：kebab-case、文件命名、工具命名
+- `docs/principles/skill-development.md` - 技能開發慣例：frontmatter、主體結構、依賴宣告
+- `docs/principles/testing-conventions.md` - 測試慣例：node:test、隔離、Python 測試發現
+- `README.md` - 公開安裝指南與技能目錄
+- `CHANGELOG.md` - 版本發佈歷史
+- `LICENSE` - MIT 授權條款

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to this repository are documented in this file.
 
+## [v3.13.1] - 2026-05-14
+
+### Changed
+
+- Rewrite `AGENTS.md` into a compact project-instructions format focused on development commands, business goals, and documentation index.
+- Add project-level `CLAUDE.md` with consistent content.
+- Change `optimise-skill` description to Chinese and add section spacing for readability.
+- Add architecture diff visualization acceptance criterion to `generate-spec`.
+
+### Added
+
+- Standardized `docs/` structure with feature, architecture, and principle categories.
+- Sync `README.md` skill list with the actual curated catalog.
+
+## [v3.13.0] - 2026-05-14
+
+### Changed
+
+- Further tighten SKILL.md files (`archive-specs`, `commit-and-push`, `generate-spec`, `init-project-html`, `maintain-project-constraints`, `merge-changes-from-local-branches`, `solve-issues-found-during-review`, `systematic-debug`, `test-case-strategy`, `update-project-html`, `version-release`) by removing inline examples, standardizing section headings, and simplifying descriptions.
+
+### Added
+
+- `generate-spec/references/definition.md`, `init-project-html/references/definition.md`, `update-project-html/references/definition.md` with shared terminology for feature modules and sub-modules.
+
+### Removed
+
+- Remove `iterative-code-performance`, `iterative-code-quality`, `merge-conflict-resolver`, `spec-to-project-html`, and `submission-readiness-check` skills that are no longer part of the curated catalog.
+
 ## [v3.12.1] - 2026-05-14
 
 ### Changed

package/CLAUDE.md

@@ -0,0 +1,38 @@
+# Apollo Toolkit
+
+## Common Development Commands
+
+- `npm test` - 執行 Node 測試套件（`node --test`）。
+- `node bin/apollo-toolkit.js [mode...]` - 直接從倉庫啟動 CLI，將技能安裝至指定目標（codex/openclaw/trae/agents/claude-code/all）。
+- `node bin/apollo-toolkit.js uninstall [mode...]` - 從指定目標移除已安裝的 Apollo Toolkit 技能。
+- `node bin/apollo-toolkit.js tools` - 列出所有內建 CLI 工具及其分類。
+- `node bin/apollo-toolkit.js <tool> [args...]` - 執行內建工具（如 `filter-logs`、`search-logs`、`architecture`、`create-specs` 等）。
+- `node bin/apollo-toolkit.js architecture [diff]` - 開啟專案 HTML 架構圖，或搭配 `diff` 產生分頁式 before/after 檢視器。
+- `python3 scripts/validate_skill_frontmatter.py` - 驗證所有頂層技能 `SKILL.md` 的 frontmatter 格式與命名規範。
+- `python3 scripts/validate_openai_agent_config.py` - 驗證所有技能 `agents/openai.yaml` 的設定完整性。
+- `./scripts/install_skills.sh [mode...]` - 透過本地 shell 腳本安裝技能（非 npm 安裝方式）。
+
+## Project Business Goals
+
+- Provide a curated set of reusable agent skills installable into Codex, OpenClaw, Trae, Agents, and Claude Code skill directories.
+- Enable spec-first software delivery: feature planning, implementation (including parallel subagents and worktree isolation), code review, systematic debugging, and release management.
+- Support evidence-based research (deep research, financial analysis, API fingerprinting), media generation (video, audio, storyboard), and educational content (PDF exams, error books, KaTeX rendering).
+- Automate platform workflows: GitHub issue/PR operations, blockchain development (Solana, Jupiter, Marginfi), and OpenClaw configuration.
+- Keep skills focused, composable, and easy to reuse; split shared capabilities into dedicated skills when multiple workflows can depend on them.
+
+## Project Documentation Index
+
+- `docs/features/skill-installation.md` - 安裝、解除安裝與使用內建工具
+- `docs/features/software-development.md` - spec 驅動的開發生命週期
+- `docs/features/research-and-content.md` - 研究、媒體與教育內容生成
+- `docs/features/platform-automation.md` - GitHub、區塊鏈與 OpenClaw 自動化
+- `docs/features/catalog-maintenance.md` - 技能優化、記憶管理、記帳與驗證
+- `docs/architecture/cli-architecture.md` - CLI 設計：命令調度、工具註冊、更新檢查
+- `docs/architecture/installer-architecture.md` - 安裝器設計：原子同步、manifest 追蹤、連結模式
+- `docs/architecture/skill-structure.md` - 技能目錄佈局、frontmatter 規範、選擇性擴充
+- `docs/principles/naming-conventions.md` - 命名慣例：kebab-case、文件命名、工具命名
+- `docs/principles/skill-development.md` - 技能開發慣例：frontmatter、主體結構、依賴宣告
+- `docs/principles/testing-conventions.md` - 測試慣例：node:test、隔離、Python 測試發現
+- `README.md` - 公開安裝指南與技能目錄
+- `CHANGELOG.md` - 版本發佈歷史
+- `LICENSE` - MIT 授權條款

package/README.md

@@ -6,53 +6,46 @@ A curated skill catalog for Codex, OpenClaw, Trae, Agents, and Claude Code with
 
 - align-project-documents
 - analyse-app-logs
-- archive-specs
 - answering-questions-with-research
-- commit-and-push
+- archive-specs
+- cjk-pdf
 - codex-memory-manager
+- commit-and-push
 - deep-research-topics
 - develop-new-features
-
 - docs-to-voice
-- exam-pdf-workflow
 - document-vision-reader
 - enhance-existing-features
+- exam-pdf-workflow
 - feature-propose
 - financial-research
-- read-github-issue
 - generate-spec
-
 - implement-specs
 - implement-specs-with-subagents
 - implement-specs-with-worktree
-- init-project-html
 - improve-observability
-- iterative-code-performance
-- iterative-code-quality
+- init-project-html
 - jupiter-development
 - katex
 - learn-skill-from-conversations
 - learning-error-book
-- marginfi-development
 - maintain-project-constraints
+- marginfi-development
+- merge-changes-from-local-branches
 - novel-to-short-video
 - open-github-issue
 - open-source-pr-workflow
 - openai-text-to-image-storyboard
 - openclaw-configuration
 - optimise-skill
-
+- read-github-issue
 - record-spending
 - resolve-review-comments
-
-
 - review-spec-related-changes
-
 - shadow-api-model-research
+- ship-github-issue-fix
 - solana-development
-- spec-to-project-html
 - solve-issues-found-during-review
-- submission-readiness-check
 - systematic-debug
 - test-case-strategy
 - text-to-short-video

package/archive-specs/SKILL.md

@@ -23,12 +23,6 @@ description: 將已完成的spec歸檔到 `docs/archive/` 下。當你需要將s
 
 使用 `align-project-documents`, `maintain-project-constraints` 技能，按照這兩個技能之中的指引，更新項目文檔。並將完成的spec全部移動到 `docs/archive/`。
 
-## 使用範例
-
-- "這批 spec 已經實作完成，幫我整理成正式文件並歸檔" -> "先同步 `docs/` 與 `AGENTS.md` / `CLAUDE.md`，再把已完成的 spec 移到 archive"
-- "只有批次中的兩個子 spec 做完，另外一個還在進行" -> "只歸檔完成的子目錄，保留仍在使用的 `coordination.md`"
-- "spec 寫了未來計畫，但 repo 還沒實作" -> "不把該內容當成正式文件，只在需要時標成 `TBD` 或保留在 active planning"
-
 ## 參考資料索引
 
 - `references/templates/readme.md`：README.md 模板

package/commit-and-push/SKILL.md

@@ -23,20 +23,14 @@ description: 提供提交指引以及作為提交前的必要品控閘門。當
 
 ### 3. 同步項目文檔
 
-使用 `submission-readiness-check` 並遵照當中的指引，同步更新項目文檔，確保項目文檔時刻與repo保持一致。
+使用 `align-project-documents`, `maintain-project-constraints` 這兩個技能，並遵照當中的指引，同步更新項目文檔，確保項目文檔時刻與repo保持一致。
 
 ### 4. 提交及推送變更
 
 依使用者的 staging 邊界建立 commit，提交訊息遵循 `references/commit-messages.md`。
-只有在使用者明確要求更新remote時才 push。
+只有在使用者明確要求更新 remote 時才 push。
 
-## 範例
-
-- 「只把已 staged 的 `foo.ts` 提交」-> 只能提交已暫存內容，不能順手把未 staged 的 `bar.ts` 一起帶進來
-- 「幫我 push 這個 branch」-> 先完成 review 與 readiness gate，再 push，最後用 hash 證明remote已同步
-- 「順便幫我發版」-> 不使用本技能，改走 `version-release`
-
-## 參考資料索引
+## 參考資料
 
 - `references/commit-messages.md`：提交訊息格式
 - `references/branch-naming.md`：分支命名慣例

package/generate-spec/SKILL.md

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

package/generate-spec/references/definition.md

@@ -0,0 +1,12 @@
+## 功能模塊
+
+功能模塊是直接面向用戶的功能，如：
+- 登陸功能
+- 註冊功能
+- 邀請碼功能
+
+功能模塊由子模塊的合作、交互實現
+
+## 子模塊
+
+子模塊是功能模塊的關鍵組成部分。具體定義依照代碼的實作邊界得出。

package/init-project-html/SKILL.md

@@ -1,40 +1,36 @@
 ---
 name: init-project-html
-description: >-
-  使用 `apltk architecture` 初始化專案 HTML 架構圖譜，生成基礎 atlas YAML 與渲染後的 HTML 頁面。所有宣告基於倉庫證據；每個功能模組由一個可寫子 agent 負責，主 agent 必須等待全部子 agent 完成後，才能補跨功能連接並執行 render 與 validate。
+description: 當你需要為項目初始化架構圖時，使用此技能。
 ---
 
 ## 技能目標
 
-透過 `apltk architecture` 為目前倉庫建立基礎專案架構圖譜，產出受 CLI 管理的 atlas 狀態檔與渲染後的 HTML 頁面。
+在 `apltk` cli 的幫助下製作項目架構圖，幫助用戶理解項目的軟件架構
 
 ## 驗收條件
 
-- 只透過 `apltk architecture` 修改圖譜；不得手改 `resources/project-architecture/**/*.html`。
-- 所有宣告可追溯到真實程式碼、設定、SQL 或外部邊界；無法確認的部分用 `TBD` 或在 `meta.summary` 記錄遺漏原因。
-- 宏觀圖完整表達功能與子模組關係；所有跨邊界互動使用 `call`、`return`、`data-row`、`failure` 邊表達。
-- 每個非平凡子模組具備足夠內部結構：已宣告 `function`、`variable`、有序 `dataflow`、必要時的 `error`，且引用可通過校驗。
-- 採用「每個功能一個可寫子 agent」分工；主 agent 等所有子 agent 完成後才補跨功能邊，且 `apltk architecture validate` 通過。
+- 架構圖清楚描述了功能模塊之間的關係及子模塊之間的關係
 
 ## 工作流程
 
-1. 執行 `apltk architecture --help`，以 CLI 說明為唯一命令真源。
-2. 做整倉淺層盤點，列出功能模組的 slug、使用者視角職責、入口點與主要邊界資源。
-3. 為每個功能派發一個可寫子 agent，負責宣告該功能的全部子模組、函式、變數、資料流、本地錯誤與功能內邊。子 agent 返回子模組摘要及需要主 agent 補上的跨功能邊界資訊。
-4. 主 agent 不得重讀已委派功能的原始碼，也不得重複宣告子 agent 已處理的功能內元件。
-5. 全部子 agent 完成後，主 agent 統一補齊跨功能 edge、必要時補共享 meta 或 actor，然後執行 `apltk architecture render` 與 `apltk architecture validate`。
-6. 抽查渲染結果，確認宏觀圖和至少一個代表性子模組頁滿足驗收條件，彙報功能數、子模組數、邊數量、未覆蓋路徑與原因。
+### 1. 閱讀並理解代碼庫
 
-## 使用範例
+按照功能模塊的定義，全面檢索並將代碼庫拆分為單個或多個功能模塊。接著，開始對功能模塊下的子模塊進行識別及深度閱讀。
+如果外部環境允許使用 subagents ，建議為每一個功能模塊分配一個 subagents 進行深度閱讀，並要求 subagents 完整列出：
+- 該功能模塊與其他功能模塊之間是否存在交互；如有，如何交互。
+- 該功能模塊內部存在哪些子模塊，這些子模塊之間如何交互並實現功能模塊的功能。
+- 該功能模塊及下屬子模塊的資料流、錯誤處理。
 
-- 「替這個倉庫首次生成 HTML 架構圖」→ 梳理功能模組，按功能分派子 agent，彙總跨功能邊，生成基礎 atlas 與渲染頁面。交付物為 `resources/project-architecture/` 下的完整 atlas 狀態檔與通過驗證的 HTML 頁面。
-- 「把系統的資料流、呼叫關係和回滾路徑視覺化」→ 使用 `call` / `return` / `data-row` / `failure` 邊表達跨邊界關係，為每個關鍵子模組補齊內部 `dataflow`。
+### 2. 使用 `apltk` cli 工具協助生成架構圖
 
-## 參考資料索引
+將前一步獲取到的代碼庫只是通過 cli 工具轉化為清晰的架構圖。
+完成之後，驗證架構圖格式正確、可渲染。
+
+## 參考資料
 
 - `references/TEMPLATE_SPEC.md`：atlas 欄位、列舉和 CLI 寫入形狀速查表。
-- `lib/atlas/cli.js`：`apltk architecture` 的實作入口。
-- `lib/atlas/schema.js`：圖譜資料結構與校驗規則。
+- `references/definition.md`: 功能模塊和子模塊的詳細定義。
+- `references/architecture-page.template.html`: 模板html。
+- `references/architecture.css`: 風格模板。
 - `sample-demo/`：完整示例輸出，用於理解基礎 atlas 的最終形態。
-- `spec-to-project-html/SKILL.md`：面向規劃文件的 overlay 版本。
-- `update-project-html/SKILL.md`：面向已存在基礎 atlas 的增量刷新版本。
+- `apltk architecture --help` - cli 工具的指引指令。

package/init-project-html/references/definition.md

@@ -0,0 +1,12 @@
+## 功能模塊
+
+功能模塊是直接面向用戶的功能，如：
+- 登陸功能
+- 註冊功能
+- 邀請碼功能
+
+功能模塊由子模塊的合作、交互實現
+
+## 子模塊
+
+子模塊是功能模塊的關鍵組成部分。具體定義依照代碼的實作邊界得出。

package/maintain-project-constraints/SKILL.md

@@ -1,35 +1,27 @@
 ---
 name: maintain-project-constraints
-description: >-
-  依據倉庫現況刷新根目錄 `AGENTS.md` / `CLAUDE.md`，只保留 Common Development Commands、Project Business Goals、Project Documentation Index 三個可追溯區塊。
+description: 當你需要更新 `CLAUDE.md` 或 `AGENTS.md` 這兩份項目規範文檔的時候，調用這個技能。
 ---
 
 ## 技能目標
 
-基於當前倉庫證據，產出或刷新根目錄 `AGENTS.md` 與 `CLAUDE.md`，使其準確反映開發命令、專案商業目標與文件索引，不捏造任何內容。
+基於當前 repo 的最新文檔和及代碼，維護項目規範文檔。
 
 ## 驗收條件
 
-- 最終文件正文只包含三個區塊，順序固定：`Common Development Commands` → `Project Business Goals` → `Project Documentation Index`。
-- `Common Development Commands` 中每條命令可追溯到 `package.json`、`Makefile`、`bin/`、`scripts/` 或 CI 設定等真實入口。
-- `Project Business Goals` 只描述專案層級目的、服務對象與交付結果，不展開為功能清單。
-- `Project Documentation Index` 覆蓋現存 `docs/features/`、`docs/architecture/`、`docs/principles/` 與重要根目錄文件，每項對應真實路徑。
-- 過時路徑、虛構命令與多餘區塊已被移除。
-- 若 `AGENTS.md` 與 `CLAUDE.md` 同時存在且未聲明故意分歧，兩者三個區塊內容一致。
+- `CLAUDE.md`, `AGENTS.md` 已經被更新到最新狀態
 
 ## 工作流程
 
-1. 從倉庫現況收集可驗證的命令入口、專案目的與現有文件清單，不以舊約束文件作為唯一真相。
-2. 根據證據生成三個必需區塊，確保每條命令、商業目標與文件索引可被直接追溯。
-3. 按專案慣例更新或補齊 `AGENTS.md` / `CLAUDE.md`，正文限制在三個規定區塊內。
-4. 完成前逐項校驗命令來源、文件路徑與雙文件一致性，清除所有陳舊或多餘內容。
+### 1. 閱讀 repo
 
-## 使用範例
+深入閱讀當前項目文檔及實作代碼，並建立對於項目的全面認知。
+如果外部環境允許使用 subagents，建議通過調度 subagents 完成對 repo 代碼的深入閱讀。
 
-- 「重建 `docs/` 後，請同步刷新 `AGENTS.md` 和 `CLAUDE.md`」→ 根據當前腳本、入口與文件樹重寫兩個根目錄約束文件，只保留三個規定區塊並確保索引完整。
-- 「這個專案的 `CLAUDE.md` 已經過時，請補一份對應的 `AGENTS.md`」→ 依據現有命令與文件結構建立缺失文件，讓兩份約束文件在預期一致時保持同構。
-- 「請清理根目錄約束文件裡的舊命令與失效路徑」→ 驗證每條命令與索引路徑是否仍成立，只保留能被倉庫證據支持的內容。
+### 2. 更新項目規範文檔
 
-## 參考資料索引
+按照模板當中給出的格式，更新或創建 `CLAUDE.md`, `AGENTS.md`。
 
-- `references/constraint-file-reference.md`：三區塊契約、撰寫規則、核對清單與輸出模板。
+## 參考資料
+
+- `references/constraint-file-reference.md`：三區塊契約、撰寫規則、核對清單與輸出模板。

package/merge-changes-from-local-branches/SKILL.md

@@ -1,40 +1,27 @@
 ---
 name: merge-changes-from-local-branches
-description: >-
-  將使用者指定的本地分支合併回當前分支，依序完成衝突處理、驗證、安全清理與最終提交準備；除非本次對話明確要求，否則不推送遠端。
+description: 當你需要將 spec 相關的本地實作分支合併回當前所在分支時，調用這個技能。
 ---
 
 ## 技能目標
 
-在工作開始時的當前本地分支上，整合使用者指定的本地分支（或由 spec / batch 規劃可無歧義對應出的分支），完成合併、驗證、清理，並讓整合結果可安全交由 `commit-and-push` 收尾。
+將 spec 相關的本地實作分支合併回當前所在分支。
 
 ## 驗收條件
 
-- 所有合併變更落在流程開始時的原始當前分支，不會未經允許改換目標分支。
-- 合併範圍只包含使用者明確指定，或可由 `coordination.md` / spec 無歧義映射出的分支；若映射不清楚則停止並回報。
-- 當 batch 規劃存在 `Merge order` / landing order 時，實際整合順序與規劃一致；順序衝突或不明確時不猜測執行。
-- 所有衝突以保留正確行為為原則解決，並在刪除來源分支或交給 `commit-and-push` 前完成驗證。
-- 只清理已成功合併且已驗證的來源分支或 worktree；不強制刪除尚未真正合入的來源。
-- 最終交付是原始當前分支上的整合結果與簡潔摘要；只有使用者於本次對話明確要求時才推送遠端。本技能不單獨執行 `archive-specs`。
+- 分支的變更被合併，且所有潛在衝突代碼被解決。
 
 ## 工作流程
 
-1. 以流程開始時的當前分支為唯一目標分支，確認合併範圍（使用者明確指定的分支，或由 spec / `coordination.md` 無歧義映射出的分支與整合順序）。
-2. 確認工作樹適合執行合併：若存在干擾整合的未提交變更，停止並回報，不自行 stash 或切換分支。
-3. 依既定順序逐一合併 in-scope 分支。對已合入或無新增內容的分支，跳過並記錄原因。發生衝突時閱讀雙方內容編輯出正確結果；無法在不猜測意圖的前提下解決時停止並回報。必要時使用 `merge-conflict-resolver`。
-4. 先對衝突區域或高風險改動執行針對性驗證，再對整體整合結果執行倉庫慣用的標準驗證。驗證失敗先在當前分支修正。
-5. 僅清理已完成合併且通過驗證的來源分支與對應 worktree；安全刪除被拒絕時保留來源並回報，不使用強制刪除。
-6. 交由 `commit-and-push` 完成必要審查、submission-readiness gate 與本地提交。若 `commit-and-push` 不可用則停止並回報，不走裸 `git commit`。
-7. 總結已合併與跳過的分支、順序依據、衝突處理原則、驗證結果，以及流程最終停在本地 `HEAD` 還是包含遠端推送。
+### 1. 建立規格文檔基線認知
 
-## 使用範例
+閱讀目前用戶指定的 spec，並查看目前分支狀態，找到與 spec 相關的分支。
 
-- 「把 `feature/api-layer` 和 `feature/cli-wrapper` 合回目前分支」→ 以目前分支為唯一目標，依指定順序完成整合、驗證與安全清理，再交給 `commit-and-push` 做本地提交。
-- 「根據 batch 的 `coordination.md` 把各 worktree 分支合回來，但先不要 push」→ 從 batch 規劃確認無歧義分支映射與 landing order，依序合併、驗證、清理，只做到本地提交。
-- 「把那幾個應該相關的分支一起合一下」→ 若無法從使用者輸入或規劃文件明確判定分支集合與順序，停止並回報需要補充資訊。
+### 2. 合併分支及處理衝突
 
-## 參考資料索引
+按照 `coordination.md` 的建議順序，對分支進行合併。
+在解決分支衝突時，必須確保 spec 要求的功能沒有被破壞。
 
-- `commit-and-push/SKILL.md`：最終提交、submission-readiness 與是否允許推送的權威流程。
-- `merge-conflict-resolver/SKILL.md`：衝突需要精確合成時的輔助技能。
-- `docs/plans/**/coordination.md`：batch 規劃存在時的 landing order 與分支映射依據。
+### 3. 提交變更
+
+使用 `commit-and-push` 這個技能，將變更提交到當前分支上，不需要 push 到 remote。