@laitszkin/apollo-toolkit 2.11.0 → 2.11.2

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.11.2] - 2026-03-23
+
+### Changed
+- Update `develop-new-features` and `enhance-existing-features` so small localized work such as bug fixes, pure frontend polish, and simple adjustments can skip spec generation, while non-trivial feature work still uses approval-backed specs.
+- Strengthen `generate-spec` so spec creation must verify relevant official documentation for external dependencies before writing requirements or scope.
+- Refine spec templates so `spec.md` uses dedicated `In Scope` and `Out of Scope` sections, checklist completion uses structured completion records, and E2E versus integration decisions support multiple per-flow records without encouraging false checkbox completion.
+
+## [v2.11.1] - 2026-03-23
+
+### Changed
+- Add a dedicated GitHub Actions validation job for `SKILL.md` description length checks.
+- Enforce a maximum `description` length of 1024 characters in `scripts/validate_skill_frontmatter.py`.
+- Shorten `enhance-existing-features` metadata so its `description` stays within the loader limit without changing intent.
+
 ## [v2.11.0] - 2026-03-23
 
 ### Added

package/develop-new-features/SKILL.md

@@ -28,13 +28,13 @@ description: >-
 ## Standards
 
 - Evidence: Review authoritative docs and the existing codebase before planning or implementation.
-- Execution: Run `generate-spec` for every new feature or product-behavior change, obtain approval, then continue through implementation, testing, and backfill until the approved plan is fully reconciled.
+- Execution: Use specs only for feature work that is genuinely multi-step, cross-surface, or higher risk; skip specs for obviously small/localized work and route that work to direct implementation or the appropriate maintenance skill instead.
 - Quality: Add risk-based tests with property-based, regression, integration, E2E, adversarial, and rollback coverage when relevant.
 - Output: Keep the approved planning artifacts and the final implementation aligned with actual completion results.
 
 ## Goal
 
-Use a shared spec-generation workflow for all new feature work, then implement the approved behavior with strong test coverage and minimal rework.
+Use a shared spec-generation workflow for non-trivial new feature work, then implement the approved behavior with strong test coverage and minimal rework.
 
 ## Workflow
 
@@ -47,7 +47,15 @@ Use a shared spec-generation workflow for all new feature work, then implement t
 
 ### 2) Run `$generate-spec`
 
-- Specs are mandatory for every new feature, product behavior change, and greenfield project.
+- First decide whether the request truly belongs in this skill.
+- Do not use this skill or generate specs when the request is actually one of these:
+  - bug fixes or regressions that restore intended behavior without introducing new product behavior
+  - copy-only, styling-only, spacing-only, layout-only, or other purely presentational UI tweaks with localized impact
+  - simple configuration, constant, feature-flag, dependency, or content updates confined to one small area
+  - small refactors, naming cleanups, or internal code-health work with no externally visible behavior change
+  - narrowly scoped adjustments that touch only a few files/modules and do not require cross-team alignment or approval artifacts
+- In those cases, do not create `spec.md` / `tasks.md` / `checklist.md`; instead use the appropriate direct implementation workflow (for example `enhance-existing-features` for small brownfield adjustments or `systematic-debug` for bug fixes).
+- Specs are required when the request is truly a non-trivial new feature, product behavior change, or greenfield project that needs shared planning.
 - Follow `$generate-spec` completely for:
   - generating `docs/plans/{YYYY-MM-DD}_{change_name}/spec.md`, `tasks.md`, and `checklist.md`
   - filling BDD requirements and risk-driven test plans
@@ -98,7 +106,11 @@ Rules:
 
 - Backfill `spec.md`, `tasks.md`, and `checklist.md` through `$generate-spec` workflow after implementation and testing.
 - In `spec.md`, mark each approved requirement with its actual completion state, such as completed, partially completed, deferred, or not implemented, plus brief evidence or rationale where needed.
-- Mark every completed task in `tasks.md`, resolve every applicable checklist item, and explicitly label any remaining item as deferred or blocked with the reason.
+- Mark every completed task in `tasks.md`.
+- In `checklist.md`, update only the items that are actually applicable to the approved scope and executed validation.
+- Do not mark template alternatives, unused example rows, or non-applicable decision branches as completed just to make the file look fully checked.
+- Rewrite, remove, or leave `N/A` on template-only sections so the final checklist reflects the real work rather than the starter template.
+- Explicitly label any truly remaining applicable item as deferred or blocked with the reason.
 - Report the implemented scope, test execution, and any concrete `N/A` reasons.
 
 ## Working Rules
@@ -107,6 +119,7 @@ Rules:
 - Keep implementation traceable to approved requirement IDs and planned risks.
 - Prefer realism over rigid templates: add or remove test coverage only when the risk profile justifies it.
 - Every planned test should justify a distinct risk; remove shallow duplicates that only prove the code "still runs".
+- Treat starter template alternatives as mutually exclusive options, not as boxes that all need to be checked.
 - If a spec set exists and approval has been granted, do not yield with unfinished in-scope tasks or checklist items unless the user approves a deferment or an external blocker makes completion impossible.
 
 ## References

package/develop-new-features/references/testing-e2e.md

@@ -32,4 +32,5 @@
 ## Spec/checklist authoring hints
 - Mark high-risk key paths in `spec.md` requirement descriptions.
 - Record E2E decisions, mapped test cases, and results in `checklist.md`.
+- When different flows need different strategies, create multiple decision records instead of forcing one shared E2E decision for the whole feature.
 - If skipping E2E, specify replacement integration test cases (`IT-xx`) and rationale in `checklist.md`.

package/enhance-existing-features/SKILL.md

@@ -1,21 +1,15 @@
 ---
 name: enhance-existing-features
 description: >-
-  Build and extend brownfield features in an existing codebase. Always explore
-  the codebase first, then decide from the user's requested change whether
-  specs (`spec.md`/`tasks.md`/`checklist.md`) are required before coding. When
-  specs are required, depend on `generate-spec` for the shared planning,
-  clarification, approval, and backfill workflow. If a spec set exists and is
-  approved, complete all planned tasks and applicable checklist items before
-  yielding unless the user changes scope or an external blocker prevents safe
-  completion. Even when specs are not
-  required, still add and run related tests for
-  unit/property-based/user-critical integration chain/E2E coverage. Tests must
-  not stop at happy-path validation: for business-logic changes require
-  property-based testing unless explicitly `N/A` with reason, design
-  adversarial/regression/authorization/idempotency/concurrency coverage where
-  relevant, use mocks for external services in logic chains, and verify
-  meaningful business outcomes rather than smoke-only success.
+  Extend brownfield features by exploring the codebase first, then deciding
+  whether shared specs (`spec.md`/`tasks.md`/`checklist.md`) are required
+  before coding. When specs are needed, use `generate-spec` for planning,
+  clarification, approval, and backfill, and complete approved in-scope tasks
+  before yielding unless scope changes or an external blocker prevents safe
+  completion. With or without specs, add and run relevant unit,
+  property-based, regression, integration, E2E, and adversarial tests as
+  applicable, use mocks for external services in logic chains, and verify
+  meaningful business outcomes instead of smoke-only success.
 ---
 
 # Enhance Existing Features
@@ -54,9 +48,20 @@ Safely extend brownfield systems by exploring the existing codebase first, using
 Use the user's requested change together with the codebase exploration results to decide whether to generate specs.
 
 Trigger specs when any of the following is true:
-- high complexity changes
-- critical module changes
-- cross-module changes
+- the change introduces new user-visible behavior, not just a bug fix restoring intended behavior
+- requirements are ambiguous enough that approval on written scope, tradeoffs, or edge cases is useful
+- multiple modules, layers, services, or teams must stay aligned
+- the change touches critical flows, sensitive data, permissions, money movement, migrations, or irreversible operations
+- the risk profile is high enough that explicit requirement-to-test traceability will materially reduce mistakes
+
+Do not generate specs when the work is clearly small and localized, such as:
+- bug fixes or regressions that restore already-intended behavior without changing product scope
+- pure frontend polish: copy tweaks, styling, spacing, alignment, responsive touch-ups, visual cleanup, or simple template/view wiring
+- small configuration, constant, dependency, content, or feature-flag updates confined to one area
+- straightforward CRUD field additions, validation message tweaks, or one-path handler adjustments with limited blast radius
+- refactors, renames, dead-code cleanup, or observability-only changes that do not alter user-visible behavior
+
+When in doubt, prefer direct implementation for genuinely low-risk localized changes, and reserve specs for changes whose scope or risk would benefit from explicit approval artifacts.
 
 If triggered:
 - Run `$generate-spec` and follow its workflow completely.
@@ -114,7 +119,11 @@ Rules:
 
 - If specs were used, backfill `spec.md`, `tasks.md`, and `checklist.md` through `$generate-spec` workflow based on actual completion and test outcomes.
 - In `spec.md`, mark each relevant requirement with its actual completion state, such as completed, partially completed, deferred, or not implemented, plus brief evidence or rationale where needed.
-- If specs were used, mark every completed task in `tasks.md`, resolve every applicable checklist item, and explicitly label any remaining item as deferred or blocked with the reason.
+- If specs were used, mark every completed task in `tasks.md`.
+- If specs were used, update only the applicable checklist items that correspond to real scope, chosen test strategy, and actual execution.
+- Do not mark unused template examples, mutually exclusive alternatives, or non-applicable branches as completed.
+- Remove, rewrite, or leave `N/A` on starter-template items when they do not belong to the real change.
+- Explicitly label any still-applicable remaining item as deferred or blocked with the reason.
 - If specs were not used, provide a concise execution summary including test IDs/results, regression coverage, mock scenario coverage, adversarial coverage, and any `N/A` reasons.
 
 ## Working Rules
@@ -123,6 +132,7 @@ Rules:
 - Always decide the need for specs only after exploring the existing codebase.
 - Maintain traceability between requirements, tasks, and tests when specs are present.
 - Treat checklists as living artifacts: adjust items to match real change scope.
+- Treat mutually exclusive template choices as a decision to record, not multiple boxes to finish.
 - Every planned test should justify a distinct risk; remove shallow duplicates that only prove the code "still runs".
 - If a spec set exists and approval has been granted, do not yield with unfinished in-scope tasks or checklist items unless the user approves a deferment or an external blocker makes completion impossible.
 

package/enhance-existing-features/references/e2e-tests.md

@@ -22,4 +22,5 @@
 
 ## Recording rules
 - Specs flow: record E2E or replacement strategy with outcomes in `checklist.md`.
+- When different flows need different strategies, create multiple decision records in `checklist.md` so each flow/risk slice keeps its own rationale and linked case IDs.
 - Non-specs flow: explain E2E execution or replacement testing with rationale in the response.

package/generate-spec/SKILL.md

@@ -14,9 +14,9 @@ description: Generate and maintain shared feature planning artifacts (`spec.md`,
 
 ## Standards
 
-- Evidence: Review the relevant code, configs, and authoritative docs before filling requirements or test plans.
+- Evidence: Review the relevant code, configs, and authoritative docs before filling requirements or test plans; when external dependencies, libraries, frameworks, APIs, or platforms are involved, checking their official documentation is mandatory during spec creation.
 - Execution: Generate the planning files first, complete them with traceable requirements and risks, handle clarification updates, then wait for explicit approval before implementation.
-- Quality: Keep `spec.md`, `tasks.md`, and `checklist.md` synchronized and map each planned test to a concrete risk or requirement.
+- Quality: Keep `spec.md`, `tasks.md`, and `checklist.md` synchronized, map each planned test to a concrete risk or requirement, and tailor the templates so only applicable items remain active.
 - Output: Store planning artifacts under `docs/plans/{YYYY-MM-DD}_{change_name}/` and keep them concise, executable, and easy to update.
 
 ## Goal
@@ -29,6 +29,9 @@ 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.
+- 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`.
 - Inspect existing `docs/plans/` directories before deciding whether to edit an existing plan set.
 - Reuse an existing plan set only when it clearly matches the same requested issue/change scope.
@@ -50,9 +53,11 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 ### 3) Fill `spec.md`
 
 - Keep the goal and scope concrete.
+- Ensure the described scope and requirements do not contradict the relevant official documentation or integration contracts.
 - Write functional behaviors in BDD form with `GIVEN`, `WHEN`, `THEN`, `AND`, and `Requirements`.
 - Make each requirement testable.
 - Cover boundaries, authorization, external dependency states, abuse/adversarial paths, failure handling, and any relevant idempotency/concurrency/data-integrity risks.
+- Record the official-doc references actually used for the spec, especially for external dependency behavior and constraints.
 - If requirements are unclear, list 3-5 clarification questions; otherwise write `None`.
 
 ### 4) Fill `tasks.md`
@@ -64,11 +69,15 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 
 ### 5) Fill `checklist.md`
 
-- Use checkbox format `- [ ]` only.
+- 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.
 - 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.
 
 ### 6) Process clarifications and approval
 
@@ -82,6 +91,10 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 
 - Mark completed tasks in `tasks.md`.
 - Update `checklist.md` with real test outcomes, `N/A` reasons, and any scope adjustments.
+- Only mark checklist items complete when the work actually happened or the recorded decision actually applies.
+- Do not check off unused examples, placeholder rows, or non-selected decision options.
+- If different flows use different test strategies, preserve separate decision records in the final checklist instead of merging them into a misleading single summary.
+- If different parts of the approved scope have different completion states, preserve separate completion records in the final checklist instead of flattening them into one ambiguous status.
 - Remove stale placeholders or template-only guidance once the documents are finalized.
 
 ## Working Rules
@@ -89,6 +102,8 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - By default, write planning docs in the user's language.
 - Keep requirement IDs, task IDs, and test IDs traceable across all three files.
 - Prefer realistic coverage over boilerplate: add or remove checklist items based on actual risk.
+- Finalized planning docs should read like the actual approved plan and execution record, not like a fully checked starter template.
+- If official documentation materially constrains implementation choices, reflect that constraint explicitly in the spec instead of leaving it implicit.
 - Use kebab-case for `change_name`; avoid spaces and special characters.
 - Path rule: `scripts/...` and `references/...` in this file always mean paths under the current skill folder, not the target project root.
 - Never overwrite a nearby issue's plan set just because the technical area overlaps; shared modules are not sufficient evidence that the scope is the same.

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

@@ -6,7 +6,11 @@
 ## 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`.
 - 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.
@@ -60,10 +64,19 @@
 - [ ] 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.
 
-## E2E Decision Record (pick one or customize)
-- [ ] Build E2E (case: [E2E-xx]; reason: [importance/complexity/cross-layer risk]).
-- [ ] Do not build E2E; cover with integration tests instead (alternative case: [IT-xx]; reason: [stability/cost/environment limitation]).
-- [ ] No additional E2E/integration hardening required (reason: [existing coverage already addresses risk]).
+## E2E / Integration Decision Records
+
+### 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]
+
+### 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]
 
 ## Execution Summary (fill with actual results)
 - [ ] Unit tests: `PASS / FAIL / NOT RUN / N/A`
@@ -74,5 +87,16 @@
 - [ ] External service mock scenarios: `PASS / FAIL / NOT RUN / N/A`
 - [ ] Adversarial/penetration-style cases: `PASS / FAIL / NOT RUN / N/A`
 
-## Completion Rule
-- [ ] Agent has updated checkboxes, test outcomes, and necessary notes based on real execution (including added/removed items).
+## Completion Records
+
+### 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 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]

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

@@ -8,8 +8,12 @@
 [Describe the business goal and user value in one sentence.]
 
 ## Scope
-- In scope: [What is included in this change]
-- Out of scope: [What is explicitly excluded]
+
+### In Scope
+[What is included in this change]
+
+### Out of Scope
+[What is explicitly excluded]
 
 ## Functional Behaviors (BDD)
 
@@ -51,5 +55,6 @@
 ## References
 - Official docs:
   - [Link or document 1]
+  - [Link or document 2]
 - Related code files:
   - [File path 1]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "2.11.0",
+  "version": "2.11.2",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",

package/scripts/validate_skill_frontmatter.py

@@ -11,6 +11,7 @@ import yaml
 
 NAME_PATTERN = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
 REQUIRED_KEYS = {"name", "description"}
+MAX_DESCRIPTION_LENGTH = 1024
 
 
 def repo_root() -> Path:
@@ -81,6 +82,11 @@ def validate_skill(skill_dir: Path) -> list[str]:
     description = frontmatter.get("description")
     if not isinstance(description, str) or not description.strip():
         errors.append(f"{skill_md}: 'description' must be a non-empty string.")
+    elif len(description) > MAX_DESCRIPTION_LENGTH:
+        errors.append(
+            f"{skill_md}: invalid description: exceeds maximum length of "
+            f"{MAX_DESCRIPTION_LENGTH} characters"
+        )
 
     return errors