@laitszkin/apollo-toolkit 2.14.7 → 2.14.8

package/CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.14.8] - 2026-04-08
+
+### Changed
+- Tighten `generate-spec` so multi-spec batch planning must slice work into independently completable specs that can each be approved, implemented, tested, and merged without depending on another spec in the same batch landing first.
+- Update `generate-spec` coordination guidance and templates so batch-level merge order may be a convenience only, never a functional prerequisite between specs.
 ## [v2.14.7] - 2026-04-08
 
 ### Changed

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`.
+- 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.
 - 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,10 +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, merge order, and cross-spec integration checkpoints.
+- `coordination.md`: for multi-spec batches only, record shared preparation, ownership boundaries, replacement direction, 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.

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, 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 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.
 - 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, 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 and independently implementable, and keep them concise, executable, and easy to update.
 
 ## Goal
 
@@ -45,6 +45,8 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - If the requested work would span more than three modules, do not draft one oversized coupled plan.
 - Instead, split the work into multiple spec sets, each independently valid and each covering no more than three modules.
 - 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.
 - Use:
   - `SKILL_ROOT=<path_to_generate-spec_skill>`
   - `WORKSPACE_ROOT=<target_project_root>`
@@ -98,9 +100,11 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Create `coordination.md` only when one user request is intentionally split into multiple spec sets that may be implemented in parallel.
 - Place it at `docs/plans/{YYYY-MM-DD}/{batch_name}/coordination.md`.
 - 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.
 - 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.
+- If the batch still needs a recommended merge order, make that order operationally convenient rather than functionally required for any single spec to work correctly.
 - Keep single-spec concerns in that spec's own `design.md`; reserve `coordination.md` for batch-wide rules only.
 
 ### 7) Fill `checklist.md`
@@ -142,6 +146,7 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Keep requirement IDs, task IDs, and test IDs traceable across all three files.
 - 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.
 - 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`.
 - Prefer realistic coverage over boilerplate: add or remove checklist items based on actual risk.
 - When external dependencies materially shape the change, `contract.md` is required and must capture the official-source-backed contract in the standardized record format.

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, 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 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."

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

@@ -10,6 +10,7 @@
 - Included spec sets: [[spec-name-1], [spec-name-2]]
 - Shared outcome: [what the batch delivers when all spec sets land]
 - Out of scope: [shared exclusions for the batch]
+- Independence rule: [state how each spec remains independently implementable, testable, and mergeable without another spec in this batch landing first]
 
 ## Shared Context
 - Current baseline: [the current system shape that all spec sets must assume]
@@ -35,17 +36,19 @@
 - Primary concern: [what this spec owns]
 - Allowed touch points: [files/modules it may change]
 - Must not change: [files/modules owned by another spec unless explicitly coordinated]
-- Depends on shared preparation: [None / specific shared item above]
+- Depends on shared preparation: [None / specific shared item above that already exists or can be completed within this spec]
+- Cross-spec implementation dependency: [None; if not None, re-slice the batch]
 
 ### Spec Set 2: [spec-name-2]
 - Primary concern: [what this spec owns]
 - Allowed touch points: [files/modules it may change]
 - Must not change: [files/modules owned by another spec unless explicitly coordinated]
-- Depends on shared preparation: [None / specific shared item above]
+- Depends on shared preparation: [None / specific shared item above that already exists or can be completed within this spec]
+- Cross-spec implementation dependency: [None; if not None, re-slice the batch]
 
 ## Conflict Boundaries
 - Shared files requiring coordination: [file/module list or `None`]
-- Merge order / landing order: [independent / explicit order]
+- Merge order / landing order: [independent / optional convenience order only, never a functional prerequisite]
 - Worktree notes: [branch naming, rebase expectations, or `None`]
 
 ## Integration Checkpoints

package/package.json

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