@laitszkin/apollo-toolkit 2.12.8 → 2.13.0

package/AGENTS.md

@@ -44,6 +44,7 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can configure OpenClaw from official documentation, including `~/.openclaw/openclaw.json`, skills loading, SecretRefs, CLI edits, and validation or repair workflows.
 - Users can investigate production or local simulation runs, calibrate reusable presets, and fix toolchain realism gaps between harness behavior and expected on-chain behavior.
 - Users can record multi-account spending and balance changes in monthly Excel ledgers with summary analytics and charts.
+- Users can recover missing or archived `docs/plans/...` spec sets from issue context, git history, and repository evidence before continuing feature work.
 - Users can review the current git change set from an unbiased reviewer perspective to find abstraction opportunities and simplification candidates.
 - Users can process GitHub pull request review comments and resolve addressed threads.
 - Users can perform repository-wide code reviews and publish confirmed findings as GitHub issues.

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.13.0] - 2026-04-05
+
+### Added
+- Add `recover-missing-plan` for restoring or reconstructing missing `docs/plans/...` plan sets from repository evidence, git history, and authoritative issue context before implementation continues.
+- Expand `generate-spec` with standardized `contract.md` and `design.md` templates plus generator support so plan sets can capture external dependency contracts and architecture deltas alongside `spec.md`, `tasks.md`, and `checklist.md`.
+
+### Changed
+- Update `develop-new-features`, `enhance-existing-features`, `archive-specs`, and related agent prompts to treat `contract.md` and `design.md` as first-class planning artifacts wherever `generate-spec` is used.
+- Update `ship-github-issue-fix` to require `recover-missing-plan` when a referenced `docs/plans/...` path is missing or archived unexpectedly.
+- Expand repository capability docs and skill inventory to include `recover-missing-plan` and the broader five-file planning workflow.
+- Strengthen `weekly-financial-event-report` so it checks for an existing report covering the same research window before regenerating output, and requires exact calendar dates for exchange/session timing when reporting market-sensitive follow-up.
+
 ## [v2.12.7] - 2026-04-02
 
 ### Added

package/README.md

@@ -36,6 +36,7 @@ A curated skill catalog for Codex, OpenClaw, and Trae with a managed installer t
 - openai-text-to-image-storyboard
 - openclaw-configuration
 - production-sim-debug
+- recover-missing-plan
 - record-spending
 - resolve-review-comments
 - review-change-set
@@ -146,6 +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`.
+- `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

@@ -4,7 +4,7 @@ A documentation skill that converts completed spec files into standardized proje
 
 ## Core capabilities
 
-- Scans `spec.md`, `tasks.md`, and `checklist.md` collections as documentation input.
+- Scans `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.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.

package/archive-specs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: archive-specs
-description: Convert completed project spec sets into maintainable project documentation and archive the consumed planning files. Use when users want to consolidate `spec.md`/`tasks.md`/`checklist.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` files 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`, and `checklist.md`.
+- Find all relevant planning files such as `docs/plans/**/spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.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.
 
@@ -89,7 +89,7 @@ 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`, and `checklist.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`, and `design.md` files, or their containing 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.

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 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 specs 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, 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."

package/develop-new-features/README.md

@@ -5,10 +5,10 @@ A spec-first feature development skill for new behavior and greenfield work. It
 ## Key capabilities
 
 - Requires `generate-spec` before any implementation starts.
-- Treats `spec.md`, `tasks.md`, and `checklist.md` as approval-gated artifacts, not optional notes.
+- Treats `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` as approval-gated artifacts, not optional notes.
 - Covers unit, regression, property-based, integration, E2E, and adversarial testing based on actual risk.
 - Reuses existing architecture and avoids speculative expansion.
-- Backfills `spec.md`, `tasks.md`, and `checklist.md` after implementation and testing complete.
+- Backfills `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` after implementation and testing complete.
 - Once approval is granted and implementation starts, finishes all in-scope planned tasks and applicable checklist items before yielding unless the user defers work or an external blocker prevents safe completion.
 
 ## Repository layout
@@ -33,7 +33,7 @@ A spec-first feature development skill for new behavior and greenfield work. It
 2. Run `generate-spec` to create and maintain `docs/plans/{YYYY-MM-DD}_{change_name}/`.
 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`, and `checklist.md`.
+5. Run risk-driven tests and backfill `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md`.
 
 ## Testing expectations
 

package/develop-new-features/SKILL.md

@@ -20,7 +20,7 @@ description: >-
 
 ## Dependencies
 
-- Required: `generate-spec` for `spec.md`, `tasks.md`, `checklist.md`, clarification handling, approval gating, and completion-status backfill.
+- Required: `generate-spec` for `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md`, clarification handling, approval gating, and completion-status backfill.
 - Conditional: none.
 - Optional: none.
 - Fallback: If `generate-spec` is unavailable, stop and report the missing dependency.
@@ -54,15 +54,17 @@ Use a shared spec-generation workflow for non-trivial new feature work, then imp
   - simple configuration, constant, feature-flag, dependency, or content updates confined to one small area
   - small refactors, naming cleanups, or internal code-health work with no externally visible behavior change
   - narrowly scoped adjustments that touch only a few files/modules and do not require cross-team alignment or approval artifacts
-- In those cases, do not create `spec.md` / `tasks.md` / `checklist.md`; instead use the appropriate direct implementation workflow (for example `enhance-existing-features` for small brownfield adjustments or `systematic-debug` for bug fixes).
+- In those cases, do not create planning docs; instead use the appropriate direct implementation workflow (for example `enhance-existing-features` for small brownfield adjustments or `systematic-debug` for bug fixes).
 - Specs are required when the request is truly a non-trivial new feature, product behavior change, or greenfield project that needs shared planning.
 - Treat each spec set as a narrowly scoped workstream that covers at most three modules.
 - 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.
 - Follow `$generate-spec` completely for:
-  - generating `docs/plans/{YYYY-MM-DD}_{change_name}/spec.md`, `tasks.md`, and `checklist.md`
+  - generating `docs/plans/{YYYY-MM-DD}_{change_name}/spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md`
   - 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`
   - handling clarification responses
   - obtaining explicit approval before coding
   - backfilling document status after implementation and testing, including requirement completion in `spec.md`
@@ -108,10 +110,12 @@ Rules:
 
 ### 6) Completion updates
 
-- Backfill `spec.md`, `tasks.md`, and `checklist.md` through `$generate-spec` workflow after implementation and testing.
+- Backfill `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` through `$generate-spec` workflow after implementation and testing.
 - 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.
+- In `contract.md`, keep the final external dependency contract records aligned with the implementation and verified upstream constraints.
+- In `design.md`, keep the final architecture/design description aligned with the implementation that actually shipped.
 - Do not mark template alternatives, unused example rows, or non-applicable decision branches as completed just to make the file look fully checked.
 - Rewrite, remove, or leave `N/A` on template-only sections so the final checklist reflects the real work rather than the starter template.
 - Explicitly label any truly remaining applicable item as deferred or blocked with the reason.

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}, wait for explicit approval, then complete the approved implementation end-to-end with risk-driven tests and full backfill of spec.md, tasks.md, and checklist.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>/{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."

package/enhance-existing-features/README.md

@@ -33,7 +33,7 @@ A brownfield feature-extension skill: map dependencies first, decide whether sha
 2. Trigger `generate-spec` only when the change is high complexity, hits a critical module, or crosses module boundaries.
 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`, and `checklist.md` when specs exist.
+5. Run risk-driven tests and backfill `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` when specs exist.
 
 ## Test requirements
 

package/enhance-existing-features/SKILL.md

@@ -2,7 +2,7 @@
 name: enhance-existing-features
 description: >-
   Extend brownfield features by exploring the codebase first, then deciding
-  whether shared specs (`spec.md`/`tasks.md`/`checklist.md`) are required
+  whether shared planning docs (`spec.md`/`tasks.md`/`checklist.md`/`contract.md`/`design.md`) are required
   before coding. When specs are needed, use `generate-spec` for planning,
   clarification, approval, and backfill, and complete approved in-scope tasks
   before yielding unless scope changes or an external blocker prevents safe
@@ -17,7 +17,7 @@ description: >-
 ## Dependencies
 
 - Required: `generate-spec` for shared planning docs when spec-trigger conditions are met.
-- Conditional: none.
+- Conditional: `recover-missing-plan` when the user points to a required `docs/plans/...` spec set that is missing, archived, or mismatched in the current workspace.
 - Optional: none.
 - Fallback: If specs are required and `generate-spec` is unavailable, stop and report the missing dependency.
 
@@ -64,12 +64,15 @@ Do not generate specs when the work is clearly small and localized, such as:
 When in doubt, prefer direct implementation for genuinely low-risk localized changes, and reserve specs for changes whose scope or risk would benefit from explicit approval artifacts.
 
 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`, and `checklist.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.
 - 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.
 - After implementation and testing, update the same plan set so `spec.md` reflects requirement completion status in addition to task and checklist progress.
 - If users answer clarification questions, update the planning docs and obtain explicit approval again before implementation.
 - Do not modify implementation code before approval.
@@ -120,10 +123,12 @@ Rules:
 
 ### 6) Completion updates
 
-- If specs were used, backfill `spec.md`, `tasks.md`, and `checklist.md` through `$generate-spec` workflow based on actual completion and test outcomes.
+- 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.
 - 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.
+- If specs were used, update `contract.md` so the documented dependency obligations and constraints match the implemented reality.
+- If specs were used, update `design.md` so the architecture/design record matches the delivered implementation.
 - Do not mark unused template examples, mutually exclusive alternatives, or non-applicable branches as completed.
 - Remove, rewrite, or leave `N/A` on starter-template items when they do not belong to the real change.
 - Explicitly label any still-applicable remaining item as deferred or blocked with the reason.

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, 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, and checklist.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 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."

package/generate-spec/README.md

@@ -1,14 +1,15 @@
 # generate-spec
 
-A shared planning skill for feature work. It centralizes creation and maintenance of `spec.md`, `tasks.md`, and `checklist.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`, and `design.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`, and `checklist.md` in one step.
+- Generates `docs/plans/{YYYY-MM-DD}_{change_name}/spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` in one step.
 - 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.
 - Keeps requirement, task, and test coverage mapping traceable.
+- Standardizes external dependency contracts in `contract.md` and architecture/design deltas in `design.md`.
 
 ## Repository layout
 
@@ -23,7 +24,9 @@ A shared planning skill for feature work. It centralizes creation and maintenanc
 │   └── templates/
 │       ├── spec.md
 │       ├── tasks.md
-│       └── checklist.md
+│       ├── checklist.md
+│       ├── contract.md
+│       └── design.md
 └── scripts/
     └── create-specs
 ```
@@ -45,7 +48,9 @@ Default output:
 docs/plans/<today>_membership-upgrade-flow/
 ├── spec.md
 ├── tasks.md
-└── checklist.md
+├── checklist.md
+├── contract.md
+└── design.md
 ```
 
 ## Authoring rules
@@ -53,6 +58,8 @@ docs/plans/<today>_membership-upgrade-flow/
 - `spec.md`: use BDD keywords `GIVEN / WHEN / THEN / AND / Requirements`.
 - `tasks.md`: use `## **Task N: ...**`, `- N. [ ]`, and `- N.x [ ]`.
 - `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.
 - 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`) 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`) 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.
 ---
 
 # Generate Spec
@@ -15,8 +15,8 @@ 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 first, complete them with traceable requirements and risks, handle clarification updates, then wait for explicit approval before implementation.
-- Quality: Keep `spec.md`, `tasks.md`, and `checklist.md` synchronized, map each planned test to a concrete risk or requirement, and tailor the templates so only applicable items remain active.
+- 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.
 
 ## Goal
@@ -32,7 +32,7 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - If the change depends on frameworks, libraries, SDKs, APIs, CLIs, hosted services, or other external systems, find and read the relevant official documentation before drafting requirements.
 - Treat official documentation lookup as mandatory evidence gathering, not an optional refinement step.
 - Use the official docs to verify expected behavior, supported constraints, configuration surface, integration contracts, and any implementation limits that should shape the spec.
-- Record the references that should appear in `spec.md`.
+- Record the references that should appear in `spec.md` and the dependency evidence that should appear in `contract.md`.
 - Inspect existing `docs/plans/` directories before deciding whether to edit an existing plan set.
 - Reuse an existing plan set only when it clearly matches the same requested issue/change scope.
 - If the requested work is adjacent to, but not actually covered by, an existing plan set, create a new directory instead of overwriting the neighboring one.
@@ -40,6 +40,11 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 ### 2) Generate the planning files
 
 - Resolve paths from this skill directory, not the target project directory.
+- Before generating files, identify the concrete modules that would be touched by the requested change.
+- Keep each spec set scoped to at most three modules.
+- If the requested work would span more than three modules, do not draft one oversized coupled plan.
+- 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.
 - Use:
   - `SKILL_ROOT=<path_to_generate-spec_skill>`
   - `WORKSPACE_ROOT=<target_project_root>`
@@ -48,6 +53,8 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
   - `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}/`.
 
 ### 3) Fill `spec.md`
@@ -67,7 +74,21 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Use `- N. [ ]` for tasks and `- N.x [ ]` for subtasks.
 - Include explicit tasks for testing, mocks/fakes, regression coverage, and adversarial or edge-case hardening when relevant.
 
-### 5) Fill `checklist.md`
+### 5) Fill `contract.md`
+
+- When the change uses external dependencies, libraries, frameworks, SDKs, APIs, CLIs, hosted services, or other upstream systems, document each material dependency in a standardized dependency record.
+- For each dependency, capture the official source, the invocation surface, required inputs, expected outputs, supported behavior, limits, compatibility constraints, security/access requirements, failure contract, and caller obligations.
+- Record constraints and forbidden assumptions explicitly so later implementation and review do not rely on unstated expectations.
+- If no external dependency materially constrains the change, write `None` and a brief scope-based reason instead of inventing a fake dependency record.
+
+### 6) Fill `design.md`
+
+- Write the architecture/design delta related to the current spec in a standardized format.
+- 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.
+
+### 7) Fill `checklist.md`
 
 - Use checkbox format `- [ ]` for checklist items, except structured placeholder fields that are intentionally left for later fill-in.
 - Treat the template as a starting point and adapt it to the actual scope.
@@ -79,18 +100,20 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Within each decision record, keep only the selected strategy or clearly mark the non-selected path as `N/A`; never treat mutually exclusive choices inside one record as multiple completed outcomes.
 - For completion-summary sections, create as many completion records as needed for distinct flows, requirement groups, or workstreams; do not force the whole spec into a single completion line when different parts finish differently.
 
-### 6) Process clarifications and approval
+### 8) Process clarifications and approval
 
 - When the user answers clarification questions, first update the clarification and approval section in `checklist.md`.
-- Review whether `spec.md`, `tasks.md`, and `checklist.md` must be updated.
+- Review whether `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` must be updated.
 - After any clarification-driven update, obtain explicit approval on the updated spec set again.
 - Do not modify implementation code before approval.
 - When clarification reveals the work is a different issue or materially different scope than the current plan set, stop editing that plan set and generate a new one with a distinct `change_name`.
 
-### 7) Backfill after implementation and testing
+### 9) Backfill after implementation and testing
 
 - Mark completed tasks in `tasks.md`.
 - 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.
 - 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.
@@ -101,7 +124,11 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 
 - By default, write planning docs in the user's language.
 - 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.
 - 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.
 - Finalized planning docs should read like the actual approved plan and execution record, not like a fully checked starter template.
 - If official documentation materially constrains implementation choices, reflect that constraint explicitly in the spec instead of leaving it implicit.
 - Use kebab-case for `change_name`; avoid spaces and special characters.
@@ -114,3 +141,5 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - `references/templates/spec.md`: BDD requirement template.
 - `references/templates/tasks.md`: task breakdown template.
 - `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.

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} from shared templates, fill BDD requirements and risk-driven test planning, process clarification updates, and wait for explicit approval before implementation."
+  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."

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

@@ -17,7 +17,7 @@
 
 ## Clarification & Approval Gate (required when clarification replies exist)
 - [ ] User clarification responses are recorded (map to `spec.md`; if none, mark `N/A`).
-- [ ] Affected specs are reviewed/updated (`spec.md` / `tasks.md` / `checklist.md`; if no updates needed, mark `N/A` + reason).
+- [ ] Affected plans are reviewed/updated (`spec.md` / `tasks.md` / `checklist.md` / `contract.md` / `design.md`; if no updates needed, mark `N/A` + reason).
 - [ ] Explicit user approval on updated specs is obtained (date/conversation reference: [to be filled]).
 
 ## Behavior-to-Test Checklist (customizable)

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

@@ -0,0 +1,65 @@
+# Contract: [Feature Name]
+
+- Date: [YYYY-MM-DD]
+- Feature: [Feature Name]
+- Change Name: [change_name]
+
+## Purpose
+[Describe why external dependency contracts matter for this change.]
+
+## Usage Rule
+- Write one dependency record per external library, framework, SDK, API, CLI, platform service, or hosted system that materially constrains implementation.
+- If no external dependency materially affects the change, write `None` under `## Dependency Records` and briefly explain why this document is not needed for the current scope.
+- Every claim in this file must be backed by the official documentation or the verified upstream source actually used during planning.
+
+## Dependency Records
+
+### Dependency 1: [Dependency Name]
+- Type: [library / framework / SDK / API / CLI / hosted service / platform]
+- Version / Scope: [exact version, major line, API version, or `Not fixed`]
+- Official Source: [link]
+- Why It Matters: [what this dependency is responsible for in the change]
+- Invocation Surface:
+  - Entry points: [package import / endpoint / command / webhook / queue topic]
+  - Call pattern: [sync / async / streaming / webhook / batch / polling]
+  - Required inputs: [auth, headers, env vars, config keys, payload fields]
+  - Expected outputs: [return shape, side effects, emitted events, persisted state]
+- Constraints:
+  - Supported behavior: [documented supported modes relevant to this change]
+  - Limits: [rate limits, payload limits, timeout, ordering, pagination, size, quota]
+  - Compatibility: [runtime / platform / version / region / account constraints]
+  - Security / access: [auth model, scopes, permissions, secret handling]
+- Failure Contract:
+  - Error modes: [documented errors, degraded states, retries, eventual consistency]
+  - Caller obligations: [retry rules, idempotency keys, backoff, validation, cleanup]
+  - Forbidden assumptions: [what the implementation must not assume]
+- Verification Plan:
+  - Spec mapping: [R?.?]
+  - Design mapping: [section in `design.md`]
+  - Planned coverage: [UT / PBT / IT / E2E / mock scenario IDs]
+  - Evidence notes: [specific doc section or source snippet summary]
+
+### Dependency 2: [Dependency Name]
+- Type: [library / framework / SDK / API / CLI / hosted service / platform]
+- Version / Scope: [exact version, major line, API version, or `Not fixed`]
+- Official Source: [link]
+- Why It Matters: [what this dependency is responsible for in the change]
+- Invocation Surface:
+  - Entry points: [package import / endpoint / command / webhook / queue topic]
+  - Call pattern: [sync / async / streaming / webhook / batch / polling]
+  - Required inputs: [auth, headers, env vars, config keys, payload fields]
+  - Expected outputs: [return shape, side effects, emitted events, persisted state]
+- Constraints:
+  - Supported behavior: [documented supported modes relevant to this change]
+  - Limits: [rate limits, payload limits, timeout, ordering, pagination, size, quota]
+  - Compatibility: [runtime / platform / version / region / account constraints]
+  - Security / access: [auth model, scopes, permissions, secret handling]
+- Failure Contract:
+  - Error modes: [documented errors, degraded states, retries, eventual consistency]
+  - Caller obligations: [retry rules, idempotency keys, backoff, validation, cleanup]
+  - Forbidden assumptions: [what the implementation must not assume]
+- Verification Plan:
+  - Spec mapping: [R?.?]
+  - Design mapping: [section in `design.md`]
+  - Planned coverage: [UT / PBT / IT / E2E / mock scenario IDs]
+  - Evidence notes: [specific doc section or source snippet summary]

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

@@ -0,0 +1,65 @@
+# Design: [Feature Name]
+
+- Date: [YYYY-MM-DD]
+- Feature: [Feature Name]
+- Change Name: [change_name]
+
+## Design Goal
+[Describe the architecture/design objective for this spec change.]
+
+## Change Summary
+- Requested change: [one sentence]
+- Existing baseline: [current architecture or behavior relevant to the change]
+- Proposed design delta: [what will change structurally]
+
+## Scope Mapping
+- Spec requirements covered: [R?.?]
+- Affected modules: [module/file/service list]
+- External contracts involved: [dependency names from `contract.md`, or `None`]
+
+## Current Architecture
+[Describe the relevant current components, data flow, control flow, and boundaries.]
+
+## Proposed Architecture
+[Describe the new or updated structure, ownership boundaries, and interaction flow.]
+
+## Component Changes
+
+### Component 1: [Name]
+- Responsibility: [what this component owns after the change]
+- Inputs: [events, params, payloads, config]
+- Outputs: [return values, writes, emitted events, calls]
+- Dependencies: [internal modules and external contracts]
+- Invariants: [business or technical rules that must hold]
+
+### Component 2: [Name]
+- Responsibility: [what this component owns after the change]
+- Inputs: [events, params, payloads, config]
+- Outputs: [return values, writes, emitted events, calls]
+- Dependencies: [internal modules and external contracts]
+- Invariants: [business or technical rules that must hold]
+
+## Sequence / Control Flow
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+## Data / State Impact
+- Created or updated data: [schemas, fields, caches, files, queues, config]
+- Consistency rules: [ordering, transactionality, idempotency, deduplication]
+- Migration / rollout needs: [if none, write `None`]
+
+## Risk and Tradeoffs
+- Key risks: [failure, concurrency, authorization, partial-write, dependency risk]
+- Rejected alternatives: [alternative + why it was not chosen]
+- Operational constraints: [performance, quota, observability, deployment coupling]
+
+## Validation Plan
+- Tests: [UT / PBT / IT / E2E / adversarial]
+- Contract checks: [how `contract.md` constraints will be validated]
+- Rollback / fallback: [how to contain or reverse impact]
+
+## Open Questions
+[Write `None` if the design is settled.]
+- [Question 1]
+- [Question 2]

package/generate-spec/scripts/create-specs

@@ -6,7 +6,13 @@ import re
 from datetime import date
 from pathlib import Path
 
-TEMPLATE_FILENAMES = ("spec.md", "tasks.md", "checklist.md")
+TEMPLATE_FILENAMES = (
+    "spec.md",
+    "tasks.md",
+    "checklist.md",
+    "contract.md",
+    "design.md",
+)
 PLACEHOLDERS = ("[Feature Name]", "[功能名稱]")
 
 
@@ -32,7 +38,7 @@ def _render(content: str, today: str, feature_name: str, change_name: str) -> st
 def main() -> int:
     parser = argparse.ArgumentParser(
         description=(
-            "Create planning docs (spec.md, tasks.md, checklist.md) "
+            "Create planning docs (spec.md, tasks.md, checklist.md, contract.md, design.md) "
             "from templates with folder format docs/plans/{date}_{change_name}."
         ),
     )
@@ -54,7 +60,7 @@ def main() -> int:
     parser.add_argument(
         "--template-dir",
         default=str(_default_template_dir()),
-        help="Directory containing spec.md/tasks.md/checklist.md templates",
+        help="Directory containing planning document templates",
     )
     parser.add_argument(
         "--force",

package/package.json

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

package/recover-missing-plan/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: recover-missing-plan
+description: Recover a missing or mismatched `docs/plans/...` plan set by verifying the path, checking archives and git history, reading the authoritative issue context, and restoring or reconstructing `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` before implementation continues.
+---
+
+# Recover Missing Plan
+
+## Dependencies
+
+- Required: `read-github-issue` and `generate-spec`.
+- Conditional: none.
+- Optional: none.
+- Fallback: If the authoritative issue context cannot be read and no archived or historical plan evidence exists, stop and report the missing evidence instead of guessing the scope.
+
+## Standards
+
+- Evidence: Confirm the requested plan path really is missing, search the repository and git history, and use authoritative issue context before restoring or recreating planning files.
+- Execution: Prefer restoring the original plan set when trustworthy evidence exists; reconstruct only the minimum required files and only after establishing the intended issue scope.
+- Quality: Do not invent requirements, do not overwrite a different issue's plan set, and keep active-vs-archived placement aligned with the actual delivery state.
+- Output: Leave behind the correct `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` set plus a short evidence trail explaining whether the plan was restored, reconstructed, or redirected to an archived location.
+
+## 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.
+
+Typical triggers:
+- The user references a specific `docs/plans/...` directory that is absent from the current worktree.
+- A feature workflow expects approved spec files, but the plan was archived, never checked out, or exists only in another branch/worktree.
+- An implementation task must continue from GitHub issue context because the original planning artifacts are missing.
+
+## Workflow
+
+### 1) Prove the path mismatch first
+
+- Confirm the requested path exactly.
+- List `docs/plans/`, `docs/archive/plans/`, and any nearby plan directories with similar names.
+- Search the repository for the issue number, `change_name`, and user-provided path fragment.
+- Check whether the plan is genuinely missing, merely archived, or present under a slightly different normalized directory name.
+
+### 2) Search for trustworthy local recovery sources
+
+- Inspect git-tracked history for the missing plan files before recreating anything.
+- Check other local branches or worktrees when the repository uses parallel issue branches.
+- If the user asked to finish already-completed work, verify whether the correct action is to update `docs/archive/plans/...` instead of creating a new active plan.
+- Treat archived specs, prior commits, and clearly matching neighboring plan sets as recovery evidence, not as permission to infer new scope.
+
+### 3) Read authoritative issue context when local evidence is incomplete
+
+- Use `$read-github-issue` to read the actual remote issue and comments.
+- Prefer repository helpers when they work, but immediately fall back to raw `gh issue view` when wrappers return empty or incomplete output.
+- Use the issue to recover acceptance criteria, constraints, and naming only after confirming it is the same scope as the missing plan.
+- If the issue and local evidence disagree, stop and report the conflict instead of blending them.
+
+### 4) Decide restore vs reconstruct vs redirect
+
+Choose one path explicitly:
+- Restore: reuse the original plan content when a trustworthy historical copy exists.
+- Reconstruct: create a fresh plan set only when the issue scope is clear and the files truly do not exist anywhere trustworthy.
+- Redirect: if the work is already completed and the correct files live under `docs/archive/plans/...`, use the archived location and continue the requested archival or reporting workflow from there.
+
+Rules:
+- Never overwrite a neighboring issue's plan set just because the technical area overlaps.
+- Keep reconstructed scope limited to the same issue only.
+- If reconstruction would touch more than three modules, split the work through `$generate-spec` instead of drafting an oversized recovered plan.
+
+### 5) Rebuild the plan set carefully
+
+- When reconstruction is required, use `$generate-spec` to create the canonical `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` skeleton.
+- Fill the recovered plan from verified evidence only: issue text, codebase inspection, official docs when relevant, and already-landed implementation facts if the work was partially completed.
+- Keep the recovered planning docs in the user's language unless repository conventions require otherwise.
+- When the user asked to continue implementation immediately, recover only the current issue's plan set and then hand control back to the owning workflow skill.
+
+### 6) Backfill completion state honestly
+
+- If code already exists, mark only the tasks and checklist items supported by actual evidence and tests.
+- If work is still pending, leave the recovered plan active under `docs/plans/...`.
+- If work is already complete and the project archives finished plans, move or keep the recovered set under `docs/archive/plans/...` and update any relevant plan index.
+- Record exactly which evidence source justified the recovery choice.
+
+## Working Rules
+
+- Missing plan recovery is an evidence-restoration workflow, not a shortcut to skip planning discipline.
+- Prefer archived or historical files over freshly rewritten prose whenever a reliable source exists.
+- When the repository's issue helper scripts fail, use direct `gh` commands instead of stalling.
+- Do not silently continue implementation with no recovered plan when the owning workflow depends on one.
+
+## References
+
+- `$read-github-issue`: authoritative remote issue retrieval.
+- `$generate-spec`: canonical spec/task/checklist generation and backfill workflow.

package/recover-missing-plan/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Recover Missing Plan"
+  short_description: "Recover missing docs/plans spec sets from evidence"
+  default_prompt: "Use $recover-missing-plan when the user references a docs/plans plan set that is missing from the current workspace or appears to have been archived unexpectedly; verify the path mismatch, search the repository and git history, read the authoritative GitHub issue when needed, restore or reconstruct the correct spec.md/tasks.md/checklist.md/contract.md/design.md set from evidence, and only then continue the requested implementation or archival workflow."

package/ship-github-issue-fix/SKILL.md

@@ -7,7 +7,7 @@ description: Resolve a GitHub issue in an existing repository and submit the fix
 
 ## Dependencies
 
-- Required: `read-github-issue`, `enhance-existing-features`, and `commit-and-push`.
+- Required: `read-github-issue`, `enhance-existing-features`, `recover-missing-plan`, and `commit-and-push`.
 - Conditional: `systematic-debug` when the issue is primarily a bug investigation or failing behavior report.
 - Optional: none.
 - Fallback: If any required dependency is unavailable, stop and report which dependency blocked the workflow.
@@ -36,6 +36,7 @@ Use this skill for the recurring workflow where the user wants one GitHub issue
 ### 2) Explore the codebase and decide whether specs are required
 
 - After reading the issue, inspect the real entrypoints, affected modules, tests, and existing planning files.
+- If the user references an expected `docs/plans/...` path that is missing or archived unexpectedly, run `$recover-missing-plan` before treating the issue as unspecced work.
 - Run `$enhance-existing-features` to decide whether specs are required from the actual change surface.
 - Default to direct implementation for clearly localized bug fixes, regressions, narrow optimizations, or small workflow corrections, even when the issue wording sounds broad.
 - Require specs when the explored change touches critical money movement, permissions, high-risk concurrency, or multi-module behavior changes that need approval traceability.

package/weekly-financial-event-report/SKILL.md

@@ -15,7 +15,7 @@ description: Read a user-specified PDF that marks the week's key financial event
 ## Standards
 
 - Evidence: Research only events explicitly marked in the source PDF plus clearly material breaking developments, and verify claims with current authoritative sources.
-- Execution: Read the PDF first, prefer `pdf` for extraction but fall back to the bundled macOS PDFKit extractor when local PDF tooling is missing, lock the research window, research each marked event, then hand the final briefing to `pdf` for rendering and QA with deterministic table-safe layout rules when needed.
+- Execution: Read the PDF first, prefer `pdf` for extraction but fall back to the bundled macOS PDFKit extractor when local PDF tooling is missing, lock the research window, check for an existing report covering that same window before duplicating work, research each marked event, then hand the final briefing to `pdf` for rendering and QA with deterministic table-safe layout rules when needed.
 - Quality: Keep the report concise, Chinese-compatible, explicit about source-versus-breaking events, conflicts, uncertainty, PDF font safety, and long-text table legibility.
 - Output: Save only the final standardized PDF under the month folder using the financial-event-report naming scheme.
 
@@ -57,6 +57,7 @@ Do not guess any input that materially changes the research window or report sco
   - company filings or official releases
 - Use high-quality financial reporting to triangulate facts, surface timelines, or explain market reactions.
 - Record the event date or publication date for every material claim.
+- Use exact calendar dates for market holidays, exchange closures, and "next session" timing instead of relative wording such as "today" or "next Monday" alone.
 - Separate confirmed facts from interpretation.
 - Distinguish between:
   - events explicitly marked in the source PDF
@@ -91,6 +92,16 @@ swift scripts/extract_pdf_text_pdfkit.swift /absolute/path/to/source.pdf
 - If the research window remains unclear, report the ambiguity instead of assuming one.
 - State exact calendar dates and timezone in the report.
 
+### 2.5) Check for an existing report before regenerating
+
+- Before drafting a new report, inspect the target month folder for an existing `financial-event-report` PDF that already covers the same exact date range.
+- If an existing report already covers the locked window, read it first and compare it with the newly confirmed marked events plus any newly discovered breaking developments.
+- Reuse the existing report as the baseline when it already covers the same window, and regenerate only when at least one of these is true:
+  - the source PDF reveals a marked event that the existing report missed
+  - a material breaking event landed after the prior report was generated
+  - the earlier report used an incorrect or incomplete research window
+- If the existing report is still complete and current for the same window, stop and report that no refresh is needed instead of rewriting the same deliverable.
+
 ### 3) Research each marked event deeply
 
 - For every marked event, gather:
@@ -114,6 +125,7 @@ swift scripts/extract_pdf_text_pdfkit.swift /absolute/path/to/source.pdf
   - geopolitical shocks with direct market spillovers
   - unexpected company events with broad market consequences
 - Label these clearly as newly added breaking events rather than source-PDF items.
+- When a breaking event affects how an already published data point should be interpreted at the next market session, state the exact upcoming trading date or reopening date.
 
 ### 5) Write the standardized report