@laitszkin/apollo-toolkit 3.8.0 → 3.8.2

package/CHANGELOG.md

@@ -12,6 +12,16 @@ All notable changes to this repository are documented in this file.
 - Strip ~375 lines of verbosity across 32 skill files: remove empty Dependencies sections, merge redundant Overview paragraphs, deduplicate repeated principles in `generate-spec`, and consolidate `archive-specs` workflow steps
 - Extract inline output templates and issue schemas into skill-local reference files for `scheduled-runtime-health-check` and `open-github-issue`
 
+## [v3.8.1] - 2026-05-01
+
+### Changed
+- Enhance `solve-issues-found-during-review` skill: add finding classification by module and business logic chain, parallel sub-agent deployment with isolated workspaces, and change consolidation with conflict resolution; fall back to sequential fixing when sub-agents are unavailable
+
+## [v3.8.2] - 2026-05-02
+
+### Changed
+- Simplify `generate-spec` coordination.md to three sections (Business Goals, Design Principles, Spec Boundaries) and restructure preparation.md to follow tasks.md-style compact format
+
 ## [Unreleased]
 
 ### Added

package/generate-spec/SKILL.md

@@ -118,30 +118,30 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 
 - Create `coordination.md` only when one user request is intentionally split into multiple spec sets that may be implemented in parallel.
 - 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.
-- See Working Rules for the independence rule.
-- 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.
-- Record the concrete file ownership map, forbidden touch points, and shared files that require explicit coordination before edits begin.
-- For every known collision candidate, record the conflict shape, the pre-agreed owner or additive-only edit rule, and the trigger that requires re-coordination before implementation continues.
-- For shared APIs, event schemas, config shapes, manifests, or artifact fields, record whether changes are additive-only during the batch and which spec set owns the canonical naming.
-- When temporary compatibility shims, adapters, or legacy bridges must survive until the whole batch lands, record that retention rule explicitly so one worktree does not remove a path another still depends on.
-- Record the post-merge integration checkpoints that must be re-verified after multiple worktrees land, especially when text merges may succeed while behavior still drifts.
-- 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.
+- Use it as the batch-level source of truth organized in three sections: **Business Goals**, **Design Principles**, and **Spec Boundaries**.
 - Keep single-spec concerns in that spec's own `design.md`; reserve `coordination.md` for batch-wide rules only.
+- See Working Rules for the independence rule.
+
+**Business Goals** — Record the shared batch outcome, list the member spec sets, state parallel readiness, and note shared exclusions. If the batch is not ready, point to `preparation.md` or list blocking coordination items.
+
+**Design Principles** — Record the current baseline, shared invariants and constraints that every spec must preserve, legacy replacement direction, compatibility windows, and post-cutover cleanup. Keep these high-level and cross-cutting; leave per-spec design decisions in each `design.md`.
+
+**Spec Boundaries** — Split into two sub-sections:
+- **Ownership Map**: For each spec set, list its primary concern, allowed touch points, and forbidden touch points. This is the merge-conflict prevention contract.
+- **Collisions & Integration**: Record shared-file edit rules, API/schema freeze owners, compatibility shim retention rules, merge order, post-merge integration checkpoints, and the re-coordination trigger. Every known collision candidate must have a pre-agreed resolution.
 
 ### 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.
+- Follow a tasks.md-like structure with a **Preparation Goal** header, atomic preparation tasks, a **Validation** section, and a **Handoff** section.
+- In **Preparation Goal**, state why this prerequisite is necessary, confirm that no core business logic is implemented here, list which specs depend on it, and define when parallel work can start.
+- In each **Task P[N]**, use the same compact format as `tasks.md`: a one-line Purpose, Scope, and Out of scope guardrails, followed by atomic checkbox items with concrete file paths, modifications, 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.
+- In **Validation**, list the verification commands, expected results, and regression risks that prove the prepared baseline is ready.
+- In **Handoff**, record what member specs may assume, what they must not change, and the re-coordination rule if preparation changes later.
 - Remove overlapping instructions from member specs; specs must reference the prepared baseline as an assumption instead of repeating the setup tasks.
 - See Working Rules for the parallel-safety rule.
 

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

@@ -3,75 +3,45 @@
 - Date: [YYYY-MM-DD]
 - Batch: [batch_name]
 
-## Coordination Goal
-[Describe the shared implementation goal across this batch of parallel spec sets.]
+## Business Goals
 
-## 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]
+[Describe the shared business outcome this batch delivers when all spec sets land.]
 
-## Batch Scope
-- Included spec sets: [[spec-name-1], [spec-name-2]]
+- Batch members: [[spec-name-1], [spec-name-2]]
 - Shared outcome: [what the batch delivers when all spec sets land]
+- Parallel readiness: [Yes / No; if No, list blocking items or link to preparation.md]
 - Out of scope: [shared exclusions for the batch]
-- Independence rule: [state how each spec remains independently implementable, testable, and mergeable without another spec in this batch landing first]
 
-## Shared Context
-- Current baseline: [the current system shape that all spec sets must assume]
-- Shared constraints: [runtime, rollout, compatibility, or ownership constraints]
-- Shared invariants: [rules every spec set must preserve]
+## Design Principles
+
+[Shared design constraints every spec must follow during implementation.]
 
-## 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]
+- Current baseline: [the current system state all spec sets must assume]
+- Shared invariants: [rules every spec set must preserve]
+- Shared constraints: [runtime, rollout, compatibility, or ownership constraints]
+- Legacy direction: [legacy behavior being replaced and the replacement strategy; None if not applicable]
 - Compatibility window: [None / temporary coexistence period]
-- Cleanup required after cutover: [delete flag / remove adapter / drop old field / remove old tests]
+- Cleanup after cutover: [delete flag / remove adapter / drop old field; None if not applicable]
 
-## Spec Ownership Map
+## Spec Boundaries
 
-### Spec Set 1: [spec-name-1]
+### Ownership Map
+
+#### Spec Set 1: [spec-name-1]
 - 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]
-- Cross-spec implementation dependency: [None; if not None, re-slice the batch]
 
-### Spec Set 2: [spec-name-2]
+#### 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]
-- Cross-spec implementation dependency: [None; if not None, re-slice the batch]
-
-## Conflict Boundaries
-- Shared files requiring coordination: [file/module list or `None`]
-- File ownership / edit guardrails: [which spec set owns which shared files or `None`]
-- Shared API / schema freeze: [frozen owner + additive-only rule, or `None`]
-- Compatibility shim retention rules: [which adapters/flags/tests must remain until batch completion, or `None`]
-- Merge order / landing order: [independent / optional convenience order only, never a functional prerequisite]
-- Worktree notes: [branch naming, rebase expectations, or `None`]
-
-## Collision Resolution Records
-
-### Collision 1: [Shared file / schema / manifest / contract]
-- Involved spec sets: [[spec-name-1], [spec-name-2]]
-- Conflict shape: [same file / same symbol / same schema field / same generated artifact]
-- Pre-agreed resolution: [single owner / additive-only edits / split by section / move into one spec]
-- Allowed edits per spec: [exact ownership boundary]
-- Escalation rule: [when engineers must stop and re-coordinate]
-
-### Collision 2: [Shared file / schema / manifest / contract]
-- Involved spec sets: [[spec-name-1], [spec-name-2]]
-- Conflict shape: [same file / same symbol / same schema field / same generated artifact]
-- Pre-agreed resolution: [single owner / additive-only edits / split by section / move into one spec]
-- Allowed edits per spec: [exact ownership boundary]
-- Escalation rule: [when engineers must stop and re-coordinate]
 
-## Integration Checkpoints
-- Combined behaviors to verify after merge: [cross-spec outcome]
-- Required final test scope: [integration / E2E / migration / rollback]
-- Rollback notes: [how to contain partial batch rollout]
+### Collisions & Integration
 
-## Open Questions
-[Write `None` if the batch coordination is settled.]
-- [Question 1]
+- Shared files & edit rules: [which files require coordination and the pre-agreed rules per spec]
+- Shared API / schema freeze: [frozen owner + additive-only rule, or None]
+- Compatibility shim retention: [which adapters/flags/tests must remain until batch completion, or None]
+- Merge order: [independent / suggested convenience order only]
+- Integration checkpoints: [combined cross-spec behaviors to verify after merge]
+- Re-coordination trigger: [what change forces the batch to stop and re-align]

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

@@ -4,66 +4,49 @@
 - 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]
+- Why this exists: [why the batch cannot be parallelized without this prerequisite work]
+- Core business boundary: [No core business logic or target outcome is implemented here]
+- Depends on (specs): [[spec-name-1], [spec-name-2]]
+- Parallel work starts after: [commit / verification / approval of this preparation]
+- Out of scope: [member-spec implementation work that must remain in spec files]
+
+## **Task P1: [Preparation Task Title]**
+
+Purpose: [why this prerequisite is required before parallel work]
+Scope: [files/modules this task may touch]
+Out of scope: [core business logic, target outcome, member-spec behavior]
+
+- P1. [ ] **[file/function]** — **[specific modification; expected output]**
+  - Verify: [command/check/manual inspection]
+
+- P2. [ ] **[file/function]** — **[specific modification; expected output]**
+  - Verify: [command/check/manual inspection]
+
+## **Task P2: [Preparation Task Title]**
+
+Purpose: [why this prerequisite is required before parallel work]
+Scope: [files/modules this task may touch]
+Out of scope: [core business logic, target outcome, member-spec behavior]
+
+- P1. [ ] **[file/function]** — **[specific modification; expected output]**
+  - Verify: [command/check/manual inspection]
+
+- P2. [ ] **[file/function]** — **[specific modification; expected output]**
+  - Verify: [command/check/manual inspection]
+
+## Validation
+
+- Verification required: [commands/checks before subagents start]
+- Expected results: [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]
+## Handoff
+
+- Preparation commit required before parallel work: [Yes / No]
 - Member specs assume: [prepared baseline assumptions]
-- Member specs must not change: [prepared surfaces that are now frozen/additive-only]
+- Member specs must not change: [prepared surfaces now frozen or 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]
+- If preparation changes later: [stop and re-coordinate rule]

package/package.json

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

package/solve-issues-found-during-review/SKILL.md

@@ -9,6 +9,7 @@ description: Fix issues discovered during a review pass (review-change-set, revi
 
 - Required: none. This skill reads issues from a review report that must already exist or be supplied by the caller.
 - Conditional: `review-change-set` for re-validation after fixes when the fix set is code-affecting; `systematic-debug` when a fix attempt encounters unexpected test or runtime failures.
+- Conditional: When parallel sub-agents are available, the capability to merge changes from independent workspaces and resolve inter-workspace conflicts after parallel fix work.
 - Optional: `discover-edge-cases` to confirm edge-case coverage after fixing; `harden-app-security` to confirm security fixes are effective.
 - Fallback: If a required re-validation dependency is unavailable after a code-affecting fix, run `git diff --stat` and relevant tests manually and report what was verified.
 
@@ -39,9 +40,52 @@ Group findings into ordered buckets:
 
 Within each bucket, order by the reviewer's stated priority. If the review does not assign severity, treat architecture/business-goal gaps as High and simplification/style suggestions as Low.
 
-### 3) Fix findings from highest severity to lowest
+### 3) Classify findings by module and business logic chain
 
-For each finding in priority order:
+Before fixing, group findings by:
+
+- **Module**: which subsystem, component, or layer each finding belongs to.
+- **Business logic chain**: findings along the same data flow, request path, or feature pipeline.
+
+This classification determines which findings can be fixed independently in parallel and which share dependencies that require coordinated treatment.
+
+### 4) Deploy parallel fix work (when sub-agent capability is available)
+
+If the runtime supports spawning sub-agents with isolated workspaces:
+
+**a. Assign each module group to a sub-agent**
+
+- Group findings by the classification above. Each independent module or business chain becomes a work package.
+- Assign each work package to a sub-agent, giving it the relevant findings, the affected file paths, and the original review context.
+- Each sub-agent works in its own isolated workspace with no risk of interfering with others.
+
+**b. Sub-agents fix and validate their assigned findings**
+
+Each sub-agent independently:
+
+- Reads its assigned findings and the affected code.
+- Applies the minimal fix for each finding in severity order within its scope.
+- Validates correctness (tests, reproduction steps, linting) before marking findings as resolved.
+- Reports back which findings were fixed, deferred, or could not be reproduced, along with a summary of changes.
+
+**c. Consolidate and resolve conflicts**
+
+After all sub-agents complete:
+
+- Merge changes from each isolated workspace back into the main workspace, one at a time.
+- If conflicts arise, resolve them by keeping both sides of the fix intent — do not discard either party's changes unless they are truly contradictory.
+- When two fixes touch the same code, prefer the more conservative change (less behavioral deviation) unless the review finding explicitly demands the more aggressive one.
+- If a conflict cannot be resolved without deviating from the original fix intent, flag it for manual review and move on.
+
+**d. Re-validate after consolidation**
+
+Run all relevant tests across the consolidated changes to confirm the merged result is correct.
+
+If the runtime does **not** support sub-agents with isolated workspaces, fall back to fixing findings sequentially in severity order as described in the next step.
+
+### 5) Fix findings sequentially (fallback when sub-agents are unavailable)
+
+For each finding in priority order, when parallel sub-agent capability is not available:
 
 **a. Understand the finding and the fix target**
 
@@ -65,7 +109,7 @@ For each finding in priority order:
 
 Proceed to the next finding. Do not skip severity levels: finish all Critical findings before starting High, etc.
 
-### 4) Re-validate the full scope
+### 6) Re-validate the full scope
 
 When all findings have been processed:
 
@@ -73,7 +117,7 @@ When all findings have been processed:
 - Run all relevant tests across the changed files.
 - Run `git diff --stat` to produce a summary of what changed.
 
-### 5) Report the result
+### 7) Report the result
 
 Return: