@laitszkin/apollo-toolkit 2.13.3 → 2.14.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ 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
+- Update `learn-skill-from-conversations` so it must inventory the current repository's existing skills first, weigh repeated user corrections and error-driven lessons more heavily, extract duplicated workflow fragments into shared skills when warranted, wrap repeatedly customized external skills, and keep project-specific tooling patterns in the owning project's `~/.codex/skills/`.
+
+### Fixed
+- Synchronize `package-lock.json` metadata with the current package version and CLI bin aliases before release publication.
+
 ## [v2.13.3] - 2026-04-05
 
 ### Removed

package/codex/learn-skill-from-conversations/README.md

@@ -10,7 +10,12 @@ This skill extracts the latest conversations from `~/.codex/sessions` and `~/.co
 - Stops immediately when there are no recent sessions
 - Cleans up `sessions` files older than 7 days after reading
 - Deletes `archived_sessions` files after reading them
+- Reads existing skills in the current working repository before proposing new ones
+- Prioritizes repeated user corrections, reported errors, tool failures, and reusable workflow gaps
+- Encourages extracting duplicated workflow fragments into shared skills when several skills need the same pattern
+- Wraps repeatedly customized external skills in a local skill when that produces a more reusable workflow
 - Defaults to creating a new skill unless strong overlap is confirmed
+- Keeps project-specific tool workflows out of the shared catalog and places them in the relevant project's `~/.codex/skills/`
 - Validates each changed skill with `quick_validate.py`
 
 ## Project Structure
@@ -40,7 +45,7 @@ python3 scripts/extract_recent_conversations.py --lookback-minutes 1440
 ```
 
 - If output is `NO_RECENT_CONVERSATIONS`, no action is required.
-- Otherwise, review extracted `[USER]` / `[ASSISTANT]` messages and apply updates through `skill-creator`.
+- Otherwise, review extracted `[USER]` / `[ASSISTANT]` messages, compare the lessons against existing skills in the current repository, and apply updates through `skill-creator`.
 
 ## License
 

package/codex/learn-skill-from-conversations/SKILL.md

@@ -15,9 +15,9 @@ description: Learn and evolve the local skill library from recent Codex conversa
 ## Standards
 
 - Evidence: Extract recent Codex session history first and derive reusable lessons only from actual conversation patterns.
-- Execution: Inventory the current skill catalog before editing, prioritize repeated requests, user corrections, reported errors, and post-completion follow-up asks that reveal missing closure, then prefer a focused update to the strongest related skill or create a new skill only when the overlap is weak.
-- Quality: Take no action when there are no recent sessions, avoid unrelated broad refactors, and validate every changed skill.
-- Output: Report the analyzed sessions, extracted lessons, created or updated skills, and the reasoning behind each decision.
+- Execution: Inventory the current working directory's existing skills before editing, prioritize repeated requests, user corrections, tool failures, logic bugs, architecture mismatches, documentation drift, and post-completion follow-up asks that reveal missing closure, then prefer a focused update to the strongest related skill or create a new skill only when the overlap is weak.
+- Quality: Take no action when there are no recent sessions, avoid unrelated broad refactors, keep shared skills cross-project reusable, route project-specific tooling patterns into the relevant project's `~/.codex/skills/`, and validate every changed skill.
+- Output: Report the analyzed sessions, extracted lessons, created or updated skills, shared-vs-project-specific placement decisions, and the reasoning behind each decision.
 
 ## Overview
 
@@ -46,10 +46,15 @@ python3 ~/.codex/skills/learn-skill-from-conversations/scripts/extract_recent_co
 ### 2) Derive reusable lessons
 
 - Identify repeated user needs, recurring friction, and repeated manual workflows.
+- Focus especially on repeated needs, repeated user corrections, and user-reported errors, then ask how a skill can prevent the same failure mode from recurring.
 - Give extra weight to moments where the user corrected the agent, rejected an earlier interpretation, or pointed out a missing preference or requirement.
 - Give extra weight to user-reported errors, regressions, or avoidable mistakes, then ask how a skill can prevent repeating that failure mode.
+- Treat tool-call failures, broken code paths, logic mistakes, weak architecture choices, and outputs that drifted from official documentation as valuable evidence when they expose a reusable missing guardrail or workflow.
 - Treat a user follow-up that asks for cleanup or an omitted finalization step immediately after the assistant reported completion as evidence that the workflow's done criteria were incomplete.
 - When that kind of follow-up recurs, tighten the owning skill's completion checklist before considering any new-skill extraction.
+- Even when a user request was highly specific, check whether the underlying workflow can be generalized into a reusable skill for the same class of tasks.
+- When multiple existing skills use a near-identical workflow fragment, consider extracting that fragment into a dedicated shared skill instead of leaving the duplication in place.
+- When an external skill is repeatedly used with the same user-specific customization layer, prefer wrapping it in a new local skill that encodes those standing conventions.
 - Ignore one-off issues that do not provide reusable value.
 - Distinguish between:
   - repeated trigger intent that deserves a new skill
@@ -58,7 +63,7 @@ python3 ~/.codex/skills/learn-skill-from-conversations/scripts/extract_recent_co
 
 ### 3) Decide new skill vs existing skill (default: new skill)
 
-- First read the relevant skills already present in the working repository so you do not create a duplicate under a different name.
+- First read the relevant skills already present in the current working directory repository (for example `apollo-toolkit`) so you do not create a duplicate under a different name.
 - Prefer creating a new skill.
 - Edit an existing skill only when the lesson is strongly related.
 - Treat relation as strong only when all three conditions hold:
@@ -67,12 +72,17 @@ python3 ~/.codex/skills/learn-skill-from-conversations/scripts/extract_recent_co
   - The update does not dilute the existing skill's scope.
 - When the recurring lesson is mainly about preventing a known mistake, prefer updating the existing skill that should have prevented it instead of creating a parallel skill.
 - When several skills repeat the same narrow workflow fragment, prefer extracting that fragment into a dedicated shared skill instead of copying the same guidance again.
+- When the strongest candidate is an external skill but the user repeatedly adds the same customization or policy layer, create a wrapper skill that calls that external skill while encoding the recurring local conventions.
+- Decide whether the lesson is cross-project reusable before choosing the destination:
+  - Cross-project reusable skills belong in the shared skill library.
+  - Project-specific workflows, especially ones tied to custom tools from a single repository, belong in that project's `~/.codex/skills/` directory instead of the shared catalog.
 - If uncertain, create a new skill instead of expanding an old one.
 
 ### 4) Apply changes through skill-creator
 
 - Explicitly follow `$skill-creator` workflow before editing skills.
-- For new skills, initialize with `~/.codex/skills/.system/skill-creator/scripts/init_skill.py`, then complete `SKILL.md` and required resources.
+- For new shared skills, initialize with `~/.codex/skills/.system/skill-creator/scripts/init_skill.py`, then complete `SKILL.md` and required resources.
+- For new project-specific skills, create or update them under the relevant project's `~/.codex/skills/` directory instead of the shared catalog.
 - For existing skills, make minimal focused edits and keep behavior consistent.
 
 ### 5) Validate every changed skill
@@ -87,10 +97,11 @@ python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py <skill-p
 
 ### 6) Report result
 
-- Summarize analyzed sessions, repeated needs, user corrections, error-driven lessons, created/updated skills, and why each decision was made.
+- Summarize analyzed sessions, repeated needs, user corrections, error-driven lessons, created/updated skills, placement decisions, and why each decision was made.
 
 ## Guardrails
 
 - Take no action when there are no sessions in the last 24 hours.
 - Avoid broad refactors across unrelated skills.
 - Avoid duplicate skills when an existing skill is strongly related.
+- Do not promote project-specific tool usage into the shared catalog unless the workflow is clearly reusable across repositories.

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