@laitszkin/apollo-toolkit 3.5.0 → 3.6.1

package/AGENTS.md

@@ -26,7 +26,7 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can choose between symlink mode (auto-update via git pull) and copy mode (stable snapshot) with `--symlink` / `--copy` flags.
 - Users can run bundled helper tools through `apltk tools` and direct `apltk <tool>` commands for selected packaged skill scripts.
 - Users can design and implement new features through a spec-first workflow.
-- Users can generate shared feature planning artifacts for approval-gated workflows, including parallel multi-spec batches coordinated through one batch-level `coordination.md`.
+- Users can generate shared feature planning artifacts for approval-gated workflows, including parallel multi-spec batches coordinated through `coordination.md` and, only when needed, minimal non-business prerequisite work in `preparation.md`.
 - Users can convert text or documents into audio files with subtitle timelines.
 - Users can turn lecture slides, past papers, and answer books into mock exams, worked solutions, study notes, or graded PDFs with KaTeX-rendered math.
 - Users can extend existing features in a brownfield codebase with required tests and approvals.
@@ -52,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,23 @@ All notable changes to this repository are documented in this file.
 ### Added
 - (None yet)
 
+## [v3.6.1] - 2026-04-28
+
+### Added
+- Add an optional `generate-spec` `preparation.md` template and `apltk create-specs --with-preparation` support for minimal non-business prerequisite work before parallel spec implementation.
+
+### Changed
+- Tighten `implement-specs-with-subagents` so the coordinating agent completes and commits documented prerequisite preparation before launching implementation subagents.
+- Keep `coordination.md` focused on ownership and collision rules by removing preparation-task fields from its template.
+
+## [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

package/README.md

@@ -45,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
@@ -202,6 +203,7 @@ Compatibility note:
 - `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/README.md

@@ -1,11 +1,12 @@
 # generate-spec
 
-A shared planning skill for feature work. It centralizes creation and maintenance of `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md`, and when needed `coordination.md` so other skills can reuse one consistent approval-gated spec workflow with risk-driven test planning from `test-case-strategy`.
+A shared planning skill for feature work. It centralizes creation and maintenance of `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md`, and when needed shared `coordination.md` or `preparation.md` so other skills can reuse one consistent approval-gated spec workflow with risk-driven test planning from `test-case-strategy`.
 
 ## Core capabilities
 
 - Generates single-spec plans under `docs/plans/{YYYY-MM-DD}/{change_name}/`.
 - Generates multi-spec parallel batches under `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` with a shared `coordination.md`, while keeping every batch spec independently completable and safe to implement concurrently.
+- Optionally generates a batch-level `preparation.md` only when minimal non-business prerequisite work must land before specs can be implemented in parallel.
 - Uses shared templates so spec-first and brownfield workflows follow the same planning structure.
 - Requires clarification handling and explicit user approval before implementation starts.
 - Backfills task and checklist status after implementation and testing.
@@ -29,7 +30,8 @@ A shared planning skill for feature work. It centralizes creation and maintenanc
 │       ├── checklist.md
 │       ├── contract.md
 │       ├── design.md
-│       └── coordination.md
+│       ├── coordination.md
+│       └── preparation.md
 └── scripts/
     └── create-specs
 ```
@@ -64,6 +66,19 @@ apltk create-specs "Membership write path" \
   --output-dir "$WORKSPACE_ROOT/docs/plans"
 ```
 
+Parallel batch with prerequisite preparation:
+
+```bash
+apltk create-specs "Membership write path" \
+  --change-name membership-write-path \
+  --batch-name membership-cutover \
+  --with-coordination \
+  --with-preparation \
+  --output-dir "$WORKSPACE_ROOT/docs/plans"
+```
+
+Use `--with-preparation` only when shared prerequisite work is required before parallel implementation. That file must stay minimal and must not contain core business logic, target user behavior, or member-spec implementation tasks.
+
 ```text
 docs/plans/<today>/membership-cutover/
 ├── coordination.md
@@ -82,7 +97,8 @@ docs/plans/<today>/membership-cutover/
 - `checklist.md`: use `- [ ]` only, adapt items to real scope, record actual results, and map behavior risks to test IDs plus oracles selected through `test-case-strategy`.
 - `contract.md`: when external dependencies materially shape the change, record their official-source-backed invocation surface, constraints, and caller obligations in the standard dependency-record format.
 - `design.md`: record the architecture/design delta in the standard format, including affected modules, flow, invariants, tradeoffs, and validation plan.
-- `coordination.md`: for multi-spec batches only, record shared preparation, ownership boundaries, replacement direction, file ownership guardrails, known collision candidates, pre-agreed edit rules for shared surfaces, shared API/schema freeze or additive-only rules, compatibility-shim retention rules, merge order, and cross-spec integration checkpoints, but never use it to make one spec depend on another spec's implementation before it can be completed.
+- `coordination.md`: for multi-spec batches only, record ownership boundaries, replacement direction, file ownership guardrails, known collision candidates, pre-agreed edit rules for shared surfaces, shared API/schema freeze or additive-only rules, compatibility-shim retention rules, merge order, and cross-spec integration checkpoints, but never use it to make one spec depend on another spec's implementation before it can be completed.
+- `preparation.md`: optional batch-level prerequisite plan used only when specs cannot be made parallel-safe without prior shared work; keep it tasks-like, minimal, verified, and free of core business logic or target outcomes.
 - If clarification responses change the plan, update the docs and obtain approval again before coding.
 
 ## Notes

package/generate-spec/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generate-spec
-description: Generate and maintain shared feature planning artifacts (`spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md`, and when needed `coordination.md`) from standard templates with clarification tracking, approval gating, unit drift-check planning, and post-implementation backfill. Use when a workflow needs specs before coding, or when another skill needs to create/update planning docs under `docs/plans/{YYYY-MM-DD}/...`.
+description: Generate and maintain shared feature planning artifacts (`spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md`, and when needed shared `coordination.md` or `preparation.md`) from standard templates with clarification tracking, approval gating, unit drift-check planning, and post-implementation backfill. Use when a workflow needs specs before coding, or when another skill needs to create/update planning docs under `docs/plans/{YYYY-MM-DD}/...`.
 ---
 
 # Generate Spec
@@ -15,9 +15,9 @@ 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 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.
+- 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, add `preparation.md` only when the specs cannot be made parallel-safe without prior shared work, keep that preparation minimal and free of core business logic or target outcomes, complete plans 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`, `design.md`, and any shared batch docs 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 shared `coordination.md` for multi-spec parallel work. Add shared `preparation.md` at the batch root only when prerequisite work must land before member specs can run in parallel, and keep individual specs concise, executable, non-overlapping with that preparation, and easy to update.
 
 ## Goal
 
@@ -48,15 +48,20 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Instead, split the work into multiple spec sets, each independently valid and each covering no more than three modules.
 - Define those spec sets so they do not conflict with each other and do not require another spec set to land first in order to be approved or implemented safely.
 - For batch generation, treat cross-spec implementation dependency as a planning bug: if Spec B cannot be completed safely until Spec A lands, they should be one spec set or be re-sliced so each spec has its own self-contained outcome.
-- Allow shared preparation in `coordination.md` only when each spec can still complete that preparation or operate against an already-existing baseline without waiting for another spec's code changes.
+- Use `preparation.md`, not individual spec files, when the only safe way to parallelize a batch is to land shared prerequisite work before any spec starts.
+- Keep `preparation.md` as small as possible: it may define enabling scaffolds, shared test fixtures, naming/contract stubs, mechanical migrations, or non-business compatibility surfaces, but it must not implement core business logic, the target user behavior, or any member spec's actual outcome.
+- If the required pre-work would change business behavior, implement target logic, or satisfy a meaningful requirement by itself, re-slice it into one or more normal spec sets instead of placing it in `preparation.md`.
+- Allow shared preparation only when it is completed before parallel implementation begins; do not hide required pre-work inside one member spec while other specs depend on it.
 - Treat any unresolved shared-file collision, overlapping ownership, or incompatible contract change across spec sets as a planning bug to resolve before approval, not an implementation-time surprise.
-- If two candidate spec sets would still need to edit the same non-additive surface, either merge them into one spec set or record a concrete ownership split plus additive-only rule that makes parallel work safe.
+- If two candidate spec sets would still need to edit the same non-additive surface, either merge them into one spec set, record a concrete ownership split plus additive-only rule that makes parallel work safe, or move the shared pre-work into `preparation.md` when the pre-work can be completed once before all specs.
 - Use:
   - `WORKSPACE_ROOT=<target_project_root>`
   - `apltk create-specs "<feature_name>" --change-name <kebab-case> --output-dir "$WORKSPACE_ROOT/docs/plans"`
 - For parallel multi-spec generation, also use:
   - `--batch-name <kebab-case-batch-name>`
   - `--with-coordination`
+- If and only if multiple spec sets cannot be made parallel-safe without prior shared work, also use:
+  - `--with-preparation`
 - Always generate:
   - `references/templates/spec.md`
   - `references/templates/tasks.md`
@@ -64,6 +69,7 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
   - `references/templates/contract.md`
   - `references/templates/design.md`
 - Generate `references/templates/coordination.md` at the batch root when multiple spec sets are intentionally created for parallel implementation.
+- Generate `references/templates/preparation.md` at the batch root only when required prerequisite work must be completed before member specs can be parallel-implemented.
 - 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.
@@ -105,6 +111,7 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Cross-reference relevant requirement IDs from `spec.md` and any external dependency records from `contract.md`.
 - Make architecture boundaries, invariants, and rollback/fallback expectations explicit when they matter to safe implementation.
 - When the spec belongs to a parallel batch, add a short reference to the parent `coordination.md`, state the exact assumptions that let this spec be implemented in parallel, and keep `design.md` focused on the single-spec delta rather than duplicating cross-spec ownership rules.
+- When the batch uses `preparation.md`, write each spec's implementation guidance as if the preparation has already been completed and committed; do not duplicate preparation tasks, verification, or shared setup in member specs.
 
 ### 6.5) Fill `coordination.md` for parallel multi-spec batches
 
@@ -112,8 +119,8 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Place it at `docs/plans/{YYYY-MM-DD}/{batch_name}/coordination.md`.
 - Use it as the batch-level source of truth for shared preparation, ownership boundaries, merge order, and cross-spec constraints.
 - Record explicitly that each spec set must remain independently completable and must not rely on another spec set's code changes, unfinished tasks, or merge order to achieve its own approved outcome.
-- Record shared fields, shared contracts, or shared data-shape preparation that multiple spec sets must align on before implementation starts.
-- Record whether the batch is ready for parallel implementation now; if not, list the blocking coordination items that must be settled before any spec starts.
+- Record shared fields, shared contracts, or shared data-shape assumptions that multiple spec sets must align on.
+- Record whether the batch is ready for parallel implementation now; if not, point to `preparation.md` for executable prerequisite work or list coordination decisions that must still be settled.
 - When one spec set replaces or removes legacy behavior, state that direction explicitly so all worktrees implement toward the same target rather than preserving the old behavior accidentally.
 - Capture which spec set may touch which modules, which files require coordination, and whether any landing order or cutover sequence must be respected.
 - Treat `coordination.md` as a merge-conflict prevention contract, not just a planning summary.
@@ -125,6 +132,20 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - If the batch still needs a recommended merge order, make that order operationally convenient rather than functionally required for any single spec to work correctly.
 - Keep single-spec concerns in that spec's own `design.md`; reserve `coordination.md` for batch-wide rules only.
 
+### 6.6) Fill `preparation.md` only for prerequisite work
+
+- Create `preparation.md` only when multiple spec sets cannot be implemented safely in parallel until shared prerequisite work is completed first.
+- Place it at `docs/plans/{YYYY-MM-DD}/{batch_name}/preparation.md`.
+- Treat it as a pre-parallel implementation queue for the coordinating/main agent, not as another member spec.
+- Write it in a tasks-like style with atomic preparation items, explicit outputs, completion conditions, and verification hooks.
+- Include only the smallest shared prerequisite work that every affected spec can assume after it lands.
+- Exclude core business logic, target business outcomes, user-visible behavior changes, and member-spec implementation guidance; those belong in normal spec files.
+- Include relevant validation work for the preparation itself.
+- Do not include member-spec implementation tasks in `preparation.md`.
+- Remove overlapping instructions from member specs; specs must reference the prepared baseline as an assumption instead of repeating the setup tasks.
+- If the required work is large enough to become its own product behavior slice, or if it carries core business logic, re-slice the batch instead of hiding that slice in `preparation.md`.
+- If the batch can be made parallel-safe through ownership rules, additive-only constraints, or re-slicing, do not create `preparation.md`.
+
 ### 7) Fill `checklist.md`
 
 - Use checkbox format `- [ ]` for checklist items, except structured placeholder fields that are intentionally left for later fill-in.
@@ -153,6 +174,7 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Update `contract.md` when the final dependency usage, obligations, or verified constraints differ from the planning draft.
 - Update `design.md` when the approved architecture changes during implementation, and record the final chosen design rather than leaving stale placeholders.
 - Update `coordination.md` when shared ownership, replacement sequencing, or cross-spec preparation changed during implementation or merge planning.
+- Update `preparation.md` when prerequisite work was completed, verified, skipped with an approved reason, or changed during implementation.
 - Only mark checklist items complete when the work actually happened or the recorded decision actually applies.
 - Do not check off unused examples, placeholder rows, or non-selected decision options.
 - If different flows use different test strategies, preserve separate decision records in the final checklist instead of merging them into a misleading single summary.
@@ -167,8 +189,10 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Never allow one spec set to cover more than three modules.
 - When a request exceeds that scope, split it into independent, non-conflicting, non-dependent spec sets before approval.
 - For batch specs, independence is mandatory: each spec must describe a complete slice that can be implemented, tested, reviewed, and merged without waiting for another spec in the same batch.
-- For batch specs, parallel readiness is also mandatory: each spec must be safe to implement concurrently, with shared-file collisions and ownership rules settled in `coordination.md` before coding begins.
+- For batch specs, parallel readiness is also mandatory: each spec must be safe to implement concurrently after any approved `preparation.md` work is completed, with shared-file collisions and ownership rules settled in `coordination.md` before coding begins.
+- Use `preparation.md` sparingly: it is allowed only for explicit, minimal, non-business pre-parallel shared work, not for normal cross-spec coordination or member-spec implementation.
 - When multiple spec sets are created for one batch, keep their shared implementation direction in one `coordination.md` instead of duplicating cross-spec rules in every `design.md`.
+- When `preparation.md` exists, every member spec must avoid duplicating its tasks and must state its implementation assumptions against the post-preparation baseline.
 - For parallel worktree batches, make `coordination.md` specific enough that another engineer can tell which files they may edit, which shared contracts are frozen or additive-only, which shims must remain in place, and what combined behaviors need verification after merge.
 - Prefer realistic coverage over boilerplate: add or remove checklist items based on actual risk.
 - When external dependencies materially shape the change, `contract.md` is required and must capture the official-source-backed contract in the standardized record format.
@@ -191,3 +215,4 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - `references/templates/contract.md`: external dependency contract template.
 - `references/templates/design.md`: architecture/design delta template.
 - `references/templates/coordination.md`: parallel batch coordination template.
+- `references/templates/preparation.md`: optional pre-parallel prerequisite work template.

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, 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."
+  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 shared coordination.md and, only when specs cannot be parallel-safe without prior shared work, a minimal non-business preparation.md; treat this skill's current references/templates/*.md files as the binding format even when older project specs use different layouts, ensure member specs assume preparation is already complete and do not duplicate its tasks, 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/generate-spec/references/templates/coordination.md

@@ -9,6 +9,7 @@
 ## Parallel Readiness Gate
 - Ready for parallel implementation now: [Yes / No]
 - Blocking coordination items before coding: [None / list concrete ownership or contract decisions that must be settled first]
+- Preparation document required before parallel work: [No / Yes, see `preparation.md`]
 - Re-coordination trigger: [what kind of new overlap or contract change forces the batch to stop and re-align]
 
 ## Batch Scope
@@ -22,15 +23,7 @@
 - Shared constraints: [runtime, rollout, compatibility, or ownership constraints]
 - Shared invariants: [rules every spec set must preserve]
 
-## Shared Preparation
-
-### Shared Fields / Contracts
-- Shared fields to introduce or reuse: [field / config / API shape / event schema]
-- Canonical source of truth: [which module or data owner defines them]
-- Required preparation before implementation: [migration, adapter, stub, flag, fallback, fixture]
-- Additive-only rule during batch: [what may be added safely without breaking parallel work, or `None`]
-
-### Replacement / Legacy Direction
+## Replacement / Legacy Direction
 - Legacy behavior being replaced: [feature / flow / module / endpoint / UI]
 - Required implementation direction: [replace in place / shadow then cut over / adapter bridge / phased removal]
 - Compatibility window: [None / temporary coexistence period]
@@ -42,14 +35,12 @@
 - Primary concern: [what this spec owns]
 - Allowed touch points: [files/modules it may change]
 - Must not change: [files/modules owned by another spec unless explicitly coordinated]
-- Depends on shared preparation: [None / specific shared item above that already exists or can be completed within this spec]
 - Cross-spec implementation dependency: [None; if not None, re-slice the batch]
 
 ### Spec Set 2: [spec-name-2]
 - Primary concern: [what this spec owns]
 - Allowed touch points: [files/modules it may change]
 - Must not change: [files/modules owned by another spec unless explicitly coordinated]
-- Depends on shared preparation: [None / specific shared item above that already exists or can be completed within this spec]
 - Cross-spec implementation dependency: [None; if not None, re-slice the batch]
 
 ## Conflict Boundaries

package/generate-spec/references/templates/preparation.md

@@ -0,0 +1,69 @@
+# Preparation: [Feature Name]
+
+- Date: [YYYY-MM-DD]
+- Batch: [batch_name]
+
+## Preparation Goal
+[Describe the smallest shared prerequisite state that must exist before member specs can be implemented in parallel. This must not implement core business logic or deliver the batch target outcome.]
+
+## Use Condition
+- Why this file exists: [explain why the batch cannot be safely parallelized without this prerequisite work]
+- Minimality rule: [why this is the smallest viable prerequisite, not a member-spec implementation slice]
+- Core business boundary: [state `No core business logic or target outcome is implemented here`; if that is false, re-slice the specs instead]
+- Specs that rely on this preparation: [[spec-name-1], [spec-name-2]]
+- Parallel implementation starts after: [commit / verification / approval condition]
+- Out of scope: [member-spec implementation work that must remain in the individual spec files]
+
+## Prepared Baseline
+- Current baseline before preparation: [current state]
+- Required baseline after preparation: [state all member specs may assume]
+- Shared files or contracts prepared here: [files/modules/API/schema/config/test fixtures]
+- Member specs must not repeat: [tasks/edits/verification covered by this file]
+- Core business behavior changed here: [No; if yes, this file is being misused]
+
+## Preparation Tasks
+
+### **Task P1: [Preparation Task Title]**
+- Purpose: [why this minimal non-business prerequisite is required before parallel work]
+- Affected specs: [[spec-name-1], [spec-name-2]]
+- Allowed scope: [files/modules this preparation task may touch]
+- Out-of-scope guardrails: [core business logic, target outcome, and member-spec behavior that must stay out of preparation]
+- Inputs: [coordination/design/contract/official-doc evidence]
+- Expected output: [concrete prepared artifact or code/doc state]
+- Completion condition: [observable state that proves the task is done]
+- Verification hook: [command/check/review step]
+- Unit drift check: [UT-xx target unit; expected result/assertion, or N/A with reason]
+- P1. [ ] [Atomic preparation action with one concrete output]
+- P1. [ ] [Atomic verification or regression action]
+
+### **Task P2: [Preparation Task Title]**
+- Purpose: [why this minimal non-business prerequisite is required before parallel work]
+- Affected specs: [[spec-name-1], [spec-name-2]]
+- Allowed scope: [files/modules this preparation task may touch]
+- Out-of-scope guardrails: [core business logic, target outcome, and member-spec behavior that must stay out of preparation]
+- Inputs: [coordination/design/contract/official-doc evidence]
+- Expected output: [concrete prepared artifact or code/doc state]
+- Completion condition: [observable state that proves the task is done]
+- Verification hook: [command/check/review step]
+- Unit drift check: [UT-xx target unit; expected result/assertion, or N/A with reason]
+- P2. [ ] [Atomic preparation action with one concrete output]
+- P2. [ ] [Atomic verification or regression action]
+
+## Validation Plan
+- Required verification before subagents start: [commands/checks]
+- Expected results/assertions: [what proves the prepared baseline is usable]
+- Regression risks covered: [risk IDs or behavior slices]
+- Verification owner: [main/coordinating agent]
+
+## Handoff Contract For Member Specs
+- Preparation commit required before subagents start: [Yes]
+- Member specs assume: [prepared baseline assumptions]
+- Member specs must not change: [prepared surfaces that are now frozen/additive-only]
+- Member specs own all business behavior: [Yes]
+- If preparation changes later: [stop condition and re-coordination rule]
+
+## Completion Record
+- Preparation status: [Not started / In progress / Complete / Blocked / N/A]
+- Preparation commit: [commit hash or `None yet`]
+- Verification executed: [commands/checks/results]
+- Remaining blockers before parallel implementation: [None / list]

package/generate-spec/scripts/create-specs

@@ -14,6 +14,7 @@ TEMPLATE_FILENAMES = (
     "design.md",
 )
 COORDINATION_TEMPLATE = "coordination.md"
+PREPARATION_TEMPLATE = "preparation.md"
 PLACEHOLDERS = ("[Feature Name]", "[功能名稱]")
 
 
@@ -49,7 +50,8 @@ def main() -> int:
             "Create planning docs (spec.md, tasks.md, checklist.md, contract.md, design.md) "
             "from templates with folder format docs/plans/{date}/{change_name} "
             "or docs/plans/{date}/{batch_name}/{change_name}, including coordination "
-            "templates for truly parallel-safe batch specs."
+            "and optional preparation templates for batch specs that need shared "
+            "pre-work before parallel implementation."
         ),
     )
     parser.add_argument("feature_name", help="Display name used in generated documents")
@@ -78,6 +80,15 @@ def main() -> int:
             "for up-front ownership and collision coordination."
         ),
     )
+    parser.add_argument(
+        "--with-preparation",
+        action="store_true",
+        help=(
+            "When used with --batch-name, also create or update "
+            "docs/plans/{date}/{batch_name}/preparation.md from the shared template "
+            "for prerequisite work that must be completed before parallel implementation."
+        ),
+    )
     parser.add_argument(
         "--output-dir",
         default="docs/plans",
@@ -110,6 +121,8 @@ def main() -> int:
     batch_name = args.batch_name.strip() if args.batch_name else None
     if args.with_coordination and not batch_name:
         raise SystemExit("--with-coordination requires --batch-name")
+    if args.with_preparation and not batch_name:
+        raise SystemExit("--with-preparation requires --batch-name")
 
     template_dir = Path(args.template_dir).expanduser().resolve()
     if not template_dir.exists() or not template_dir.is_dir():
@@ -120,6 +133,8 @@ def main() -> int:
     ]
     if args.with_coordination and not (template_dir / COORDINATION_TEMPLATE).exists():
         missing_templates.append(COORDINATION_TEMPLATE)
+    if args.with_preparation and not (template_dir / PREPARATION_TEMPLATE).exists():
+        missing_templates.append(PREPARATION_TEMPLATE)
     if missing_templates:
         missing = ", ".join(missing_templates)
         raise SystemExit(f"Missing template files in {template_dir}: {missing}")
@@ -134,6 +149,9 @@ def main() -> int:
     coordination_path = (
         batch_root / COORDINATION_TEMPLATE if args.with_coordination and batch_root else None
     )
+    preparation_path = (
+        batch_root / PREPARATION_TEMPLATE if args.with_preparation and batch_root else None
+    )
     existing_files = [path for path in output_paths if path.exists()]
     if existing_files and not args.force:
         existing = ", ".join(str(path) for path in existing_files)
@@ -171,10 +189,25 @@ def main() -> int:
             encoding="utf-8",
         )
 
+    if preparation_path and (args.force or not preparation_path.exists()):
+        preparation_template = template_dir / PREPARATION_TEMPLATE
+        preparation_path.write_text(
+            _render(
+                content=preparation_template.read_text(encoding="utf-8"),
+                today=today,
+                feature_name=feature_name,
+                change_name=change_name,
+                batch_name=batch_name,
+            ),
+            encoding="utf-8",
+        )
+
     for output_path in output_paths:
         print(output_path)
     if coordination_path:
         print(coordination_path)
+    if preparation_path:
+        print(preparation_path)
     return 0
 
 

package/generate-spec/tests/test_create_specs.py

@@ -64,7 +64,7 @@ class CreateSpecsTests(unittest.TestCase):
         self.assertIn("batch-safe-planner", rendered)
         self.assertIn("parallel-batch", rendered)
 
-    def test_main_creates_spec_files_and_coordination_file(self) -> None:
+    def test_main_creates_spec_files_and_shared_batch_files(self) -> None:
         with tempfile.TemporaryDirectory() as temp_dir:
             root = Path(temp_dir)
             template_dir = root / "templates"
@@ -80,6 +80,10 @@ class CreateSpecsTests(unittest.TestCase):
                 "coordination [YYYY-MM-DD] [Feature Name] [change_name] [batch_name]\n",
                 encoding="utf-8",
             )
+            (template_dir / MODULE.PREPARATION_TEMPLATE).write_text(
+                "preparation [YYYY-MM-DD] [Feature Name] [change_name] [batch_name]\n",
+                encoding="utf-8",
+            )
 
             argv = [
                 "create-specs",
@@ -87,6 +91,7 @@ class CreateSpecsTests(unittest.TestCase):
                 "--batch-name",
                 "parallel-batch",
                 "--with-coordination",
+                "--with-preparation",
                 "--output-dir",
                 str(output_dir),
                 "--template-dir",
@@ -110,6 +115,35 @@ class CreateSpecsTests(unittest.TestCase):
             coordination = output_dir / "2026-04-18" / "parallel-batch" / "coordination.md"
             self.assertTrue(coordination.is_file())
             self.assertIn(str(coordination), stdout.getvalue())
+            preparation = output_dir / "2026-04-18" / "parallel-batch" / "preparation.md"
+            self.assertTrue(preparation.is_file())
+            self.assertIn("preparation", preparation.read_text(encoding="utf-8"))
+            self.assertIn(str(preparation), stdout.getvalue())
+
+    def test_main_requires_batch_name_for_preparation_file(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            template_dir = Path(temp_dir) / "templates"
+            template_dir.mkdir(parents=True)
+            for name in MODULE.TEMPLATE_FILENAMES:
+                (template_dir / name).write_text("template\n", encoding="utf-8")
+            (template_dir / MODULE.PREPARATION_TEMPLATE).write_text(
+                "preparation\n",
+                encoding="utf-8",
+            )
+
+            argv = [
+                "create-specs",
+                "My Feature",
+                "--with-preparation",
+                "--template-dir",
+                str(template_dir),
+            ]
+
+            with patch.object(sys, "argv", argv):
+                with self.assertRaises(SystemExit) as context:
+                    MODULE.main()
+
+            self.assertIn("--with-preparation requires --batch-name", str(context.exception))
 
     def test_main_rejects_existing_files_without_force(self) -> None:
         with tempfile.TemporaryDirectory() as temp_dir:

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

@@ -5,9 +5,10 @@ description: >-
   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.
+  workers while completing any explicitly documented shared prerequisite work
+  before delegation, 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
@@ -21,9 +22,9 @@ description: >-
 
 ## 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.
+- Evidence: Read the batch-level `coordination.md` and `preparation.md` when present, enumerate the exact spec directories to implement, verify each delegated spec has the required planning files, and identify any explicit prerequisite notes before starting subagents.
+- Execution: Complete and commit explicitly documented prerequisite preparation on the working branch before delegation, then 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, ensure subagents branch from a baseline that includes prerequisite commits, 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
@@ -36,6 +37,7 @@ Coordinate a multi-spec implementation batch safely by delegating each approved
 
 - Locate the requested batch under `docs/plans/{YYYY-MM-DD}/{batch_name}/`.
 - Read `coordination.md` first when it exists.
+- Read `preparation.md` 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`
@@ -45,6 +47,19 @@ Coordinate a multi-spec implementation batch safely by delegating each approved
   - `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.
+- If `preparation.md` exists, or if the in-scope spec documents explicitly state that prerequisite work must be completed before parallel implementation, treat that preparation as blocking before subagent launch.
+
+### 1.5) Complete documented prerequisite preparation
+
+- Use this step only when `preparation.md` exists or the specs clearly annotate required pre-work.
+- The coordinating agent owns the prerequisite work; do not delegate it to implementation subagents.
+- Read the preparation tasks, expected outputs, and verification hooks before editing.
+- Complete only the shared prerequisite scope that all specs must assume before parallel work starts.
+- Run the verification commands or checks listed for the preparation.
+- Commit the preparation to the working branch that future implementation worktrees or subagents will use as their base.
+- Record the preparation commit in the ledger.
+- Do not start implementation subagents until the preparation commit exists and the working branch is clean.
+- If preparation cannot be completed or verified, stop and report the blocker instead of launching subagents.
 
 ### 2) Build a delegation plan
 
@@ -58,6 +73,7 @@ Coordinate a multi-spec implementation batch safely by delegating each approved
   - commit
   - tests
   - blockers
+- If preparation was completed, include the preparation commit that all subagents must treat as their base.
 - 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.
@@ -79,6 +95,7 @@ For each subagent, provide only task-local instructions:
 - Exact spec directory path.
 - Parent `coordination.md` path when present.
 - Requirement to use `implement-specs-with-worktree`.
+- Requirement to base work on the committed prerequisite-preparation branch state when preparation was performed.
 - Requirement to read the full spec bundle before editing.
 - Requirement to implement inside its own isolated worktree.
 - Requirement to run relevant tests.
@@ -107,11 +124,13 @@ Do not pass the coordinating agent's full reasoning, unrelated sibling specs, or
 ## Working Rules
 
 - One spec directory maps to one implementation subagent.
+- Explicitly documented prerequisite preparation is completed, verified, and committed by the coordinating agent before any implementation subagent starts.
 - 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.
+- The coordinating agent owns shared prerequisite commits; implementation subagents must not redo or overlap that preparation unless the preparation commit is missing or invalid.
 - 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.
 
@@ -119,4 +138,5 @@ Do not pass the coordinating agent's full reasoning, unrelated sibling specs, or
 
 - `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.
+- `preparation.md`: optional batch-level prerequisite plan that must be completed before parallel subagent work starts.
 - `review-change-set`: optional post-implementation review workflow before merge or submission.

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

@@ -1,4 +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."
+  default_prompt: "Use $implement-specs-with-subagents to read coordination.md and any preparation.md first, complete and commit explicitly documented prerequisite preparation on the working branch before delegation, then 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/implement-specs-with-worktree/SKILL.md

@@ -3,9 +3,9 @@ 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}/` or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/`
-  plus parent `coordination.md` when present, and implement the approved tasks
-  within an isolated git worktree, with every code, test, and spec edit made
-  inside that worktree rather than the parent checkout. Use when the user asks
+  plus parent `coordination.md` and `preparation.md` when present, and implement
+  the approved tasks within an isolated git worktree, with every code, test, and
+  spec edit made inside that worktree rather than the parent checkout. 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 parent working tree. If not already in a
   worktree, create a new worktree with a spec-named branch from the same parent
@@ -24,7 +24,7 @@ description: >-
 
 ## Standards
 
-- Evidence: Read and understand the complete specs set before starting implementation, identify the authoritative parent branch that the worktree should inherit from, verify whether the requested scope is already implemented on that parent branch or current main working tree, and when the requested plan path is missing from the current worktree verify where the authoritative copy actually lives before substituting any nearby spec.
+- Evidence: Read and understand the complete specs set before starting implementation, including parent `coordination.md` and `preparation.md` when present, identify the authoritative parent branch that the worktree should inherit from, verify whether the requested scope is already implemented on that parent branch or current main working tree, and when the requested plan path is missing from the current worktree verify where the authoritative copy actually lives before substituting any nearby spec.
 - Execution: Create or use an isolated worktree for implementation only when the requested spec still needs work, sync the exact approved plan set into that worktree when it is missing there, create the worktree branch from the same parent branch as the worktree base, use the spec-set name as the canonical branch/worktree name, inspect sibling worktrees for the same batch before editing shared files when parallel implementations may already be active, prefer direct `git` ref checks over brittle shell inference when deciding whether a branch or worktree already exists, and commit to a local branch when done. Do not edit product files from the parent checkout; every implementation, test, and spec backfill change must happen inside the active worktree directory after verifying `git rev-parse --show-toplevel` and `pwd` point at the same worktree root.
 - Quality: Complete all planned tasks, run relevant tests, backfill the spec documents with actual completion status, avoid dragging unrelated sibling specs into the worktree just because they share a batch directory, inspect overlapping runtime/config/shared touch points before diverging from another active sibling worktree in the same batch, revert unrelated formatter-only noise outside the spec-owned scope before committing, if branch/worktree creation reports ambiguous state re-check the actual git refs and worktree list before retrying, and when using targeted Rust `cargo test` selectors remember Cargo accepts only one positional test filter so each distinct selector needs its own confirmed command.
 - Output: Keep the worktree branch clean with only the intended implementation commits.
@@ -45,14 +45,15 @@ Implement approved spec planning sets in an isolated git worktree, ensuring the
   - prefer the exact matching plan directory from the repository's authoritative branch or main working tree over archived, approximate, or sibling plan directories
   - if the plan lives under a batch directory, sync only the requested spec directory plus the shared `coordination.md` that governs it
   - do not copy neighboring sibling spec directories into the worktree unless the user explicitly expanded scope
-- When the plan sits under a batch directory, also read the sibling `coordination.md` before implementation.
+- When the plan sits under a batch directory, also read the sibling `coordination.md` and `preparation.md` before implementation when those files exist.
 - 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.
+- If `coordination.md` exists in the parent batch directory, read it as the shared source of truth for ownership boundaries, replacement direction, merge order, and cross-spec integration checkpoints.
+- If `preparation.md` exists in the parent batch directory, treat it as the already-completed prerequisite baseline for this spec; do not redo its tasks inside the member spec unless the preparation commit is missing or the document says the prerequisite remains blocked.
 - Understand the scope, requirements, and planned tasks before proceeding.
 
 ### 2) Check current worktree state
@@ -106,6 +107,7 @@ Use branch naming from `references/branch-naming.md`.
 - 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.
+- When `preparation.md` exists, implement against its prepared baseline assumptions and avoid duplicating preparation tasks in the member spec.
 - 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:
@@ -128,6 +130,7 @@ After implementation and testing:
 - 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.
+- If preparation assumptions changed or were found missing, update `preparation.md` or stop for re-coordination instead of silently moving prerequisite work into the member spec.
 - Do not mark unused template examples or non-applicable items as complete.
 
 ### 6) Commit changes
@@ -158,6 +161,7 @@ After implementation and testing:
 - 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.
+- When `preparation.md` exists, treat it as a prerequisite baseline owned outside the member spec; do not duplicate or alter its tasks unless explicitly requested.
 - 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.
 - Revert formatter-only edits outside the owned spec scope before the final commit so the worktree stays reviewable and merge-safe.
 - Follow the testing standards from `enhance-existing-features` and `develop-new-features`.

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.5.0",
+  "version": "3.6.1",
   "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."