@laitszkin/apollo-toolkit 3.12.1 → 3.13.0

package/iterative-code-quality/references/module-coverage.md

@@ -1,126 +0,0 @@
-# Module Coverage And Deep-Read Iterations
-
-## Purpose
-
-Prevent the agent from repeatedly improving only familiar or easy files while untouched modules remain unexamined.
-
-Use this reference in Step 1 to build the module inventory and in Step 2 to choose which module or module cluster receives the next deep-read iteration.
-
-Deep-read here does not mean generic reading. It means scanning the module through each available job lens so the agent can identify whether naming cleanup, simplification, module-boundary cleanup, logging alignment, test addition, or staged unlock work is justified.
-
-## Module inventory
-
-List every meaningful in-scope module before completion. A module may be:
-
-- a package, app, service, route group, command group, worker, or library,
-- a domain folder with a clear responsibility,
-- a runtime entrypoint plus its owned helpers,
-- a testable subsystem with stable callers and contracts.
-
-Record each module with:
-
-- module name and path roots,
-- primary responsibility,
-- entrypoints and public interfaces,
-- key callers and callees,
-- tests and guardrails,
-- logging or telemetry surfaces,
-- risk level and estimated ease,
-- current coverage status.
-
-Exclude generated, vendored, lock, build-output, snapshot, fixture-only, or explicitly out-of-scope areas only with evidence.
-
-## Coverage ledger statuses
-
-Use simple statuses so stopping conditions are auditable:
-
-- `unvisited`: inventoried but not deeply read yet.
-- `deep-read`: callers, callees, tests, logs, contracts, core files, and all available job lenses were inspected with enough context to judge quality.
-- `refactored`: at least one behavior-neutral improvement landed for this module.
-- `validated-clear`: deep read found no actionable in-scope quality issue worth changing now.
-- `deferred`: an issue exists but is blocked, unsafe, speculative, approval-dependent, or requires macro-architecture/product scope.
-- `excluded`: not human-maintained source or outside the user's requested scope.
-
-Completion is not allowed while any in-scope module remains `unvisited`.
-
-## Easy-first module ordering
-
-Start with the easiest useful modules when that reduces risk:
-
-- small surface area,
-- clear ownership,
-- local tests or cheap guardrails,
-- limited side effects,
-- low public API or persistence risk,
-- likely to clarify names, tests, boundaries, or seams used by harder modules.
-
-Do not confuse easy-first with low-value churn. The chosen module should either resolve real quality issues or create context/guardrails that make later modules safer.
-
-If multiple modules are equally easy, prefer the one that unlocks harder modules by improving shared naming, helpers, tests, logging, or dependency seams.
-
-## Deep-read requirements
-
-A module iteration is not deep-read until the agent inspects:
-
-- module entrypoints and public interfaces,
-- internal core files and responsibility boundaries,
-- key callers and downstream callees,
-- tests, fixtures, mocks, and validation commands,
-- logs, metrics, tracing, and error messages,
-- configuration, persistence, and external-service contracts when relevant,
-- known TODOs, comments, or docs that describe current behavior.
-
-It also must inspect the module through each available job lens:
-
-- `naming cleanup`: are names hiding ownership, units, state, lifecycle, or intent?
-- `function simplification / extraction`: are there duplicated flows, hard-coded orchestration paths, or overly mixed functions?
-- `module-boundary cleanup`: are responsibilities mixed in ways that can be split safely?
-- `logging alignment`: are logs stale, misleading, or missing at important branch/outcome points?
-- `test addition`: are important behaviors, edges, or invariants weakly guarded?
-- `staged unlock work`: if the module is too coupled for direct cleanup, what is the next smaller unlock step?
-
-Do not mark a module `validated-clear` from a shallow file skim.
-Do not mark a module `validated-clear` until every available job lens has been checked and classified as one of: actionable now, unlock-first, deferred, excluded, or no meaningful issue found.
-
-## Choosing the next module
-
-After every iteration:
-
-1. Re-scan the module ledger.
-2. Prefer an `unvisited` module unless a just-touched module must be stabilized before moving on.
-3. Choose the easiest useful `unvisited` module that can be deeply read and improved or validated now.
-4. Scan that module through every available job lens before deciding what "this round" means.
-5. If the next unvisited module is high-risk and under-guarded, choose guardrail-building jobs first.
-6. If the next unvisited module is too coupled for direct cleanup, choose staged unlock work rather than skipping it.
-7. Return to the full-codebase scan after validation and update the ledger.
-
-Revisiting a familiar module is valid only when:
-
-- it blocks safe deep reading of an unvisited module,
-- a previous refactor created follow-up drift that must be stabilized,
-- validation exposed a real defect or stale contract,
-- cross-module cleanup requires touching it together with the next module.
-
-## Module cluster iterations
-
-One iteration may cover a small cluster of modules when they share one boundary or invariant, such as:
-
-- a command and its parser,
-- a route and its service,
-- a domain module and its test helpers,
-- an integration wrapper and its local fake.
-
-Keep clusters bounded. Do not use clustering to claim full-repository coverage without deep context.
-
-## Stage-gate questions
-
-At the end of each iteration, answer:
-
-- Which module or module cluster was deeply read?
-- Which job lenses were checked, and which jobs were selected and why?
-- What quality issue was fixed, or why is the module validated-clear?
-- Which guardrails prove behavior was preserved?
-- Which modules remain `unvisited`?
-- Which module is the next easiest useful target?
-
-If any in-scope module remains `unvisited`, the correct action is to return to Step 1, not to finish.

package/iterative-code-quality/references/naming-and-simplification.md

@@ -1,73 +0,0 @@
-# Naming And Function Simplification
-
-## Naming improvements
-
-Rename only when the current name creates real ambiguity.
-
-Good rename reasons:
-
-- hides domain role, unit, quantity, ownership, or lifecycle stage,
-- uses stale terminology after a refactor,
-- collides with another concept in the same scope,
-- makes boolean, enum, or state-transition meaning unclear,
-- forces readers to inspect implementation before understanding intent.
-
-Avoid renaming when:
-
-- the name is already clear in local context,
-- the change is pure personal preference,
-- the name is part of a stable external API, database schema, event contract, or migration-sensitive field,
-- the rename would create broad churn without reducing ambiguity.
-
-## Naming patterns
-
-- Prefer domain nouns over implementation nouns: `selectedAccount` over `item`.
-- Include units for quantities: `timeoutMs`, `amountCents`, `windowDays`.
-- Use booleans that read as predicates: `isEligible`, `hasPendingRetry`, `shouldPersist`.
-- Name collections by contents: `pendingInvoices`, not `list`.
-- Name state transitions by lifecycle: `markSettlementComplete`, not `updateStatus`.
-- Keep test data names meaningful: `expiredSubscription`, `duplicateEvent`, `unauthorizedActor`.
-
-## Function simplification signals
-
-Simplify functions that contain:
-
-- repeated guard clauses or duplicated validation,
-- mixed parsing, validation, orchestration, persistence, and formatting,
-- nested branches that hide the main path,
-- temporary variables whose names encode implementation steps rather than domain state,
-- hard-coded workflow steps repeated in multiple callers,
-- comments explaining what code structure should make obvious.
-
-## Safe simplification moves
-
-- Extract pure transformations and validations into small helpers.
-- Replace repeated literal mappings with a named table or function.
-- Flatten nested conditionals with explicit guard clauses when it clarifies failure paths.
-- Centralize one business rule behind one function when multiple callers duplicate it.
-- Split orchestration from local computation when tests need a deterministic unit.
-- Delete dead compatibility paths only when reachability evidence and tests support deletion.
-
-## Extraction rules
-
-Create a reusable helper only when at least one condition is true:
-
-- two or more call sites duplicate the same rule,
-- the extracted logic has a clear domain name and stable contract,
-- the helper makes a high-value invariant testable,
-- the helper isolates an external dependency contract or side-effect boundary,
-- the current function has multiple reasons to change.
-
-Keep extracted helpers close to the owner module unless the repository already has a shared utility location for that domain.
-
-## Behavior preservation checklist
-
-Before and after simplification, verify:
-
-- inputs, outputs, exceptions, side effects, and ordering are unchanged,
-- persisted data and emitted events keep the same contract,
-- public API and CLI behavior remain stable,
-- log fields remain compatible unless stale names were intentionally corrected,
-- existing tests still pass and new tests cover extracted rules.
-
-If these checks can be enforced by existing or newly added tests, do not treat subjective confidence alone as a reason to avoid the simplification.

package/iterative-code-quality/references/repository-scan.md

@@ -1,65 +0,0 @@
-# Repository Scan And Backlog Selection
-
-## Purpose
-
-Build a factual map before changing code, then choose the highest-value quality improvements while tracking module-by-module job-oriented deep-read coverage.
-
-## Required scan
-
-- Read `AGENTS.md/CLAUDE.md`, `README*`, project docs, manifests, task runners, CI configs, and test setup.
-- List entrypoints: CLI commands, servers, workers, jobs, frontend routes, scripts, libraries, or public packages.
-- Identify core domain modules, external integrations, persistence boundaries, logging utilities, and test helpers.
-- Create a module inventory and coverage ledger using `references/module-coverage.md`.
-- For each module, scan through the available job lenses instead of treating scan as generic code reading.
-- Inspect current git state before editing so unrelated user changes are not overwritten.
-- Identify generated, vendored, lock, snapshot, build-output, and fixture files; exclude them from refactoring unless they are human-maintained source.
-
-## Code quality backlog signals
-
-Prioritize files or functions with:
-
-- high fan-in or many call sites,
-- critical business rules or money/security/data-integrity decisions,
-- duplicated condition trees, conversions, validation, or external-call choreography,
-- unclear naming around ownership, units, state, or lifecycle,
-- large functions that mix parsing, validation, orchestration, side effects, and formatting,
-- log messages that describe old concepts or omit branch/failure context,
-- low or missing tests around meaningful invariants and edge cases.
-
-## Evidence to capture
-
-For each candidate record:
-
-- file path and symbol name,
-- owning module or module cluster,
-- job lens that exposed the issue,
-- observed quality problem,
-- why it matters to maintainability or correctness confidence,
-- expected behavior-neutral change,
-- tests or validations needed to prove safety,
-- reason to defer if the candidate requires product or architecture approval.
-
-## Exclusion rules
-
-Do not refactor:
-
-- third-party, generated, or compiled artifacts,
-- snapshots where churn would hide signal,
-- code the user marked as actively edited elsewhere,
-- public schema/API names that require migration planning,
-- areas that cannot be validated and are not causing a clear quality risk.
-
-## Backlog scoring
-
-Prefer a small set of high-confidence improvements over an exhaustive sweep.
-
-Score each candidate by:
-
-1. **Impact**: criticality, call frequency, future change risk.
-2. **Confidence**: evidence that the change is behavior-neutral.
-3. **Validation**: ability to test or otherwise prove equivalence.
-4. **Blast radius**: number of modules, public contracts, and migrations affected.
-
-Start with high-impact, high-confidence, low-blast-radius items. Escalate broad changes only when smaller passes cannot resolve the root problem.
-
-Do not finish from backlog scoring alone. Completion also requires the module coverage ledger to show that every in-scope module has been deeply read and either improved, validated-clear, deferred, or excluded with evidence.

package/iterative-code-quality/references/testing-strategy.md

@@ -1,95 +0,0 @@
-# Risk-Based Testing Strategy
-
-## Principle
-
-Choose tests from the risk inventory, not from a generic coverage target.
-
-For every non-trivial pass, ask what could regress silently if the cleanup were wrong.
-
-Use the resulting guardrails aggressively: when tests or equivalent verification can prove behavior preservation, they should unlock bolder refactors rather than merely justify small cosmetic edits.
-
-Confidence decisions must include the agent's own ability to understand and complete the refactor, not only the apparent difficulty of the code. Strong tests, characterization coverage, narrow rollback points, and clear validation commands are objective support: if the refactor breaks behavior, the agent should use the failing guardrails to repair the true owner and return the suite to green instead of treating the task as impossible.
-
-Do not require pre-existing tests before every refactor. Instead:
-
-- if existing guardrails are already sufficient, proceed;
-- if the area is high-risk and guardrails are weak, add the smallest high-value tests first and treat that as progress toward the refactor.
-
-The intended end state is not merely "some tests passed for touched files". The refactor is complete only when the relevant guarded test surface for the repository remains green after the cleanup.
-
-## Unit tests
-
-Use for:
-
-- extracted helpers,
-- renamed or simplified business rules,
-- validation and rejection logic,
-- branch-specific errors and side effects,
-- formatting or parsing boundaries.
-
-Good oracles:
-
-- exact return values,
-- exact domain state transitions,
-- exact error class or reason code,
-- emitted side effect or explicit lack of side effect.
-
-For high-risk legacy code with weak coverage, characterization-style unit tests are often the first unlock step even before the larger cleanup happens.
-
-## Property-based tests
-
-Use when logic has invariants or broad input space:
-
-- serialization or parsing round trips,
-- sorting, grouping, deduplication, aggregation,
-- authorization or eligibility predicates,
-- idempotency, retry, replay, and state-machine transitions,
-- generated mocked external-service states.
-
-Record `N/A` only with a concrete reason, such as "no generated input space; pass only renamed local variables."
-
-## Integration tests
-
-Use when the risk spans modules:
-
-- orchestration calling extracted domain helpers,
-- persistence plus domain transition,
-- API/CLI handler plus service layer,
-- logging contract across a real execution path,
-- adapter behavior with mocked external services.
-
-For external services, prefer mocks, fakes, local emulators, or recorded stable fixtures unless the real contract is explicitly under test.
-
-When risk comes from multi-module coupling rather than one local function, integration coverage is often the best guardrail to add before refactoring.
-
-## E2E tests
-
-Use only when:
-
-- the project already has reliable E2E infrastructure,
-- the path is user-critical,
-- required external services are stable, controlled, or safely mocked,
-- the same confidence cannot be gained from faster integration tests.
-
-If E2E is unreliable or too costly, add stronger integration coverage and state the reason.
-
-## Edge and adversarial coverage
-
-Consider:
-
-- null, empty, malformed, duplicate, oversized, and boundary inputs,
-- unauthorized actors and invalid transitions,
-- stale, duplicate, out-of-order, or replayed events,
-- dependency timeout, 429/500, partial response, and inconsistent response,
-- partial write, rollback, compensation, and idempotency behavior,
-- concurrency or shared-state contamination when the code is stateful.
-
-## Test hygiene
-
-- Keep tests deterministic and close to the behavior owner.
-- Prefer table-driven cases for many similar business permutations.
-- Preserve failing seeds or examples from property-based tests.
-- Do not weaken existing tests to fit the refactor.
-- If old tests asserted implementation details, rewrite them around stable behavior while preserving the business invariant.
-- Once stable guardrails exist, do not refuse a maintainability-improving refactor purely because confidence feels lower than ideal; combine self-assessed ability with the objective safety net and let the guardrails decide.
-- If stable guardrails do not yet exist for a high-risk area, create them as the next execution direction instead of treating the refactor as blocked forever.

package/merge-conflict-resolver/SKILL.md

@@ -1,46 +0,0 @@
----
-name: merge-conflict-resolver
-description: Resolve git merge conflicts using deterministic rules that preserve correct functionality. Use when branch consolidation encounters merge conflicts and needs automated resolution guidance that reads both parent versions and applies scenario-specific strategies.
----
-
-# Merge Conflict Resolver
-
-## Dependencies
-
-- Required: none.
-- Conditional: **`commit-and-push`** when the user expects the resolved tree to be **committed** or **pushed**—**MUST** run that skill for the submission leg instead of bare `git commit` / ad-hoc push when readiness gates apply.
-- Optional: none.
-- Fallback: If a **gated** submission was requested but **`commit-and-push`** is unavailable, **MUST** stop and report.
-
-## Standards
-
-- Evidence: Read both parent versions from conflict markers before resolving.
-- Execution: Read conflicts → apply scenario rules → verify with tests → recommit via **`commit-and-push`** when persisting to git.
-- Quality: Prefer preserving functionality over keeping either branch's exact changes.
-- Output: Return resolved files with passing verification.
-
-## Workflow
-
-### 1) Read conflict markers
-
-- Read both parent versions from conflict markers before editing.
-- Never use `-X ours`/`-X theirs` as the default strategy; only for narrowly justified conflicts after reading the actual content.
-
-### 2) Apply scenario rules
-
-| Scenario | Resolution |
-|----------|-----------|
-| Same line, both branches changed behavior | Read both code paths and compose merged logic preserving the verified invariant |
-| Same line, bug fix vs refactor | Keep the bug fix, reapply compatible refactor structure |
-| File deleted in one, modified in other | Keep version supported by current references/tests; delete only if proven correct |
-| Both modified same file differently | Preserve both when compatible; manually compose overlapping changes |
-| Test files conflict | Preserve both coverages unless one assertion is obsolete |
-| Config file (non-overlapping keys) | Keep both values |
-| package.json dependency | Keep higher version if compatible |
-| Same function added differently | Keep both; rename if needed |
-
-### 3) Verify after resolution
-
-- `git add <resolved-files>`
-- Run targeted tests or build checks for changed files.
-- If verification fails, resolve differently before committing.

package/merge-conflict-resolver/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "merge-conflict-resolver"
-  short_description: "Resolve git merge conflicts with deterministic, evidence-based rules"
-  default_prompt: >-
-    Use $merge-conflict-resolver to read both sides of conflict markers, apply scenario-specific resolution rules that preserve intended behavior, verify with the project’s tests or checks, and when the user needs persistence, hand off to $commit-and-push instead of ad-hoc git commands.

package/spec-to-project-html/SKILL.md

@@ -1,42 +0,0 @@
----
-name: spec-to-project-html
-description: >-
-  使用 `apltk architecture --spec <spec_dir>` 將專案 HTML 架構圖同步到活躍規劃文件。單個 spec 寫入 `<spec_dir>/architecture_diff/`，批量 spec 寫入 `coordination.md` 旁的共享 overlay；每個受影響功能由一個可寫子 agent 負責功能內 overlay 更新，主 agent 必須等待全部子 agent 完成後，才能補跨功能邊、渲染並驗證。基礎 atlas 不得被此技能修改。
----
-
-# 規劃文件同步到專案 HTML 架構圖
-
-## 技能目標
-
-根據 `docs/plans/...` 下的規劃文件，為專案架構圖生成或更新 spec overlay，使評審者能夠透過 `apltk architecture diff` 直接查看 proposed-after 架構變化，同時保持基礎 atlas 不被污染。
-
-## 驗收條件
-
-- 只透過 `apltk architecture --spec <spec_dir>` 寫入 overlay；單個 spec 產物位於 `<spec_dir>/architecture_diff/`，批量 spec 則寫入 `coordination.md` 同級的共享 overlay；不得手改 `architecture_diff/**/*.html`。
-- 讀取規劃文件時遵循 `spec.md` → `design.md` → `contract.md` → `coordination.md` 的順序；所有重要宣告都能同時回溯到 spec 語句和相關程式碼或設計證據。
-- 對於程式碼尚未實作、但規劃中已經提出的結構，必須顯式使用 `planned`、`gap` 或 `TBD` 標記，而不能偽裝成已落地實作。
-- 按「每個受影響功能一個可寫子 agent」執行 overlay 更新；主 agent 必須等全部子 agent 完成後，才允許補跨功能邊、共享 `meta` 或共享 `actor`。
-- `apltk architecture validate --spec <spec_dir>` 通過，且 `apltk architecture diff` 中的頁面配對正確，沒有懸空邊、孤兒頁面或錯誤的 add/remove 配對。
-
-## 工作流程
-
-1. 先定位本次規劃目錄；使用者明確給出路徑時優先使用，否則結合 `coordination.md` 找到正確 plan 集，並整理相關需求編號用於追蹤。
-2. 執行 `apltk architecture --help` 取得最新命令形態，然後按 `spec.md`、`design.md`、`contract.md`、`coordination.md` 的順序讀取內容，確定哪些功能、子模組、邊、變數或錯誤語義會發生變化。
-3. 先只列出受影響功能，不要提前把所有原始碼塞進主 agent。除了直接變更的功能，也要納入跨功能邊另一端的功能，確保 overlay 中的跨邊界關係完整。
-4. 為每個受影響功能派發一個可寫子 agent。每個子 agent 只負責自己功能內的 overlay 寫入：子模組、函式、變數、資料流、錯誤，以及功能內邊；若規劃領先於程式碼，則在角色、用途或資料流文案中明確標註 `planned`、`gap` 或 `TBD`。
-5. 子 agent 只返回功能內變更摘要、跨功能邊界變化和待記錄的 `planned/gap` 標記；主 agent 不得重讀已委派功能原始碼，也不得重複寫功能內元件。
-6. 等全部子 agent 完成後，主 agent 統一補跨功能 `edge`、必要的共享 `meta` / `actor`，再執行 `apltk architecture validate --spec <spec_dir>`，並透過 `apltk architecture diff` 檢查 overlay 頁面是否正確映射到 before/after 視圖。
-7. 最終報告至少包含：觸及的 overlay 檔案或 CLI 變更類別、`modified` / `added` / `removed` 數量、所有子 agent 已完成後才開始跨功能連線的確認、未解決的 spec 與程式碼差距，以及後續跟進行動。
-
-## 使用範例
-
-- 「把這份新 spec 的架構變化渲染成 before/after HTML 對照。」 -> 「讀取 plan 集，按受影響功能分派子 agent，寫入 `architecture_diff/` overlay，並用 `apltk architecture diff` 驗證。」
-- 「批量規劃下多個 spec 共用一份架構 overlay。」 -> 「仍以成員 spec 路徑呼叫 `--spec`，但讓 CLI 自動彙總到 `coordination.md` 同級的共享 overlay 根目錄。」
-
-## 參考資料索引
-
-- `init-project-html/SKILL.md`：基礎語義規則、邊類型與子模組表達約束。
-- `references/TEMPLATE_SPEC.md`：overlay 模式下的欄位、列舉與 diff 配對規則速查表。
-
-- `generate-spec`、`implement-specs*`：需求編號和規劃流程的上游來源。
-- `apltk architecture --help`：`--spec` 模式命令與參數的唯一真源。

package/spec-to-project-html/agents/openai.yaml

@@ -1,11 +0,0 @@
-interface:
-  display_name: "spec-to-project-html"
-  short_description: "Sync the project HTML architecture atlas with active planning specs via `apltk architecture --spec`"
-  default_prompt: >-
-    Use $spec-to-project-html. Read docs/plans (spec → design → contract). Every overlay mutation: `apltk architecture --spec <spec_dir> …`. **Exact commands: `apltk architecture --help`** — do not trust long command lists in docs.
-    Single specs write `<spec_dir>/architecture_diff/atlas/*.yaml` + affected HTML under `<spec_dir>/architecture_diff/`. Batch member paths resolve to the shared batch-root `architecture_diff/` beside `coordination.md`, so one batch keeps one overlay + one rendered diff. Base `resources/project-architecture/` is read-only here. NEVER hand-edit `architecture_diff/**`.
-    **`apltk architecture diff`** builds a paginated viewer: scans all `docs/plans/**/architecture_diff/`, pairs overlay paths with base atlas HTML by relative path, labels modified/added/removed — use it to verify the architecture delta before hand-off.
-    **Subagents only:** dispatch ONE write-capable subagent per AFFECTED feature; each applies ALL intra-feature overlay mutations (`submodule`/`function`/`variable`/`dataflow`/`error`/`edge` within that feature). Each returns ONLY change summary + outbound boundary deltas for OTHER features.
-    **HARD GATE:** main agent MUST wait until ALL subagents finish before ANY cross-feature `edge add|remove`, overlay `meta` that stitches multiple features, or shared `actor` for cross-feature context. Then `render --spec`, `validate --spec`.
-    Sub-module pages stay self-only — cross-boundary = `edge`. For removals/renames in overlay, follow SKILL.md (`submodule remove` / remove+add pattern) so `diff` classifies correctly.
-    After work: `validate --spec` MUST be OK; run `diff` and report modified/added/removed counts. Semantic rules: $init-project-html SKILL.md.

package/spec-to-project-html/references/TEMPLATE_SPEC.md

@@ -1,113 +0,0 @@
-# Atlas component schema — reference cheat sheet (spec-to-project-html copy)
-
-> Reference material only. The binding rules (read strategy, evidence requirements, what each verb means) live in `init-project-html/SKILL.md` (atlas authority) and this skill's `SKILL.md` (spec-overlay variant). This file lists the exact fields and enum values that `apltk architecture --spec <spec_dir>` accepts; the renderer produces consistent DOM/CSS/ARIA hooks under `<spec_dir>/architecture_diff/` so agents never need to touch HTML.
-
-## State files on disk
-
-Base atlas (read-only from this skill's perspective):
-
-```
-<project>/resources/project-architecture/atlas/
-├── atlas.index.yaml
-├── features/<slug>.yaml
-├── atlas.history.log
-└── atlas.history.undo.json
-```
-
-Overlay (where this skill writes via `--spec`):
-
-```
-<spec_dir>/architecture_diff/
-├── atlas/
-│   ├── atlas.index.yaml          # optional partial override (meta / actors / cross-feature edges / feature order)
-│   ├── features/<slug>.yaml      # full proposed state of any changed feature
-│   ├── _removed.yaml             # {features: [...], submodules: [{feature, submodule}]}
-│   ├── atlas.history.log
-│   └── atlas.history.undo.json
-├── index.html                    # rendered (re-emit only when macro visibly changes)
-├── features/<slug>/index.html    # rendered (re-emit when the feature page would visibly change)
-├── features/<slug>/<sub>.html    # rendered (re-emit when the sub-module's tables/dataflow change)
-├── _removed.txt                  # auto-written by the renderer; lists removed HTML paths
-└── assets/                       # architecture.css + viewer.client.js (copied by the renderer)
-```
-
-## Components (mirrors `init-project-html/references/TEMPLATE_SPEC.md`)
-
-### `meta`
-
-| Field   | Type   | Required | Notes |
-| ------- | ------ | -------- | ----- |
-| title   | string | yes      | Macro page H1; the spec overlay typically keeps the base title. |
-| summary | string | no       | Update if the spec changes scanned roots or known omissions. |
-
-CLI: `apltk architecture meta set --spec <spec_dir> --title "..." --summary "..."`
-
-### `actor`
-
-| Field | Type | Required | Notes |
-| ----- | ---- | -------- | ----- |
-| id    | kebab-case | yes | Stable identity. |
-| label | string | yes | Display name. |
-
-CLI: `apltk architecture actor add --spec <spec_dir> --id ... --label "..."`
-
-### `feature`
-
-Same shape as base mode (`slug`, `title`, `story`, `dependsOn`, `submodules`, `edges`). `submodule add|remove`, `function add|remove`, etc. mutate the feature's full overlay snapshot under the hood — declare what you would have declared in base mode, but pass `--spec <spec_dir>`.
-
-CLI: `apltk architecture feature add --spec <spec_dir> --slug <kebab> --title "..." --story "..."`
-
-### `submodule`
-
-| Field | Type | Required | Notes |
-| ----- | ---- | -------- | ----- |
-| slug  | kebab-case | yes | The HTML filename. |
-| kind  | enum `ui` `api` `service` `db` `pure-fn` `queue` `external` | yes | Drives node colour + chip. |
-| role  | string | no | Own responsibility in one sentence. Use `planned: ...` or `gap: ...` to mark spec items the code does not yet implement. |
-| functions / variables / dataflow / errors | arrays | no | Edited through their own CLI verbs. |
-
-CLI: `apltk architecture submodule add|set|remove --spec <spec_dir> --feature X --slug Y --kind ... --role "..."`
-
-### `function`, `variable`, `dataflow`, `error`
-
-Each row uses the same fields documented in `init-project-html/references/TEMPLATE_SPEC.md`. Always pass `--spec <spec_dir>` so the write lands in the overlay.
-
-`dataflow` steps accept the same structured fields in overlay mode — `--fn` must reference a function declared in this overlay (or inherited from base) for the same sub-module; `--reads` / `--writes` must reference variables declared there. `validate --spec <spec_dir>` enforces these references against the **merged** state, so adding a step that names a function/variable the spec also introduces is fine as long as both land in the same overlay.
-
-### `edge`
-
-| Field | Type | Required | Notes |
-| ----- | ---- | -------- | ----- |
-| id    | kebab-case | recommended | Pass `--id <stable>` when adding or removing so the CLI matches unambiguously. |
-| from  | `feature/submodule` or (intra-feature) `submodule` | yes | |
-| to    | same shape | yes | |
-| kind  | enum `call` `return` `data-row` `failure` | yes | |
-| label | string | no | |
-
-CLI: `apltk architecture edge add|remove --spec <spec_dir> --from <feature>[/sub] --to <feature>[/sub] --kind ... --label "..."`
-
-## Diff classification (how `apltk architecture diff` pairs pages)
-
-`apltk architecture diff` scans every `docs/plans/**/architecture_diff/**/*.html` (skipping `assets/` and `atlas/`) and pairs by path against `resources/project-architecture/`:
-
-| Base exists? | Overlay HTML exists? | Listed in `_removed.txt`? | Classification |
-| ------------ | -------------------- | ------------------------- | -------------- |
-| yes          | yes                  | no                        | **modified** (split before/after view) |
-| no           | yes                  | no                        | **added** (single after view) |
-| yes          | no                   | yes                       | **removed** (single before view) |
-
-The renderer writes `_removed.txt` automatically from `_removed.yaml`; agents only set the YAML through `feature remove` / `submodule remove`.
-
-## Quick example: add a 2FA sub-module to an existing feature
-
-```bash
-apltk architecture --spec docs/plans/2026-05-11/add-2fa \
-  submodule add --feature register --slug 2fa --kind service \
-  --role "TOTP verification (planned: not yet implemented)"
-apltk architecture --spec docs/plans/2026-05-11/add-2fa \
-  edge add --from register/api --to register/2fa --kind call --label "verify TOTP" --id e-api-2fa
-apltk architecture --spec docs/plans/2026-05-11/add-2fa validate
-apltk architecture diff
-```
-
-The CLI writes only the affected HTML pages (`features/register/2fa.html` plus any page whose visible state changed) into `architecture_diff/`, and the diff viewer pairs them with the base atlas.

package/submission-readiness-check/SKILL.md

@@ -1,39 +0,0 @@
----
-name: submission-readiness-check
-description: >-
-  用於在 commit、push、PR 或 release 前做最後同步檢查。會確認 `CHANGELOG.md`、
-  專案文件、`AGENTS.md` / `CLAUDE.md` 與已完成的 planning artifacts 是否都已更新到可提交狀態。
----
-
-## 目標
-
-在任何提交、推送、開 PR 或發版前，先把 repository 的外部說明、內部約束與 planning artifacts 同步到一致狀態，避免把未整理完成的變更交給下一個提交流程。
-
-## 驗收條件
-
-- 已盤點真實的提交面，包括 git 狀態、staged diff、現有 docs、planning artifacts 與目標提交流程
-- 當 spec 已完成且應轉成長期文件時，已先完成 `archive-specs`，而不是把它留給後續流程猜測處理
-- `docs/`、`AGENTS.md` / `CLAUDE.md` 與必要的 `README.md` 已根據實際行為與工作流程同步
-- `CHANGELOG.md` 的 `Unreleased` 區塊已準確對應這次將提交、開 PR 或發版的真實範圍
-- 最終輸出的是明確的 ready / blocking verdict，而不是模糊警告
-
-## 工作流程
-
-1. 先讀取 git 狀態、staged / unstaged diff，並盤點 repo 是否有 `CHANGELOG.md`、`AGENTS.md`、`CLAUDE.md`、標準化 `docs/` 結構，以及任何 `docs/plans/...` 計劃集
-2. 判斷下游流程屬於 `commit-push`、`pull-request` 或 `release`，因為不同流程對 changelog 與發版資料的要求不同
-3. 檢查 planning artifacts 是否應轉檔；只要 plan set 已對應本次交付成果，或專案文件仍未標準化，就必須先跑 `archive-specs`
-4. 在 spec 歸檔判斷完成後，同步專案文件；必要時執行 `align-project-documents` 更新 `docs/`，再用 `maintain-project-constraints` 更新 `AGENTS.md` / `CLAUDE.md`
-5. 檢查 `CHANGELOG.md`：對 commit / PR 流程，要讓 `Unreleased` 精準反映這次待提交內容，同時保留其他未出貨工作；對 release 流程，`Unreleased` 必須非空且已整理成可直接切版的 release notes
-6. 彙整哪些項目已同步、哪些仍阻塞；若還有未完成的 gate，明確回報 blocking item，而不是把責任留給下一個技能
-
-## 範例
-
-- 「準備提交這批變更」-> 檢查是否有未同步 changelog、文件與已完成但尚未歸檔的 spec
-- 「準備開 PR」-> 確保 `Unreleased` 反映當前 PR 範圍，並把 `AGENTS.md` / `CLAUDE.md` 與 docs 同步好
-- 「準備發版」-> 確保 `Unreleased` 非空且可直接作為 release notes，並先完成任何必要的 spec 歸檔與文件標準化
-
-## 參考資料
-
-- `align-project-documents`：同步 `docs/features/`、`docs/architecture/`、`docs/principles/`
-- `maintain-project-constraints`：同步 `AGENTS.md` / `CLAUDE.md`
-- `archive-specs`：在符合條件時轉檔並歸檔 planning artifacts

package/submission-readiness-check/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Submission Readiness"
-  short_description: "Sync changelog and docs before submit"
-  default_prompt: "Use $submission-readiness-check to prepare repository docs, changelog, and plan archives before commit, push, or release."