@laitszkin/apollo-toolkit 2.13.4 → 2.14.0

package/CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+### 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/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,137 @@
+---
+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 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.
+
+## 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.
+- 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 branch.
+- If there are uncommitted changes on main, stash them:
+  ```bash
+  git stash push -m "WIP: temporary stash before branch merging"
+  ```
+
+### 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:
+   - **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:
+   ```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
+   - Keeps more recent bug fixes
+
+5. Complete the merge:
+   ```bash
+   git commit -m "Merge branch '<branch-name>' into main"
+   ```
+
+### 4) Verify merged state
+
+- Run relevant tests to ensure nothing is broken:
+  ```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
+
+The merge commits already serve as commits. If additional staging is needed:
+
+```bash
+git status
+git add -A
+git commit --amend --no-edit  # Amend the last merge commit if needed
+```
+
+### 6) Report completion
+
+- List all branches that were merged.
+- Confirm main is updated with all changes.
+- Note any conflicts that were resolved and the rationale.
+- 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.
+
+## 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 |
+| 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/package.json

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