@laitszkin/apollo-toolkit 3.6.0 → 3.6.2

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,20 @@ All notable changes to this repository are documented in this file.
 ### Added
 - (None yet)
 
+## [v3.6.2] - 2026-04-28
+
+### Changed
+- Normalize `AGENTS.md` references to `AGENTS.md/CLAUDE.md` across the skill catalog for CLAUDE.md awareness.
+
+## [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/archive-specs/SKILL.md

@@ -7,7 +7,7 @@ description: Convert completed project plan sets into maintainable project docum
 
 ## Dependencies
 
-- Required: `align-project-documents` to align repository docs with current code before archiving, and `maintain-project-constraints` to synchronize `AGENTS.md` after the doc update.
+- Required: `align-project-documents` to align repository docs with current code before archiving, and `maintain-project-constraints` to synchronize `AGENTS.md/CLAUDE.md` after the doc update.
 - Conditional: none.
 - Optional: none.
 - Fallback: not applicable.
@@ -15,9 +15,9 @@ description: Convert completed project plan sets into maintainable project docum
 ## Standards
 
 - Evidence: Treat code, config, deployment files, and current spec files as evidence sources; never guess when a detail is missing.
-- Execution: Inventory all relevant specs first, reconcile them with the current repository, use `align-project-documents` to update durable project docs, use `maintain-project-constraints` to refresh `AGENTS.md` when repository guidance changed, then archive only the truly consumed planning artifacts.
+- Execution: Inventory all relevant specs first, reconcile them with the current repository, use `align-project-documents` to update durable project docs, use `maintain-project-constraints` to refresh `AGENTS.md/CLAUDE.md` when repository guidance changed, then archive only the truly consumed planning artifacts.
 - Quality: Prefer source-of-truth behavior over stale plan text, align existing docs to the same standard structure, and call out unknowns explicitly instead of inventing missing setup details.
-- Output: Produce synchronized durable docs (`README.md`, categorized project docs, and `AGENTS.md` when needed), then archive or remove superseded spec files after the conversion is complete.
+- Output: Produce synchronized durable docs (`README.md`, categorized project docs, and `AGENTS.md/CLAUDE.md` when needed), then archive or remove superseded spec files after the conversion is complete.
 
 ## Goal
 
@@ -87,7 +87,7 @@ Ensure the split project docs cover all of the following:
 - `docs/README.md` should act as the reference list for the categorized docs.
 - Each category doc should stay focused on one topic instead of acting like another monolithic handbook.
 - Remove template placeholders and stale planning language before finishing.
-- After the docs are aligned, run `maintain-project-constraints` whenever the documentation changes imply `AGENTS.md` needs to reflect updated workflows, commands, or repository capabilities.
+- After the docs are aligned, run `maintain-project-constraints` whenever the documentation changes imply `AGENTS.md/CLAUDE.md` needs to reflect updated workflows, commands, or repository capabilities.
 
 ### 7) Archive superseded spec files after successful conversion
 

package/commit-and-push/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Commit and Push"
   short_description: "Submit local changes with commit and push only"
-  default_prompt: "Use $commit-and-push to inspect the current git state and classify the diff. Treat every conditional gate whose scenario is met as blocking before any commit: if the change set includes code changes, run $review-change-set; if the reviewed risk profile says edge-case or security review is needed, run $discover-edge-cases and $harden-app-security as blocking gates too; if completed specs should be converted or docs need normalization, ensure $archive-specs runs through $submission-readiness-check; if changelog synchronization is needed, complete it before continuing. Then run any additional required code-quality skills, hand the repository to $submission-readiness-check so it can synchronize completed plan archives, project docs, AGENTS.md, and CHANGELOG.md before any commit, confirm root CHANGELOG.md Unreleased reflects the actual pending change set, preserve user staging intent, create a concise Conventional Commit, and push to the intended branch without any versioning or release steps."
+  default_prompt: "Use $commit-and-push to inspect the current git state and classify the diff. Treat every conditional gate whose scenario is met as blocking before any commit: if the change set includes code changes, run $review-change-set; if the reviewed risk profile says edge-case or security review is needed, run $discover-edge-cases and $harden-app-security as blocking gates too; if completed specs should be converted or docs need normalization, ensure $archive-specs runs through $submission-readiness-check; if changelog synchronization is needed, complete it before continuing. Then run any additional required code-quality skills, hand the repository to $submission-readiness-check so it can synchronize completed plan archives, project docs, AGENTS.md/CLAUDE.md, and CHANGELOG.md before any commit, confirm root CHANGELOG.md Unreleased reflects the actual pending change set, preserve user staging intent, create a concise Conventional Commit, and push to the intended branch without any versioning or release steps."

package/feature-propose/README.md

@@ -7,8 +7,8 @@ It guides the agent to:
 2. Classify user-facing functions into MVP / Important / Enhancement / Performance.
 3. Propose numbered feature recommendations with clear implementation direction.
 4. Publish accepted proposals through `open-github-issue` with reason and suggested architecture.
-5. Record accepted feature proposals in `AGENTS.md`.
-6. Remove implemented proposals from `AGENTS.md` after delivery.
+5. Record accepted feature proposals in `AGENTS.md/CLAUDE.md`.
+6. Remove implemented proposals from `AGENTS.md/CLAUDE.md` after delivery.
 
 ## Repository layout
 

package/feature-propose/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: feature-propose
-description: Professional product-management workflow for proposing features from an existing codebase. Use when the user asks to understand an application, classify features from a user perspective into MVP/Important/Enhancement/Performance tiers, ask 3-5 clarifying questions when needed, propose numbered feature recommendations, publish accepted proposals through `open-github-issue`, record accepted items in AGENTS.md, and remove implemented items from AGENTS.md.
+description: Professional product-management workflow for proposing features from an existing codebase. Use when the user asks to understand an application, classify features from a user perspective into MVP/Important/Enhancement/Performance tiers, ask 3-5 clarifying questions when needed, propose numbered feature recommendations, publish accepted proposals through `open-github-issue`, record accepted items in AGENTS.md/CLAUDE.md, and remove implemented items from AGENTS.md/CLAUDE.md.
 ---
 
 # Feature Propose
@@ -10,7 +10,7 @@ description: Professional product-management workflow for proposing features fro
 - Required: none.
 - Conditional: `open-github-issue` for accepted features that should be published as GitHub issues.
 - Optional: none.
-- Fallback: If issue publication is skipped or unavailable, keep accepted proposals synchronized in `AGENTS.md` and report the publication state explicitly.
+- Fallback: If issue publication is skipped or unavailable, keep accepted proposals synchronized in `AGENTS.md/CLAUDE.md` and report the publication state explicitly.
 
 ## Standards
 
@@ -21,7 +21,7 @@ description: Professional product-management workflow for proposing features fro
 
 ## Overview
 
-Act as a professional PM: build a complete understanding of the current product from code, classify capabilities by user value, propose prioritized features, publish accepted proposals through `open-github-issue`, persist accepted proposals in `AGENTS.md`, and keep the list clean by removing implemented items.
+Act as a professional PM: build a complete understanding of the current product from code, classify capabilities by user value, propose prioritized features, publish accepted proposals through `open-github-issue`, persist accepted proposals in `AGENTS.md/CLAUDE.md`, and keep the list clean by removing implemented items.
 
 ## References
 
@@ -36,7 +36,7 @@ Load these references as needed during classification:
 
 ### 1) Explore the codebase before proposing anything
 
-- Read repo-level guidance first (`AGENTS.md`, `README`, major docs).
+- Read repo-level guidance first (`AGENTS.md/CLAUDE.md`, `README`, major docs).
 - Map architecture, entrypoints, user-facing flows, data models, and external integrations.
 - Identify implemented features, obvious gaps, and technical constraints from code and tests.
 - Summarize findings before moving to prioritization.
@@ -72,17 +72,17 @@ Load these references as needed during classification:
   - Acceptance criteria
 - Keep proposals focused and minimal; avoid over-engineering.
 
-### 5) Persist accepted features to AGENTS.md, publish them, and clean up after implementation
+### 5) Persist accepted features to AGENTS.md/CLAUDE.md, publish them, and clean up after implementation
 
 - Ask the user to accept/reject/edit features by number.
-- Once accepted, update repo-root `AGENTS.md` with a dedicated section:
+- Once accepted, update repo-root `AGENTS.md/CLAUDE.md` with a dedicated section:
   - `## Accepted Feature Proposals`
 - Append accepted features as a numbered list with:
   - Date (`YYYY-MM-DD`)
   - Type (`MVP`, `Important`, `Enhancement`, `Performance`)
   - Short feature statement
-- Preserve existing `AGENTS.md` content and style; do not rewrite unrelated sections.
-- If `AGENTS.md` does not exist, ask before creating it.
+- Preserve existing `AGENTS.md/CLAUDE.md` content and style; do not rewrite unrelated sections.
+- If `AGENTS.md/CLAUDE.md` does not exist, ask before creating it.
 - For each accepted feature, invoke `open-github-issue` exactly once with feature-proposal content.
 - Default to publishing accepted features unless the user explicitly says not to create GitHub issues.
 - Pass these fields to `open-github-issue`:
@@ -94,7 +94,7 @@ Load these references as needed during classification:
   - `repo`: target repository in `owner/repo` format when known
 - If invoking the publisher CLI directly, pass accepted proposal details through `apltk open-github-issue --payload-file <json>` or `@file` inputs rather than inline shell arguments so Markdown and code identifiers remain literal.
 - Reuse the returned `mode`, `issue_url`, and `publish_error` in the response.
-- After the related feature is implemented, remove that feature entry from `## Accepted Feature Proposals` in `AGENTS.md`.
+- After the related feature is implemented, remove that feature entry from `## Accepted Feature Proposals` in `AGENTS.md/CLAUDE.md`.
 - Remove only implemented items; keep unimplemented accepted items untouched.
 
 ## Output template

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: