@laitszkin/apollo-toolkit 2.14.0 → 2.14.2

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.14.2] - 2026-04-06
+
+### Changed
+- Rewire `merge-changes-from-local-branches` so its final local-branch submission stage is handed to `commit-and-push`, which now owns the shared changelog/readiness/archival flow after merges.
+- Rework `archive-specs` so documentation alignment is delegated to `align-project-documents` and `maintain-project-constraints` before completed plan sets are archived.
+- Clarify that `commit-and-push` and `version-release` depend directly on `archive-specs` for completed plan conversion and project-doc alignment, instead of duplicating downstream documentation-sync steps.
+
+## [v2.14.1] - 2026-04-06
+
+### Changed
+- Tighten `merge-changes-from-local-branches` so it inspects branch divergence before merging, resolves conflicts by composing verified behavior instead of relying on blanket `-X ours/theirs` or timestamp heuristics, and requires targeted verification after conflictful merges.
+
+### Fixed
+- Add missing `agents/openai.yaml` metadata for `merge-changes-from-local-branches` and `implement-specs-with-worktree` so repository agent-config validation passes and both skills expose UI metadata consistently.
+
+## [v2.14.0] - 2026-04-05
+
 ### Added
 - Add `agents` install mode to CLI and installer, aligning npm-based CLI with shell script capabilities.
 - Add `implement-specs-with-worktree` skill for implementing specs in isolated git worktrees.

package/archive-specs/SKILL.md

@@ -7,7 +7,7 @@ description: Convert completed project plan sets into maintainable project docum
 
 ## Dependencies
 
-- Required: none.
+- Required: `align-project-documents` to align repository docs with current code before archiving, and `maintain-project-constraints` to synchronize `AGENTS.md` after the doc update.
 - Conditional: none.
 - Optional: none.
 - Fallback: not applicable.
@@ -15,9 +15,9 @@ description: Convert completed project plan sets into maintainable project docum
 ## Standards
 
 - Evidence: Treat code, config, deployment files, and current spec files as evidence sources; never guess when a detail is missing.
-- Execution: Inventory all relevant specs first, reconcile them with the current repository, then generate or update standardized docs from the provided templates.
+- Execution: Inventory all relevant specs first, reconcile them with the current repository, use `align-project-documents` to update durable project docs, use `maintain-project-constraints` to refresh `AGENTS.md` when repository guidance changed, then archive only the truly consumed planning artifacts.
 - Quality: Prefer source-of-truth behavior over stale plan text, align existing docs to the same standard structure, and call out unknowns explicitly instead of inventing missing setup details.
-- Output: Produce a concise `README.md` plus a categorized project-doc set, then archive or remove superseded spec files after the conversion is complete.
+- Output: Produce synchronized durable docs (`README.md`, categorized project docs, and `AGENTS.md` when needed), then archive or remove superseded spec files after the conversion is complete.
 
 ## Goal
 
@@ -44,6 +44,7 @@ Convert completed planning artifacts into stable, standardized project documenta
 
 ### 3) Standardize existing project docs into categorized outputs
 
+- Hand the documentation rewrite/alignment work to `align-project-documents`; use the templates below only as the target shape and evidence checklist.
 - If the project already has `README.md`, handbooks, setup guides, architecture docs, or runbooks, rewrite or reorganize them so they follow this skill's standardized split-document structure instead of leaving mixed formats in place.
 - Use `references/templates/readme.md` for the concise project introduction.
 - Use `references/templates/docs-index.md` for the project documentation index and reference list.
@@ -85,6 +86,7 @@ Ensure the split project docs cover all of the following:
 - `docs/README.md` should act as the reference list for the categorized docs.
 - Each category doc should stay focused on one topic instead of acting like another monolithic handbook.
 - Remove template placeholders and stale planning language before finishing.
+- After the docs are aligned, run `maintain-project-constraints` whenever the documentation changes imply `AGENTS.md` needs to reflect updated workflows, commands, or repository capabilities.
 
 ### 7) Archive superseded spec files after successful conversion
 

package/commit-and-push/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: commit-and-push
-description: "Guide the agent to submit local changes with commit and push only (no versioning). Use when users ask to commit, submit, or push changes without requesting tag/version/release operations. During submission, run `archive-specs` to convert completed spec sets into project documentation and archive the consumed plans, and also use it when existing project docs do not match the standardized project-doc structure."
+description: "Guide the agent to submit local changes with commit and push only (no versioning). Use when users ask to commit, submit, or push changes without requesting tag/version/release operations. 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."
 ---
 
 # Commit and Push
@@ -8,14 +8,14 @@ description: "Guide the agent to submit local changes with commit and push only
 ## Dependencies
 
 - Required: `submission-readiness-check` before the final commit.
-- Conditional: `review-change-set` is required for code-affecting changes; `discover-edge-cases` and `harden-app-security` are important review gates that remain conditional, but become required whenever the reviewed scope or risk profile warrants them.
+- Conditional: `archive-specs` when completed plan sets should be converted or repository docs need alignment; `review-change-set` is required for code-affecting changes; `discover-edge-cases` and `harden-app-security` are important review gates that remain conditional, but become required whenever the reviewed scope or risk profile warrants them.
 - Optional: none.
 - Fallback: If any required dependency is unavailable, stop and report the missing dependency.
 
 ## Standards
 
 - Evidence: Inspect git state and classify the change set before deciding which quality gates apply, then compare the actual pending diff against root `CHANGELOG.md` `Unreleased` before committing.
-- Execution: Run the required quality-gate skills when applicable, and treat every conditional gate whose scenario is met as blocking before submission; hand the repository to `submission-readiness-check` for changelog/docs/plan finalization, preserve staging intent, honor any explicit user-specified target branch, and when the worktree is already clean inspect local `HEAD`, upstream state, and the most recent relevant commit before deciding the request is a no-op; when worktree-based delivery is involved, verify where the authoritative target branch lives before moving history, re-validate on that target branch after replay or merge, and remove the temporary worktree only after the target branch is safely updated; then commit and push without release steps; run dependent git mutations sequentially and verify the remote branch actually contains the new local `HEAD` before reporting success.
+- Execution: Run the required quality-gate skills when applicable, and treat every conditional gate whose scenario is met as blocking before submission; hand the repository to `submission-readiness-check` for readiness classification, invoke `archive-specs` directly whenever completed plan sets should be converted or project docs need alignment, preserve staging intent, honor any explicit user-specified target branch, and when the worktree is already clean inspect local `HEAD`, upstream state, and the most recent relevant commit before deciding the request is a no-op; when worktree-based delivery is involved, verify where the authoritative target branch lives before moving history, re-validate on that target branch after replay or merge, and remove the temporary worktree only after the target branch is safely updated; then commit and push without release steps; run dependent git mutations sequentially and verify the remote branch actually contains the new local `HEAD` before reporting success.
 - Quality: Re-run relevant validation for runtime changes, preserve unrelated local work safely when branch switching or post-push local sync is required, and do not bypass blocking readiness findings such as missing/stale `Unreleased` bullets or unsynchronized project docs.
 - Output: Produce a concise Conventional Commit, push it to the intended branch, and report any temporary stash/restore or local branch sync that was required.
 
@@ -61,10 +61,11 @@ Load only when needed:
    - Re-run relevant tests when runtime logic changes.
 5. Run shared submission readiness
    - Execute `$submission-readiness-check` after code/doc scans are complete and before the final commit.
-   - Let it decide whether completed plan sets should be converted, whether project docs or `AGENTS.md` need synchronization, and whether `CHANGELOG.md` is blocking submission.
+   - Let it decide whether completed plan sets should be converted, whether project docs need alignment through `archive-specs`, and whether `CHANGELOG.md` is blocking submission.
    - Do not continue to commit while `submission-readiness-check` reports unresolved readiness blockers.
    - Treat root `CHANGELOG.md` `Unreleased` coverage as mandatory for code-affecting or user-visible changes: if the current work is not reflected there yet, update it before committing instead of merely noting the gap.
    - Re-open the final `CHANGELOG.md` diff after readiness updates and confirm the `Unreleased` bullets describe the same scope as the commit you are about to create.
+   - When readiness indicates doc conversion or project-doc drift, run `archive-specs` before the final commit instead of duplicating documentation alignment work locally.
 6. Commit
    - Preserve user staging intent where possible.
    - Write a concise Conventional Commit message using `references/commit-messages.md`.

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

@@ -0,0 +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, create or reuse an isolated git worktree, implement all approved tasks with the required tests, backfill completion status into the planning docs, and commit the result to the local worktree branch without affecting main."

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

@@ -4,26 +4,28 @@ description: >-
   Read changes from all local git branches and merge them into the local main
   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). Commit the merged result to local main without pushing to
-  remote. Use when the user asks to consolidate local branch work, merge all
-  changes into main, or prepare local branches for integration.
+  working behavior). Hand the final merged local branch state to `commit-and-push`
+  so the commit workflow can handle changelog/readiness steps and any required
+  spec archival before the work is considered complete. Use when the user asks
+  to consolidate local branch work, merge all changes into main, or prepare local
+  branches for integration.
 ---
 
 # Merge Changes from Local Branches
 
 ## Dependencies
 
-- Required: none (uses native git commands).
+- Required: `commit-and-push` for the final local-branch submission flow after merge verification.
 - Conditional: none.
-- Optional: `commit-and-push` if commit message guidance is needed.
+- Optional: none.
 - Fallback: If git operations fail, stop and report the error.
 
 ## Standards
 
-- Evidence: Inspect all local branches and their changes before merging.
-- Execution: Merge each branch into main, auto-resolve conflicts to preserve functionality, and commit the result.
-- Quality: Ensure the final merged state is functional with no broken code.
-- Output: Produce a clean main branch with all local changes integrated.
+- 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.
+- 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.
 
 ## Goal
 
@@ -34,6 +36,8 @@ Consolidate all local branch changes into the local main branch with automatic c
 ### 1) Inventory all local branches
 
 - Run `git branch` to list all local branches.
+- Check the current branch with `git branch --show-current` and capture `git status -sb`.
+- 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
@@ -41,11 +45,9 @@ Consolidate all local branch changes into the local main branch with automatic c
 
 ### 2) Ensure clean state on main
 
-- Check `git status` on main branch.
-- If there are uncommitted changes on main, stash them:
-  ```bash
-  git stash push -m "WIP: temporary stash before branch merging"
-  ```
+- 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
 
@@ -62,19 +64,14 @@ For each local branch (excluding main):
    ```
 
 3. If conflicts occur, resolve them automatically using these rules:
-   - **Same line, different content**: Prefer the change with:
-     - More recent timestamp, OR
-     - The change that preserves existing functionality (analyze context to determine which branch's change maintains correct behavior)
-   - **File deleted in one branch, modified in another**: Keep the modification unless the deletion is explicitly required for the feature
-   - **Both branches modified same file differently**: Keep both sets of changes if non-overlapping; if overlapping, use the more recent change
-   - **Test files conflicting**: Keep both test cases unless they test mutually exclusive behaviors
-
-   Auto-resolve using git's merge strategies:
-   ```bash
-   git merge -X ours <branch-name>      # Prefer main's version for conflicts
-   git merge -X theirs <branch-name>    # Prefer the merged branch's version
-   ```
-   Or manually edit conflicted files and:
+   - Read the conflict markers and both parent versions before editing.
+   - **Same line, different content**: keep the version that matches the intended post-merge behavior, not simply the newer edit.
+   - **File deleted in one branch, modified in another**: keep the version supported by current code references and tests; do not silently drop reachable code.
+   - **Both branches modified the same file differently**: preserve both changes when they are compatible; if they overlap, manually compose a merged result that keeps the verified logic from both sides.
+   - **Test files conflicting**: preserve coverage for both behaviors unless one assertion is now obsolete by verified implementation changes.
+   - Use `-X ours` / `-X theirs` only for a narrowly justified conflict after reading the actual content; never use those flags as the default merge strategy.
+
+   After resolving files:
    ```bash
    git add <resolved-files>
    ```
@@ -82,7 +79,8 @@ For each local branch (excluding main):
 4. If auto-resolution is ambiguous, prefer the change that:
    - Does not break existing tests
    - Preserves the documented feature intent
-   - Keeps more recent bug fixes
+   - Aligns with the code currently shipped on the source branch
+   - Minimizes hidden semantic drift between the merged modules
 
 5. Complete the merge:
    ```bash
@@ -91,46 +89,48 @@ For each local branch (excluding main):
 
 ### 4) Verify merged state
 
-- Run relevant tests to ensure nothing is broken:
+- After each conflictful merge, run the most relevant targeted tests or build checks for the files that changed.
+- After all merges complete, run the repository's broader validation command when one exists:
   ```bash
-  # Run tests if a test command exists
   npm test  # or yarn test, cargo test, etc.
   ```
-- If tests fail, investigate and fix the conflict resolution.
-
-### 5) Commit the merged result
+- If verification fails, fix the merged state on `main` before proceeding.
 
-The merge commits already serve as commits. If additional staging is needed:
+### 5) Hand off the merged result for shared submission handling
 
-```bash
-git status
-git add -A
-git commit --amend --no-edit  # Amend the last merge commit if needed
-```
+- 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
+  - the final commit creation on the local target branch
+- Do not duplicate commit-message, changelog, or spec-archival logic inside this skill.
+- If a follow-up fix is required after verification, make that fix on `main` before handing off to `commit-and-push`.
 
 ### 6) Report completion
 
 - List all branches that were merged.
+- List any branches intentionally skipped because they were already merged, empty, or out of scope.
 - Confirm main is updated with all changes.
 - Note any conflicts that were resolved and the rationale.
-- Confirm no remote push was performed.
+- Report the verification commands that were run.
+- Confirm whether the workflow stopped at the local commit boundary or continued into a remote push because the user explicitly requested it.
 
 ## Working Rules
 
 - 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 — this skill only merges to local main.
+- 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.
 - If a branch contains no meaningful changes (empty merge), skip it.
 - 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.
 
 ## Conflict Resolution Examples
 
 | Scenario | Resolution Strategy |
 |----------|---------------------|
-| Same line, main has older change | Keep branch's change |
-| Same line, branch has older change | Keep main's change |
-| File deleted in branch, modified in main | Keep main's modification |
+| Same line, both branches changed behavior | Read both code paths and compose the merged logic that preserves the verified invariant |
+| Same line, one branch is a bug fix and the other is a refactor | Keep the bug fix and reapply the compatible refactor structure manually if needed |
+| File deleted in branch, modified in main | Keep the version supported by current references/tests and remove only if the deletion is proven correct |
 | Both added same function differently | Keep both; rename if needed |
 | Config file conflict | Keep both values if non-overlapping |
 | Test file conflict | Keep both test cases |

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

@@ -0,0 +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."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "2.14.0",
+  "version": "2.14.2",
   "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. Before finalizing the release, run `archive-specs` to convert completed spec sets into project documentation and archive the consumed plans, and also use it when existing project docs do not match the standardized project-doc structure."
+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."
 ---
 
 # Version Release
@@ -8,14 +8,14 @@ description: "Guide the agent to prepare and publish a versioned release (versio
 ## Dependencies
 
 - Required: `submission-readiness-check` before version metadata edits, tagging, or release publication.
-- Conditional: `review-change-set` is required for code-affecting releases before metadata edits and the final commit; `discover-edge-cases` and `harden-app-security` are important review gates that remain conditional, but become required whenever the reviewed scope or risk profile warrants them.
+- Conditional: `archive-specs` when completed plan sets should be converted or repository docs need alignment; `review-change-set` is required for code-affecting releases before metadata edits and the final commit; `discover-edge-cases` and `harden-app-security` are important review gates that remain conditional, but become required whenever the reviewed scope or risk profile warrants them.
 - Optional: none.
 - Fallback: If a required release dependency is unavailable, stop and report the missing dependency.
 
 ## Standards
 
 - Evidence: Inspect the active change set, current version files, existing tag format, existing remote tags/releases, and root `CHANGELOG.md` `Unreleased` content before touching version files, tags, or release metadata.
-- Execution: Use this workflow only for explicit release intent, run the required quality gates when applicable, and treat every conditional gate whose scenario is met as blocking before versioning or publication; hand the repository to `submission-readiness-check` before versioning work, and if the worktree is already clean inspect the current version, local/remote tag state, and existing GitHub release state before deciding whether the request is already satisfied; then cut the release directly from `CHANGELOG.md` `Unreleased`, update versions and docs, commit, tag, push, and publish the GitHub release with actual release tooling rather than PR-surrogate directives; run git mutations sequentially and verify both the branch tip and release tag exist remotely before publishing the GitHub release.
+- Execution: Use this workflow only for explicit release intent, run the required quality gates when applicable, and treat every conditional gate whose scenario is met as blocking before versioning or publication; hand the repository to `submission-readiness-check` before versioning work, invoke `archive-specs` directly whenever completed plan sets should be converted or project docs need alignment, and if the worktree is already clean inspect the current version, local/remote tag state, and existing GitHub release state before deciding whether the request is already satisfied; then cut the release directly from `CHANGELOG.md` `Unreleased`, update versions and docs, commit, tag, push, and publish the GitHub release with actual release tooling rather than PR-surrogate directives; run git mutations sequentially and verify both the branch tip and release tag exist remotely before publishing the GitHub release.
 - Quality: Never guess versions, align user-facing docs with actual code, do not bypass readiness blockers from `submission-readiness-check`, do not reconstruct release notes from `git diff` when curated changelog content already exists, and do not report release success until the commit, tag, and GitHub release all exist for the same version.
 - Output: Produce a versioned release commit and tag, publish a matching GitHub release, and keep changelog plus relevant repository documentation synchronized.
 
@@ -61,8 +61,9 @@ Load only when needed:
    - Resolve all confirmed findings before changing version files, tags, or release metadata.
 4. Run shared submission readiness
    - Execute `$submission-readiness-check` before version file edits, tags, or release publication.
-   - Let it decide whether completed plan sets should be archived, whether project docs or `AGENTS.md` need synchronization, and whether `CHANGELOG.md` `Unreleased` is ready to be cut into a versioned release entry.
+   - Let it decide whether completed plan sets should be converted, whether project docs need alignment through `archive-specs`, and whether `CHANGELOG.md` `Unreleased` is ready to be cut into a versioned release entry.
    - Do not continue while `submission-readiness-check` reports unresolved blockers.
+   - When readiness indicates completed-spec conversion or project-doc drift, run `archive-specs` before version edits instead of reproducing documentation alignment inside the release workflow.
 5. Decide version and tag format
    - Read existing version files (for example `project.toml`, `package.json`, or repo-specific version files).
    - Infer existing tag format (`vX.Y.Z` or `X.Y.Z`) from repository tags.