@laitszkin/apollo-toolkit 2.14.14 → 2.14.15

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.14.15] - 2026-04-11
+
+### Changed
+- Update `merge-changes-from-local-branches` so merge scope is determined from explicit branch names or spec-name mappings, instead of verifying child-branch ancestry from git history.
+- Update `implement-specs-with-worktree` so new worktree branches inherit from the same parent branch as the worktree base, and use the spec-set name as the canonical branch/worktree identifier.
+
 ## [v2.14.14] - 2026-04-11
 
 ### Changed

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

@@ -6,9 +6,10 @@ description: >-
   plus parent `coordination.md` when present, and implement the approved tasks
   within an isolated git worktree. Use when the user asks to implement from an
   existing spec set, execute a spec plan, or work on a feature branch without
-  affecting the main working tree. If not already in a worktree, create a new
-  worktree with an independent branch, implement all planned tasks, then commit
-  the changes to that local branch when complete.
+  affecting the parent working tree. If not already in a worktree, create a new
+  worktree with a spec-named branch from the same parent branch as the worktree
+  base, implement all planned tasks, then commit the changes to that local
+  branch when complete.
 ---
 
 # Implement Specs with Worktree
@@ -22,14 +23,14 @@ description: >-
 
 ## Standards
 
-- Evidence: Read and understand the complete specs set before starting implementation, and when the requested plan path is missing from the current worktree verify where the authoritative copy actually lives before substituting any nearby spec.
-- Execution: Create or use an isolated worktree for implementation, sync the exact approved plan set into that worktree when it is missing there, follow the implementation standards from the dependent skills, and commit to a local branch when done.
+- Evidence: Read and understand the complete specs set before starting implementation, identify the authoritative parent branch that the worktree should inherit from, and when the requested plan path is missing from the current worktree verify where the authoritative copy actually lives before substituting any nearby spec.
+- Execution: Create or use an isolated worktree for implementation, sync the exact approved plan set into that worktree when it is missing there, create the worktree branch from the same parent branch as the worktree base, use the spec-set name as the canonical branch/worktree name, follow the implementation standards from the dependent skills, and commit to a local branch when done.
 - Quality: Complete all planned tasks, run relevant tests, backfill the spec documents with actual completion status, and avoid dragging unrelated sibling specs into the worktree just because they share a batch directory.
 - Output: Keep the worktree branch clean with only the intended implementation commits.
 
 ## Goal
 
-Implement approved spec planning sets in an isolated git worktree, ensuring main development is never interrupted by in-progress work.
+Implement approved spec planning sets in an isolated git worktree, ensuring the parent working tree is never interrupted by in-progress work.
 
 ## Workflow
 
@@ -58,18 +59,26 @@ Implement approved spec planning sets in an isolated git worktree, ensuring main
 - Run `git worktree list` to see existing worktrees and branches.
 - Determine if the current session is already inside a worktree (check `git rev-parse --show-toplevel` and compare with `git worktree list`).
 - If the current worktree is missing the exact requested plan set, sync that plan into the worktree before coding and re-read the synced files there so implementation happens against the same plan snapshot that will be backfilled later.
+- Determine the authoritative parent branch for the new worktree:
+  - if the current checkout already comes from a branch, reuse that branch as the base
+  - if the current session is inside a detached worktree, identify the parent branch that owns that worktree before creating another branch from it
+  - do not default to `main` unless `main` is actually the parent branch of the worktree you are extending
 
 ### 3) Create a new worktree if needed
 
 If not already in a worktree, or if the user explicitly requests a fresh worktree:
 
-- Create a new branch for this implementation:
+- Derive the canonical spec name from the requested `change_name` directory.
+- Use that spec name as the shared branch/worktree identifier:
+  - branch name: `<type>/<spec-name>` following `references/branch-naming.md`
+  - worktree directory name: `<spec-name>`
+- Create a new branch for this implementation from the same parent branch identified in step 2:
   ```bash
-  git branch <branch-name> main
+  git branch <branch-name> <parent-branch>
   ```
 - Add a new worktree:
   ```bash
-  git worktree add ../<worktree-name> -b <branch-name>
+  git worktree add ../<spec-name> <branch-name>
   ```
 - Move into the new worktree directory and begin work there.
 
@@ -117,12 +126,14 @@ After implementation and testing:
 ### 7) Report completion
 
 - Summarize what was implemented.
-- Note the branch name and worktree location.
-- Confirm that main remains unaffected.
+- Note the spec-derived branch name and worktree location.
+- Confirm that the parent branch remains unaffected.
 
 ## Working Rules
 
-- Always work in an isolated worktree to keep main clean.
+- Always work in an isolated worktree to keep the parent checkout clean.
+- Keep the new branch based on the same parent branch as the worktree base; do not silently rebase the workflow onto a different branch.
+- Use the spec-set name as the canonical identifier for the branch and worktree unless the user explicitly asks for a different naming scheme.
 - 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.

package/implement-specs-with-worktree/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Implement Specs with Worktree"
   short_description: "Implement an approved spec set inside an isolated git worktree"
-  default_prompt: "Use $implement-specs-with-worktree to read the full plan set under docs/plans, including parent coordination.md when the spec belongs to a parallel batch, create or reuse an isolated git worktree, implement all approved tasks within the shared ownership and replacement-direction constraints, backfill completion status into the planning docs, and commit the result to the local worktree branch without affecting main."
+  default_prompt: "Use $implement-specs-with-worktree to read the full plan set under docs/plans, including parent coordination.md when the spec belongs to a parallel batch, identify the parent branch that the worktree should inherit from, create or reuse an isolated git worktree whose branch and directory names are derived from the spec name, implement all approved tasks within the shared ownership and replacement-direction constraints, backfill completion status into the planning docs, and commit the result to the local worktree branch without affecting the parent branch."

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

@@ -1,16 +1,16 @@
 ---
 name: merge-changes-from-local-branches
 description: >-
-  Read changes from local child branches that forked from the current local
-  branch and merge them back into that same branch. When conflicts arise,
-  auto-resolve them by keeping correct functionality (preferring the more recent
-  change on the same line, or the change that preserves working behavior). Run
-  `archive-specs` after merge verification so completed plan sets are archived
-  and durable project docs are synchronized, then hand the current branch state
-  to `commit-and-push` so the final submit workflow commits and pushes on that
-  same local branch. Use when the user asks to consolidate child-branch work,
-  merge branches branched from the current branch, or prepare the current branch
-  for integration.
+  Read changes from local branches identified by branch name and merge them back
+  into the current local branch. When conflicts arise, auto-resolve them by
+  keeping correct functionality (preferring the more recent change on the same
+  line, or the change that preserves working behavior). Run `archive-specs`
+  after merge verification so completed plan sets are archived and durable
+  project docs are synchronized, then hand the current branch state to
+  `commit-and-push` so the final submit workflow commits and pushes on that same
+  local branch. Use when the user asks to consolidate local branch work, merge
+  named branches into the current branch, or prepare the current branch for
+  integration.
 ---
 
 # Merge Changes from Local Branches
@@ -24,41 +24,43 @@ description: >-
 
 ## Standards
 
-- Evidence: Inspect the original current branch, local branches, ahead/behind status, verified child-branch ancestry, actual conflicting files, and any active batch-spec `coordination.md` merge-order guidance before deciding what to merge.
-- Execution: Merge only the relevant child branches that verifiably forked from the original current branch back into that same branch, 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 child branch and its detached worktree only after the merged result is confirmed, run `archive-specs` so completed plan sets are archived and durable docs are synchronized, then hand the final current-branch state to `commit-and-push` so changelog/readiness/commit/push work happens through the shared submission workflow on the same branch.
-- Quality: Never use blanket timestamp rules or default `-X ours/theirs` conflict resolution as the primary merge strategy, never infer branch parentage without git evidence, and do not declare success until the final current-branch state has been checked, verified, and cleared for post-merge archival/doc-sync work.
-- Output: Produce a clean current branch with all relevant child-branch changes integrated and ready for the shared submit workflow.
+- Evidence: Inspect the original current branch, local branches, branch-name matches provided by the user or active spec names, actual conflicting files, and any active batch-spec `coordination.md` merge-order guidance before deciding what to merge.
+- Execution: Merge only the relevant named branches back into the original current branch, 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 source branch and its detached worktree only after the merged result is confirmed, run `archive-specs` so completed plan sets are archived and durable docs are synchronized, then hand the final current-branch state to `commit-and-push` so changelog/readiness/commit/push work happens through the shared submission workflow on the same branch.
+- Quality: Never use blanket timestamp rules or default `-X ours/theirs` conflict resolution as the primary merge strategy, never infer in-scope branches from ancestry heuristics when branch names already define the target set, and do not declare success until the final current-branch state has been checked, verified, and cleared for post-merge archival/doc-sync work.
+- Output: Produce a clean current branch with all relevant named-branch changes integrated and ready for the shared submit workflow.
 
 ## Goal
 
-Consolidate verified child-branch changes back into the original current branch with automatic conflict resolution that preserves correct functionality.
+Consolidate the intended named local branches back into the original current branch with automatic conflict resolution that preserves correct functionality.
 
 ## Workflow
 
-### 1) Inventory the current branch and in-scope child branches
+### 1) Inventory the current branch and in-scope named branches
 
 - 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.
 - Treat the original current branch as the authoritative merge target for the whole workflow; do not silently switch that target to `main`.
-- Determine whether each candidate branch is a child branch of the current branch by using git evidence such as `git merge-base --fork-point <current-branch> <candidate>`, `git merge-base <current-branch> <candidate>`, and branch reflog/history when needed.
-- Accept a branch as in scope only when the evidence shows it actually forked from the current branch; skip parent branches, sibling branches, and unrelated local branches.
-- If child-branch ancestry is ambiguous, stop and report the ambiguity instead of guessing.
+- Determine the in-scope branches directly from branch names:
+  - prefer the exact branch names the user provided
+  - otherwise map active spec-set names or documented merge-order entries to branch names
+  - otherwise stop and report the missing branch-name target instead of inferring from ancestry
+- Accept a branch as in scope only when its branch name can be matched unambiguously to the requested merge set; skip unrelated local branches.
 - Compare each in-scope candidate branch against the current branch with `git log --oneline <current-branch>..<candidate>`, `git diff --stat <current-branch>...<candidate>`, or equivalent evidence so empty or already-merged branches are skipped.
 - For each branch, note:
   - Branch name
-  - Verified fork-point evidence from the current branch
+  - How the branch name was matched to the requested merge set
   - Commits ahead of the current branch
   - 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 only the in-scope child branches in the documented order when that order is explicit.
+- Map branch names to the corresponding spec sets or worktrees using the batch folder names, spec-set names, and documented merge-order entries; do not guess when the mapping is ambiguous.
+- Merge only the in-scope named 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.
+- If no active batch spec provides an explicit merge order, fall back to the requested branch-name list and merge the relevant branches sequentially in that explicit name order.
 
 ### 2) Ensure clean state on the original current branch
 
@@ -69,7 +71,7 @@ Consolidate verified child-branch changes back into the original current branch
 
 ### 3) Merge branches sequentially in the resolved order
 
-For each in-scope child branch:
+For each in-scope named branch:
 
 1. Check out the original current branch:
    ```bash
@@ -124,7 +126,7 @@ For each in-scope child branch:
 
 ### 6) Hand off the merged result for shared submission handling
 
-- After a child branch has been merged successfully and the merged current-branch state has been verified, remove the source branch worktree if one exists:
+- After a source branch has been merged successfully and the merged current-branch state has been verified, remove the source branch worktree if one exists:
   ```bash
   git worktree list
   git worktree remove <worktree-path>
@@ -148,7 +150,7 @@ For each in-scope child branch:
 
 ### 7) Report completion
 
-- List all child branches that were merged.
+- List all named branches that were merged.
 - List any branches intentionally skipped because they were already merged, empty, or out of scope.
 - Confirm the original current branch is updated with all merged changes.
 - Note any conflicts that were resolved and the rationale.
@@ -161,13 +163,13 @@ For each in-scope child branch:
 - Never force-push; use only merge or rebase with merge.
 - Prefer preserving functionality over keeping either branch's exact changes.
 - Do not push to remote from this skill directly; let `commit-and-push` own any later publish step only when the user explicitly requests it.
-- Never merge parent branches, sibling branches, or unverified branches into the current branch; merge only branches whose child relationship to the original current branch is supported by git evidence.
+- Never merge unrelated or ambiguously matched branches into the current branch; merge only branches whose names are explicitly requested or can be matched unambiguously from the active spec context.
 - If a branch contains no meaningful changes (empty merge), skip it.
 - Keep the current 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.
-- When active batch specs provide merge-order guidance for in-scope child branches, 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.
+- When active batch specs provide merge-order guidance for in-scope named branches, 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 verified child branches back into the current branch with checked conflict resolution"
-  default_prompt: "Use $merge-changes-from-local-branches to inventory the current branch plus any local child branches that verifiably forked from it, inspect active batch-spec `coordination.md` files under `docs/plans/` and follow their documented merge order when present, merge only those in-scope child branches back into the same current branch, resolve conflicts by reading and composing the correct behavior instead of relying on blanket merge strategies, run targeted verification after conflictful merges, run `archive-specs` so completed plan sets are archived and durable docs are synchronized before the final submit step, delete successfully merged source branches and detached worktrees only after verification succeeds, and leave remote publication to `commit-and-push`."
+  short_description: "Merge named local branches back into the current branch with checked conflict resolution"
+  default_prompt: "Use $merge-changes-from-local-branches to inventory the current branch plus the named local branches that should be merged, inspect active batch-spec `coordination.md` files under `docs/plans/` and follow their documented merge order when present, match the merge scope by branch name instead of branch ancestry, merge only those in-scope branches back into the same current branch, resolve conflicts by reading and composing the correct behavior instead of relying on blanket merge strategies, run targeted verification after conflictful merges, run `archive-specs` so completed plan sets are archived and durable docs are synchronized before the final submit step, delete successfully merged source branches and detached worktrees only after verification succeeds, and leave remote publication to `commit-and-push`."

package/package.json

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