@laitszkin/apollo-toolkit 2.14.8 → 2.14.10

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.14.10] - 2026-04-09
+
+### Changed
+- Strengthen `generate-spec` coordination guidance and template so parallel worktree batches must record file ownership guardrails, shared API or schema freeze rules, compatibility-shim retention rules, and post-merge integration checkpoints that reduce functional merge conflicts.
+- Update `implement-specs-with-worktree` so engineers executing batch specs must treat those `coordination.md` guardrails as blocking constraints during implementation instead of optional notes.
+
+## [v2.14.9] - 2026-04-08
+
+### Changed
+- Update `merge-changes-from-local-branches` so it must inspect active batch-spec `coordination.md` files under `docs/plans/` and follow their documented merge order when one is explicitly provided.
+- Clarify that merge-order guidance from active batch specs is authoritative unless the plan is stale, conflicting, or cannot be mapped safely to the current branches.
+
 ## [v2.14.8] - 2026-04-08
 
 ### Changed

package/generate-spec/README.md

@@ -84,7 +84,7 @@ 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, 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, 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

package/generate-spec/SKILL.md

@@ -104,6 +104,11 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - 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.
+- 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 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.
 - 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.
 
@@ -148,6 +153,7 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - 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`.
+- 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.
 - When external dependencies materially shape the change, `contract.md` is required and must capture the official-source-backed contract in the standardized record format.
 - `design.md` is required and must describe the architecture/design delta for the spec in the standardized format, even when the final design is intentionally minimal.

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

@@ -48,6 +48,9 @@
 
 ## Conflict Boundaries
 - Shared files requiring coordination: [file/module list or `None`]
+- File ownership / edit guardrails: [which spec set owns which shared files or `None`]
+- Shared API / schema freeze: [frozen owner + additive-only rule, or `None`]
+- Compatibility shim retention rules: [which adapters/flags/tests must remain until batch completion, or `None`]
 - Merge order / landing order: [independent / optional convenience order only, never a functional prerequisite]
 - Worktree notes: [branch naming, rebase expectations, or `None`]
 

package/implement-specs-with-worktree/SKILL.md

@@ -75,6 +75,7 @@ Use branch naming from `references/branch-naming.md`.
 - Verify latest authoritative docs for involved stacks/integrations.
 - When `coordination.md` exists, respect its shared-field preparation, legacy-replacement direction, and allowed touch-point boundaries before editing.
 - Implement each task in `tasks.md` systematically.
+- When `coordination.md` defines file ownership guardrails, additive-only shared-contract rules, or compatibility-shim retention requirements, treat them as blocking execution constraints rather than optional guidance.
 - For each implemented change, add appropriate tests:
   - Unit tests for changed logic
   - Regression tests for bug-prone behavior
@@ -119,6 +120,7 @@ After implementation and testing:
 - Complete all planned tasks before committing; do not stop with partial work.
 - Treat the specs as the source of truth for scope — do not deviate without user approval.
 - When `coordination.md` exists, treat it as the source of truth for batch-level ownership and cutover direction.
+- Never remove a shared shim, rename a shared field, or rewrite a shared file outside the ownership map unless `coordination.md` explicitly allows that change or the user approves a coordination update first.
 - Follow the testing standards from `enhance-existing-features` and `develop-new-features`.
 - Do not push to remote unless the user explicitly requests it.
 

package/merge-changes-from-local-branches/SKILL.md

@@ -22,8 +22,8 @@ description: >-
 
 ## Standards
 
-- Evidence: Inspect the current branch state, local branches, ahead/behind status, and actual conflicting files before deciding what to merge.
-- Execution: Merge only the relevant local branches into `main` sequentially, resolve conflicts by reading both sides and editing the merged result to preserve shipped behavior, verify the merged state, delete each successfully merged branch and its detached worktree only after the merged result is confirmed, then hand the final local branch state to `commit-and-push` so commit/changelog/spec-archival work happens through the shared submission workflow.
+- Evidence: Inspect the current branch state, local branches, ahead/behind status, actual conflicting files, and any active batch-spec `coordination.md` merge-order guidance before deciding what to merge.
+- Execution: Merge only the relevant local branches into `main` sequentially, read any active batch-spec `coordination.md` and honor its documented merge order when present, resolve conflicts by reading both sides and editing the merged result to preserve shipped behavior, verify the merged state, delete each successfully merged branch and its detached worktree only after the merged result is confirmed, then hand the final local branch state to `commit-and-push` so commit/changelog/spec-archival work happens through the shared submission workflow.
 - Quality: Never use blanket timestamp rules or default `-X ours/theirs` conflict resolution as the primary merge strategy, and do not declare success until the final `main` state has been checked and verified.
 - Output: Produce a clean local main branch with all local changes integrated and ready for the shared submit workflow.
 
@@ -37,19 +37,29 @@ Consolidate all local branch changes into the local main branch with automatic c
 
 - Run `git branch` to list all local branches.
 - Check the current branch with `git branch --show-current` and capture `git status -sb`.
+- Inspect active planning artifacts under `docs/plans/` and look for batch roots that still contain live spec sets plus a `coordination.md`.
+- When an active batch is present, read its `coordination.md` before deciding merge order.
 - Compare each candidate branch against `main` with `git log --oneline main..branch`, `git diff --stat main...branch`, or equivalent evidence so empty or already-merged branches are skipped.
 - For each branch, note:
   - Branch name
   - Commits ahead of main
   - Last commit message (via `git log -1 --oneline`)
 
+### 1.5) Resolve merge order from active batch specs
+
+- Treat active batch specs as authoritative merge-order guidance when they include a concrete `Merge order / landing order` entry in `coordination.md`.
+- Map branch names to the corresponding spec sets or worktrees using the batch folder names, spec-set names, and current git evidence; do not guess when the mapping is ambiguous.
+- Merge branches in the documented order when that order is explicit.
+- If multiple active batches exist, reconcile their merge-order guidance before merging; if the orders conflict or the branch-to-spec mapping is unclear, stop and report the ambiguity instead of choosing an arbitrary sequence.
+- If no active batch spec provides an explicit merge order, fall back to the normal branch inventory evidence and merge the relevant branches sequentially based on the safest verified order.
+
 ### 2) Ensure clean state on main
 
 - Check `git status` on `main`.
 - If `main` has uncommitted changes that are unrelated to the merge request, stop and report them instead of stashing automatically.
 - Only proceed once you can state which branch or branches actually need to be merged.
 
-### 3) Merge branches sequentially
+### 3) Merge branches sequentially in the resolved order
 
 For each local branch (excluding main):
 
@@ -139,6 +149,7 @@ For each local branch (excluding main):
 - If a branch's merge breaks tests, resolve the conflict differently before committing.
 - Do not stash or discard unrelated work automatically; stop when the working tree state makes the merge ambiguous.
 - Delete merged source branches and their detached worktrees only after the merge commit and verification both succeed.
+- When active batch specs provide merge-order guidance, follow that order unless new evidence proves the plan is stale or inapplicable; if so, stop and report the mismatch instead of silently overriding the batch plan.
 
 ## Conflict Resolution Examples
 

package/merge-changes-from-local-branches/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Merge Changes from Local Branches"
   short_description: "Merge relevant local branches into main with verified conflict resolution"
-  default_prompt: "Use $merge-changes-from-local-branches to inventory local branches, merge only the relevant ones into local main, resolve conflicts by reading and composing the correct behavior instead of relying on blanket merge strategies, run targeted verification after conflictful merges, delete successfully merged source branches and detached worktrees only after verification succeeds, and leave remote state untouched."
+  default_prompt: "Use $merge-changes-from-local-branches to inventory local branches, inspect active batch-spec `coordination.md` files under docs/plans and follow their documented merge order when present, merge only the relevant ones into local main, resolve conflicts by reading and composing the correct behavior instead of relying on blanket merge strategies, run targeted verification after conflictful merges, delete successfully merged source branches and detached worktrees only after verification succeeds, and leave remote state untouched."

package/package.json

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