@laitszkin/apollo-toolkit 3.8.2 → 3.8.4

package/archive-specs/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "archive-specs"
-  short_description: "Convert completed specs into project docs and archive the consumed plans"
-  default_prompt: "Use $archive-specs to inventory the project's spec.md/tasks.md/checklist.md/contract.md/design.md files plus any batch-level coordination.md, reconcile them with the current repository, use coordination.md to understand shared preparation and legacy-replacement direction across parallel plan sets, rewrite existing project docs into a standardized categorized structure when needed, generate or update a concise README plus split project docs for getting started, configuration, architecture, features, and developer guidance, maintain a docs/README.md reference list, then archive the consumed source plans after successful conversion, deleting them only when the repository clearly does not need historical retention and keeping coordination.md active while any spec set still depends on it."
+  short_description: "Convert completed specs into standardized project docs and archive the consumed plans"
+  default_prompt: "Use $archive-specs to inventory the project's spec.md/tasks.md/checklist.md/contract.md/design.md files plus any batch-level coordination.md, reconcile them with the current repository, use coordination.md to understand shared preparation and legacy-replacement direction across parallel plan sets, delegate documentation generation to align-project-documents which produces standardized docs under docs/features/ (BDD user-facing features), docs/architecture/ (macro-level design principles), and docs/principles/ (code conventions and constraints), then delegate AGENTS.md/CLAUDE.md refresh to maintain-project-constraints which writes business goals, common commands, and the project documentation index. Archive the consumed source plans after successful conversion, deleting them only when the repository clearly does not need historical retention and keeping coordination.md active while any spec set still depends on it."

package/archive-specs/references/templates/architecture.md

@@ -1,29 +1,21 @@
-# Architecture
+# <模組／層名稱> 設計原則
 
-## 1. High-Level Structure
+[One-sentence summary of this module's role in the system.]
 
-- Entry points: [CLI/server/app/worker]
-- Major modules: [module names and responsibilities]
-- Data flow summary: [request/event/job flow]
-- Integration boundaries: [DB/API/queue/filesystem]
+## <原則標題>
 
-## 2. Directory Guide
+<原則描述：這條原則規範什麼、為什麼這樣設計、適用範圍>
 
-| Path | Responsibility |
-| --- | --- |
-| `[path]` | [What lives here] |
-| `[path]` | [What lives here] |
+## <原則標題>
 
-## 3. Key Flows
+<原則描述>
 
-### [Flow Name]
-- Trigger: [route/command/job]
-- Main steps: [step summary]
-- Dependencies: [internal/external]
-- Failure boundaries: [where failures surface]
+---
 
-## 4. Operational Notes
+## Writing Rules
 
-- State/storage model: [DB/files/cache/queue]
-- Concurrency or ordering concerns: [if any]
-- Observability entrypoints: [logs/metrics/traces/dashboards]
+- State design principles, not implementation details.
+- Keep each principle macro-level so it survives minor code changes.
+- Focus on: module responsibilities, boundary rules, data flow direction, and integration contracts.
+- Each file covers one module or architectural layer.
+- Before writing a principle, ask: "Would a refactor that renames files or extracts a helper violate this principle?" If yes, the principle is too specific.

package/archive-specs/references/templates/docs-index.md

@@ -1,35 +1,35 @@
-# [Project Name] Documentation
+# [Project Name] Documentation Index
 
-## Start Here
+## Features (`docs/features/`)
 
-- Project overview: `README.md`
-- Setup and deployment: `docs/getting-started.md`
-- Configuration and external services: `docs/configuration.md`
-- Architecture: `docs/architecture.md`
-- Features and workflows: `docs/features.md`
-- Developer guide: `docs/developer-guide.md`
+User-facing capabilities described with BDD scenarios (Given/When/Then). Each file covers one functional category.
 
-## Document Guide
+| File | Category | Description |
+| --- | --- | --- |
+| `docs/features/[category].md` | [category name] | [One-line description] |
 
-### Getting Started
-- Audience: [operators / developers / both]
-- Covers: installation, prerequisites, local run, deployment flow
+## Architecture (`docs/architecture/`)
 
-### Configuration
-- Audience: [operators / developers / both]
-- Covers: env vars, config files, secrets, external services, API key setup
+Macro-level design principles organized by module or layer. Each principle is abstract enough to survive minor code changes.
 
-### Architecture
-- Audience: [developers / maintainers]
-- Covers: system boundaries, module responsibilities, data flow, key directories
+| File | Module | Description |
+| --- | --- | --- |
+| `docs/architecture/[module].md` | [module name] | [One-line description] |
 
-### Features
-- Audience: [users / support / developers]
-- Covers: major workflows, entrypoints, user value, important edge cases
+## Principles (`docs/principles/`)
 
-### Developer Guide
-- Audience: [developers / maintainers]
-- Covers: domain concepts, risk hotspots, testing expectations, debugging entrypoints
+Code style, naming conventions, and development constraints extracted from the codebase.
+
+| File | Topic | Description |
+| --- | --- | --- |
+| `docs/principles/[topic].md` | [topic name] | [One-line description] |
+
+## Root Documents
+
+- `README.md` — project overview and quick start
+- `CONTRIBUTING.md` — contribution workflow (if applicable)
+- `SECURITY.md` — vulnerability reporting (if applicable)
+- `CHANGELOG.md` — release history (if applicable)
 
 ## Reference List
 

package/archive-specs/references/templates/features.md

@@ -1,25 +1,25 @@
-# Features
+# <功能類別名稱>
 
-## 1. Feature Summary
+[One-sentence summary of this functional category from a user perspective.]
 
-- Supported user workflows: [short list]
-- Primary entrypoints: [routes/pages/commands/jobs]
-- Notable limitations or guardrails: [if any]
+## <功能名稱>
 
-## 2. Feature Details
+- **Given** <前置條件>
+- **When** <使用者操作>
+- **Then** <預期結果>
 
-### [Feature or Workflow Name]
+## <功能名稱>
 
-- User value: [Why it matters]
-- Trigger or entrypoint: [route/command/page/job]
-- Core flow: [happy path summary]
-- Edge or failure notes: [important caveats]
-- Evidence: [spec/code/doc path]
+- **Given** <前置條件>
+- **When** <使用者操作>
+- **Then** <預期結果>
 
-### [Feature or Workflow Name]
+---
 
-- User value: [Why it matters]
-- Trigger or entrypoint: [route/command/page/job]
-- Core flow: [happy path summary]
-- Edge or failure notes: [important caveats]
-- Evidence: [spec/code/doc path]
+## Writing Rules
+
+- Describe behavior from a user's perspective; never mention file paths, function names, or database tables.
+- Use BDD phrasing: **Given** (precondition) → **When** (action) → **Then** (outcome).
+- Each file covers exactly one functional category (e.g., authentication, data export, notifications).
+- Group related features under descriptive subheadings.
+- Title the file with a term users would recognize, not a module name.

package/archive-specs/references/templates/principles.md

@@ -0,0 +1,28 @@
+# <慣例類別>
+
+[One-sentence summary of what this convention area covers.]
+
+## <慣例名稱>
+
+<慣例描述>
+
+**理由**: <為什麼採用此慣例>
+
+**範例**: <從代碼庫提取的具體範例>
+
+## <慣例名稱>
+
+<慣例描述>
+
+**理由**: <為什麼採用此慣例>
+
+**範例**: <從代碼庫提取的具體範例>
+
+---
+
+## Writing Rules
+
+- Each file covers one convention area (e.g., naming, coding style, dependency management, error handling, testing).
+- State the convention clearly.
+- Provide rationale traceable to the codebase.
+- Include a brief example from the codebase, not an invented one.

package/archive-specs/references/templates/readme.md

@@ -29,20 +29,11 @@
 
 ## Documentation
 
-- Project docs index: `docs/README.md`
-- Setup and deployment: `docs/getting-started.md`
-- Configuration: `docs/configuration.md`
-- Architecture: `docs/architecture.md`
-- Features: `docs/features.md`
-- Developer guide: `docs/developer-guide.md`
+Detailed documentation is available under `docs/` and indexed in `AGENTS.md`/`CLAUDE.md`:
 
-## Main Features
-
-### [Feature Area 1]
-[Short explanation of the user-facing value and the main flow.]
-
-### [Feature Area 2]
-[Short explanation of the user-facing value and the main flow.]
+- **Features** (`docs/features/`): user-facing capabilities described with BDD scenarios
+- **Architecture** (`docs/architecture/`): macro-level design principles by module
+- **Principles** (`docs/principles/`): code style, naming conventions, and development constraints
 
 ## Notes
 

package/generate-spec/SKILL.md

@@ -29,8 +29,7 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 
 - Confirm the target workspace root, feature name, and a kebab-case `change_name`.
 - Review only the code, configuration, and external docs needed to understand the requested behavior.
-- If the change depends on frameworks, libraries, SDKs, APIs, CLIs, hosted services, or other external systems, find and read the relevant official documentation before drafting requirements.
-- Treat official documentation lookup as mandatory evidence gathering, not an optional refinement step.
+- **Official documentation lookup is mandatory** when the change depends on frameworks, libraries, SDKs, APIs, CLIs, hosted services, or other external systems. This is a required evidence-gathering step, not an optional refinement.
 - Use the official docs to verify expected behavior, supported constraints, configuration surface, integration contracts, and any implementation limits that should shape the spec.
 - Record the references that should appear in `spec.md` and the dependency evidence that should appear in `contract.md`.
 - Inspect existing `docs/plans/` directories before deciding whether to edit an existing plan set.
@@ -147,16 +146,15 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 
 ### 7) Fill `checklist.md`
 
-- Use checkbox format `- [ ]` for checklist items, except structured placeholder fields that are intentionally left for later fill-in.
-- Treat the template as a starting point and adapt it to the actual scope.
-- Remove or rewrite template examples that are not part of the real plan instead of leaving them as fake work to be checked later.
-- Map observable behaviors to requirement IDs and real test case IDs.
-- Use `$test-case-strategy` to choose the smallest test level that proves each risk and to define meaningful oracles before implementation.
-- Record risk class, oracle/assertion focus, dependency strategy, and test results.
-- Property-based coverage is required for business-logic changes unless a concrete `N/A` reason is recorded.
-- For decision sections, create as many records as needed for distinct flows or risk slices; do not collapse unrelated decisions into one record.
-- Within each decision record, keep only the selected strategy or clearly mark the non-selected path as `N/A`; never treat mutually exclusive choices inside one record as multiple completed outcomes.
-- For completion-summary sections, create as many completion records as needed for distinct flows, requirement groups, or workstreams; do not force the whole spec into a single completion line when different parts finish differently.
+- Use checkbox format `- [ ]` for checklist items.
+- Adapt the template to actual scope; remove inapplicable items.
+- Map observable behaviors to requirement IDs and test case IDs using `$test-case-strategy`.
+- Each Behavior-to-Test item: `[CL-xx]: [behavior] — R?.? → [Test IDs] — Result: [status]`.
+- Property-based coverage required for business-logic changes unless `N/A` with concrete reason.
+- Hardening items: keep as single-line checkboxes with `N/A` + reason when not applicable.
+- E2E/Integration decisions: one checkbox per decision with inline reason.
+- Execution summary: one checkbox per test category with status.
+- Completion records: one checkbox per flow/group with status and remaining items.
 
 ### 8) Process clarifications and approval
 

package/generate-spec/references/templates/checklist.md

@@ -4,104 +4,49 @@
 - Feature: [Feature Name]
 
 ## Usage Notes
-- This checklist is a starter template. Add, remove, or rewrite items based on actual scope.
-- Use `- [ ]` for all items; mark completed items as `- [x]`.
-- The final completion summary section may use structured placeholders instead of checkboxes.
-- If an item is not applicable, keep `N/A` with a concrete reason.
-- Do not mark placeholder examples or mutually exclusive alternatives as completed unless they were actually selected and executed.
-- Duplicate or remove decision-record blocks as needed; the final document should contain as many records as the real change requires.
-- Duplicate or remove completion-record blocks as needed; the final document should contain as many records as the real change requires.
-- Suggested test result values: `PASS / FAIL / BLOCKED / NOT RUN / N/A`.
-- Use `$test-case-strategy` to choose test levels, define meaningful oracles, and record unit drift checks for atomic tasks.
-- For business-logic changes, property-based coverage is required unless a concrete `N/A` reason is recorded.
-- Each checklist item should map to a distinct risk; avoid repeating shallow happy-path cases.
 
-## Clarification & Approval Gate (required when clarification replies exist)
-- [ ] User clarification responses are recorded (map to `spec.md`; if none, mark `N/A`).
-- [ ] Affected plans are reviewed/updated (`spec.md` / `tasks.md` / `checklist.md` / `contract.md` / `design.md`; if no updates needed, mark `N/A` + reason).
-- [ ] Explicit user approval on updated specs is obtained (date/conversation reference: [to be filled]).
+- Add/remove items based on actual scope; keep only applicable items.
+- Use `$test-case-strategy` for test level selection, oracle design, and drift-check planning.
+- Property-based coverage required for business-logic changes unless `N/A` with reason.
+- Test result values: `PASS / FAIL / BLOCKED / NOT RUN / N/A`.
 
-## Behavior-to-Test Checklist (customizable)
+## Clarification & Approval Gate
 
-- [ ] CL-01 [Observable behavior]
-  - Requirement mapping: [R1.x]
-  - Actual test case IDs: [UT/PBT/IT/E2E-xx]
-  - Test level: [Unit / Property-based / Integration / E2E]
-  - Risk class: [boundary / authorization / concurrency / external failure / data integrity / adversarial abuse / regression]
-  - Property/matrix focus: [invariant / generated business input space / external state matrix / adversarial case]
-  - External dependency strategy: [none / mocked service states / near-real dependency]
-  - Oracle/assertion focus: [exact output / persisted state / side effects / no partial write / compensation / emitted event / permission denial]
-  - Unit drift check: [UT-xx target unit; expected result/assertion, or N/A with reason]
-  - Test result: `PASS / FAIL / BLOCKED / NOT RUN / N/A`
-  - Notes (optional): [risk, limitation, observation]
+- [ ] Clarification responses recorded (or `N/A` if none).
+- [ ] Affected plans updated after clarification (or `N/A` + reason).
+- [ ] Explicit approval obtained (date/ref: [to be filled]).
 
-- [ ] CL-02 [Observable behavior]
-  - Requirement mapping: [R?.?]
-  - Actual test case IDs: [UT/PBT/IT/E2E-xx]
-  - Test level: [Unit / Property-based / Integration / E2E]
-  - Risk class: [boundary / authorization / concurrency / external failure / data integrity / adversarial abuse / regression]
-  - Property/matrix focus: [invariant / generated business input space / external state matrix / adversarial case]
-  - External dependency strategy: [none / mocked service states / near-real dependency]
-  - Oracle/assertion focus: [exact output / persisted state / side effects / no partial write / compensation / emitted event / permission denial]
-  - Unit drift check: [UT-xx target unit; expected result/assertion, or N/A with reason]
-  - Test result: `PASS / FAIL / BLOCKED / NOT RUN / N/A`
-  - Notes (optional): [risk, limitation, observation]
+## Behavior-to-Test Checklist
 
-- [ ] CL-03 [Observable behavior]
-  - Requirement mapping: [R?.?]
-  - Actual test case IDs: [UT/PBT/IT/E2E-xx]
-  - Test level: [Unit / Property-based / Integration / E2E]
-  - Risk class: [boundary / authorization / concurrency / external failure / data integrity / adversarial abuse / regression]
-  - Property/matrix focus: [invariant / generated business input space / external state matrix / adversarial case]
-  - External dependency strategy: [none / mocked service states / near-real dependency]
-  - Oracle/assertion focus: [exact output / persisted state / side effects / no partial write / compensation / emitted event / permission denial]
-  - Unit drift check: [UT-xx target unit; expected result/assertion, or N/A with reason]
-  - Test result: `PASS / FAIL / BLOCKED / NOT RUN / N/A`
-  - Notes (optional): [risk, limitation, observation]
+- [ ] CL-01: [Observable behavior] — R?.? → [Test IDs] — Result: `[status]`
+- [ ] CL-02: [Observable behavior] — R?.? → [Test IDs] — Result: `[status]`
+- [ ] CL-03: [Observable behavior] — R?.? → [Test IDs] — Result: `[status]`
 
-## Required Hardening Records
-- [ ] Regression tests are added/updated for bug-prone or high-risk behavior, or `N/A` is recorded with a concrete reason.
-- [ ] Focused unit drift checks are defined for non-trivial atomic implementation tasks, or `N/A` is recorded with the replacement verification and concrete reason.
-- [ ] Property-based coverage is added/updated for changed business logic, or `N/A` is recorded with a concrete reason.
-- [ ] External services in the business logic chain are mocked/faked for scenario testing, or `N/A` is recorded with a concrete reason.
-- [ ] Adversarial/penetration-style cases are added/updated for abuse paths and edge combinations, or `N/A` is recorded with a concrete reason.
-- [ ] Authorization, invalid transition, replay/idempotency, and concurrency risks are evaluated; uncovered items are marked `N/A` with concrete reasons.
-- [ ] Assertions verify business outcomes and side effects/no-side-effects, not only "returns 200" or "does not throw".
-- [ ] Test fixtures are reproducible (fixed seed/clock/fixtures) or `N/A` is recorded with a concrete reason.
+## Hardening Checklist
 
-## E2E / Integration Decision Records
+- [ ] Regression tests for bug-prone/high-risk behavior (or `N/A` + reason).
+- [ ] Unit drift checks for non-trivial tasks (or `N/A` + reason).
+- [ ] Property-based coverage for business logic (or `N/A` + reason).
+- [ ] External services mocked/faked (or `N/A` + reason).
+- [ ] Adversarial cases for abuse paths (or `N/A` + reason).
+- [ ] Authorization, idempotency, concurrency risks evaluated (or `N/A` + reason).
+- [ ] Assertions verify outcomes/side-effects, not just "returns 200".
+- [ ] Fixtures reproducible (fixed seed/clock) (or `N/A` + reason).
 
-### Decision Record 1: [Flow / Requirement / Risk Slice]
-- Requirement mapping: [R?.? / CL-xx]
-- Decision: [Build E2E / Cover with integration instead / Existing coverage already sufficient / N/A]
-- Linked case IDs: [E2E-xx / IT-xx / existing suite reference]
-- Reason: [importance, cross-layer risk, stability/cost tradeoff, or why no extra coverage is needed]
+## E2E / Integration Decisions
 
-### Decision Record 2: [Flow / Requirement / Risk Slice]
-- Requirement mapping: [R?.? / CL-xx]
-- Decision: [Build E2E / Cover with integration instead / Existing coverage already sufficient / N/A]
-- Linked case IDs: [E2E-xx / IT-xx / existing suite reference]
-- Reason: [importance, cross-layer risk, stability/cost tradeoff, or why no extra coverage is needed]
+- [ ] [Flow/Risk]: [E2E / Integration replacement / Existing coverage / N/A] — Reason: [why]
 
-## Execution Summary (fill with actual results)
-- [ ] Unit tests: `PASS / FAIL / NOT RUN / N/A`
-- [ ] Regression tests: `PASS / FAIL / NOT RUN / N/A`
-- [ ] Property-based tests: `PASS / FAIL / NOT RUN / N/A`
-- [ ] Integration tests: `PASS / FAIL / NOT RUN / N/A`
-- [ ] E2E tests: `PASS / FAIL / NOT RUN / N/A`
-- [ ] External service mock scenarios: `PASS / FAIL / NOT RUN / N/A`
-- [ ] Adversarial/penetration-style cases: `PASS / FAIL / NOT RUN / N/A`
+## Execution Summary
 
-## Completion Records
+- [ ] Unit: `[status]`
+- [ ] Regression: `[status]`
+- [ ] Property-based: `[status]`
+- [ ] Integration: `[status]`
+- [ ] E2E: `[status]`
+- [ ] Mock scenarios: `[status]`
+- [ ] Adversarial: `[status]`
 
-### Completion Record 1: [Flow / Requirement Group / Workstream]
-- Requirement mapping: [R?.? / Task N / CL-xx]
-- Completion status: [completed / partially completed / blocked / deferred]
-- Remaining applicable items: [None / list remaining items]
-- Notes: [brief execution-backed summary]
+## Completion Records
 
-### Completion Record 2: [Flow / Requirement Group / Workstream]
-- Requirement mapping: [R?.? / Task N / CL-xx]
-- Completion status: [completed / partially completed / blocked / deferred]
-- Remaining applicable items: [None / list remaining items]
-- Notes: [brief execution-backed summary]
+- [ ] [Flow/Group]: [completed / partial / blocked / deferred] — Remaining: [None / list]