@laitszkin/apollo-toolkit 3.6.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.

package/CHANGELOG.md

@@ -7,6 +7,15 @@ 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

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/package.json

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