@laitszkin/apollo-toolkit 2.0.0

package/analyse-app-logs/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: analyse-app-logs
+description: Comprehensive application log investigation workflow that reads logs end-to-end, correlates signals with code paths and runtime context, and identifies evidence-backed issues with impact and remediation steps. Use when users ask to analyze logs, investigate incidents, find root causes from log records, explain recurring warnings/errors, or check whether logs reveal hidden system problems.
+---
+
+# Analyse App Logs
+
+## Dependencies
+
+- Required: none.
+- Conditional: `open-github-issue` when confirmed issues should be published.
+- Optional: none.
+- Fallback: If publication is needed and `open-github-issue` is unavailable, return draft issue content instead of inventing another publisher.
+
+## Standards
+
+- Evidence: Use a bounded investigation window and correlate log lines with code, runtime context, and concrete identifiers.
+- Execution: Scope the incident, build a timeline, validate candidate issues, then prioritize and optionally publish them.
+- Quality: Separate confirmed issues from hypotheses and include time-window, log, code, impact, and confidence evidence for each report.
+- Output: Return incident summary, confirmed issues, hypotheses, monitoring improvements, and publication status.
+
+## Overview
+
+Use this skill to analyze application logs systematically with the codebase and runtime context, then report confirmed issues with clear evidence, confidence, and next actions.
+
+## Core principles
+
+- Prioritize evidence over assumptions; avoid speculative conclusions.
+- Prefer a bounded, recent investigation window over unbounded history; anchor analysis on a concrete time boundary such as the last container restart, pod recreation, deploy, or first failure.
+- Correlate log symptoms with code paths, configuration, and external dependencies.
+- Distinguish clearly between confirmed issues and hypotheses.
+- Keep findings actionable: impact, urgency, and fix direction.
+
+## Workflow
+
+1. Define investigation scope
+   - Confirm service/component, environment, and incident time window.
+   - If the user does not provide a trustworthy window, derive one from a concrete runtime boundary first, such as the last container restart, pod recreation, deploy start, worker boot, or first failure after a known healthy state.
+   - Prefer analyzing logs only inside that bounded window first (for example, from the last restart until now) to avoid stale logs polluting the diagnosis; widen the window only when the bounded slice cannot explain the symptom.
+   - Identify relevant identifiers (trace ID, request ID, user ID, job ID, tx hash).
+2. Build a timeline from logs
+   - Extract key events in chronological order within the chosen window: deploys, config changes, warnings, errors, retries, and recoveries.
+   - Group repeated symptoms by signature (error type, message prefix, stack frame, endpoint).
+3. Correlate across context
+   - Link related log lines using identifiers and timestamps.
+   - Map stack traces and log messages to exact code locations.
+   - Cross-check with runtime context (feature flags, env vars, dependency health, upstream/downstream services).
+4. Validate candidate issues
+   - Use `references/investigation-checklist.md` to verify each candidate issue before reporting.
+   - Use `references/log-signal-patterns.md` to classify common failure patterns and avoid false positives.
+5. Prioritize and propose actions
+   - Rank by severity and user/business impact.
+   - Recommend the smallest safe fixes first.
+   - Suggest additional instrumentation only when current logs cannot confirm root cause.
+6. Publish confirmed issues through dependency skill
+   - Invoke `open-github-issue` once per confirmed issue.
+   - Pass the prepared title, problem description, suspected cause, reproduction conditions, and target repo.
+   - Reuse the dependency output to report `gh-cli` / `github-token` / `draft-only` publication mode.
+
+## Evidence requirements
+
+For each reported issue, include:
+
+- Time-window evidence: selected start/end boundaries, timezone, and why this window was chosen.
+- Log evidence: concrete lines, timestamps, IDs, and frequency.
+- Code evidence: `path:line` mapping to the probable failing logic.
+- Impact statement: affected functionality, users, or data integrity risk.
+- Confidence level: high / medium / low, with reason.
+
+If evidence is insufficient, report as **hypothesis** and specify exactly what additional logs/metrics are needed.
+
+## GitHub issue handoff rules
+
+For each confirmed issue, delegate exactly one GitHub issue publication to `open-github-issue`.
+
+Pass these fields to the dependency skill:
+
+- `title`: short symptom summary such as `[Log] payment timeout spike`
+- `problem-description`: symptom, impact, and key log evidence
+- `suspected-cause`: `path:line`, causal chain, and confidence
+- `reproduction`: steps/conditions if known; otherwise leave empty
+- `repo`: target repository in `owner/repo` format when known
+
+Issue body sections must always include these three parts:
+
+- Chinese-language repositories: use localized equivalents of
+  `Problem Description`, `Suspected Cause`, and `Reproduction Conditions (if available)`.
+- Non-Chinese repositories: use
+  `Problem Description`, `Suspected Cause`, and `Reproduction Conditions (if available)`.
+
+If reproduction is unknown, let `open-github-issue` insert the default language-appropriate non-reproducible note.
+
+## Output format
+
+Use this structure in responses:
+
+1. Incident summary
+   - Scope, timeframe, and overall health status.
+2. Confirmed issues (ordered by severity)
+   - Symptom
+   - Log evidence
+   - Code correlation (`path:line`)
+   - Root cause analysis
+   - Impact
+   - Recommended remediation
+3. Hypotheses and required validation
+   - What is suspected
+   - Why confidence is limited
+   - Required data to confirm/deny
+4. Monitoring and prevention improvements
+   - Missing alerts/log fields
+   - Suggested guardrails or dashboards
+5. GitHub issue publication status
+   - Publication mode (`gh-cli` / `github-token` / `draft-only`)
+   - Created issue URLs or draft bodies with fallback reason
+
+## Resources
+
+- `references/investigation-checklist.md`: Step-by-step checklist for evidence-driven log investigations.
+- `references/log-signal-patterns.md`: Common log signatures, likely causes, validation hints, and false-positive guards.
+- Dependency skill: `open-github-issue` for deterministic issue publishing with auth fallback and README language detection.

package/analyse-app-logs/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Analyse App Logs"
+  short_description: "Analyze logs with code context to detect issues"
+  default_prompt: "Use $analyse-app-logs to inspect application logs with code context, first anchor the investigation to a bounded recent time window such as the last container restart or deploy, identify evidence-backed issues, suggest concrete remediation steps, and delegate confirmed GitHub issue publication to $open-github-issue."

package/analyse-app-logs/references/investigation-checklist.md

@@ -0,0 +1,58 @@
+# Investigation Checklist
+
+Use this checklist before finalizing conclusions.
+
+## 1) Scope and data quality
+
+- [ ] Confirm the exact incident window (start/end time and timezone).
+- [ ] Prefer a fixed, recent window anchored to a concrete runtime boundary (last container restart, pod recreation, deploy, worker boot, or first post-recovery failure).
+- [ ] If no explicit window is given, derive one before reading broad log history and record why it was chosen.
+- [ ] Confirm logs come from the correct service, environment, and version.
+- [ ] Confirm log completeness (no ingestion gaps, rotated files missing, or sampling blind spots).
+
+## 2) Signal extraction
+
+- [ ] Collect all `ERROR` and `WARN` signatures within the window.
+- [ ] Count frequency and burst periods for each signature.
+- [ ] Identify leading indicators before the first hard failure.
+
+## 3) Correlation
+
+- [ ] Correlate events by trace/request/job/transaction ID.
+- [ ] Correlate failures with deploys, config changes, and dependency incidents.
+- [ ] Correlate user-facing symptoms with backend exceptions.
+
+## 4) Code mapping
+
+- [ ] Map stack traces/log callsites to concrete code locations.
+- [ ] Verify execution path and guard conditions around the failing point.
+- [ ] Check recent changes in related modules and configuration defaults.
+
+## 5) Root-cause validation
+
+- [ ] Confirm at least one reproducible or strongly evidenced causal chain.
+- [ ] Rule out common alternatives (bad input, timeout, dependency outage, race condition, resource pressure).
+- [ ] Mark unverified claims as hypotheses, not confirmed findings.
+
+## 6) Impact and prioritization
+
+- [ ] Define affected users/systems and blast radius.
+- [ ] Estimate severity (critical/high/medium/low) using impact × frequency.
+- [ ] Separate immediate containment steps from permanent fixes.
+
+## 7) Preventive improvements
+
+- [ ] Identify missing log fields needed for faster diagnosis.
+- [ ] Suggest alert thresholds for early detection.
+- [ ] Recommend observability gaps to close (metrics/traces/health checks).
+
+## 8) GitHub issue publication
+
+- [ ] Resolve target repo (`--repo owner/name` or git `origin`).
+- [ ] Detect issue language from target repo remote README (Chinese repo -> localized issue body; otherwise English issue body).
+- [ ] If `gh auth status` succeeds, publish with `gh issue create`.
+- [ ] If `gh` is not authenticated, publish with `GITHUB_TOKEN`/`GH_TOKEN` via REST API.
+- [ ] If both auth paths are unavailable, return draft issue content and reason.
+- [ ] Ensure every issue body includes `Problem Description` (or localized equivalent).
+- [ ] Ensure every issue body includes `Suspected Cause` (or localized equivalent).
+- [ ] Ensure every issue body includes `Reproduction Conditions (if available)` (or localized equivalent).

package/analyse-app-logs/references/log-signal-patterns.md

@@ -0,0 +1,52 @@
+# Log Signal Patterns
+
+Map common log signals to likely causes. Always validate with surrounding context.
+
+## Timeout / deadline exceeded
+
+- Typical signals: `timeout`, `deadline exceeded`, `upstream request timed out`
+- Common causes: upstream latency spike, connection pool exhaustion, DNS/TLS stalls
+- Validate by checking: dependency latency trend, queue depth, connection usage, retry storms
+- False-positive guard: short-lived network blips may not explain sustained failures
+
+## Retry storm / thundering herd
+
+- Typical signals: repeated retry messages with shrinking intervals
+- Common causes: missing backoff/jitter, synchronized workers, transient dependency failures
+- Validate by checking: retry counts, concurrency bursts, same request IDs repeated rapidly
+- False-positive guard: scheduled batch windows can look bursty but expected
+
+## Authentication / authorization failures
+
+- Typical signals: `401`, `403`, `invalid token`, `signature mismatch`, `permission denied`
+- Common causes: expired credentials, clock skew, role misconfiguration, key rotation mismatch
+- Validate by checking: token expiry, IAM/ACL changes, auth service logs, server clock drift
+- False-positive guard: malicious probing traffic may not indicate platform regression
+
+## Resource exhaustion
+
+- Typical signals: `OOM`, `too many open files`, `connection refused`, `cannot allocate memory`
+- Common causes: memory leaks, unbounded queues, file descriptor leaks, pool mis-sizing
+- Validate by checking: memory/FD trends, GC pauses, restart cadence, worker lifecycle
+- False-positive guard: one-off deploy spikes can mimic leaks
+
+## Data integrity / schema mismatch
+
+- Typical signals: `constraint violation`, `invalid format`, `deserialization error`, `column missing`
+- Common causes: incompatible deploy order, partial migrations, producer-consumer contract drift
+- Validate by checking: migration history, payload schema version, deploy timeline
+- False-positive guard: corrupt legacy records may produce localized errors only
+
+## Concurrency / race condition
+
+- Typical signals: duplicate operations, intermittent lock errors, non-deterministic failures
+- Common causes: missing idempotency, lock scope too narrow, stale read-modify-write cycles
+- Validate by checking: duplicate keys, overlapping timestamps, critical-section boundaries
+- False-positive guard: manual replays can create similar duplicate traces
+
+## External dependency outage
+
+- Typical signals: transport errors, DNS failures, handshake failures, 5xx bursts from upstream
+- Common causes: provider outage, certificate changes, network partition, rate limiting
+- Validate by checking: provider status pages, cross-region behavior, status-code distribution
+- False-positive guard: local config errors can appear as dependency outage

package/answering-questions-with-research/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: answering-questions-with-research
+description: This skill should be used when the user asks a question that needs complete, evidence-based answers by combining repository discovery with web research.
+---
+
+# Answering Questions With Research
+
+## Dependencies
+
+- Required: none.
+- Conditional: none.
+- Optional: none.
+- Fallback: not applicable.
+
+## Standards
+
+- Evidence: Verify repository facts from local files first and confirm time-sensitive claims with current external sources.
+- Execution: Perform repository discovery before web research, then combine both into one evidence-based answer.
+- Quality: Prefer official or primary sources, state what was and was not verified, and do not guess.
+- Output: Respond concisely, separate confirmed facts from uncertainty, and include external source links when used.
+
+## Trigger Conditions
+
+Use this skill whenever the user asks a question and expects a complete, factual answer.
+
+## Required Workflow
+
+1. Perform repository discovery first.
+   - Explore the codebase before answering.
+   - Locate relevant files with fast search tools (for example, `rg --files` and `rg`).
+   - Read only the files needed to confirm facts.
+2. Perform web search second.
+   - Gather external information relevant to the user question.
+   - Prefer official docs and primary sources.
+   - Verify time-sensitive facts with current sources.
+3. Produce a complete answer.
+   - Combine repository findings and web findings.
+   - Address all user concerns as fully as possible.
+   - Clearly separate confirmed facts from assumptions.
+   - Include source links for externally verified claims.
+
+## Quality Rules
+
+- Do not guess when evidence is missing.
+- State what was verified and what could not be verified.
+- Keep the answer concise, direct, and actionable.

package/answering-questions-with-research/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Answering Questions With Research"
+  short_description: "Combine repo discovery and web research for evidence-based answers"
+  default_prompt: "Use $answering-questions-with-research to answer this question by exploring the repository first, then verifying relevant external facts with current primary sources, and clearly separate confirmed findings from unknowns or assumptions."

package/bin/apollo-toolkit.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+const { run } = require('../lib/cli');
+
+run(process.argv.slice(2)).then((code) => {
+  process.exitCode = code;
+});

package/commit-and-push/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lai Tsz Kin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/commit-and-push/README.md

@@ -0,0 +1,26 @@
+# commit-and-push
+
+A Codex skill for commit-and-push workflows without release/version operations.
+
+## What this skill does
+
+`commit-and-push` helps agents safely submit local changes by:
+
+1. Inspecting git status and staged state.
+2. Running `specs-to-project-docs` when the current change set contains new completed spec files.
+3. Running `align-project-documents` and `maintain-project-constraints` before commit.
+4. Running additional dependency skills for code-affecting diffs.
+5. Committing with a concise Conventional Commit message.
+6. Pushing to the current branch.
+
+## Scope
+
+Use this skill when the user asks to commit/push/submit changes and does **not** request:
+
+- version bumping
+- tagging
+- release changelog workflows
+
+If the current diff includes new completed specs, convert them into categorized project docs first and let `specs-to-project-docs` remove or archive the superseded spec files.
+
+For release workflows, use `version-release`.

package/commit-and-push/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: commit-and-push
+description: "Guide the agent to submit local changes with commit and push only (no versioning). Use when users ask to commit, submit, or push changes without requesting tag/version/release operations. If the current change set includes new completed spec files, run `specs-to-project-docs` before the final commit so project docs are standardized into categorized files and the old specs are removed or archived."
+---
+
+# Commit and Push
+
+## Dependencies
+
+- Required: `align-project-documents` and `maintain-project-constraints` before the final commit.
+- Conditional: `review-change-set`, `discover-edge-cases`, and `harden-app-security` for code-affecting changes; `specs-to-project-docs` when the current change set includes new completed spec files.
+- Optional: none.
+- Fallback: If any required dependency is unavailable, or if `specs-to-project-docs` is required for spec conversion but unavailable, stop and report the missing dependency.
+
+## Standards
+
+- Evidence: Inspect git state and classify the change set before deciding which quality gates apply.
+- Execution: Run the dependency skills in order, standardize project docs into categorized outputs when new specs are present, preserve staging intent, then commit and push without release steps.
+- Quality: Re-run relevant validation for runtime changes and keep project docs plus agent constraints synchronized before committing.
+- Output: Produce a concise Conventional Commit and push it to the current branch only.
+
+## Overview
+
+Run a standardized commit-and-push workflow without release/version steps.
+
+## References
+
+Load only when needed:
+
+- `references/commit-messages.md`
+- `references/branch-naming.md`
+
+## Workflow
+
+1. Inspect current state
+   - Run `git status -sb`, `git diff --stat`, and `git diff --cached --stat`.
+   - Check staged files with `git diff --cached --name-only`.
+2. Classify changes
+   - `code-affecting`: runtime code, tests, build scripts, CI logic, or behavior-changing config.
+   - `docs-only`: content updates only (for example README, docs, comments).
+   - `new-specs-present`: the current change set adds or updates completed planning files such as `spec.md`, `tasks.md`, `checklist.md`, or their containing plan directories.
+3. Run code-affecting dependency skills (when applicable)
+   - Execute `review-change-set` first to challenge architecture and simplification assumptions.
+   - Execute `discover-edge-cases` next to surface unresolved edge-case risks.
+   - Resolve any confirmed findings.
+   - Ensure `harden-app-security` has been executed for the same code-affecting scope as an adversarial quality gate.
+   - Re-run relevant tests when runtime logic changes.
+4. Standardize project docs when new specs are present
+   - Execute `specs-to-project-docs` when `new-specs-present` is true and the related implementation scope is already complete enough for documentation consolidation.
+   - Let `specs-to-project-docs` convert the relevant specs into categorized project docs such as `docs/README.md`, `docs/getting-started.md`, `docs/configuration.md`, `docs/architecture.md`, `docs/features.md`, and `docs/developer-guide.md`.
+   - Let the skill normalize any existing project docs to the same structure and remove or archive superseded source spec files.
+   - If the specs still represent active unfinished work, do not convert them yet; report that the spec files remain active and should not be deleted.
+5. Run pre-commit sync dependencies
+   - Execute `align-project-documents` after spec conversion and code/doc scans are complete.
+   - Execute `maintain-project-constraints` immediately before the commit.
+6. Keep docs synchronized when needed
+   - Apply the output from `specs-to-project-docs` when new specs were converted into categorized project docs.
+   - Apply the output from `align-project-documents` when behavior or usage changed.
+   - Apply the output from `maintain-project-constraints` when agent workflow/rules changed.
+7. Commit
+   - Preserve user staging intent where possible.
+   - Write a concise Conventional Commit message using `references/commit-messages.md`.
+8. Push
+   - Push commit(s) to the current branch.
+
+## Notes
+
+- Never run version bump, tag creation, or changelog release steps in this skill.
+- If release/version/tag work is requested, use `version-release` instead.
+- If a new branch is required, follow `references/branch-naming.md`.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Commit and Push"
+  short_description: "Submit local changes with commit and push only"
+  default_prompt: "Use $commit-and-push to inspect the current git state, classify the diff, run required dependency skills ($align-project-documents and $maintain-project-constraints, plus $review-change-set, $discover-edge-cases, and $harden-app-security as quality gates for code-affecting changes), run $specs-to-project-docs when the current change set includes new completed spec files so project docs are standardized into categorized files and old specs are removed or archived, then create a concise Conventional Commit and push to the current branch without any versioning or release steps."

package/commit-and-push/references/branch-naming.md

@@ -0,0 +1,15 @@
+# Branch Naming Instructions
+
+Use a short, descriptive branch name in this pattern:
+
+- type/short-description
+- type/issue-id-short-description (if issue ids are used)
+
+Guidelines:
+- Use lowercase letters and hyphens only.
+- Align type with commit message types (feat, fix, docs, chore, refactor, test).
+- Do not rename the current branch unless the user explicitly asks.
+
+Examples:
+- feat/add-rpc-timeouts
+- fix/1234-parse-registry

package/commit-and-push/references/commit-messages.md

@@ -0,0 +1,19 @@
+# Commit Message Instructions
+
+Use a concise Conventional Commit style:
+
+- Format: type: short subject
+- Subject: imperative, lower case, no trailing period, <= 72 chars
+- Scope: include only if the repo already uses it (type(scope): subject)
+- Select `type` from the actual change intent in the staged diff (feature, bugfix, docs, etc.)
+- Do not use version-only subjects (for example `feat: v1.2.3`)
+- If the commit only contains release metadata, use `chore(release): ...`
+
+Common types:
+- feat, fix, docs, chore, refactor, test, style, perf, build, ci
+
+Examples:
+- feat: add rpc retry backoff
+- fix: handle empty response payload
+- docs: update env var table
+- chore(release): bump version and update changelog

package/deep-research-topics/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LaiTszKin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/deep-research-topics/README.md

@@ -0,0 +1,43 @@
+# Deep Research Topics
+
+`deep-research-topics` is a reusable research skill for producing evidence-based topic deliverables.
+
+It helps an agent:
+
+1. Understand and scope a research request.
+2. Break the topic into concrete research questions.
+3. Perform deep research with authoritative sources.
+4. Read workspace files to match the existing writing style.
+5. Produce a final file in PDF by default, or Word/slides output when requested.
+
+## Dependency skills
+
+- `pdf`: default output format
+- `doc`: optional Word output when requested
+- `slides`: optional slide output when requested
+
+## Language behavior
+
+- Default output language: Chinese
+- If the user requests another language, follow the user request.
+- If the workspace already has a dominant language and the user does not override it, follow the workspace language.
+- Use characters and formatting that are safe for Chinese or mixed CJK output.
+
+## Repository layout
+
+- `SKILL.md`: trigger rules, workflow, and dependency contract
+- `agents/openai.yaml`: agent-facing metadata
+
+## Typical use cases
+
+Use this skill for:
+
+- topic briefings
+- background research memos
+- literature scans
+- competitive or landscape research
+- decision-support reports
+
+## License
+
+MIT. See `LICENSE`.

package/deep-research-topics/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: deep-research-topics
+description: "Research specific topics deeply and turn them into evidence-based deliverables. Use when users need a structured research report, briefing, background memo, literature scan, or decision-support document grounded in authoritative sources. Default to PDF output, but switch to DOCX or PPTX when the user explicitly asks for those formats."
+---
+
+# Deep Research Topics
+
+## Dependencies
+
+- Required: none.
+- Conditional: `pdf` by default, `doc` when Word output is requested, and `slides` when slides are requested.
+- Optional: none.
+- Fallback: If the required output skill is unavailable, stop and report the missing dependency instead of inventing another export path.
+
+## Standards
+
+- Evidence: Prioritize authoritative sources, verify time-sensitive claims, and keep traceable notes for important facts.
+- Execution: Define research questions, inspect workspace style, draft the content, then hand off to exactly one output skill unless multiple formats are explicitly requested.
+- Quality: Distinguish verified facts from analysis or inference and call out limitations, conflicts, or stale data explicitly.
+- Output: Deliver a polished research file with clear sections, citations, dates, and source links.
+
+## Overview
+
+Use this skill when a user needs topic research that goes beyond a quick answer and should end as a polished file deliverable.
+
+## Required Workflow
+
+1. Understand the request
+   - Identify the research goal, target audience, decision context, time range, geography, and required depth.
+   - Extract explicit deliverable requirements such as format, sections, length, and citation expectations.
+2. Break the topic into research questions
+   - Define the topic boundary and key terms.
+   - Split the work into the main subtopics, competing views, recent developments, supporting data, and open questions.
+   - Turn vague requests into a concrete research checklist before drafting.
+3. Perform deep research
+   - Prioritize authoritative sources: official documentation, government or regulator materials, academic papers, standards bodies, company filings, and well-established institutions.
+   - Use secondary reporting only to triangulate, summarize, or discover primary sources.
+   - Verify time-sensitive facts with current sources and record publication dates.
+   - Keep traceable notes for claims, metrics, dates, and citations.
+4. Read workspace files before writing
+   - Inspect relevant files in the current workspace to learn the existing language, tone, terminology, heading structure, table style, and citation pattern.
+   - Reuse established structure and vocabulary when a clear house style already exists.
+   - If no relevant files exist, use a clean evidence-first structure.
+5. Decide output language and character compatibility
+   - Default to Chinese.
+   - If the user explicitly requests another language, follow the user request.
+   - Otherwise, if the workspace already has a dominant language, follow that language for consistency.
+   - Use characters, punctuation, and fonts that are safe for Chinese or mixed CJK output. Avoid unusual glyphs that commonly break in PDF, DOCX, or PPTX rendering.
+6. Draft the deliverable
+   - Include an executive summary or research overview.
+   - Organize findings by research question or subtopic.
+   - Distinguish verified facts from analysis or inference.
+   - Include citations, dates, and source links for important claims.
+   - State limitations, unresolved questions, and conflicts in the evidence when they exist.
+7. Hand off to the selected output skill
+   - Use `pdf` by default.
+   - Switch to `doc` or `slides` only when requested or clearly required by the workspace convention.
+   - Preserve headings, tables, citations, and appendix material during the handoff.
+   - If the selected output skill is `pdf`, require PDF visual QA before completion:
+     - open the rendered PDF locally
+     - capture temporary screenshots from representative pages
+     - inspect layout, spacing, glyph rendering, tables, and dense text blocks
+     - regenerate if the visual result is wrong or unattractive
+     - delete all temporary QA screenshots after the final PDF passes inspection unless the user explicitly asks to keep them
+
+## Source Quality Rules
+
+- Prefer primary and authoritative sources over commentary.
+- Use multiple high-quality sources when the claim is important or contested.
+- Do not guess when evidence is incomplete.
+- Call out uncertainty, disagreement, or stale data explicitly.
+- Keep citations specific enough that another agent can trace them quickly.
+
+## Output Expectations
+
+The final deliverable should usually contain:
+
+1. Title and scope
+2. Executive summary
+3. Research questions or evaluation framework
+4. Findings by section
+5. Evidence and citations
+6. Implications, recommendations, or next steps when requested
+7. Limitations or open questions

package/deep-research-topics/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Deep Research Topics"
+  short_description: "Research a topic deeply and deliver a file-backed briefing"
+  default_prompt: "Use $deep-research-topics to understand the user's research goal, break the topic into concrete research questions, gather high-credibility and authoritative sources, inspect relevant workspace files for language and style consistency, and produce a polished deliverable in PDF by default or DOCX/PPTX when the user requests those formats."

package/develop-new-features/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lai Tsz Kin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.