@laitszkin/apollo-toolkit 2.14.12 → 2.14.14

package/AGENTS.md

@@ -34,6 +34,7 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can run a shared submission-readiness pass that synchronizes changelog, project docs, `AGENTS.md`, and completed plan archives before commit, push, PR creation, or release.
 - Users can learn new or improved skills from recent Codex conversation history.
 - Users can audit and maintain the skill catalog itself, including dependency classification and shared-skill extraction decisions.
+- Users can implement approved spec planning sets directly in the current checkout and commit them to the active branch.
 - Users can summarize mistakes into separate multiple-choice and long-answer error books backed by structured reference files and rendered PDFs.
 - Users can build or review marginfi protocol integrations using official SDK, CLI, protocol, and The Arena documentation.
 - Users can create or maintain `AGENTS.md` so project constraints stay aligned with the repository.

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.14.14] - 2026-04-11
+
+### Changed
+- Tighten `commit-and-push` so it must distinguish staged versus unstaged work before choosing commit scope, preserve intentionally separated commit boundaries, and only broaden scope after an explicit user request.
+- Update `learn-skill-from-conversations` so repeated follow-ups that correct commit scope or local-versus-remote submission boundaries are treated as evidence to harden the owning submit workflow.
+
+## [v2.14.13] - 2026-04-10
+
+### Added
+- Add `implement-specs` for executing approved spec sets directly in the current checkout without creating a branch or git worktree.
+
 ## [v2.14.12] - 2026-04-10
 
 ### Changed

package/README.md

@@ -22,6 +22,7 @@ A curated skill catalog for Codex, OpenClaw, Trae, and Claude Code with a manage
 - read-github-issue
 - generate-spec
 - harden-app-security
+- implement-specs
 - improve-observability
 - jupiter-development
 - katex

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

@@ -15,7 +15,7 @@ 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 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; when a Codex automation prompt includes an explicit `Automation memory:` path, treat that path as the authoritative run-memory location instead of assuming `$CODEX_HOME` is available in the shell.
+- 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; treat repeated scope-correction follow-ups around staged versus unstaged work, local-commit versus push boundaries, and similar submission-scope misunderstandings as signals to tighten the owning submit workflow instead of inventing a parallel skill; when a Codex automation prompt includes an explicit `Automation memory:` path, treat that path as the authoritative run-memory location instead of assuming `$CODEX_HOME` is available in the shell.
 - 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.
 
@@ -53,6 +53,7 @@ python3 ~/.codex/skills/learn-skill-from-conversations/scripts/extract_recent_co
 - 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.
+- Treat a user follow-up that changes commit scope after the assistant already inferred a narrower or broader submission boundary as evidence that the relevant submit workflow needs clearer staged-versus-unstaged and local-versus-remote boundary rules.
 - 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.

package/commit-and-push/SKILL.md

@@ -14,10 +14,10 @@ description: "Guide the agent to submit local changes with commit and push only
 
 ## 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 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.
+- 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, while also distinguishing the staged surface from additional unstaged work before deciding commit scope.
+- 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; when the user asks for multiple commits or a narrower staged subset, keep those commit boundaries explicit instead of broadening scope implicitly; 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, do not bypass blocking readiness findings such as missing/stale `Unreleased` bullets or unsynchronized project docs, and never collapse intentionally separated commit scopes just because related unstaged changes are present.
+- Output: Produce a concise Conventional Commit, push it to the intended branch, and report any temporary stash/restore, commit-scope separation, or local branch sync that was required.
 
 ## Overview
 
@@ -35,6 +35,7 @@ Load only when needed:
 1. Inspect current state
    - Run `git status -sb`, `git diff --stat`, and `git diff --cached --stat`.
    - Check staged files with `git diff --cached --name-only`.
+   - Compare the staged and unstaged surfaces explicitly so you can tell whether the user already prepared a narrower commit than the full worktree diff.
    - Inventory repository planning artifacts and project docs, not only staged files, to detect repo specs and non-standard documentation layouts.
    - If the worktree is already clean, inspect `git log -1 --stat`, local `HEAD`, and the configured upstream state before concluding there is nothing to submit; use that evidence to determine whether the requested work was already committed and pushed, committed but not pushed, or never landed.
 2. Classify changes
@@ -68,6 +69,8 @@ Load only when needed:
    - 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.
+   - If the user explicitly asks for separate commits, or the staged set is already a deliberate subset of the worktree, keep those scopes separated and do not auto-stage the remaining diff unless the user expands the requested scope.
+   - If the user later broadens the requested scope, restate the new grouping, verify it against the actual staged/unstaged surfaces, and only then create the additional commit(s).
    - Write a concise Conventional Commit message using `references/commit-messages.md`.
 7. Push
    - Push commit(s) to the intended branch.
@@ -86,6 +89,7 @@ Load only when needed:
 - Never claim the repository is ready to commit while root `CHANGELOG.md` `Unreleased` is missing the current change or still describes superseded work.
 - Never fabricate a commit/push result when the worktree is already clean; either identify the exact existing commit/upstream state that satisfies the user's request or say that no matching new submission exists.
 - Never delete a temporary worktree before the target branch has been updated, tested, and verified to contain the intended final content.
+- Never auto-stage or auto-merge unrelated unstaged changes into a commit when the user or current index state already defines narrower commit boundaries.
 - If release/version/tag work is requested, use `version-release` instead.
 - If a new branch is required, follow `references/branch-naming.md`.
 - A pushed implementation can still leave an active spec set behind; commit completion and spec archival are separate decisions.

package/implement-specs/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: implement-specs
+description: >-
+  Read a specs planning set (spec.md, tasks.md, checklist.md, contract.md, design.md)
+  from `docs/plans/{YYYY-MM-DD}/{change_name}/` or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/`
+  plus parent `coordination.md` when present, and implement the approved tasks
+  directly in the current checkout. Use when the user asks to implement from an
+  existing spec set, execute a spec plan, or complete approved planning work
+  without creating a new branch or isolated git worktree. Commit the completed
+  implementation to the current branch when done.
+---
+
+# Implement Specs
+
+## Dependencies
+
+- Required: `enhance-existing-features` and `develop-new-features` for implementation standards.
+- Conditional: `generate-spec` if spec files need clarification or updates; `recover-missing-plan` if the requested plan path is missing from the current checkout.
+- 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, and when the requested plan path is missing verify where the authoritative copy actually lives before substituting any nearby spec.
+- Execution: Work directly in the current checkout, do not create or switch branches, do not add git worktrees, follow the implementation standards from the dependent skills, and commit to the current 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 scope just because they share a batch directory.
+- Output: Leave the current branch with a focused implementation commit containing only the intended changes.
+
+## Goal
+
+Implement approved spec planning sets directly in the current checkout when the user wants the work to land on the active branch instead of an isolated implementation branch.
+
+## Workflow
+
+### 1) Identify and read the specs set
+
+- Locate the specs directory. The path format is `docs/plans/{YYYY-MM-DD}/{change_name}/` for single-spec work, or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` for coordinated multi-spec work.
+- 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/`.
+- If the requested path is absent from the current checkout, stop and identify the authoritative source before implementing:
+  - inspect the repository history and relevant local branches for that exact `docs/plans/...` path
+  - use `recover-missing-plan` when the plan must be restored or reconstructed before work can continue
+  - prefer the exact matching plan directory from the authoritative branch or main working tree over archived, approximate, or sibling plan directories
+  - if the plan lives under a batch directory, recover only the requested spec directory plus the shared `coordination.md` that governs it
+  - do not copy neighboring sibling spec directories into scope unless the user explicitly expands scope
+- When the plan sits under a batch directory, also read the sibling `coordination.md` before implementation.
+- 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
+- If `coordination.md` exists in the parent batch directory, read it as the shared source of truth for ownership boundaries, shared preparation, replacement direction, merge order, and cross-spec integration checkpoints.
+- Understand the scope, requirements, and planned tasks before proceeding.
+
+### 2) Check current branch state
+
+- Run `git status -sb` and identify the current branch.
+- Preserve unrelated user changes. If the checkout contains unrelated dirty files, avoid editing them and report any blockers before proceeding.
+- Confirm that the current branch is the intended destination for the implementation. Do not create, rename, or switch branches unless the user explicitly changes scope.
+- If the exact requested plan was recovered into the current checkout, re-read the recovered files before coding so implementation and backfill use the same plan snapshot.
+
+### 3) Implement the planned tasks
+
+- Explore the existing codebase relevant to the planned tasks.
+- Verify latest authoritative docs for involved stacks/integrations.
+- When `coordination.md` exists, respect its shared-field preparation, legacy-replacement direction, and allowed touch-point boundaries before editing.
+- Implement each task in `tasks.md` systematically.
+- When `coordination.md` defines file ownership guardrails, additive-only shared-contract rules, or compatibility-shim retention requirements, treat them as blocking execution constraints rather than optional guidance.
+- 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.
+
+### 4) 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.
+- If the shared implementation direction changed, update the parent `coordination.md` as well before finishing.
+- Do not mark unused template examples or non-applicable items as complete.
+
+### 5) 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 current branch:
+  ```bash
+  git commit -m "<conventional-commit-message>"
+  ```
+
+### 6) Report completion
+
+- Summarize what was implemented.
+- Note the current branch and commit hash.
+- Confirm which tests ran and which planned documents were backfilled.
+
+## Working Rules
+
+- Always work in the current checkout; never create a branch or git worktree inside this skill unless the user explicitly changes the request.
+- 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.
+- Never remove a shared shim, rename a shared field, or rewrite a shared file outside the ownership map unless `coordination.md` explicitly allows that change or the user approves a coordination update first.
+- Follow the testing standards from `enhance-existing-features` and `develop-new-features`.
+- Do not push to remote unless the user explicitly requests it.
+
+## References
+
+- `enhance-existing-features`: implementation standards for brownfield work
+- `develop-new-features`: implementation standards for new feature work
+- `recover-missing-plan`: recovery workflow for missing or mismatched spec sets

package/implement-specs/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Implement Specs"
+  short_description: "Implement approved specs in the current checkout"
+  default_prompt: "Use $implement-specs to read the full plan set under docs/plans, including parent coordination.md when the spec belongs to a parallel batch, implement all approved tasks in the current checkout without creating branches or git worktrees, backfill completion status into the planning docs, and commit the result to the current branch."

package/package.json

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