@laitszkin/apollo-toolkit 3.4.1 → 3.6.0

package/AGENTS.md

@@ -39,6 +39,8 @@ This repository enables users to install and run a curated set of reusable agent
 - 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 implement approved spec planning sets inside isolated git worktrees and keep the parent checkout clean.
+- Users can coordinate approved multi-spec implementation batches by assigning each spec directory to an independent worktree-backed subagent with bounded concurrency.
 - 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.
@@ -50,6 +52,7 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can record multi-account spending and balance changes in monthly Excel ledgers with summary analytics and charts.
 - Users can recover missing or archived `docs/plans/...` spec sets from issue context, git history, and repository evidence before continuing feature work.
 - Users can review the current git change set from an unbiased reviewer perspective to find abstraction opportunities and simplification candidates.
+- Users can review recent or user-specified spec-backed changes against the governing planning documents, treating unmet business goals as the most severe findings before secondary edge-case, security, and code-review checks.
 - Users can process GitHub pull request review comments and resolve addressed threads.
 - Users can perform repository-wide code reviews and publish confirmed findings as GitHub issues.
 - Users can schedule a bounded project runtime window, stop it automatically, and analyze module health from captured logs.

package/CHANGELOG.md

@@ -7,6 +7,22 @@ All notable changes to this repository are documented in this file.
 ### Added
 - (None yet)
 
+## [v3.6.0] - 2026-04-28
+
+### Added
+- Add `review-spec-related-changes`, a spec-compliance review skill that checks recent or named planning documents against implementation evidence and treats unmet business goals as the most severe findings before secondary edge-case, security, and code-review checks.
+
+### Changed
+- Remove the post-merge code-review gate from `merge-changes-from-local-branches` so spec-related review now lives in the dedicated `review-spec-related-changes` skill.
+
+## [v3.5.0] - 2026-04-28
+
+### Added
+- Add `implement-specs-with-subagents`, a coordinator skill that assigns each approved spec directory to an independent worktree-backed subagent with staggered starts and a maximum of four active implementation agents.
+
+### Changed
+- Tighten `generate-spec` so current templates remain the binding format even when older project specs use different layouts.
+
 ## [v3.4.1] - 2026-04-28
 
 ### Changed

package/README.md

@@ -23,6 +23,8 @@ A curated skill catalog for Codex, OpenClaw, Trae, Agents, and Claude Code with
 - generate-spec
 - harden-app-security
 - implement-specs
+- implement-specs-with-subagents
+- implement-specs-with-worktree
 - improve-observability
 - iterative-code-performance
 - iterative-code-quality
@@ -43,6 +45,7 @@ A curated skill catalog for Codex, OpenClaw, Trae, Agents, and Claude Code with
 - resolve-review-comments
 - review-change-set
 - review-codebases
+- review-spec-related-changes
 - scheduled-runtime-health-check
 - shadow-api-model-research
 - solana-development
@@ -196,9 +199,11 @@ The install commands below were checked with the Skills CLI unless otherwise not
 Compatibility note:
 
 - `generate-spec` is a local skill used by `develop-new-features` and `enhance-existing-features`, and it can produce either a single spec set under `docs/plans/{YYYY-MM-DD}/{change_name}/` or a coordinated parallel batch under `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` with shared `coordination.md`.
+- `implement-specs-with-subagents` coordinates one `implement-specs-with-worktree` subagent per spec directory for approved multi-spec batches, with staggered launches and a maximum of four active implementation subagents.
 - `recover-missing-plan` is a local skill used by `enhance-existing-features` and `ship-github-issue-fix` when a referenced `docs/plans/...` spec set is missing or archived.
 - `maintain-skill-catalog` can conditionally use `find-skills`, but its install source is not verified in this repository, so it is intentionally omitted from the table.
 - `read-github-issue` uses GitHub CLI (`gh`) directly for remote issue discovery and inspection, so it does not add any extra skill dependency.
+- `review-spec-related-changes` is a local skill that depends on `review-change-set`, `discover-edge-cases`, and `harden-app-security` for secondary code-practice checks after business-goal completion is reviewed against the governing specs.
 
 ## Release publishing
 

package/generate-spec/SKILL.md

@@ -15,8 +15,8 @@ description: Generate and maintain shared feature planning artifacts (`spec.md`,
 ## Standards
 
 - Evidence: Review the relevant code, configs, and authoritative docs before filling requirements or test plans; when external dependencies, libraries, frameworks, APIs, or platforms are involved, checking their official documentation is mandatory during spec creation.
-- Execution: Generate the planning files first, keep each spec set tightly scoped, split broader work into multiple independent spec sets when needed, ensure every batch spec is independently completable and truly parallel-implementable without depending on another spec set to land first, surface shared-file or shared-contract collision risks during planning, resolve those coordination rules before implementation starts, complete them with traceable requirements and risks, handle clarification updates, then wait for explicit approval before implementation.
-- Quality: Keep `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` synchronized, use `test-case-strategy` to map each planned test to a concrete risk or requirement, and tailor the templates so only applicable items remain active.
+- Execution: Generate the planning files from this skill's current templates first, keep each spec set tightly scoped, split broader work into multiple independent spec sets when needed, ensure every batch spec is independently completable and truly parallel-implementable without depending on another spec set to land first, surface shared-file or shared-contract collision risks during planning, resolve those coordination rules before implementation starts, complete them with traceable requirements and risks, handle clarification updates, then wait for explicit approval before implementation.
+- Quality: Keep `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` synchronized, use `test-case-strategy` to map each planned test to a concrete risk or requirement, preserve the actual headings and field structure from this skill's templates, and tailor the templates so only applicable items remain active.
 - Output: Store planning artifacts under `docs/plans/{YYYY-MM-DD}/{change_name}/` for single-spec work, or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` plus `coordination.md` for multi-spec parallel work whose member specs remain independently approvable, independently implementable, and ready for concurrent worktree execution with pre-agreed collision rules, and keep them concise, executable, and easy to update.
 
 ## Goal
@@ -36,6 +36,8 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Inspect existing `docs/plans/` directories before deciding whether to edit an existing plan set.
 - Reuse an existing plan set only when it clearly matches the same requested issue/change scope.
 - If the requested work is adjacent to, but not actually covered by, an existing plan set, create a new directory instead of overwriting the neighboring one.
+- Treat existing or archived project-local specs as scope evidence only, not as formatting authority.
+- Do not copy older spec layouts, condensed repo conventions, or neighboring plan structures when they differ from this skill's current templates.
 
 ### 2) Generate the planning files
 
@@ -63,6 +65,8 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
   - `references/templates/design.md`
 - Generate `references/templates/coordination.md` at the batch root when multiple spec sets are intentionally created for parallel implementation.
 - Save files under `docs/plans/{YYYY-MM-DD}/{change_name}/` or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/`.
+- After generation, fill the files in place without renaming, removing, or collapsing template headings unless a heading is explicitly template-only and not applicable to the real scope.
+- Before approval, compare the drafted files against the current template headings and required fields; fix any drift caused by following older project examples.
 
 ### 3) Fill `spec.md`
 
@@ -174,6 +178,8 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Use kebab-case for `change_name`; avoid spaces and special characters.
 - Path rule: `scripts/...` and `references/...` in this file always mean paths under the current skill folder, not the target project root.
 - Never overwrite a nearby issue's plan set just because the technical area overlaps; shared modules are not sufficient evidence that the scope is the same.
+- Template authority rule: the current `references/templates/*.md` files in this skill are the binding format for new or refreshed spec documents. Older `docs/plans/...` files may inform scope, terminology, and historical decisions, but they must not override the current template structure.
+- Before presenting specs for approval, run a template-drift pass: verify the expected template sections are present, remove stale placeholder examples, and ensure any removed section has a scope-based reason rather than being omitted because an older project spec omitted it.
 
 ## References
 

package/generate-spec/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "generate-spec"
   short_description: "Generate shared feature spec, task, and checklist docs before coding"
-  default_prompt: "Use $generate-spec to create or update single-spec plans under docs/plans/<date>/<change_name>/ or parallel batches under docs/plans/<date>/<batch_name>/<change_name>/ with a shared coordination.md, but ensure every spec in a batch remains independently approvable, independently implementable, and safe for true parallel execution without depending on another batch spec landing first; surface shared-file or shared-contract collision risks during planning, settle ownership and additive-only rules in coordination.md before implementation starts, fill BDD requirements, use $test-case-strategy for risk-driven test planning and unit drift checks, make tasks.md an atomic implementation queue with concrete outputs and verification hooks, document external dependency contracts in contract.md when they materially constrain the change, write the architecture/design delta in design.md, process clarification updates, and wait for explicit approval before implementation."
+  default_prompt: "Use $generate-spec to create or update single-spec plans under docs/plans/<date>/<change_name>/ or parallel batches under docs/plans/<date>/<batch_name>/<change_name>/ with a shared coordination.md, treating this skill's current references/templates/*.md files as the binding format even when older project specs use different layouts; ensure every batch spec remains independently approvable, independently implementable, and safe for true parallel execution without depending on another batch spec landing first; surface shared-file or shared-contract collision risks during planning, settle ownership and additive-only rules in coordination.md before implementation starts, fill BDD requirements, use $test-case-strategy for risk-driven test planning and unit drift checks, make tasks.md an atomic implementation queue with concrete outputs and verification hooks, document external dependency contracts in contract.md when they materially constrain the change, write the architecture/design delta in design.md, process clarification updates, and wait for explicit approval before implementation."

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

@@ -0,0 +1,122 @@
+---
+name: implement-specs-with-subagents
+description: >-
+  Coordinate parallel implementation of multiple approved spec sets by assigning
+  each `docs/plans/.../<change_name>/` spec directory to a separate subagent that
+  uses `implement-specs-with-worktree`. Use when a user asks to implement a
+  multi-spec batch with subagents, parallel agents, delegated agents, or isolated
+  workers while keeping at most four implementation subagents active at once,
+  staggering starts to avoid rate-limit bursts, preserving independent subagent
+  contexts, and using the user's requested model when specified.
+---
+
+# Implement Specs with Subagents
+
+## Dependencies
+
+- Required: `implement-specs-with-worktree` for each delegated spec implementation.
+- Conditional: `generate-spec` if the batch needs clarification before implementation; `review-change-set` if the user asks for an integration review after subagents finish.
+- Optional: none.
+- Fallback: If the environment cannot start independent subagents, report that limitation and fall back only if the user explicitly approves serial `implement-specs-with-worktree` execution.
+
+## Standards
+
+- Evidence: Read the batch-level `coordination.md` when present, enumerate the exact spec directories to implement, and verify each delegated spec has the required planning files before starting subagents.
+- Execution: Assign exactly one implementation subagent per spec directory, keep no more than four implementation subagents active at the same time, start subagents one at a time rather than in a burst, give each subagent an independent task-local context, and instruct every subagent to use `implement-specs-with-worktree` for its assigned spec.
+- Quality: Preserve spec ownership boundaries, avoid duplicate delegation for the same spec, track branch/worktree/commit/test outcomes for every subagent, and pause new launches when a shared blocker, collision, or rate-limit pressure appears.
+- Output: Return a concise implementation ledger covering each spec, its subagent result, worktree branch, commit or blocker, verification run, and any integration follow-up needed.
+
+## Goal
+
+Coordinate a multi-spec implementation batch safely by delegating each approved spec set to an isolated subagent-backed worktree implementation.
+
+## Workflow
+
+### 1) Identify the batch and implementation queue
+
+- Locate the requested batch under `docs/plans/{YYYY-MM-DD}/{batch_name}/`.
+- Read `coordination.md` first when it exists.
+- Enumerate only the spec directories that are in scope for this request.
+- For each spec directory, verify the presence of:
+  - `spec.md`
+  - `tasks.md`
+  - `checklist.md`
+  - `contract.md`
+  - `design.md`
+- Do not delegate archived, sibling, or approximate specs unless the user explicitly includes them.
+- If `coordination.md` says the batch is not ready for parallel implementation, stop and report the blocking coordination item instead of spawning subagents.
+
+### 2) Build a delegation plan
+
+- Create one queue item per spec directory.
+- Assign one subagent to one spec only; never ask one subagent to implement multiple spec directories.
+- Keep a visible ledger with:
+  - spec path
+  - intended branch/worktree name if known
+  - assigned subagent
+  - status
+  - commit
+  - tests
+  - blockers
+- Determine the model policy before launch:
+  - If the user specifies a model, use that model for the implementation subagents when the environment supports model selection.
+  - If the user does not specify a model, let subagents use the same model or default model policy as the coordinating agent.
+  - If the environment does not expose model selection, state that the requested model cannot be enforced and continue only when the platform's default subagent model is acceptable.
+
+### 3) Launch subagents gradually
+
+- Maintain a maximum of four active implementation subagents at any time.
+- Start subagents independently and one at a time.
+- After each start, confirm that the subagent was accepted or is running before starting the next one.
+- If a start fails due to throttling, rate limits, capacity, or platform pressure, wait before retrying and do not start additional subagents during the cooldown.
+- Prefer steady scheduling over maximum burst parallelism; four is the ceiling, not a target that must always be filled.
+
+### 4) Give each subagent independent context
+
+For each subagent, provide only task-local instructions:
+
+- Repository root.
+- Exact spec directory path.
+- Parent `coordination.md` path when present.
+- Requirement to use `implement-specs-with-worktree`.
+- Requirement to read the full spec bundle before editing.
+- Requirement to implement inside its own isolated worktree.
+- Requirement to run relevant tests.
+- Requirement to backfill the spec documents after implementation.
+- Requirement to commit locally unless the user explicitly changes the completion boundary.
+- Requirement to report branch, worktree path, commit hash, tests, and blockers.
+
+Do not pass the coordinating agent's full reasoning, unrelated sibling specs, or other subagents' private work unless a concrete coordination conflict requires it.
+
+### 5) Monitor and coordinate
+
+- While subagents run, track completions and blockers in the ledger.
+- When one subagent finishes, record its branch, worktree path, commit, verification results, and changed ownership boundaries.
+- Start the next queued spec only when the active count drops below four and no shared blocker is unresolved.
+- If two subagents report overlapping edits to a shared file or contract, pause new launches, inspect the conflict against `coordination.md`, and resolve the ownership question before continuing.
+- If a subagent fails for a spec-local issue, keep other independent subagents running, but do not launch additional work that depends on the failed scope.
+- If failures indicate a batch-wide planning defect, stop scheduling new subagents and report the defect.
+
+### 6) Finish the batch report
+
+- Do not merge branches, archive specs, push, or release unless the user explicitly requests that follow-up.
+- Summarize every spec outcome from the ledger.
+- Distinguish completed local commits from blocked or partial specs.
+- Report any integration review, merge order, or post-merge validation required by `coordination.md`.
+
+## Working Rules
+
+- One spec directory maps to one implementation subagent.
+- Maximum active implementation subagents: four.
+- Subagents must be started gradually, not all at once.
+- Every subagent must have independent context scoped to its assigned spec.
+- Every implementation subagent must use `implement-specs-with-worktree`.
+- The coordinating agent owns scheduling, ledger tracking, and conflict escalation; implementation subagents own their assigned worktree commits.
+- User-specified subagent model choices should be honored when supported; otherwise inherit the coordinating agent's model/default model policy.
+- Do not use this skill for a single spec unless the user explicitly wants subagent delegation.
+
+## References
+
+- `implement-specs-with-worktree`: required per-spec worktree implementation workflow.
+- `generate-spec`: clarification and planning repair workflow when a batch is not ready for parallel implementation.
+- `review-change-set`: optional post-implementation review workflow before merge or submission.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Implement Specs with Subagents"
+  short_description: "Coordinate parallel spec worktree implementations"
+  default_prompt: "Use $implement-specs-with-subagents to assign each approved docs/plans spec directory to one independent subagent that uses $implement-specs-with-worktree, launch at most four implementation subagents at once with staggered starts, honor any requested model when supported, track each branch, commit, test result, and blocker, and report the batch ledger without merging or pushing unless explicitly requested."

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

@@ -5,21 +5,18 @@ description: >-
   into the current local 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). After merge verification,
-  require `review-change-set` to review the merged code and confirm it still
-  matches the active spec documents before any submission workflow continues.
-  Run `archive-specs` only after that review gate passes so completed plan sets
-  are archived and durable project docs are synchronized, then hand the current
-  branch state to `commit-and-push` so the final submit workflow commits and
-  pushes on that same local branch. Use when the user asks to consolidate local
-  branch work, merge named branches into the current branch, or prepare the
-  current branch for integration.
+  run `archive-specs` so completed plan sets are archived and durable project
+  docs are synchronized, then hand the current branch state to `commit-and-push`
+  so the final submit workflow commits and pushes on that same local branch.
+  Use when the user asks to consolidate local branch work, merge named branches
+  into the current branch, or prepare the current branch for integration.
 ---
 
 # Merge Changes from Local Branches
 
 ## Dependencies
 
-- Required: `review-change-set` to review the merged code and confirm spec alignment before submission, `archive-specs` to archive completed plan sets and synchronize durable project docs after the review gate passes, and `commit-and-push` for the final current-branch submission flow.
+- Required: `archive-specs` to archive completed plan sets and synchronize durable project docs after merge verification, and `commit-and-push` for the final current-branch submission flow.
 - Conditional: none.
 - Optional: none.
 - Fallback: If git operations fail, stop and report the error.
@@ -27,7 +24,7 @@ description: >-
 ## Standards
 
 - Evidence: Inspect the original current branch, local branches, branch-name matches provided by the user or active spec names, actual conflicting files, and any active batch-spec `coordination.md` merge-order guidance before deciding what to merge.
-- Execution: Merge only the relevant named branches back into the original current branch, read any active batch-spec `coordination.md` and honor its documented merge order when present, resolve conflicts by reading both sides and editing the merged result to preserve shipped behavior, verify the merged state, run `review-change-set` to confirm the merged code still matches the active spec documents, delete each successfully merged source branch and its detached worktree only after the merged result is confirmed, run `archive-specs` only after the review gate passes so completed plan sets are archived and durable docs are synchronized, then hand the final current-branch state to `commit-and-push` so changelog/readiness/commit/push work happens through the shared submission workflow on the same branch.
+- Execution: Merge only the relevant named branches back into the original current branch, read any active batch-spec `coordination.md` and honor its documented merge order when present, resolve conflicts by reading both sides and editing the merged result to preserve shipped behavior, verify the merged state, delete each successfully merged source branch and its detached worktree only after the merged result is confirmed, run `archive-specs` after merge verification so completed plan sets are archived and durable docs are synchronized, then hand the final current-branch state to `commit-and-push` so changelog/readiness/commit/push work happens through the shared submission workflow on the same branch.
 - Quality: Never use blanket timestamp rules or default `-X ours/theirs` conflict resolution as the primary merge strategy, never infer in-scope branches from ancestry heuristics when branch names already define the target set, and do not declare success until the final current-branch state has been checked, verified, and cleared for post-merge archival/doc-sync work.
 - Output: Produce a clean current branch with all relevant named-branch changes integrated and ready for the shared submit workflow.
 
@@ -118,16 +115,9 @@ For each in-scope named branch:
   ```
 - If verification fails, fix the merged state on the current branch before proceeding.
 
-### 4.5) Review the merged change set before submission
-
-- After merge verification passes, invoke `review-change-set` on the merged current branch.
-- Compare the merged code against the active spec documents and any relevant `docs/plans/` artifacts that governed the merge.
-- Do not proceed to archival or submission until the review returns no actionable findings and the merged state is confirmed to match the spec documents.
-- If review finds a problem or spec mismatch, fix the current branch, rerun verification, and review again before continuing.
-
 ### 5) Archive completed specs and sync durable project docs
 
-- After all in-scope merges succeed, the current-branch state has been verified, and `review-change-set` has confirmed the merged code matches the spec documents, invoke `archive-specs`.
+- After all in-scope merges succeed and the current-branch state has been verified, invoke `archive-specs`.
 - Let `archive-specs` convert and archive any completed `docs/plans/...` spec sets that now reflect the delivered outcome.
 - Let `archive-specs` synchronize durable project docs and `AGENTS.md` when the merged result changed operator workflows, repository guidance, or user-visible behavior.
 - Do not proceed to the final submission commit while required archival or documentation updates remain unfinished.
@@ -150,7 +140,7 @@ For each in-scope named branch:
   - the currently checked-out branch
   - branches that were skipped, failed to merge, or still need manual follow-up
 - If `git branch -d` refuses deletion because the branch is not actually merged, stop and report the branch instead of forcing deletion with `-D`.
-- Once merge verification, `review-change-set`, and archival/doc synchronization pass, invoke `commit-and-push` for the original current branch so the final submission flow owns:
+- Once merge verification and archival/doc synchronization pass, invoke `commit-and-push` for the original current branch so the final submission flow owns:
   - `CHANGELOG.md` readiness
   - the final commit creation on the original current branch
   - the user-requested push on that same branch

package/package.json

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

package/review-spec-related-changes/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LaiTszKin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/review-spec-related-changes/README.md

@@ -0,0 +1,53 @@
+# review-spec-related-changes
+
+`review-spec-related-changes` reviews implementation changes against recent or user-specified planning documents.
+
+## What this skill does
+
+This skill:
+
+1. Resolves the governing `docs/plans/...` spec scope from user input or recent repository changes.
+2. Checks whether each business goal and acceptance criterion is actually implemented.
+3. Treats unmet business goals as the most severe review findings.
+4. Runs secondary code-practice review through `review-change-set`, `discover-edge-cases`, and `harden-app-security` for code-affecting scopes.
+5. Reports business-goal gaps separately from edge-case, security, and maintainability findings.
+
+## When to use
+
+Use this skill when the task asks you to:
+
+- review whether recent spec-backed implementation work is complete,
+- compare current changes against a named spec directory,
+- check whether delivered code satisfies `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, or `design.md`,
+- perform a final spec-compliance review before archive, submission, PR, or release work.
+
+## Core principles
+
+- Business-goal completion is reviewed first.
+- Missing required behavior is more severe than ordinary code-practice issues.
+- Secondary edge-case, security, and code-review findings remain clearly separated.
+- Findings must cite concrete spec and code evidence.
+
+## Example
+
+Prompt example:
+
+```text
+Use $review-spec-related-changes to review the changes related to docs/plans/2026-04-28/order-routing.
+List any business goals that were not fully achieved, then run edge-case, security, and code-review checks on the related code.
+```
+
+Expected behavior:
+
+- the named spec set is read before judging the code,
+- business-goal gaps are listed first and treated as highest severity,
+- secondary review skills are invoked for the same implementation scope,
+- the final report separates spec-compliance findings from edge-case, security, and code-review findings.
+
+## References
+
+- [`SKILL.md`](./SKILL.md) - full workflow and execution rules.
+
+## License
+
+MIT

package/review-spec-related-changes/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: review-spec-related-changes
+description: Review recent or user-specified spec-related changes against the governing `docs/plans/...` spec documents, treat unmet business goals as the most severe findings, and then run code-practice cross-checks through `review-change-set`, `discover-edge-cases`, and `harden-app-security`. Use when users ask whether implemented work actually satisfies a spec, wants a spec compliance review, or asks to review changes related to recent or named planning documents.
+---
+
+# Review Spec Related Changes
+
+## Dependencies
+
+- Required: `review-change-set`, `discover-edge-cases`, and `harden-app-security` for code-affecting spec-related changes.
+- Conditional: none.
+- Optional: none.
+- Fallback: If any required review dependency is unavailable for a code-affecting scope, stop and report the missing dependency instead of returning a partial pass.
+
+## Standards
+
+- Evidence: Read the governing spec documents, the related git changes, and the minimum implementation context before deciding whether the business goal was met.
+- Execution: Resolve the spec scope first, review business-goal completion before any secondary code-practice review, then run the required review skills on the same implementation scope.
+- Quality: Treat unmet or partially met business goals as the highest-severity findings, keep secondary edge-case/security/code-review findings outside the business-goal verdict, and avoid speculative issues that are not backed by code or spec evidence.
+- Output: Return a prioritized issue list with business-goal gaps first, followed by edge-case, security, and code-review findings, each tied to specific spec and code evidence.
+
+## Goal
+
+Determine whether the implementation actually satisfies the relevant planning documents, then separately assess whether the related code is safe, robust, and maintainable.
+
+## Scope Resolution
+
+### User-specified spec documents
+
+- If the user names a spec directory or file, read every governing document in that spec set, including `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md`, and batch-level `coordination.md` when present.
+- Treat the named spec documents as the authoritative business goal unless the repository contains a newer superseding plan that the user explicitly referenced.
+- Map the spec to implementation changes using task entries, owned files, git diff paths, branch names, commit messages, and code references from the spec.
+
+### Recent spec-related changes
+
+- If the user asks for recent spec-related review without naming a spec, inspect the current git state first:
+  ```bash
+  git status -sb
+  git diff --name-only
+  git diff --cached --name-only
+  ```
+- Look for changed or recently touched planning documents under `docs/plans/`, `docs/archive/plans/`, or the repository's documented planning location.
+- If no planning document changed, inspect recent commits and active plan directories to identify the most recent spec set that plausibly governs the current implementation.
+- If multiple candidate spec sets remain plausible and cannot be separated by changed files or branch names, stop and report the ambiguity instead of guessing.
+
+## Workflow
+
+### 1) Build the spec baseline
+
+- Read the governing spec documents end-to-end.
+- Extract the concrete business goals, acceptance criteria, non-goals, deferred work, and explicit verification requirements.
+- Build a compact checklist of claims that can be proven or disproven from code, tests, docs, or command output.
+- Keep business goals separate from implementation-quality expectations. A clean implementation does not compensate for an unmet business requirement.
+
+### 2) Map implementation evidence
+
+- Read the related diff, staged changes, commits, or changed files that correspond to the spec scope.
+- Follow the minimum dependency chain needed to understand whether the behavior is actually implemented.
+- Run or inspect the verification commands named by the spec when they are available and safe to run.
+- Mark each business goal as:
+  - `Met`: direct implementation and verification evidence exists.
+  - `Partially met`: some required behavior exists, but an acceptance criterion, integration path, or verification proof is missing.
+  - `Not met`: implementation evidence is absent or contradicts the spec.
+  - `Deferred/N/A`: the spec explicitly excludes or defers the item.
+
+### 3) Review business-goal completion first
+
+- Report every `Not met` and `Partially met` business goal before secondary review findings.
+- Assign the highest severity to business-goal failures because they mean the delivered change does not satisfy the requested work.
+- Include exact spec evidence and code evidence for each gap.
+- Do not continue into archival, submission, or release recommendations while business-goal failures remain unresolved.
+
+### 4) Run secondary code-practice reviews
+
+After the business-goal pass is complete, invoke the required review skills on the same code-affecting scope:
+
+- Use `review-change-set` to identify architecture, abstraction, and simplification findings in the related diff.
+- Use `discover-edge-cases` to identify reproducible boundary, failure-path, state, and observability risks.
+- Use `harden-app-security` to identify reproducible vulnerabilities and adversarial trust-boundary failures.
+
+Keep these findings separate from the business-goal verdict unless the issue also prevents a required acceptance criterion from being satisfied.
+
+### 5) Produce the final review
+
+Return findings in this order:
+
+1. Business-goal failures
+   - Severity: always highest for unmet or partially met required goals.
+   - Include spec evidence, implementation evidence, and the missing acceptance criterion.
+2. Edge-case findings
+   - Include reproduction or concrete trigger evidence.
+3. Security findings
+   - Include exploit path, protected asset, and reproducibility evidence.
+4. Code-review findings
+   - Include architecture, abstraction, simplification, or maintainability evidence.
+5. Passing evidence
+   - Summarize the business goals that were confirmed met.
+6. Residual uncertainty
+   - List unverified checks, commands not run, ambiguous spec mappings, or external dependencies that could not be proven.
+
+If no actionable issue is found, state that no business-goal, edge-case, security, or code-review findings were identified, and still list the spec documents and verification evidence reviewed.
+
+## Working Rules
+
+- Do not edit code, tests, or specs during this review.
+- Do not archive specs, commit, push, tag, or release from this skill.
+- Do not let secondary code quality findings bury business-goal failures.
+- Do not treat checked tasks as proof by themselves; verify the implementation.
+- Do not infer success from author intent, branch names, or prior conversation context unless the repository evidence supports it.
+- Prefer fewer confirmed findings over broad speculative feedback.

package/review-spec-related-changes/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Review Spec Related Changes"
+  short_description: "Review spec-backed changes for business-goal completion and secondary code-practice risks"
+  default_prompt: "Use $review-spec-related-changes to resolve the recent or user-specified spec documents, verify each business goal and acceptance criterion against the related implementation evidence, treat unmet business goals as the most severe findings, and then run $review-change-set, $discover-edge-cases, and $harden-app-security on the same code-affecting scope for secondary code-practice review."