@laitszkin/apollo-toolkit 2.14.2 → 2.14.4

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.14.4] - 2026-04-07
+
+### Changed
+- Clarify `maintain-project-constraints` so `Core project purpose` must describe the repository's macro goal or problem-to-solve, instead of restating its implemented feature list.
+
+## [v2.14.3] - 2026-04-07
+
+### Changed
+- Strengthen `systematic-debug` so runtime-pipeline investigations must anchor on one canonical run or artifact root, map failures to concrete stages, and separate toolchain/platform faults from application-logic faults before fixing.
+- Strengthen `scheduled-runtime-health-check` so bounded runs must record the canonical run folder as soon as it materializes and use structured artifacts from that same run when analyzing health.
+
 ## [v2.14.2] - 2026-04-06
 
 ### Changed

package/maintain-project-constraints/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: maintain-project-constraints
-description: Automatically create and maintain AGENTS.md so it stays aligned with the current repository architecture, core business flow, common commands, project purpose, and coding conventions. Use when AGENTS.md is missing or may be outdated after code changes.
+description: Automatically create and maintain AGENTS.md so it stays aligned with the current repository architecture, core business flow, common commands, macro project purpose, and coding conventions. Use when AGENTS.md is missing or may be outdated after code changes.
 ---
 
 # Maintain Project Constraints
@@ -42,6 +42,13 @@ After completing any code modification task, proactively run this skill to verif
 - Core project purpose
 - Code style and coding conventions
 
+For the `Core project purpose` section, always use this format:
+
+1. Describe the repository's macro purpose instead of repeating implemented features.
+2. State what broader problem the project is meant to solve or what outcome it aims to achieve.
+3. Prefer product- or business-level intent framing when applicable.
+4. Keep it concise, but make sure the purpose is understandable without reading the rest of the document.
+
 For the `Common Commands` section, always use this format:
 
 1. Include only commands that are real, current, and useful in this repository.
@@ -99,6 +106,7 @@ When `AGENTS.md` is absent:
 
 - Create a new root-level `AGENTS.md`.
 - Document architecture, business flow, purpose, and coding conventions from observed facts.
+- Write `Core project purpose` as the repository's macro intent, such as the problem it aims to solve or the outcome it exists to achieve, rather than as a feature list.
 - Document the repository's common commands from observed command entry points and docs.
 - Write `Core business flow` as one summary sentence followed by unordered bullets that cover every current capability found in the repository.
 - Write `Common commands` as short bullets in the style of ``- `command` — when to use it.``.
@@ -121,6 +129,7 @@ When `AGENTS.md` exists but is outdated:
 - Remove stale commands, flags, or task names that no longer exist.
 - Verify every command in `Common Commands` is either documented in repository docs or directly supported by the current codebase.
 - Verify the `Core business flow` section includes a one-sentence summary plus unordered bullets for all currently existing capabilities; do not leave major functions unlisted.
+- Verify `Core project purpose` explains the repository's macro goal and does not merely restate the feature inventory.
 - Keep instructions concise, concrete, and operational for future agents.
 
 ## Writing Rules
@@ -128,6 +137,7 @@ When `AGENTS.md` exists but is outdated:
 - Use clear headings and short bullet points.
 - Prefer repository terms already used in code/docs.
 - Do not include speculative architecture claims.
+- In `Core project purpose`, describe why the project exists at a macro level; for example, what user or business problem it solves, not a restatement of `Core business flow`.
 - In `Core business flow`, prefer many short bullets over a few vague bullets; when the product grows, add more bullets so the list remains exhaustive.
 - In `Common Commands`, prefer the smallest useful set of high-signal commands over an exhaustive dump of every helper script.
 - Keep the document focused on how agents should understand and operate in this project.

package/maintain-project-constraints/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Maintain Project Constraints"
-  short_description: "Automatically create and maintain AGENTS.md so it stays aligned with the current repository architecture, core business flow, common commands, project purpose, and coding conventions. Use when AGENTS.md is missing or may be outdated after code changes."
-  default_prompt: "Use $maintain-project-constraints to automatically create and maintain AGENTS.md so it stays aligned with the current repository architecture, core business flow, common commands, project purpose, and coding conventions. Use when AGENTS.md is missing or may be outdated after code changes."
+  short_description: "Automatically create and maintain AGENTS.md so it stays aligned with the current repository architecture, core business flow, common commands, macro project purpose, and coding conventions. Use when AGENTS.md is missing or may be outdated after code changes."
+  default_prompt: "Use $maintain-project-constraints to automatically create and maintain AGENTS.md so it stays aligned with the current repository architecture, core business flow, common commands, macro project purpose, and coding conventions. Use when AGENTS.md is missing or may be outdated after code changes."

package/package.json

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

package/scheduled-runtime-health-check/SKILL.md

@@ -14,8 +14,8 @@ description: Use a background terminal to run a user-specified command immediate
 
 ## Standards
 
-- Evidence: Anchor every conclusion to the requested command, execution window, startup/shutdown timestamps, captured logs, and concrete runtime signals.
-- Execution: Collect the run contract, verify the real stop mechanism before launch, use a background terminal, optionally update the code only when the user asks, execute the requested command immediately or in the requested window, capture logs, stop cleanly when bounded, then delegate log review to `analyse-app-logs` only when findings are requested or needed.
+- Evidence: Anchor every conclusion to the requested command, execution window, startup/shutdown timestamps, one canonical run folder or artifact root, captured logs, and concrete runtime signals.
+- Execution: Collect the run contract, verify the real stop mechanism before launch, use a background terminal, optionally update the code only when the user asks, execute the requested command immediately or in the requested window, record the canonical run folder once the process materializes it, capture logs, stop cleanly when bounded, then delegate log review to `analyse-app-logs` only when findings are requested or needed.
 - Quality: Keep scheduling, execution, and shutdown deterministic; separate confirmed findings from hypotheses; and mark each assessed module healthy/degraded/failed/unknown with reasons.
 - Output: Return the run configuration, execution status, log locations, optional code-update result, optional module health by area, confirmed issues, potential issues, observability gaps, and scheduler status when applicable.
 
@@ -45,10 +45,12 @@ This skill is an orchestration layer. It owns the background terminal session, o
 
 - Prefer one bounded observation window over open-ended monitoring.
 - Use one dedicated background terminal session per requested run so execution and logs stay correlated.
+- Record the canonical run directory, artifact root, or other generated output location as soon as it exists, and use that as the source of truth for later analysis.
 - Treat code update as optional and only perform it when the user explicitly requests it.
 - Treat startup, steady-state, and shutdown as part of the same investigation.
 - Do not call a module healthy unless there is at least one positive signal for it.
 - Separate scheduler failures, boot failures, runtime failures, and shutdown failures.
+- For complex pipelines, identify the last successful stage before attributing the failure to application logic.
 - If logs cannot support a health judgment, mark the module as `unknown` instead of guessing.
 
 ## Required workflow
@@ -62,6 +64,7 @@ This skill is an orchestration layer. It owns the background terminal session, o
    - Create a dedicated run folder and record timezone, cwd, requested command, terminal session identifier, and any requested start/end boundaries.
    - Capture stdout and stderr from the beginning of the session so the full run stays auditable.
    - Identify and record the exact bounded-stop mechanism before launch: signal path, wrapper script, env var names, CLI flags, PID capture, and any project-specific shutdown helper.
+   - Decide in advance what the canonical evidence root will be if the command generates its own run directory, artifact bundle, database, or report file, so later diagnosis does not drift across multiple runs.
 3. Optionally update to the latest safe code state
    - Only do this step when the user explicitly asked to update the project before execution.
    - Prefer the repository's normal safe update path, such as `git pull --ff-only`, or the project's documented sync command if one exists.
@@ -73,6 +76,7 @@ This skill is an orchestration layer. It owns the background terminal session, o
    - If the user requested a future start time and no reliable scheduler is available, fail closed and report the scheduling limitation instead of starting early.
 5. Run and capture readiness
    - Execute the requested command in the same background terminal.
+   - As soon as the command emits or creates its canonical run directory, artifact root, or equivalent output location, record that path and reuse it for every later check.
    - Wait for a concrete readiness signal when the command is expected to stay up, such as a health endpoint, listening-port log, worker boot line, or queue-consumer ready message.
    - If readiness never arrives, stop the run, preserve logs, and treat it as a failed startup window.
 6. Observe and stop when bounded
@@ -84,7 +88,8 @@ This skill is an orchestration layer. It owns the background terminal session, o
 7. Explain findings from logs when requested
    - If the user asked for findings after completion, wait for the run to finish before analyzing the captured logs.
    - Invoke `analyse-app-logs` on only the captured runtime window.
-   - Pass the service or module names, environment, timezone, run folder, relevant log files, and the exact start/end boundaries.
+   - Pass the service or module names, environment, timezone, canonical run folder, relevant log files, and the exact start/end boundaries.
+   - When the command produced reports, databases, or other structured artifacts, compare them against the same run's logs before making a health judgment.
    - Reuse its confirmed issues, hypotheses, and monitoring improvements instead of rewriting a separate incident workflow.
 8. Produce the final report
    - Always summarize the actual command executed, actual start/end timestamps, execution status, and log locations.
@@ -114,7 +119,7 @@ Absence of errors alone is not enough for `healthy`.
 Use this structure in responses:
 
 1. Run summary
-   - Workspace, command, schedule if any, actual start/end timestamps, duration if bounded, readiness result, shutdown result if applicable, and log locations.
+   - Workspace, command, schedule if any, actual start/end timestamps, duration if bounded, readiness result, shutdown result if applicable, canonical run folder or artifact root, and log locations.
 2. Execution result
    - Whether the command completed, stayed up for the requested window, or failed early.
 3. Code update result

package/systematic-debug/SKILL.md

@@ -14,16 +14,18 @@ description: "Systematic debugging workflow for program issues: understand obser
 
 ## Standards
 
-- Evidence: Gather expected versus observed behavior from code and runtime facts before deciding on a cause.
-- Execution: Inspect the relevant paths, reproduce every plausible cause with tests, diagnose the real cause, then apply the minimal fix.
+- Evidence: Gather expected versus observed behavior from code and runtime facts before deciding on a cause, and when the issue involves a runtime pipeline or bounded run, anchor the investigation to one canonical artifact root or run directory instead of mixed terminal snippets from multiple runs.
+- Execution: Inspect the relevant paths, reproduce every plausible cause with tests or bounded reruns, map each observed failure to a concrete pipeline stage, distinguish toolchain/platform faults from application-logic faults, then apply the minimal fix.
 - Quality: Keep scope focused on the bug, prefer existing test patterns, and explicitly rule out hypotheses that could not be reproduced.
-- Output: Deliver the plausible-cause list, reproduction tests, validated fix summary, and passing-test confirmation.
+- Output: Deliver the plausible-cause list, the canonical evidence source, reproduction tests or reruns, validated fix summary, and passing-test confirmation.
 
 ## Core Principles
 
 - Gather facts from user reports and code behavior before changing implementation.
 - Cover all plausible causes with reproducible tests instead of guessing a single cause.
 - Keep fixes minimal, focused, and validated by passing tests.
+- When logs or runtime artifacts exist, treat one run as canonical and compare every conclusion against that same run's generated artifacts, not against ad hoc console recollection.
+- When the failing flow crosses multiple layers, identify the last confirmed successful stage before assigning blame.
 
 ## Trigger Conditions
 
@@ -39,10 +41,11 @@ Also auto-invoke this skill when mismatch evidence appears during normal executi
 
 ## Required Workflow
 
-1. **Understand and inspect**: Parse expected vs observed behavior, explore relevant code paths, and build a list of plausible root causes.
-2. **Reproduce with tests**: Write or extend tests that reproduce every plausible cause.
-3. **Diagnose and confirm**: Use reproduction evidence to confirm the true root cause and explicitly rule out non-causes.
-4. **Fix and validate**: Implement focused fixes and iterate until all reproduction tests pass.
+1. **Understand and inspect**: Parse expected vs observed behavior, explore relevant code paths, record the canonical failing run or artifact root when runtime output is involved, and build a list of plausible root causes.
+2. **Map the failure boundary**: Break the flow into concrete stages such as setup, startup, readiness, steady-state execution, persistence, and shutdown, then identify the last stage that is confirmed to have succeeded.
+3. **Reproduce with tests or bounded reruns**: Write or extend tests that reproduce every plausible cause, and when the bug depends on runtime orchestration rerun the same bounded command or scenario instead of switching contexts mid-investigation.
+4. **Diagnose and confirm**: Use reproduction evidence to confirm the true root cause, explicitly rule out non-causes, and classify whether the fault belongs to the toolchain/platform layer, the orchestration layer, or application logic.
+5. **Fix and validate**: Implement focused fixes and iterate until all reproduction tests or bounded reruns pass.
 
 ## Implementation Guidelines
 
@@ -50,10 +53,13 @@ Also auto-invoke this skill when mismatch evidence appears during normal executi
 - Prefer existing test patterns and fixtures over creating new frameworks.
 - Keep the scope to bug reproduction and resolution; avoid unrelated refactors.
 - If a hypothesized cause cannot be reproduced, document why and deprioritize it explicitly.
+- For long-running or generated-artifact workflows, record the exact command, timestamps, and artifact paths before inspecting outputs so later comparisons stay on the same evidence set.
+- Do not mix baseline data and rerun data casually; compare the same scenario or command across runs and call out when a conclusion comes from a rerun rather than the original failure.
 
 ## Deliverables
 
 - Plausible root-cause list tied to concrete code paths
-- Reproduction tests for each plausible cause
+- Canonical failing run or artifact root when runtime evidence exists
+- Reproduction tests or bounded reruns for each plausible cause
 - Fix summary mapped to failing-then-passing tests
 - Final confirmation that all related tests pass