@laitszkin/apollo-toolkit 2.14.5 → 2.14.7

package/AGENTS.md

@@ -12,7 +12,7 @@
 This repository enables users to install and run a curated set of reusable agent skills for software delivery, research, repository maintenance, and media-generation workflows.
 
 - Users can align project documentation with the current codebase.
-- Users can consolidate completed project specs into a standardized README and categorized project documentation set, then archive the consumed planning files.
+- Users can consolidate completed project specs and batch-level coordination plans into a standardized README and categorized project documentation set, then archive only the truly consumed planning files.
 - Users can investigate application logs, slice them to precise time windows, search by keyword or regex, and produce evidence-backed root-cause findings.
 - Users can answer repository-backed questions with additional web research when needed.
 - Users can commit and push local changes without performing version or release work.
@@ -22,7 +22,7 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can turn a marked weekly finance PDF into a concise evidence-based financial event report.
 - Users can install Apollo Toolkit through npm or npx and interactively choose one or more target skill directories to populate with copied skills.
 - Users can design and implement new features through a spec-first workflow.
-- Users can generate shared feature spec, task, and checklist planning artifacts for approval-gated workflows.
+- 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 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

@@ -4,6 +4,20 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.14.7] - 2026-04-08
+
+### Changed
+- Update `merge-changes-from-local-branches` so it removes successfully merged source branches and any detached worktrees only after the merge commit and verification both succeed, while refusing forced deletion for branches that are not actually merged.
+
+## [v2.14.6] - 2026-04-08
+
+### Added
+- Add batch-level `coordination.md` support to `generate-spec` so one planning request can create multiple parallel spec workstreams under `docs/plans/{YYYY-MM-DD}/{batch_name}/`, while keeping shared field preparation, ownership boundaries, merge order, and legacy-replacement direction in one canonical coordination file.
+
+### Changed
+- Update `develop-new-features`, `enhance-existing-features`, and `implement-specs-with-worktree` so multi-spec worktree execution reads and maintains shared `coordination.md` state instead of duplicating cross-spec rules inside each `design.md`.
+- Update `archive-specs` and `recover-missing-plan` so the newer nested `docs/plans/{YYYY-MM-DD}/...` layout and batch-level `coordination.md` files are recognized during archival, reconciliation, and recovery workflows.
+
 ## [v2.14.5] - 2026-04-08
 
 ### Changed

package/README.md

@@ -147,7 +147,7 @@ The install commands below were checked with the Skills CLI unless otherwise not
 
 Compatibility note:
 
-- `generate-spec` is a local skill used by `develop-new-features` and `enhance-existing-features`.
+- `generate-spec` is a local skill used by `develop-new-features` and `enhance-existing-features`, and it can produce either a single spec set under `docs/plans/{YYYY-MM-DD}/{change_name}/` or a coordinated parallel batch under `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` with shared `coordination.md`.
 - `recover-missing-plan` is a local skill used by `enhance-existing-features` and `ship-github-issue-fix` when a referenced `docs/plans/...` spec set is missing or archived.
 - `maintain-skill-catalog` can conditionally use `find-skills`, but its install source is not verified in this repository, so it is intentionally omitted from the table.
 - `read-github-issue` uses GitHub CLI (`gh`) directly for remote issue discovery and inspection, so it does not add any extra skill dependency.

package/archive-specs/README.md

@@ -1,14 +1,15 @@
 # archive-specs
 
-A documentation skill that converts completed spec files into standardized project docs and archives the consumed planning files. It produces a concise `README.md` plus a categorized document set grounded in real repository evidence.
+A documentation skill that converts completed spec files and batch-level coordination files into standardized project docs and archives the consumed planning files. It produces a concise `README.md` plus a categorized document set grounded in real repository evidence.
 
 ## Core capabilities
 
-- Scans `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` collections as documentation input.
+- Scans `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md`, and batch-level `coordination.md` collections as documentation input.
 - Reconciles spec claims against code, config, scripts, and deployment files.
 - Standardizes both new and existing project docs into topic-based files for setup, configuration, architecture, features, and developer onboarding.
 - Provides dedicated reference templates for the top-level README, the documentation index/reference list, and each category document.
 - Archives superseded spec source files after a successful conversion, and deletes them only when the repository clearly does not need historical retention.
+- Preserves active batch coordination files until no remaining spec set still depends on their shared preparation or replacement direction.
 - Keeps unknown or unverifiable details explicit instead of guessing.
 
 ## Repository layout

package/archive-specs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: archive-specs
-description: Convert completed project plan sets into maintainable project documentation and archive the consumed planning files. Use when users want to consolidate `spec.md`/`tasks.md`/`checklist.md`/`contract.md`/`design.md` files into evidence-backed docs covering installation and deployment, configuration, external service setup, architecture, feature introductions, and developer onboarding context.
+description: Convert completed project plan sets into maintainable project documentation and archive the consumed planning files. Use when users want to consolidate `spec.md`/`tasks.md`/`checklist.md`/`contract.md`/`design.md` and any batch-level `coordination.md` into evidence-backed docs covering installation and deployment, configuration, external service setup, architecture, feature introductions, and developer onboarding context.
 ---
 
 # Archive Specs
@@ -27,7 +27,7 @@ Convert completed planning artifacts into stable, standardized project documenta
 
 ### 1) Inventory documentation sources
 
-- Find all relevant planning files such as `docs/plans/**/spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md`.
+- Find all relevant planning files such as `docs/plans/**/spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md`, and any batch-level `coordination.md`.
 - Read existing `README*`, deployment scripts, manifests, env examples, infra files, CI configs, and representative source modules.
 - Build a source map for setup commands, environments, external services, module boundaries, and implemented features.
 
@@ -40,6 +40,7 @@ Convert completed planning artifacts into stable, standardized project documenta
   4. existing docs
 - When specs disagree with the codebase, keep the codebase truth and note the mismatch while updating docs.
 - Merge repeated or overlapping feature descriptions into one stable capability summary.
+- Use `coordination.md` to understand shared preparation, ownership boundaries, legacy cutover direction, and which old features or paths were intentionally replaced across multiple spec sets.
 - Distinguish between completed scope that should become durable docs and still-active scope that remains planning material for follow-up work.
 
 ### 3) Standardize existing project docs into categorized outputs
@@ -91,11 +92,12 @@ Ensure the split project docs cover all of the following:
 ### 7) Archive superseded spec files after successful conversion
 
 - After the standardized project docs are complete and verified, archive the old source spec files that were converted.
-- Prefer moving the consumed `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` files, or their containing plan directory, into a clearly marked archive path instead of leaving them mixed with active docs.
+- Prefer moving the consumed `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md`, and when applicable their shared `coordination.md`, or the containing batch/spec plan directory, into a clearly marked archive path instead of leaving them mixed with active docs.
 - Delete converted spec files only when the repository clearly does not need historical retention.
 - Do not archive or delete any spec file that is still actively needed for unfinished implementation work.
 - Treat a spec file as active when it still records pending gaps, planned later phases, follow-up integration work, or unresolved design decisions for the same change, even if one implementation commit has already shipped.
 - If only part of a plan set is complete, convert or summarize only the truly completed scope and leave the active plan set in place unless the repository has a separate archival convention for partial phases.
+- If only part of a coordinated batch is complete, archive only the fully consumed spec subdirectories and keep the batch-level `coordination.md` active until no remaining spec set relies on it.
 
 ## Working Rules
 
@@ -105,6 +107,7 @@ Ensure the split project docs cover all of the following:
 - When a section cannot be completed from evidence, keep an explicit `Unknown` or `TBD (missing repository evidence)` marker.
 - The final repository state should not keep both standardized docs and redundant active spec files for the same completed scope.
 - Do not equate "code was committed" with "planning scope is complete"; archive only when the remaining notes no longer guide future implementation.
+- Do not archive a batch `coordination.md` while it still governs active replacement work, shared field preparation, or unresolved cross-spec merge sequencing.
 
 ## References
 

package/archive-specs/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "archive-specs"
   short_description: "Convert completed specs into project docs and archive the consumed plans"
-  default_prompt: "Use $archive-specs to inventory the project's spec.md/tasks.md/checklist.md/contract.md/design.md files, reconcile them with the current repository, rewrite existing project docs into a standardized categorized structure when needed, generate or update a concise README plus split project docs for getting started, configuration, architecture, features, and developer guidance, maintain a docs/README.md reference list, then archive the consumed source plans after successful conversion, deleting them only when the repository clearly does not need historical retention."
+  default_prompt: "Use $archive-specs to inventory the project's spec.md/tasks.md/checklist.md/contract.md/design.md files plus any batch-level coordination.md, reconcile them with the current repository, use coordination.md to understand shared preparation and legacy-replacement direction across parallel plan sets, rewrite existing project docs into a standardized categorized structure when needed, generate or update a concise README plus split project docs for getting started, configuration, architecture, features, and developer guidance, maintain a docs/README.md reference list, then archive the consumed source plans after successful conversion, deleting them only when the repository clearly does not need historical retention and keeping coordination.md active while any spec set still depends on it."

package/develop-new-features/README.md

@@ -30,10 +30,11 @@ A spec-first feature development skill for new behavior and greenfield work. It
 ## Workflow summary
 
 1. Review only the official docs and code paths needed for the feature.
-2. Run `generate-spec` to create and maintain `docs/plans/{YYYY-MM-DD}_{change_name}/`.
+2. Run `generate-spec` to create and maintain `docs/plans/{YYYY-MM-DD}/{change_name}/`, or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` plus `coordination.md` for parallel batches.
 3. Wait for explicit approval on the spec set.
 4. Implement the approved behavior with minimal changes.
 5. Run risk-driven tests and backfill `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md`.
+6. For parallel batches, keep shared preparation and replacement direction in `coordination.md`.
 
 ## Testing expectations
 

package/develop-new-features/SKILL.md

@@ -60,11 +60,13 @@ Use a shared spec-generation workflow for non-trivial new feature work, then imp
 - If the requested change would require edits across more than three modules, do not force it into one oversized spec set.
 - Instead, split the work into multiple independent spec sets, each covering no more than three modules.
 - Define those spec sets so they do not conflict with each other and do not depend on another spec set being implemented first in order to be valid.
+- When multiple spec sets belong to one coordinated feature batch, place them under `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` and create one shared `coordination.md` at the batch root for shared preparation, ownership boundaries, replacement direction, and merge order.
 - Follow `$generate-spec` completely for:
-  - generating `docs/plans/{YYYY-MM-DD}_{change_name}/spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md`
+  - generating `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 parallel batches
   - filling BDD requirements and risk-driven test plans
   - documenting external dependency contracts in `contract.md` when they materially constrain the feature
   - documenting the architecture/design delta in `design.md`
+  - documenting shared preparation and implementation direction in `coordination.md` when multiple spec sets will be implemented in parallel
   - handling clarification responses
   - obtaining explicit approval before coding
   - backfilling document status after implementation and testing, including requirement completion in `spec.md`
@@ -111,6 +113,7 @@ Rules:
 ### 6) Completion updates
 
 - Backfill `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` through `$generate-spec` workflow after implementation and testing.
+- If the feature used a parallel batch, also backfill `coordination.md` with any final shared preparation, cutover, or ownership changes that emerged during execution.
 - In `spec.md`, mark each approved requirement with its actual completion state, such as completed, partially completed, deferred, or not implemented, plus brief evidence or rationale where needed.
 - Mark every completed task in `tasks.md`.
 - In `checklist.md`, update only the items that are actually applicable to the approved scope and executed validation.
@@ -126,6 +129,7 @@ Rules:
 - By default, write planning docs in the user's language.
 - Keep implementation traceable to approved requirement IDs and planned risks.
 - Keep each spec set limited to at most three modules; split larger changes into independent, non-conflicting, non-dependent spec sets before approval.
+- When multiple spec sets are used for one feature batch, keep cross-spec rules in `coordination.md` rather than repeating them in every `design.md`.
 - Prefer realism over rigid templates: add or remove test coverage only when the risk profile justifies it.
 - Every planned test should justify a distinct risk; remove shallow duplicates that only prove the code "still runs".
 - Treat starter template alternatives as mutually exclusive options, not as boxes that all need to be checked.

package/develop-new-features/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Develop New Features"
   short_description: "Spec-first feature development that depends on generate-spec"
-  default_prompt: "Use $develop-new-features to design new behavior through a spec-first workflow: review the required external docs, run $generate-spec to create and maintain docs/plans/<date>_<change_name>/{spec.md,tasks.md,checklist.md,contract.md,design.md}, wait for explicit approval, document material external dependency contracts in contract.md, document the architecture/design delta in design.md, then complete the approved implementation end-to-end with risk-driven tests and full backfill of spec.md, tasks.md, checklist.md, contract.md, and design.md before yielding, unless the user changes scope or an external blocker prevents safe completion."
+  default_prompt: "Use $develop-new-features to design new behavior through a spec-first workflow: review the required external docs, run $generate-spec to create and maintain docs/plans/<date>/<change_name>/... for single-spec work or docs/plans/<date>/<batch_name>/<change_name>/... plus coordination.md for parallel batches, wait for explicit approval, document material external dependency contracts in contract.md, document the architecture/design delta in design.md, record shared preparation and legacy-replacement direction in coordination.md when multiple specs will be implemented in parallel, then complete the approved implementation end-to-end with risk-driven tests and full backfill of spec.md, tasks.md, checklist.md, contract.md, design.md, and when applicable coordination.md before yielding, unless the user changes scope or an external blocker prevents safe completion."

package/enhance-existing-features/CHANGELOG.md

@@ -10,7 +10,7 @@ All notable changes to this project are documented in this file.
 - Added explicit rule that test coverage is required even when specs are not used.
 
 ### Added
-- Added `scripts/create-specs` for generating specs into `docs/plans/{YYYY-MM-DD}_{change_name}/`.
+- Added `scripts/create-specs` for generating specs into `docs/plans/{YYYY-MM-DD}/{change_name}/`.
 - Added reusable templates under `references/templates/`.
 
 ## [v0.1.2] - 2026-02-12

package/enhance-existing-features/README.md

@@ -34,6 +34,7 @@ A brownfield feature-extension skill: map dependencies first, decide whether sha
 3. Wait for explicit approval if planning docs were generated.
 4. Implement the smallest safe brownfield change.
 5. Run risk-driven tests and backfill `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` when specs exist.
+6. If the work is split into parallel spec sets, maintain one batch-level `coordination.md` for shared preparation, ownership, and replacement direction.
 
 ## Test requirements
 

package/enhance-existing-features/SKILL.md

@@ -66,10 +66,11 @@ When in doubt, prefer direct implementation for genuinely low-risk localized cha
 If triggered:
 - If the user already points to a specific `docs/plans/...` path and that plan set is missing or mismatched in the current workspace, run `$recover-missing-plan` before deciding whether to continue implementation or backfill.
 - Run `$generate-spec` and follow its workflow completely.
-- Use it to create or update `docs/plans/{YYYY-MM-DD}_{change_name}/spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md`.
+- Use it to create or update `docs/plans/{YYYY-MM-DD}/{change_name}/spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md`.
 - Keep each spec set scoped to at most three modules.
 - If the requested change would require edits across more than three modules, split it into multiple spec sets instead of drafting one large coupled plan.
 - Design the split spec sets so they are independently valid, do not conflict with each other, and do not require another spec set to land first.
+- When multiple spec sets are created for one coordinated change, place them under `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` and maintain one batch-level `coordination.md` that records shared preparation, ownership boundaries, replacement direction, and merge order.
 - Ensure planned behaviors and edge cases cover external dependency states, abuse/adversarial paths, and any relevant authorization/idempotency/concurrency/data-integrity risks.
 - When external dependencies materially constrain the change, make sure `contract.md` captures their official-source-backed invocation surface, constraints, and caller obligations.
 - Make sure `design.md` captures the architecture/design delta, affected modules, control flow, and tradeoff decisions for the approved scope.
@@ -124,6 +125,7 @@ Rules:
 ### 6) Completion updates
 
 - If specs were used, backfill `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` through `$generate-spec` workflow based on actual completion and test outcomes.
+- If the change used a parallel batch, update `coordination.md` whenever shared preparation, legacy replacement direction, or merge constraints changed during execution.
 - In `spec.md`, mark each relevant requirement with its actual completion state, such as completed, partially completed, deferred, or not implemented, plus brief evidence or rationale where needed.
 - If specs were used, mark every completed task in `tasks.md`.
 - If specs were used, update only the applicable checklist items that correspond to real scope, chosen test strategy, and actual execution.
@@ -139,6 +141,7 @@ Rules:
 - Keep the solution minimal and executable.
 - Always decide the need for specs only after exploring the existing codebase.
 - When specs are used, keep each spec set limited to at most three modules; split broader work into independent, non-conflicting, non-dependent spec sets before approval.
+- When specs are split for parallel worktree implementation, keep batch-wide rules only in `coordination.md` rather than copying them into every spec-local `design.md`.
 - Maintain traceability between requirements, tasks, and tests when specs are present.
 - Treat checklists as living artifacts: adjust items to match real change scope.
 - Treat mutually exclusive template choices as a decision to record, not multiple boxes to finish.

package/enhance-existing-features/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "enhance-existing-features"
   short_description: "Extend brownfield features with conditional generate-spec planning and risk-driven tests"
-  default_prompt: "Use $enhance-existing-features to extend a brownfield feature: map the affected code and dependencies first, decide whether the change is high complexity / critical module / cross-module, run $generate-spec when specs are required, wait for explicit approval before coding, document material external dependency contracts in contract.md, document the architecture/design delta in design.md, and always add risk-driven tests plus clear N/A reasons when a category truly does not apply; if a spec set exists, finish the approved tasks and applicable checklist items and backfill spec.md, tasks.md, checklist.md, contract.md, and design.md before yielding unless the user changes scope or an external blocker prevents safe completion."
+  default_prompt: "Use $enhance-existing-features to extend a brownfield feature: map the affected code and dependencies first, decide whether the change is high complexity / critical module / cross-module, run $generate-spec when specs are required, wait for explicit approval before coding, document material external dependency contracts in contract.md, document the architecture/design delta in design.md, and when one change is split into parallel spec sets maintain a shared coordination.md for common preparation, ownership boundaries, and legacy-replacement direction; always add risk-driven tests plus clear N/A reasons when a category truly does not apply; if a spec set exists, finish the approved tasks and applicable checklist items and backfill spec.md, tasks.md, checklist.md, contract.md, design.md, and when applicable coordination.md before yielding unless the user changes scope or an external blocker prevents safe completion."

package/generate-spec/README.md

@@ -1,10 +1,11 @@
 # generate-spec
 
-A shared planning skill for feature work. It centralizes creation and maintenance of `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` so other skills can reuse one consistent approval-gated spec workflow.
+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.
 
 ## Core capabilities
 
-- Generates `docs/plans/{YYYY-MM-DD}_{change_name}/spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` in one step.
+- 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`.
 - 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.
@@ -26,7 +27,8 @@ A shared planning skill for feature work. It centralizes creation and maintenanc
 │       ├── tasks.md
 │       ├── checklist.md
 │       ├── contract.md
-│       └── design.md
+│       ├── design.md
+│       └── coordination.md
 └── scripts/
     └── create-specs
 ```
@@ -42,10 +44,10 @@ python3 "$SKILL_ROOT/scripts/create-specs" "Membership upgrade flow" \
   --output-dir "$WORKSPACE_ROOT/docs/plans"
 ```
 
-Default output:
+Single-spec output:
 
 ```text
-docs/plans/<today>_membership-upgrade-flow/
+docs/plans/<today>/membership-upgrade-flow/
 ├── spec.md
 ├── tasks.md
 ├── checklist.md
@@ -53,6 +55,28 @@ docs/plans/<today>_membership-upgrade-flow/
 └── design.md
 ```
 
+Parallel batch output:
+
+```bash
+python3 "$SKILL_ROOT/scripts/create-specs" "Membership write path" \
+  --change-name membership-write-path \
+  --batch-name membership-cutover \
+  --with-coordination \
+  --template-dir "$SKILL_ROOT/references/templates" \
+  --output-dir "$WORKSPACE_ROOT/docs/plans"
+```
+
+```text
+docs/plans/<today>/membership-cutover/
+├── coordination.md
+└── membership-write-path/
+    ├── spec.md
+    ├── tasks.md
+    ├── checklist.md
+    ├── contract.md
+    └── design.md
+```
+
 ## Authoring rules
 
 - `spec.md`: use BDD keywords `GIVEN / WHEN / THEN / AND / Requirements`.
@@ -60,9 +84,10 @@ docs/plans/<today>_membership-upgrade-flow/
 - `checklist.md`: use `- [ ]` only, adapt items to real scope, and record actual results.
 - `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, merge order, and cross-spec integration checkpoints.
 - If clarification responses change the plan, update the docs and obtain approval again before coding.
 
 ## Notes
 
 - `scripts/...` and `references/...` are skill-folder paths, not project-folder paths.
-- The generator replaces `[YYYY-MM-DD]`, `[Feature Name]`, `[功能名稱]`, and `[change_name]` placeholders.
+- The generator replaces `[YYYY-MM-DD]`, `[Feature Name]`, `[功能名稱]`, `[change_name]`, and `[batch_name]` placeholders.

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`) from standard templates with clarification tracking, approval gating, and post-implementation backfill. Use when a workflow needs specs before coding, or when another skill needs to create/update `docs/plans/{YYYY-MM-DD}_{change_name}/` planning docs.
+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, 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
@@ -17,7 +17,7 @@ description: Generate and maintain shared feature planning artifacts (`spec.md`,
 - Evidence: Review the relevant code, configs, and authoritative docs before filling requirements or test plans; when external dependencies, libraries, frameworks, APIs, or platforms are involved, checking their official documentation is mandatory during spec creation.
 - Execution: Generate the planning files first, keep each spec set tightly scoped, split broader work into multiple independent spec sets when needed, 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, map each planned test to a concrete risk or requirement, and tailor the templates so only applicable items remain active.
-- Output: Store planning artifacts under `docs/plans/{YYYY-MM-DD}_{change_name}/` and keep them concise, executable, and easy to update.
+- 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, and keep them concise, executable, and easy to update.
 
 ## Goal
 
@@ -49,13 +49,17 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
   - `SKILL_ROOT=<path_to_generate-spec_skill>`
   - `WORKSPACE_ROOT=<target_project_root>`
   - `python3 "$SKILL_ROOT/scripts/create-specs" "<feature_name>" --change-name <kebab-case> --template-dir "$SKILL_ROOT/references/templates" --output-dir "$WORKSPACE_ROOT/docs/plans"`
+- For parallel multi-spec generation, also use:
+  - `--batch-name <kebab-case-batch-name>`
+  - `--with-coordination`
 - Always generate:
   - `references/templates/spec.md`
   - `references/templates/tasks.md`
   - `references/templates/checklist.md`
   - `references/templates/contract.md`
   - `references/templates/design.md`
-- Save files under `docs/plans/{YYYY-MM-DD}_{change_name}/`.
+- Generate `references/templates/coordination.md` at the batch root when multiple spec sets are intentionally created for parallel implementation.
+- Save files under `docs/plans/{YYYY-MM-DD}/{change_name}/` or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/`.
 
 ### 3) Fill `spec.md`
 
@@ -87,6 +91,17 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Identify the affected modules, current baseline, proposed architecture, component responsibilities, control flow, data/state impact, and risk/tradeoff decisions.
 - 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` and keep `design.md` focused on the single-spec delta rather than duplicating cross-spec ownership rules.
+
+### 6.5) Fill `coordination.md` for parallel multi-spec batches
+
+- Create `coordination.md` only when one user request is intentionally split into multiple spec sets that may be implemented in parallel.
+- Place it at `docs/plans/{YYYY-MM-DD}/{batch_name}/coordination.md`.
+- Use it as the batch-level source of truth for shared preparation, ownership boundaries, merge order, and cross-spec constraints.
+- Record shared fields, shared contracts, or shared data-shape preparation that multiple spec sets must align on before implementation starts.
+- 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.
+- Keep single-spec concerns in that spec's own `design.md`; reserve `coordination.md` for batch-wide rules only.
 
 ### 7) Fill `checklist.md`
 
@@ -114,6 +129,7 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Update `checklist.md` with real test outcomes, `N/A` reasons, and any scope adjustments.
 - 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.
 - 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.
@@ -126,6 +142,7 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Keep requirement IDs, task IDs, and test IDs traceable across all three files.
 - 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.
+- 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`.
 - 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.
 - `design.md` is required and must describe the architecture/design delta for the spec in the standardized format, even when the final design is intentionally minimal.
@@ -143,3 +160,4 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - `references/templates/checklist.md`: behavior-to-test alignment template.
 - `references/templates/contract.md`: external dependency contract template.
 - `references/templates/design.md`: architecture/design delta template.
+- `references/templates/coordination.md`: parallel batch coordination 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 docs/plans/<date>_<change_name>/{spec.md,tasks.md,checklist.md,contract.md,design.md} from shared templates, fill BDD requirements and risk-driven test planning, document external dependency contracts in contract.md when they materially constrain the change, write the architecture/design delta in design.md, process clarification updates, and wait for explicit approval before implementation."
+  default_prompt: "Use $generate-spec to create or update single-spec plans under docs/plans/<date>/<change_name>/ or parallel batches under docs/plans/<date>/<batch_name>/<change_name>/ with a shared coordination.md, fill BDD requirements and risk-driven test planning, document external dependency contracts in contract.md when they materially constrain the change, write the architecture/design delta in design.md, record shared preparation and legacy-replacement direction in coordination.md when multiple specs will be implemented in parallel, process clarification updates, and wait for explicit approval before implementation."

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

@@ -0,0 +1,58 @@
+# Coordination: [Feature Name]
+
+- Date: [YYYY-MM-DD]
+- Batch: [batch_name]
+
+## Coordination Goal
+[Describe the shared implementation goal across this batch of parallel spec sets.]
+
+## Batch Scope
+- Included spec sets: [[spec-name-1], [spec-name-2]]
+- Shared outcome: [what the batch delivers when all spec sets land]
+- Out of scope: [shared exclusions for the batch]
+
+## Shared Context
+- Current baseline: [the current system shape that all spec sets must assume]
+- Shared constraints: [runtime, rollout, compatibility, or ownership constraints]
+- Shared invariants: [rules every spec set must preserve]
+
+## 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]
+
+### 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]
+- Cleanup required after cutover: [delete flag / remove adapter / drop old field / remove old tests]
+
+## Spec Ownership Map
+
+### Spec Set 1: [spec-name-1]
+- Primary concern: [what this spec owns]
+- Allowed touch points: [files/modules it may change]
+- Must not change: [files/modules owned by another spec unless explicitly coordinated]
+- Depends on shared preparation: [None / specific shared item above]
+
+### 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]
+
+## Conflict Boundaries
+- Shared files requiring coordination: [file/module list or `None`]
+- Merge order / landing order: [independent / explicit order]
+- Worktree notes: [branch naming, rebase expectations, or `None`]
+
+## Integration Checkpoints
+- Combined behaviors to verify after merge: [cross-spec outcome]
+- Required final test scope: [integration / E2E / migration / rollback]
+- Rollback notes: [how to contain partial batch rollout]
+
+## Open Questions
+[Write `None` if the batch coordination is settled.]
+- [Question 1]

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

@@ -16,6 +16,7 @@
 - Spec requirements covered: [R?.?]
 - Affected modules: [module/file/service list]
 - External contracts involved: [dependency names from `contract.md`, or `None`]
+- Coordination reference: [`../coordination.md` or `None`]
 
 ## Current Architecture
 [Describe the relevant current components, data flow, control flow, and boundaries.]

package/generate-spec/scripts/create-specs

@@ -13,6 +13,7 @@ TEMPLATE_FILENAMES = (
     "contract.md",
     "design.md",
 )
+COORDINATION_TEMPLATE = "coordination.md"
 PLACEHOLDERS = ("[Feature Name]", "[功能名稱]")
 
 
@@ -27,11 +28,18 @@ def _default_template_dir() -> Path:
     return Path(__file__).resolve().parent.parent / "references" / "templates"
 
 
-def _render(content: str, today: str, feature_name: str, change_name: str) -> str:
+def _render(
+    content: str,
+    today: str,
+    feature_name: str,
+    change_name: str,
+    batch_name: str | None,
+) -> str:
     rendered = content.replace("[YYYY-MM-DD]", today)
     for placeholder in PLACEHOLDERS:
         rendered = rendered.replace(placeholder, feature_name)
     rendered = rendered.replace("[change_name]", change_name)
+    rendered = rendered.replace("[batch_name]", batch_name or "None")
     return rendered
 
 
@@ -39,7 +47,8 @@ def main() -> int:
     parser = argparse.ArgumentParser(
         description=(
             "Create planning docs (spec.md, tasks.md, checklist.md, contract.md, design.md) "
-            "from templates with folder format docs/plans/{date}_{change_name}."
+            "from templates with folder format docs/plans/{date}/{change_name} "
+            "or docs/plans/{date}/{batch_name}/{change_name}."
         ),
     )
     parser.add_argument("feature_name", help="Display name used in generated documents")
@@ -52,6 +61,21 @@ def main() -> int:
             "Defaults to slugified feature_name when omitted."
         ),
     )
+    parser.add_argument(
+        "--batch-name",
+        help=(
+            "Optional batch folder used for parallel spec generation. "
+            "When provided, specs are written under docs/plans/{date}/{batch_name}/{change_name}."
+        ),
+    )
+    parser.add_argument(
+        "--with-coordination",
+        action="store_true",
+        help=(
+            "When used with --batch-name, also create or update "
+            "docs/plans/{date}/{batch_name}/coordination.md from the shared template."
+        ),
+    )
     parser.add_argument(
         "--output-dir",
         default="docs/plans",
@@ -81,6 +105,10 @@ def main() -> int:
             "Unable to build change_name. Provide --change-name with ASCII letters/numbers."
         )
 
+    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")
+
     template_dir = Path(args.template_dir).expanduser().resolve()
     if not template_dir.exists() or not template_dir.is_dir():
         raise SystemExit(f"Template directory not found: {template_dir}")
@@ -88,15 +116,22 @@ def main() -> int:
     missing_templates = [
         name for name in TEMPLATE_FILENAMES if not (template_dir / name).exists()
     ]
+    if args.with_coordination and not (template_dir / COORDINATION_TEMPLATE).exists():
+        missing_templates.append(COORDINATION_TEMPLATE)
     if missing_templates:
         missing = ", ".join(missing_templates)
         raise SystemExit(f"Missing template files in {template_dir}: {missing}")
 
     output_dir = Path(args.output_dir).expanduser().resolve()
     today = date.today().isoformat()
-    output_root = output_dir / f"{today}_{change_name}"
+    date_root = output_dir / today
+    batch_root = date_root / batch_name if batch_name else None
+    output_root = (batch_root / change_name) if batch_root else (date_root / change_name)
 
     output_paths = [output_root / name for name in TEMPLATE_FILENAMES]
+    coordination_path = (
+        batch_root / COORDINATION_TEMPLATE if args.with_coordination 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)
@@ -116,12 +151,28 @@ def main() -> int:
                 today=today,
                 feature_name=feature_name,
                 change_name=change_name,
+                batch_name=batch_name,
+            ),
+            encoding="utf-8",
+        )
+
+    if coordination_path and (args.force or not coordination_path.exists()):
+        coordination_template = template_dir / COORDINATION_TEMPLATE
+        coordination_path.write_text(
+            _render(
+                content=coordination_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)
     return 0
 
 

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

@@ -2,7 +2,8 @@
 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}/` and implement the approved tasks
+  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. 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 main working tree. If not already in a worktree, create a new
@@ -34,15 +35,17 @@ Implement approved spec planning sets in an isolated git worktree, ensuring main
 
 ### 1) Identify and read the specs set
 
-- Locate the specs directory. The path format is `docs/plans/{YYYY-MM-DD}_{change_name}/`.
+- Locate the specs directory. The path format is `docs/plans/{YYYY-MM-DD}/{change_name}/` for single-spec work, or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` for coordinated multi-spec work.
 - If the user provides a specific path, use that directly.
 - If only a `change_name` or date is given, search for matching directories under `docs/plans/`.
+- When the plan sits under a batch directory, also read the sibling `coordination.md` before implementation.
 - 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.
 - Understand the scope, requirements, and planned tasks before proceeding.
 
 ### 2) Check current worktree state
@@ -70,6 +73,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.
 - Implement each task in `tasks.md` systematically.
 - For each implemented change, add appropriate tests:
   - Unit tests for changed logic
@@ -88,6 +92,7 @@ After implementation and testing:
 - Update `spec.md` with actual completion state for each requirement.
 - 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.
 - Do not mark unused template examples or non-applicable items as complete.
 
 ### 6) Commit changes
@@ -113,6 +118,7 @@ After implementation and testing:
 - Always work in an isolated worktree to keep main clean.
 - 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.
 - Follow the testing standards from `enhance-existing-features` and `develop-new-features`.
 - Do not push to remote unless the user explicitly requests it.
 

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

@@ -1,4 +1,4 @@
 interface:
   display_name: "Implement Specs with Worktree"
   short_description: "Implement an approved spec set inside an isolated git worktree"
-  default_prompt: "Use $implement-specs-with-worktree to read the full plan set under docs/plans, create or reuse an isolated git worktree, implement all approved tasks with the required tests, backfill completion status into the planning docs, and commit the result to the local worktree branch without affecting main."
+  default_prompt: "Use $implement-specs-with-worktree to read the full plan set under docs/plans, including parent coordination.md when the spec belongs to a parallel batch, create or reuse an isolated git worktree, implement all approved tasks within the shared ownership and replacement-direction constraints, backfill completion status into the planning docs, and commit the result to the local worktree branch without affecting main."

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

@@ -23,7 +23,7 @@ description: >-
 ## Standards
 
 - Evidence: Inspect the current branch state, local branches, ahead/behind status, and actual conflicting files before deciding what to merge.
-- Execution: Merge only the relevant local branches into `main` sequentially, resolve conflicts by reading both sides and editing the merged result to preserve shipped behavior, verify the merged state, then hand the final local branch state to `commit-and-push` so commit/changelog/spec-archival work happens through the shared submission workflow.
+- Execution: Merge only the relevant local branches into `main` sequentially, resolve conflicts by reading both sides and editing the merged result to preserve shipped behavior, verify the merged state, delete each successfully merged branch and its detached worktree only after the merged result is confirmed, then hand the final local branch state to `commit-and-push` so commit/changelog/spec-archival work happens through the shared submission workflow.
 - Quality: Never use blanket timestamp rules or default `-X ours/theirs` conflict resolution as the primary merge strategy, and do not declare success until the final `main` state has been checked and verified.
 - Output: Produce a clean local main branch with all local changes integrated and ready for the shared submit workflow.
 
@@ -98,6 +98,21 @@ For each local branch (excluding main):
 
 ### 5) Hand off the merged result for shared submission handling
 
+- After a branch has been merged successfully and the merged `main` state has been verified, remove the source branch worktree if one exists:
+  ```bash
+  git worktree list
+  git worktree remove <worktree-path>
+  ```
+- Delete only branches that were merged successfully:
+  ```bash
+  git branch -d <branch-name>
+  ```
+- If a branch still has an attached worktree, remove the worktree before deleting the branch.
+- Never delete:
+  - `main`
+  - the currently checked-out branch
+  - branches that were skipped, failed to merge, or still need manual follow-up
+- If `git branch -d` refuses deletion because the branch is not actually merged, stop and report the branch instead of forcing deletion with `-D`.
 - Once merge verification passes, invoke `commit-and-push` for the authoritative local branch so the final submission flow owns:
   - `CHANGELOG.md` readiness
   - any required `archive-specs` run
@@ -123,6 +138,7 @@ For each local branch (excluding main):
 - Keep the main branch history clean and readable.
 - If a branch's merge breaks tests, resolve the conflict differently before committing.
 - Do not stash or discard unrelated work automatically; stop when the working tree state makes the merge ambiguous.
+- Delete merged source branches and their detached worktrees only after the merge commit and verification both succeed.
 
 ## Conflict Resolution Examples
 

package/merge-changes-from-local-branches/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Merge Changes from Local Branches"
   short_description: "Merge relevant local branches into main with verified conflict resolution"
-  default_prompt: "Use $merge-changes-from-local-branches to inventory local branches, merge only the relevant ones into local main, resolve conflicts by reading and composing the correct behavior instead of relying on blanket merge strategies, run targeted verification after conflictful merges, and leave remote state untouched."
+  default_prompt: "Use $merge-changes-from-local-branches to inventory local branches, merge only the relevant ones into local main, resolve conflicts by reading and composing the correct behavior instead of relying on blanket merge strategies, run targeted verification after conflictful merges, delete successfully merged source branches and detached worktrees only after verification succeeds, and leave remote state untouched."

package/package.json

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

package/recover-missing-plan/SKILL.md

@@ -21,7 +21,7 @@ description: Recover a missing or mismatched `docs/plans/...` plan set by verify
 
 ## Overview
 
-Use this skill when the user points to `docs/plans/{date}_{change}/...` but the directory is missing, only `docs/plans/README.md` exists, the matching files were already archived, or the workspace is detached / incomplete and the plan evidence must be recovered before coding or archiving can proceed.
+Use this skill when the user points to `docs/plans/{date}/{change}/...` or `docs/plans/{date}/{batch}/{change}/...` but the directory is missing, only `docs/plans/README.md` exists, the matching files were already archived, or the workspace is detached / incomplete and the plan evidence must be recovered before coding or archiving can proceed.
 
 Typical triggers:
 - The user references a specific `docs/plans/...` directory that is absent from the current worktree.