@laitszkin/apollo-toolkit 2.13.4 → 2.14.1

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [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.
+- Add `merge-changes-from-local-branches` skill for consolidating local branch changes into main.
+
 ## [v2.13.4] - 2026-04-05
 
 ### Changed

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

@@ -0,0 +1,123 @@
+---
+name: implement-specs-with-worktree
+description: >-
+  Read a specs planning set (spec.md, tasks.md, checklist.md, contract.md, design.md)
+  from `docs/plans/{YYYY-MM-DD}_{change_name}/` 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.
+---
+
+# Implement Specs with Worktree
+
+## Dependencies
+
+- Required: `enhance-existing-features` and `develop-new-features` for implementation standards.
+- Conditional: `generate-spec` if spec files need clarification or updates.
+- Optional: none.
+- Fallback: If `enhance-existing-features` or `develop-new-features` is unavailable, stop and report the missing dependency.
+
+## Standards
+
+- Evidence: Read and understand the complete specs set before starting implementation.
+- Execution: Create or use an isolated worktree for implementation, follow the implementation standards from the dependent skills, and commit to a local branch when done.
+- Quality: Complete all planned tasks, run relevant tests, and backfill the spec documents with actual completion status.
+- 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.
+
+## Workflow
+
+### 1) Identify and read the specs set
+
+- Locate the specs directory. The path format is `docs/plans/{YYYY-MM-DD}_{change_name}/`.
+- If the user provides a specific path, use that directly.
+- If only a `change_name` or date is given, search for matching directories under `docs/plans/`.
+- Read all five spec files:
+  - `spec.md` — requirements and BDD behaviors
+  - `tasks.md` — task breakdown
+  - `checklist.md` — behavior-to-test alignment and completion tracking
+  - `contract.md` — API/interface contracts
+  - `design.md` — design decisions and architecture notes
+- Understand the scope, requirements, and planned tasks before proceeding.
+
+### 2) Check current worktree state
+
+- 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`).
+
+### 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:
+  ```bash
+  git branch <branch-name> main
+  ```
+- Add a new worktree:
+  ```bash
+  git worktree add ../<worktree-name> -b <branch-name>
+  ```
+- Move into the new worktree directory and begin work there.
+
+Use branch naming from `references/branch-naming.md`.
+
+### 4) Implement the planned tasks
+
+- Explore the existing codebase relevant to the planned tasks.
+- Verify latest authoritative docs for involved stacks/integrations.
+- Implement each task in `tasks.md` systematically.
+- For each implemented change, add appropriate tests:
+  - Unit tests for changed logic
+  - Regression tests for bug-prone behavior
+  - Property-based tests for business logic changes
+  - Integration tests for cross-module chains
+  - E2E tests for key user-visible paths
+  - Adversarial tests for abuse paths
+- Run relevant tests and fix failures.
+- Do not skip testing even for seemingly small changes.
+
+### 5) Backfill completion status
+
+After implementation and testing:
+
+- Update `spec.md` with actual completion state for each requirement.
+- Mark completed tasks in `tasks.md`.
+- Update `checklist.md` with test execution results, N/A reasons, and any scope adjustments.
+- Do not mark unused template examples or non-applicable items as complete.
+
+### 6) Commit changes
+
+- Stage the implementation files:
+  ```bash
+  git add <implementation-files> <test-files> <updated-specs>
+  ```
+- Write a concise Conventional Commit message describing the implemented scope.
+- Commit to the worktree's local branch:
+  ```bash
+  git commit -m "<conventional-commit-message>"
+  ```
+
+### 7) Report completion
+
+- Summarize what was implemented.
+- Note the branch name and worktree location.
+- Confirm that main remains unaffected.
+
+## Working Rules
+
+- Always work in an isolated worktree to keep main clean.
+- 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.
+- Follow the testing standards from `enhance-existing-features` and `develop-new-features`.
+- Do not push to remote unless the user explicitly requests it.
+
+## References
+
+- `references/branch-naming.md`: branch naming conventions
+- `enhance-existing-features`: implementation standards for brownfield work
+- `develop-new-features`: implementation standards for new feature work

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/implement-specs-with-worktree/references/branch-naming.md

@@ -0,0 +1,16 @@
+# Branch Naming Instructions
+
+Use a short, descriptive branch name in this pattern:
+
+- type/short-description
+- type/issue-id-short-description (if issue ids are used)
+
+Guidelines:
+- Use lowercase letters and hyphens only.
+- Align type with commit message types (feat, fix, docs, chore, refactor, test).
+- Do not rename the current branch unless the user explicitly asks.
+
+Examples:
+- feat/add-rpc-timeouts
+- fix/1234-parse-registry
+- impl/feature-x

package/lib/cli.js

@@ -17,6 +17,7 @@ const TARGET_OPTIONS = [
   { id: 'codex', label: 'Codex', description: '~/.codex/skills' },
   { id: 'openclaw', label: 'OpenClaw', description: '~/.openclaw/workspace*/skills' },
   { id: 'trae', label: 'Trae', description: '~/.trae/skills' },
+  { id: 'agents', label: 'Agents', description: '~/.agents/skills' },
   { id: 'claude-code', label: 'Claude Code', description: '~/.claude/skills' },
 ];
 
@@ -57,7 +58,7 @@ function buildBanner({ version, colorEnabled }) {
   return [
     buildWordmark({ colorEnabled }),
     color('Apollo Toolkit', '1', colorEnabled),
-    color('Install curated skills for Codex, OpenClaw, Trae, and Claude Code', '2', colorEnabled),
+    color('Install curated skills for Codex, OpenClaw, Trae, Agents, and Claude Code', '2', colorEnabled),
     color(`Version ${version}`, '1;33', colorEnabled),
   ].join('\n');
 }
@@ -91,6 +92,7 @@ function buildWelcomeScreen({ version, colorEnabled, stage = 4 }) {
       `  ${color('Codex', '1', colorEnabled)}     ~/.codex/skills`,
       `  ${color('OpenClaw', '1', colorEnabled)}  ~/.openclaw/workspace*/skills`,
       `  ${color('Trae', '1', colorEnabled)}      ~/.trae/skills`,
+      `  ${color('Agents', '1', colorEnabled)}     ~/.agents/skills`,
       `  ${color('Claude Code', '1', colorEnabled)} ~/.claude/skills`,
     );
   }
@@ -120,8 +122,8 @@ function buildHelpText({ version, colorEnabled }) {
     buildBanner({ version, colorEnabled }),
     '',
     'Usage:',
-    '  apltk [install] [codex|openclaw|trae|claude-code|all]...',
-    '  apollo-toolkit [install] [codex|openclaw|trae|claude-code|all]...',
+    '  apltk [install] [codex|openclaw|trae|agents|claude-code|all]...',
+    '  apollo-toolkit [install] [codex|openclaw|trae|agents|claude-code|all]...',
     '  apltk --help',
     '  apollo-toolkit --help',
     '',
@@ -131,6 +133,7 @@ function buildHelpText({ version, colorEnabled }) {
     '  npx @laitszkin/apollo-toolkit',
     '  npx @laitszkin/apollo-toolkit codex openclaw',
     '  npm i -g @laitszkin/apollo-toolkit',
+    '  apltk agents',
     '  apltk claude-code',
     '  apltk all',
     '  apollo-toolkit all',

package/lib/installer.js

@@ -3,7 +3,7 @@ const fsp = require('node:fs/promises');
 const os = require('node:os');
 const path = require('node:path');
 
-const VALID_MODES = ['codex', 'openclaw', 'trae', 'claude-code'];
+const VALID_MODES = ['codex', 'openclaw', 'trae', 'agents', 'claude-code'];
 const COPY_FILES = new Set(['AGENTS.md', 'CHANGELOG.md', 'LICENSE', 'README.md', 'package.json']);
 const COPY_DIRS = new Set(['scripts']);
 
@@ -203,6 +203,17 @@ async function getTargetRoots(modes, env = process.env) {
       continue;
     }
 
+    if (mode === 'agents') {
+      targets.push({
+        mode,
+        label: 'Agents',
+        root: env.AGENTS_SKILLS_DIR
+          ? path.resolve(expandUserPath(env.AGENTS_SKILLS_DIR, env))
+          : path.join(homeDir, '.agents', 'skills'),
+      });
+      continue;
+    }
+
     if (mode === 'openclaw') {
       const openclawHome = env.OPENCLAW_HOME
         ? path.resolve(expandUserPath(env.OPENCLAW_HOME, env))

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

@@ -0,0 +1,131 @@
+---
+name: merge-changes-from-local-branches
+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.
+---
+
+# Merge Changes from Local Branches
+
+## Dependencies
+
+- Required: none (uses native git commands).
+- Conditional: none.
+- Optional: `commit-and-push` if commit message guidance is needed.
+- Fallback: If git operations fail, stop and report the error.
+
+## 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, then verify the merged state.
+- 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 main branch with all local changes integrated.
+
+## Goal
+
+Consolidate all local branch changes into the local main branch with automatic conflict resolution that preserves correct functionality.
+
+## Workflow
+
+### 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
+  - Last commit message (via `git log -1 --oneline`)
+
+### 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
+
+For each local branch (excluding main):
+
+1. Check out main:
+   ```bash
+   git checkout main
+   ```
+
+2. Merge the branch:
+   ```bash
+   git merge <branch-name> --no-ff -m "Merge branch '<branch-name>' into main"
+   ```
+
+3. If conflicts occur, resolve them automatically using these rules:
+   - 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>
+   ```
+
+4. If auto-resolution is ambiguous, prefer the change that:
+   - Does not break existing tests
+   - Preserves the documented feature intent
+   - Aligns with the code currently shipped on the source branch
+   - Minimizes hidden semantic drift between the merged modules
+
+5. Complete the merge:
+   ```bash
+   git commit -m "Merge branch '<branch-name>' into main"
+   ```
+
+### 4) Verify merged state
+
+- 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
+  npm test  # or yarn test, cargo test, etc.
+  ```
+- If verification fails, fix the merged state on `main` before proceeding.
+
+### 5) Commit the merged result
+
+- The merge commits are the submission artifact; do not amend them unless the user explicitly asks for history rewriting.
+- If a follow-up fix is required after verification, create a normal commit on `main` that explains the correction.
+
+### 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.
+- Report the verification commands that were run.
+- Confirm no remote push was performed.
+
+## 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.
+- 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, 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.json dependency conflict | Keep higher version if compatible |

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.13.4",
+  "version": "2.14.1",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",