@laitszkin/apollo-toolkit 2.14.6 → 2.14.8

package/CHANGELOG.md

@@ -4,6 +4,16 @@ 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
+- Update `merge-changes-from-local-branches` so it removes successfully merged source branches and any detached worktrees only after the merge commit and verification both succeed, while refusing forced deletion for branches that are not actually merged.
+
 ## [v2.14.6] - 2026-04-08
 
 ### Added

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/merge-changes-from-local-branches/SKILL.md

@@ -23,7 +23,7 @@ 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, then hand the final local branch state to `commit-and-push` so commit/changelog/spec-archival work happens through the shared submission workflow.
+- 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.
 - 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.
 
@@ -98,6 +98,21 @@ For each local branch (excluding main):
 
 ### 5) Hand off the merged result for shared submission handling
 
+- After a branch has been merged successfully and the merged `main` state has been verified, remove the source branch worktree if one exists:
+  ```bash
+  git worktree list
+  git worktree remove <worktree-path>
+  ```
+- Delete only branches that were merged successfully:
+  ```bash
+  git branch -d <branch-name>
+  ```
+- If a branch still has an attached worktree, remove the worktree before deleting the branch.
+- Never delete:
+  - `main`
+  - the currently checked-out branch
+  - branches that were skipped, failed to merge, or still need manual follow-up
+- If `git branch -d` refuses deletion because the branch is not actually merged, stop and report the branch instead of forcing deletion with `-D`.
 - Once merge verification passes, invoke `commit-and-push` for the authoritative local branch so the final submission flow owns:
   - `CHANGELOG.md` readiness
   - any required `archive-specs` run
@@ -123,6 +138,7 @@ For each local branch (excluding main):
 - Keep the main branch history clean and readable.
 - 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.
 
 ## 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, and leave remote state untouched."
+  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."

package/package.json

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