@laitszkin/apollo-toolkit 2.14.15 → 2.14.17

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+### Changed
+- None yet.
+
+## [v2.14.17] - 2026-04-12
+
+### Changed
+- Tighten `version-release` so explicit semver wording such as `patch update`, `minor update`, or `major update` counts as release intent and still requires publishing the matching GitHub release.
+- Tighten `enhance-existing-features` so it must not report an enabling intermediate milestone as complete when the user asked for the final scoped behavior.
+
+## [v2.14.16] - 2026-04-11
+
+### Changed
+- Strengthen `generate-spec` so batch planning now requires spec sets to be truly parallel-implementable, not merely independently scoped.
+- Update `generate-spec` templates and prompts so `coordination.md` captures parallel-readiness gates, collision-resolution records, and pre-agreed ownership rules before concurrent implementation starts.
+
 ## [v2.14.15] - 2026-04-11
 
 ### Changed

package/enhance-existing-features/SKILL.md

@@ -24,7 +24,7 @@ description: >-
 ## Standards
 
 - Evidence: Explore the existing codebase first and verify the latest authoritative docs for the involved stack or integrations.
-- Execution: Decide whether specs are required from the actual change surface, run `generate-spec` when needed, then continue through implementation, testing, and backfill until the active scope is fully reconciled.
+- Execution: Decide whether specs are required from the actual change surface, run `generate-spec` when needed, then continue through implementation, testing, and backfill until the active scope is fully reconciled; when the user asks for a specific final behavior or architectural end state, do not substitute a preparatory or partial milestone unless the user explicitly re-scopes the request.
 - Quality: Add risk-based tests with property-based, regression, integration, E2E, adversarial, and rollback coverage when relevant.
 - Output: Keep implementation and any planning artifacts traceable, updated, and aligned with actual completion results.
 
@@ -97,6 +97,7 @@ If not triggered:
 - Update environment examples only when new inputs are required.
 - If specs exist, treat every unchecked in-scope task and applicable checklist item as part of the required deliverable for this run.
 - Do not stop after partial code changes, partial tests, or partial backfill when approved planned work remains.
+- Do not present an enabling first stage, temporary coalescing step, or other intermediate milestone as complete when the user asked for the final scoped behavior.
 - Only pause before completion if:
   - the user changes scope or explicitly asks to stop
   - new clarification requires plan updates and renewed approval

package/enhance-existing-features/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "enhance-existing-features"
   short_description: "Extend brownfield features with conditional generate-spec planning and risk-driven tests"
-  default_prompt: "Use $enhance-existing-features to extend a brownfield feature: map the affected code and dependencies first, decide whether the change is high complexity / critical module / cross-module, run $generate-spec when specs are required, wait for explicit approval before coding, document material external dependency contracts in contract.md, document the architecture/design delta in design.md, and when one change is split into parallel spec sets maintain a shared coordination.md for common preparation, ownership boundaries, and legacy-replacement direction; always add risk-driven tests plus clear N/A reasons when a category truly does not apply; if a spec set exists, finish the approved tasks and applicable checklist items and backfill spec.md, tasks.md, checklist.md, contract.md, design.md, and when applicable coordination.md before yielding unless the user changes scope or an external blocker prevents safe completion."
+  default_prompt: "Use $enhance-existing-features to extend a brownfield feature: map the affected code and dependencies first, decide whether the change is high complexity / critical module / cross-module, run $generate-spec when specs are required, wait for explicit approval before coding, document material external dependency contracts in contract.md, document the architecture/design delta in design.md, and when one change is split into parallel spec sets maintain a shared coordination.md for common preparation, ownership boundaries, and legacy-replacement direction; always add risk-driven tests plus clear N/A reasons when a category truly does not apply; if the user asked for a specific final behavior or architecture state, do not stop at an enabling intermediate milestone unless the user explicitly narrows scope; if a spec set exists, finish the approved tasks and applicable checklist items and backfill spec.md, tasks.md, checklist.md, contract.md, design.md, and when applicable coordination.md before yielding unless the user changes scope or an external blocker prevents safe completion."

package/generate-spec/README.md

@@ -5,7 +5,7 @@ A shared planning skill for feature work. It centralizes creation and maintenanc
 ## Core capabilities
 
 - Generates single-spec plans under `docs/plans/{YYYY-MM-DD}/{change_name}/`.
-- Generates multi-spec parallel batches under `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` with a shared `coordination.md`, while keeping every batch spec independently completable.
+- Generates multi-spec parallel batches under `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` with a shared `coordination.md`, while keeping every batch spec independently completable and safe to implement concurrently.
 - Uses shared templates so spec-first and brownfield workflows follow the same planning structure.
 - Requires clarification handling and explicit user approval before implementation starts.
 - Backfills task and checklist status after implementation and testing.
@@ -84,11 +84,11 @@ docs/plans/<today>/membership-cutover/
 - `checklist.md`: use `- [ ]` only, adapt items to real scope, and record actual results.
 - `contract.md`: when external dependencies materially shape the change, record their official-source-backed invocation surface, constraints, and caller obligations in the standard dependency-record format.
 - `design.md`: record the architecture/design delta in the standard format, including affected modules, flow, invariants, tradeoffs, and validation plan.
-- `coordination.md`: for multi-spec batches only, record shared preparation, ownership boundaries, replacement direction, file ownership guardrails, shared API/schema freeze or additive-only rules, compatibility-shim retention rules, merge order, and cross-spec integration checkpoints, but never use it to make one spec depend on another spec's implementation before it can be completed.
+- `coordination.md`: for multi-spec batches only, record shared preparation, ownership boundaries, replacement direction, file ownership guardrails, known collision candidates, pre-agreed edit rules for shared surfaces, shared API/schema freeze or additive-only rules, compatibility-shim retention rules, merge order, and cross-spec integration checkpoints, but never use it to make one spec depend on another spec's implementation before it can be completed.
 - If clarification responses change the plan, update the docs and obtain approval again before coding.
 
 ## Notes
 
 - `scripts/...` and `references/...` are skill-folder paths, not project-folder paths.
 - The generator replaces `[YYYY-MM-DD]`, `[Feature Name]`, `[功能名稱]`, `[change_name]`, and `[batch_name]` placeholders.
-- If a batch split produces specs that must land in a functional sequence, re-slice the work so each spec becomes independently implementable, testable, and mergeable.
+- If a batch split produces specs that must land in a functional sequence, or still leaves unresolved shared-file collisions, re-slice the work so each spec becomes independently implementable, testable, mergeable, and parallel-safe before coding starts.

package/generate-spec/SKILL.md

@@ -15,9 +15,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; 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, keep each spec set tightly scoped, split broader work into multiple independent spec sets when needed, ensure every batch spec is independently completable without depending on another spec set to land first, complete them with traceable requirements and risks, handle clarification updates, then wait for explicit approval before implementation.
+- Execution: Generate the planning files first, keep each spec set tightly scoped, split broader work into multiple independent spec sets when needed, ensure every batch spec is independently completable and truly parallel-implementable without depending on another spec set to land first, surface shared-file or shared-contract collision risks during planning, resolve those coordination rules before implementation starts, complete them with traceable requirements and risks, handle clarification updates, then wait for explicit approval before implementation.
 - Quality: Keep `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.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}/` for single-spec work, or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` plus `coordination.md` for multi-spec parallel work whose member specs remain independently approvable and independently implementable, and keep them concise, executable, and easy to update.
+- Output: Store planning artifacts under `docs/plans/{YYYY-MM-DD}/{change_name}/` for single-spec work, or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` plus `coordination.md` for multi-spec parallel work whose member specs remain independently approvable, independently implementable, and ready for concurrent worktree execution with pre-agreed collision rules, and keep them concise, executable, and easy to update.
 
 ## Goal
 
@@ -47,6 +47,8 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Define those spec sets so they do not conflict with each other and do not require another spec set to land first in order to be approved or implemented safely.
 - For batch generation, treat cross-spec implementation dependency as a planning bug: if Spec B cannot be completed safely until Spec A lands, they should be one spec set or be re-sliced so each spec has its own self-contained outcome.
 - Allow shared preparation in `coordination.md` only when each spec can still complete that preparation or operate against an already-existing baseline without waiting for another spec's code changes.
+- Treat any unresolved shared-file collision, overlapping ownership, or incompatible contract change across spec sets as a planning bug to resolve before approval, not an implementation-time surprise.
+- If two candidate spec sets would still need to edit the same non-additive surface, either merge them into one spec set or record a concrete ownership split plus additive-only rule that makes parallel work safe.
 - Use:
   - `SKILL_ROOT=<path_to_generate-spec_skill>`
   - `WORKSPACE_ROOT=<target_project_root>`
@@ -93,7 +95,7 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Identify the affected modules, current baseline, proposed architecture, component responsibilities, control flow, data/state impact, and risk/tradeoff decisions.
 - Cross-reference relevant requirement IDs from `spec.md` and any external dependency records from `contract.md`.
 - Make architecture boundaries, invariants, and rollback/fallback expectations explicit when they matter to safe implementation.
-- When the spec belongs to a parallel batch, add a short reference to the parent `coordination.md` and keep `design.md` focused on the single-spec delta rather than duplicating cross-spec ownership rules.
+- When the spec belongs to a parallel batch, add a short reference to the parent `coordination.md`, state the exact assumptions that let this spec be implemented in parallel, and keep `design.md` focused on the single-spec delta rather than duplicating cross-spec ownership rules.
 
 ### 6.5) Fill `coordination.md` for parallel multi-spec batches
 
@@ -102,10 +104,12 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Use it as the batch-level source of truth for shared preparation, ownership boundaries, merge order, and cross-spec constraints.
 - Record explicitly that each spec set must remain independently completable and must not rely on another spec set's code changes, unfinished tasks, or merge order to achieve its own approved outcome.
 - Record shared fields, shared contracts, or shared data-shape preparation that multiple spec sets must align on before implementation starts.
+- Record whether the batch is ready for parallel implementation now; if not, list the blocking coordination items that must be settled before any spec starts.
 - When one spec set replaces or removes legacy behavior, state that direction explicitly so all worktrees implement toward the same target rather than preserving the old behavior accidentally.
 - Capture which spec set may touch which modules, which files require coordination, and whether any landing order or cutover sequence must be respected.
 - Treat `coordination.md` as a merge-conflict prevention contract, not just a planning summary.
 - Record the concrete file ownership map, forbidden touch points, and shared files that require explicit coordination before edits begin.
+- For every known collision candidate, record the conflict shape, the pre-agreed owner or additive-only edit rule, and the trigger that requires re-coordination before implementation continues.
 - For shared APIs, event schemas, config shapes, manifests, or artifact fields, record whether changes are additive-only during the batch and which spec set owns the canonical naming.
 - When temporary compatibility shims, adapters, or legacy bridges must survive until the whole batch lands, record that retention rule explicitly so one worktree does not remove a path another still depends on.
 - Record the post-merge integration checkpoints that must be re-verified after multiple worktrees land, especially when text merges may succeed while behavior still drifts.
@@ -152,6 +156,7 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Never allow one spec set to cover more than three modules.
 - When a request exceeds that scope, split it into independent, non-conflicting, non-dependent spec sets before approval.
 - For batch specs, independence is mandatory: each spec must describe a complete slice that can be implemented, tested, reviewed, and merged without waiting for another spec in the same batch.
+- For batch specs, parallel readiness is also mandatory: each spec must be safe to implement concurrently, with shared-file collisions and ownership rules settled in `coordination.md` before coding begins.
 - When multiple spec sets are created for one batch, keep their shared implementation direction in one `coordination.md` instead of duplicating cross-spec rules in every `design.md`.
 - For parallel worktree batches, make `coordination.md` specific enough that another engineer can tell which files they may edit, which shared contracts are frozen or additive-only, which shims must remain in place, and what combined behaviors need verification after merge.
 - Prefer realistic coverage over boilerplate: add or remove checklist items based on actual risk.

package/generate-spec/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "generate-spec"
   short_description: "Generate shared feature spec, task, and checklist docs before coding"
-  default_prompt: "Use $generate-spec to create or update single-spec plans under docs/plans/<date>/<change_name>/ or parallel batches under docs/plans/<date>/<batch_name>/<change_name>/ with a shared coordination.md, but ensure every spec in a batch remains independently approvable and independently implementable without depending on another batch spec landing first; fill BDD requirements and risk-driven test planning, document external dependency contracts in contract.md when they materially constrain the change, write the architecture/design delta in design.md, record shared preparation and legacy-replacement direction in coordination.md when multiple specs will be implemented in parallel, process clarification updates, and wait for explicit approval before implementation."
+  default_prompt: "Use $generate-spec to create or update single-spec plans under docs/plans/<date>/<change_name>/ or parallel batches under docs/plans/<date>/<batch_name>/<change_name>/ with a shared coordination.md, but ensure every spec in a batch remains independently approvable, independently implementable, and safe for true parallel execution without depending on another batch spec landing first; surface shared-file or shared-contract collision risks during planning, settle ownership and additive-only rules in coordination.md before implementation starts, fill BDD requirements and risk-driven test planning, document external dependency contracts in contract.md when they materially constrain the change, write the architecture/design delta in design.md, process clarification updates, and wait for explicit approval before implementation."

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

@@ -6,6 +6,11 @@
 ## Coordination Goal
 [Describe the shared implementation goal across this batch of parallel spec sets.]
 
+## Parallel Readiness Gate
+- Ready for parallel implementation now: [Yes / No]
+- Blocking coordination items before coding: [None / list concrete ownership or contract decisions that must be settled first]
+- Re-coordination trigger: [what kind of new overlap or contract change forces the batch to stop and re-align]
+
 ## Batch Scope
 - Included spec sets: [[spec-name-1], [spec-name-2]]
 - Shared outcome: [what the batch delivers when all spec sets land]
@@ -23,6 +28,7 @@
 - Shared fields to introduce or reuse: [field / config / API shape / event schema]
 - Canonical source of truth: [which module or data owner defines them]
 - Required preparation before implementation: [migration, adapter, stub, flag, fallback, fixture]
+- Additive-only rule during batch: [what may be added safely without breaking parallel work, or `None`]
 
 ### Replacement / Legacy Direction
 - Legacy behavior being replaced: [feature / flow / module / endpoint / UI]
@@ -54,6 +60,22 @@
 - Merge order / landing order: [independent / optional convenience order only, never a functional prerequisite]
 - Worktree notes: [branch naming, rebase expectations, or `None`]
 
+## Collision Resolution Records
+
+### Collision 1: [Shared file / schema / manifest / contract]
+- Involved spec sets: [[spec-name-1], [spec-name-2]]
+- Conflict shape: [same file / same symbol / same schema field / same generated artifact]
+- Pre-agreed resolution: [single owner / additive-only edits / split by section / move into one spec]
+- Allowed edits per spec: [exact ownership boundary]
+- Escalation rule: [when engineers must stop and re-coordinate]
+
+### Collision 2: [Shared file / schema / manifest / contract]
+- Involved spec sets: [[spec-name-1], [spec-name-2]]
+- Conflict shape: [same file / same symbol / same schema field / same generated artifact]
+- Pre-agreed resolution: [single owner / additive-only edits / split by section / move into one spec]
+- Allowed edits per spec: [exact ownership boundary]
+- Escalation rule: [when engineers must stop and re-coordinate]
+
 ## Integration Checkpoints
 - Combined behaviors to verify after merge: [cross-spec outcome]
 - Required final test scope: [integration / E2E / migration / rollback]

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

@@ -17,6 +17,7 @@
 - Affected modules: [module/file/service list]
 - External contracts involved: [dependency names from `contract.md`, or `None`]
 - Coordination reference: [`../coordination.md` or `None`]
+- Parallel implementation assumption: [why this spec can be implemented concurrently, or `None` for single-spec work]
 
 ## Current Architecture
 [Describe the relevant current components, data flow, control flow, and boundaries.]
@@ -54,6 +55,7 @@
 - Key risks: [failure, concurrency, authorization, partial-write, dependency risk]
 - Rejected alternatives: [alternative + why it was not chosen]
 - Operational constraints: [performance, quota, observability, deployment coupling]
+- Cross-spec collision notes: [known shared-file/shared-contract collision avoided by ownership rules, or `None`]
 
 ## Validation Plan
 - Tests: [UT / PBT / IT / E2E / adversarial]

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

@@ -31,5 +31,6 @@
 - Task order should reflect actual implementation sequence.
 - Every main task must map back to `spec.md` requirement IDs.
 - Include explicit tasks for required test coverage (unit, regression, property-based, integration/E2E as applicable), mock scenario setup, and adversarial/edge-case hardening.
+- For batch specs, tasks must never include "wait for Spec X to land first" as a prerequisite; if such a dependency appears, re-slice the plan or move the coordination rule into `coordination.md`.
 - After execution, the agent must update each checkbox (`[x]` for done, `[ ]` for not done).
 - Remove all placeholder guidance text in square brackets after filling.

package/generate-spec/scripts/create-specs

@@ -48,7 +48,8 @@ def main() -> int:
         description=(
             "Create planning docs (spec.md, tasks.md, checklist.md, contract.md, design.md) "
             "from templates with folder format docs/plans/{date}/{change_name} "
-            "or docs/plans/{date}/{batch_name}/{change_name}."
+            "or docs/plans/{date}/{batch_name}/{change_name}, including coordination "
+            "templates for truly parallel-safe batch specs."
         ),
     )
     parser.add_argument("feature_name", help="Display name used in generated documents")
@@ -73,7 +74,8 @@ def main() -> int:
         action="store_true",
         help=(
             "When used with --batch-name, also create or update "
-            "docs/plans/{date}/{batch_name}/coordination.md from the shared template."
+            "docs/plans/{date}/{batch_name}/coordination.md from the shared template "
+            "for up-front ownership and collision coordination."
         ),
     )
     parser.add_argument(

package/package.json

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

package/version-release/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: version-release
-description: "Guide the agent to prepare and publish a versioned release (version bump, changelog, tag, GitHub release, and push). Use only when users explicitly request version/tag/release work. Depend directly on `archive-specs` when completed plan sets should become durable docs or when project docs need alignment, and let that skill own the downstream documentation synchronization work."
+description: "Guide the agent to prepare and publish a versioned release (version bump, changelog, tag, GitHub release, and push). Use only when users explicitly request version/tag/release work, including direct semver wording such as patch/minor/major updates. Depend directly on `archive-specs` when completed plan sets should become durable docs or when project docs need alignment, and let that skill own the downstream documentation synchronization work."
 ---
 
 # Version Release
@@ -47,6 +47,7 @@ Load only when needed:
    - Inventory repository planning artifacts and project docs, not only staged files, to detect repo specs and non-standard documentation layouts.
 2. Confirm release intent
    - Use this skill only when the user explicitly requests version/tag/release work.
+   - Treat explicit semver-delivery wording such as `patch update`, `minor update`, `major update`, `patch release`, `bump the version`, or requests to trigger release-published automation as release intent even when the user does not separately say `make a release`.
    - If no release intent is present, use `commit-and-push` instead.
 3. Classify changes and run dependencies when required
    - `code-affecting`: runtime code, tests, build scripts, CI logic, or behavior-changing config.

package/version-release/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Version Release"
   short_description: "Prepare a versioned release with bump, changelog, tag, GitHub release, and push"
-  default_prompt: "Use $version-release only for explicit release/version/tag requests: inspect the current repository state, read the current version plus existing tag/release state, and inspect root CHANGELOG.md Unreleased content. Treat every conditional gate whose scenario is met as blocking before any version bump, tag, or release step: if the release includes code changes, run $review-change-set; if the reviewed risk profile says edge-case or security review is needed, run $discover-edge-cases and $harden-app-security as blocking gates too; if completed specs should be converted or docs need normalization, ensure $archive-specs runs through $submission-readiness-check; if changelog synchronization is needed, complete it before continuing. Then run any additional required code-quality skills, hand the repository to $submission-readiness-check so completed plan archives, project docs, AGENTS.md, and changelog readiness are settled before any version bump or tag, confirm CHANGELOG.md Unreleased is release-ready, update version files, cut the release directly from CHANGELOG.md Unreleased, create the release commit and matching tag, push commits and tags, and publish the matching GitHub release before reporting success."
+  default_prompt: "Use $version-release only for explicit release/version/tag requests, including direct semver wording like patch/minor/major update or requests to trigger release-published automation: inspect the current repository state, read the current version plus existing tag/release state, and inspect root CHANGELOG.md Unreleased content. Treat every conditional gate whose scenario is met as blocking before any version bump, tag, or release step: if the release includes code changes, run $review-change-set; if the reviewed risk profile says edge-case or security review is needed, run $discover-edge-cases and $harden-app-security as blocking gates too; if completed specs should be converted or docs need normalization, ensure $archive-specs runs through $submission-readiness-check; if changelog synchronization is needed, complete it before continuing. Then run any additional required code-quality skills, hand the repository to $submission-readiness-check so completed plan archives, project docs, AGENTS.md, and changelog readiness are settled before any version bump or tag, confirm CHANGELOG.md Unreleased is release-ready, update version files, cut the release directly from CHANGELOG.md Unreleased, create the release commit and matching tag, push commits and tags, and publish the matching GitHub release before reporting success."