@laitszkin/apollo-toolkit 2.0.0

package/enhance-existing-features/references/e2e-tests.md

@@ -0,0 +1,25 @@
+# E2E Testing Guide
+
+## Purpose
+- Verify critical user-visible paths at end-to-end level.
+- Increase confidence in real behavior after cross-layer integration.
+
+## Required when
+- If changes impact key user-visible flows, add or update E2E tests.
+- E2E must still be evaluated even when specs are not used; if not applicable, record explicit rationale.
+
+## E2E decision rules
+- Prefer E2E for high-risk, high-impact, multi-step flow changes.
+- Integration tests may replace E2E when E2E is too costly, unstable, or hard to maintain.
+- When replacing E2E, provide equivalent risk coverage and record replacement cases plus reasons.
+
+## Design guidance
+- Focus on minimal critical path coverage; avoid over-expansion.
+- Use stable test data and reproducible flows.
+- Prioritize business outcomes over brittle UI details.
+- Prefer one critical success path and one highest-value denial/failure path over many shallow happy-path journeys.
+- Assert business-visible outcomes, not just DOM presence: final state, permission denial, user-facing error, persisted result, or prevented duplicate action.
+
+## Recording rules
+- Specs flow: record E2E or replacement strategy with outcomes in `checklist.md`.
+- Non-specs flow: explain E2E execution or replacement testing with rationale in the response.

package/enhance-existing-features/references/integration-tests.md

@@ -0,0 +1,30 @@
+# Integration Testing Guide
+
+## Purpose
+- Verify correctness of cross-layer/cross-module collaboration.
+- Focus especially on user-critical logic chains.
+- Validate business outcomes across the full changed chain, not just connectivity.
+
+## Required when
+- Any change affecting service/repository/API handlers/event flows should add or update integration tests.
+- Integration tests for user-critical logic chains are required even when specs are not used.
+
+## Coverage focus
+- Key data flow from entrypoint to output.
+- Cross-module contract and configuration interaction.
+- Common failure patterns (timeout, data inconsistency, external dependency failure).
+- External dependency state changes and fallback/compensation behavior.
+- Adversarial/abuse paths such as invalid transitions, replay, duplication, forged identifiers, or out-of-order events when relevant.
+
+## Design guidance
+- Prefer near-real dependencies inside the application boundary; mock/fake external services unless the real service contract itself is under test.
+- Build scenario matrices for external states such as success, timeout, retries exhausted, partial data, stale data, duplicate callbacks, inconsistent responses, and permission failures.
+- Keep test data reconstructable and cleanable.
+- When workflows can partially commit, assert rollback/compensation/no-partial-write behavior instead of only final status codes.
+- Assert business outcomes across boundaries: persisted state, emitted events, deduplication, retry accounting, audit trail, or intentional absence of writes/notifications.
+- Add at least one regression-style integration test for the highest-risk chain whenever the change fixes a bug or touches a historically fragile path.
+- Each test case should map to an explainable risk.
+
+## Recording rules
+- Specs flow: record IT cases and outcomes in `checklist.md`.
+- Non-specs flow: list user-critical integration tests, mocked external scenarios, adversarial cases, and outcomes in the response.

package/enhance-existing-features/references/property-based-tests.md

@@ -0,0 +1,33 @@
+# Property-based Testing Guide
+
+## Purpose
+- Verify invariants across large input combinations.
+- Validate business rules by generating or exhaustively enumerating meaningful input spaces and checking outputs against expected business behavior.
+- Catch combinational, adversarial, and boundary behavior that fixed examples often miss.
+
+## Required when
+- If changes include logic with describable invariants (calculation, transformation, sorting, aggregation, serialization), add/update property-based tests.
+- If changes include business rules that can be expressed as allowed outputs, forbidden outputs, valid transitions, rejection rules, or safety constraints, add/update property-based tests.
+- If logic depends on external services but the service can be replaced with a mock/fake to generate service states, property-based tests should cover those state combinations too.
+- If not applicable, record `N/A` with a concrete reason.
+
+## Common properties
+- Round-trip: `decode(encode(x)) == x`
+- Idempotency: repeated execution does not change the result
+- Monotonicity/conservation/set invariance
+- Generated invalid or unauthorized inputs always fail with an expected result/error class
+- Generated state transitions always end in an allowed business state
+- Under generated mocked service states, the business logic chain preserves fallback/retry/compensation rules
+
+## Design guidance
+- Properties must be machine-verifiable, whether they are invariants, allow-lists, rejection rules, or business-output predicates.
+- Generator strategy should include normal cases, boundaries, extremes, malformed inputs, and suspicious/adversarial combinations.
+- Prefer modeling the business rule directly: generate inputs, run the logic, then assert output/error/state transition matches the rule.
+- When the behavior is stateful, prefer state-machine or sequence-based properties over isolated single-call generators.
+- When exact outputs are hard to predict, use metamorphic properties (for example reordering, retrying, deduplicating, or replaying inputs should preserve an allowed relation).
+- For external-service-dependent logic, mock/fake the service and generate multiple service states (success, timeout, empty, partial, stale, inconsistent, duplicate, rejected).
+- Control execution cost while preserving reproducibility, and preserve failing seeds/examples for regression coverage.
+
+## Recording rules
+- If specs are used, record cases and outcomes in `checklist.md`.
+- If specs are not used, record cases, external-state coverage, adversarial coverage, or `N/A` reasons in the response.

package/enhance-existing-features/references/unit-tests.md

@@ -0,0 +1,29 @@
+# Unit Testing Guide
+
+## Purpose
+- Verify correctness of a single function/module and localize failures quickly.
+- Cover both success and failure paths for the smallest changed behavior unit.
+
+## Required when
+- Any non-trivial logic change should add or update unit tests.
+- Unit test evaluation is required even when specs are not used.
+
+## Coverage focus
+- Core logic branches and boundary values.
+- Error handling, validation failures, and incompatible states.
+- Function paths with highest regression risk.
+
+## Design guidance
+- Isolate external dependencies (mock/stub/fake).
+- Keep tests small and focused: one behavior per test.
+- Do not stop at happy-path assertions; verify exact errors, rejected states, and intentional lack of side effects when the unit should block an action.
+- Where the input space is small and discrete, exhaustively enumerate business inputs and expected outputs.
+- Prefer table-driven cases when many small business permutations share the same oracle.
+- Add regression tests for bug-prone or high-risk logic so previously broken behavior cannot silently return.
+- If the unit owns authorization, invalid transition, idempotency, or concurrency decisions, test those denials explicitly.
+- Keep tests reproducible and fast.
+- Avoid assertion-light smoke tests and snapshot-only coverage unless the snapshot has a strict business oracle behind it.
+
+## Recording rules
+- If specs are used, record mapped test cases and results in `checklist.md`.
+- If specs are not used, list test IDs and results in the response.

package/feature-propose/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tszkinlai
+
+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/feature-propose/README.md

@@ -0,0 +1,23 @@
+# feature-propose
+
+`feature-propose` is a Codex skill for product-oriented feature planning in existing codebases.
+It guides the agent to:
+
+1. Understand the product from real code evidence.
+2. Classify user-facing functions into MVP / Important / Enhancement / Performance.
+3. Propose numbered feature recommendations with clear implementation direction.
+4. Publish accepted proposals through `open-github-issue` with reason and suggested architecture.
+5. Record accepted feature proposals in `AGENTS.md`.
+6. Remove implemented proposals from `AGENTS.md` after delivery.
+
+## Repository layout
+
+- `SKILL.md`: skill metadata and workflow instructions.
+- `agents/openai.yaml`: agent-facing registration metadata.
+- `references/`: feature classification references used during proposal generation.
+
+## Usage
+
+Use this skill when a user asks to analyze an existing application and propose prioritized features from a PM perspective.
+
+Accepted proposals should be ready for GitHub tracking: each one includes a clear reason to prioritize and a suggested architecture that can be handed to `open-github-issue`.

package/feature-propose/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: feature-propose
+description: Professional product-management workflow for proposing features from an existing codebase. Use when the user asks to understand an application, classify features from a user perspective into MVP/Important/Enhancement/Performance tiers, ask 3-5 clarifying questions when needed, propose numbered feature recommendations, publish accepted proposals through `open-github-issue`, record accepted items in AGENTS.md, and remove implemented items from AGENTS.md.
+---
+
+# Feature Propose
+
+## Dependencies
+
+- Required: none.
+- Conditional: `open-github-issue` for accepted features that should be published as GitHub issues.
+- Optional: none.
+- Fallback: If issue publication is skipped or unavailable, keep accepted proposals synchronized in `AGENTS.md` and report the publication state explicitly.
+
+## Standards
+
+- Evidence: Understand the existing product from code, tests, and repo docs before proposing features.
+- Execution: Classify current functions first, ask questions only when necessary, then propose numbered features across the four priority tiers.
+- Quality: Keep proposals minimal, user-value driven, and tied to concrete modules, acceptance criteria, and prioritization reasons.
+- Output: Return current understanding, function classification, proposed features, confirmation request, and publication status when applicable.
+
+## Overview
+
+Act as a professional PM: build a complete understanding of the current product from code, classify capabilities by user value, propose prioritized features, publish accepted proposals through `open-github-issue`, persist accepted proposals in `AGENTS.md`, and keep the list clean by removing implemented items.
+
+## References
+
+Load these references as needed during classification:
+
+- `references/mvp-features.md`
+- `references/important-features.md`
+- `references/enhancement-features.md`
+- `references/performance-features.md`
+
+## Workflow
+
+### 1) Explore the codebase before proposing anything
+
+- Read repo-level guidance first (`AGENTS.md`, `README`, major docs).
+- Map architecture, entrypoints, user-facing flows, data models, and external integrations.
+- Identify implemented features, obvious gaps, and technical constraints from code and tests.
+- Summarize findings before moving to prioritization.
+- Refuse to guess when facts are missing; gather more evidence from code.
+
+### 2) Build a user-perspective function inventory
+
+- List the current user-facing functions as numbered items.
+- For each function, include: user goal, current behavior, pain point/opportunity, and key file references.
+- Classify each function into exactly one primary type using the reference definitions.
+- If a function spans multiple types, keep one primary type and note the secondary type briefly.
+
+### 3) Ask clarifying questions only when necessary
+
+- Ask 3-5 targeted questions only when uncertainty blocks accurate prioritization.
+- Focus questions on target users, business goal, release horizon, success metrics, and hard constraints.
+- If context is already sufficient, skip questions and continue directly.
+
+### 4) Propose features in four numbered groups
+
+- Present features in this order:
+  1. MVP features
+  2. Important features
+  3. Enhancement features
+  4. Performance features
+- Number every proposed feature (for example: `1`, `2`, `3`...) so acceptance can reference numbers.
+- For each feature include:
+  - User problem
+  - Expected user value
+  - Reason to prioritize now
+  - Suggested architecture
+  - Affected modules/files
+  - Acceptance criteria
+- Keep proposals focused and minimal; avoid over-engineering.
+
+### 5) Persist accepted features to AGENTS.md, publish them, and clean up after implementation
+
+- Ask the user to accept/reject/edit features by number.
+- Once accepted, update repo-root `AGENTS.md` with a dedicated section:
+  - `## Accepted Feature Proposals`
+- Append accepted features as a numbered list with:
+  - Date (`YYYY-MM-DD`)
+  - Type (`MVP`, `Important`, `Enhancement`, `Performance`)
+  - Short feature statement
+- Preserve existing `AGENTS.md` content and style; do not rewrite unrelated sections.
+- If `AGENTS.md` does not exist, ask before creating it.
+- For each accepted feature, invoke `open-github-issue` exactly once with feature-proposal content.
+- Default to publishing accepted features unless the user explicitly says not to create GitHub issues.
+- Pass these fields to `open-github-issue`:
+  - `issue-type`: `feature`
+  - `title`: short feature statement
+  - `proposal`: feature summary
+  - `reason`: why this feature should exist now
+  - `suggested-architecture`: minimal architecture and module plan
+  - `repo`: target repository in `owner/repo` format when known
+- Reuse the returned `mode`, `issue_url`, and `publish_error` in the response.
+- After the related feature is implemented, remove that feature entry from `## Accepted Feature Proposals` in `AGENTS.md`.
+- Remove only implemented items; keep unimplemented accepted items untouched.
+
+## Output template
+
+Use this structure when responding:
+
+1. `Current understanding` (codebase findings)
+2. `Function classification` (current functions mapped to 4 types)
+3. `Proposed features` (numbered)
+4. `Confirmation request` (ask user to accept/edit/reject by number)
+5. `Publication status` (only after accepted features are published through `open-github-issue`)

package/feature-propose/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "feature-propose"
+  short_description: "Propose prioritized product features"
+  default_prompt: "Use $feature-propose to explore a codebase, classify user-facing functions, propose numbered MVP/Important/Enhancement/Performance features, and publish accepted proposals through $open-github-issue."

package/feature-propose/references/enhancement-features.md

@@ -0,0 +1,25 @@
+# Enhancement Features Definition
+
+## What it is
+
+Enhancement features are quality-of-life improvements that make the product better, easier, or more delightful but are not essential for core success.
+
+## Classification rules
+
+Classify a feature as Enhancement when most of the following are true:
+
+1. Users can complete key workflows without it.
+2. It improves usability, convenience, or flexibility.
+3. Value is real but moderate in urgency.
+4. It is suitable for iterative delivery after higher-priority tiers.
+
+## What it is not
+
+- Capabilities needed to make the product functionally viable
+- Urgent items with major business risk if delayed
+- Pure system-level performance remediations tied to SLO breaches
+
+## PM check questions
+
+- Is this primarily a better experience rather than a missing core capability?
+- Would delaying it by one release still keep the product viable?

package/feature-propose/references/important-features.md

@@ -0,0 +1,25 @@
+# Important Features Definition
+
+## What it is
+
+Important features are high-value capabilities that significantly improve adoption, trust, retention, or operational reliability after MVP is usable.
+
+## Classification rules
+
+Classify a feature as Important when most of the following are true:
+
+1. The core workflow works without it, but user success is materially weaker.
+2. It removes frequent friction for a large share of users.
+3. It meaningfully impacts business goals (activation, retention, conversion, safety).
+4. It should follow soon after MVP in roadmap priority.
+
+## What it is not
+
+- Purely cosmetic changes with limited user impact
+- Deep optimization work without measurable user/business effect
+- Experimental ideas with unclear value
+
+## PM check questions
+
+- Does this feature produce measurable product outcome improvement?
+- Is it broadly valuable instead of only niche convenience?

package/feature-propose/references/mvp-features.md

@@ -0,0 +1,25 @@
+# MVP Features Definition
+
+## What it is
+
+MVP features are the minimum set of capabilities required for users to complete the product's core job successfully.
+
+## Classification rules
+
+Classify a feature as MVP when most of the following are true:
+
+1. Without it, primary users cannot complete the main workflow.
+2. It removes a critical blocker, risk, or failure in the core journey.
+3. It is required to validate product-market fit or core value hypothesis.
+4. It should be delivered as a minimal, testable slice.
+
+## What it is not
+
+- Nice-to-have improvements that do not block core usage
+- Pure polish changes without direct core-journey impact
+- Long-tail edge cases not needed for initial viability
+
+## PM check questions
+
+- If this feature is removed, can users still complete the main job?
+- Does this feature directly determine whether the product is usable at all?

package/feature-propose/references/performance-features.md

@@ -0,0 +1,25 @@
+# Performance Features Definition
+
+## What it is
+
+Performance features focus on speed, scalability, reliability, and efficiency, ensuring the system meets user expectations and operational targets.
+
+## Classification rules
+
+Classify a feature as Performance when most of the following are true:
+
+1. It targets latency, throughput, resource usage, uptime, or fault tolerance.
+2. User experience is degraded due to measurable performance/reliability issues.
+3. It is driven by SLO/SLA, scaling limits, or operational risk.
+4. Success can be validated with concrete technical metrics.
+
+## What it is not
+
+- New user-facing business workflows
+- General UI enhancements without measurable performance effect
+- Architectural rewrites without clear performance hypotheses
+
+## PM check questions
+
+- Which metric improves (for example: p95 latency, error rate, cost/request)?
+- What threshold or target proves the feature is successful?

package/financial-research/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: financial-research
+description: Research the most important tradeable instruments to watch for the coming week by reviewing the most recent completed local week of financial and economic news, then produce a standardized PDF market report. Use when the user asks for a weekly market briefing, macro recap, market sentiment summary, key financial news review, or a next-week trading watchlist.
+---
+
+# Financial Research
+
+## Dependencies
+
+- Required: `pdf` for the final deliverable.
+- Conditional: none.
+- Optional: none.
+- Fallback: If `pdf` is unavailable, stop and report the missing dependency instead of inventing another export workflow.
+
+## Standards
+
+- Evidence: Resolve the current local date and timezone first, then research the most recent completed 7-day local window with authoritative current sources.
+- Execution: Collect weekly market evidence, distill the macro picture, select 3-8 watchlist instruments, and hand the final report to `pdf`.
+- Quality: Use Chinese-compatible rendering requirements, verify exact dates and values, and complete screenshot-based PDF QA before finishing.
+- Output: Save only the final PDF under the month folder using the standardized market-research naming scheme.
+
+## Overview
+
+Create an evidence-based weekly market report for the next trading week. Start from the current local date and time, review the most recent completed local week of financial and economic news, distill the key market signals, and deliver a standardized PDF report in Chinese by default.
+
+## Behavior Contract
+
+GIVEN the user needs research on the instruments worth watching in the coming week  
+WHEN the agent uses this skill proactively or the user calls this skill directly  
+THEN the agent must check the current local date, time, and timezone first  
+AND define the research window as the most recent completed local 7-day period ending yesterday  
+AND search financial and economic news from that window  
+AND identify the week's macro conditions, overall market sentiment, key news, and the most important instruments to monitor next week  
+AND save the report under a month-based folder  
+AND keep only the final PDF report as the persistent deliverable  
+AND generate a standardized PDF report with Chinese-compatible characters  
+AND default the report language to Chinese unless the user explicitly requests another language.
+
+## Required Inputs
+
+Before drafting the report, confirm these facts from context or current sources:
+
+- Current local date, time, and timezone
+- Any user-specified geography, market, asset class, or language preference
+- If the user did not narrow the scope, cover the major global cross-asset picture
+
+Do not guess missing facts that materially change the report scope.
+
+## Research Window Rules
+
+1. Always resolve the user's local date first.
+2. Use the most recent completed 7-day local window that ends on yesterday.
+3. State exact calendar dates in the report.
+4. Example:
+   - if the local date is Sunday, research the previous Sunday through Saturday
+   - if the local date is Friday, research the previous Friday through Thursday
+
+## Source Rules
+
+- Use current web research for time-sensitive facts.
+- Prefer primary or authoritative sources first:
+  - central banks
+  - government statistical agencies
+  - regulators
+  - exchange operators
+  - company filings or official releases
+- Use high-quality financial reporting only to supplement, triangulate, or surface primary sources.
+- Record the publication date or event date for all important claims.
+- Separate verified facts from inference.
+
+## Workflow
+
+### 1) Lock the scope and timing
+
+- Check the current local time before searching.
+- Write down the exact research window with start date, end date, and timezone.
+- If the user names a region or market, prioritize that scope while keeping enough macro context to explain cross-asset spillovers.
+
+### 2) Collect the week's market evidence
+
+- Search the week's financial and economic news across the relevant markets.
+- Cover at least the drivers that materially moved markets during the window, such as:
+  - central bank decisions and guidance
+  - inflation, employment, growth, and liquidity data
+  - major fiscal, regulatory, or geopolitical developments
+  - important earnings or sector shocks when they changed broader risk appetite
+  - large moves in rates, equities, foreign exchange, commodities, or crypto when relevant
+- Build an evidence table before writing the report. For each item capture:
+  - date
+  - source
+  - event
+  - affected assets
+  - why it mattered during the week
+  - why it may matter next week
+
+### 3) Distill the market picture
+
+- Produce a concise macro summary of the week.
+- Judge the overall market sentiment from confirmed cross-asset behavior rather than headlines alone.
+- Explain whether the tone was risk-on, risk-off, mixed, or regime-shifting, and why.
+- Highlight conflicts in the evidence instead of forcing a single narrative.
+
+### 4) Select the instruments worth watching next week
+
+- Rank the most important tradeable instruments by expected relevance for the coming week.
+- Default to 3-8 instruments unless the user requests a different number.
+- Prefer liquid, recognizable instruments:
+  - major indices or ETFs
+  - major FX pairs
+  - government bond futures or benchmark yields
+  - major commodities
+  - liquid crypto pairs only when they were materially relevant during the week
+- For each selected instrument, include:
+  - instrument name and ticker or pair when available
+  - asset class
+  - this week's key driver
+  - what to watch next week
+  - base case or monitoring thesis
+  - main upside/downside risk or invalidation condition
+
+### 5) Write the standardized report
+
+- Start from `assets/weekly_market_report_template.md`.
+- Localize headings to the requested output language.
+- Default to Chinese if the user did not specify a language.
+- Use Chinese-compatible characters, punctuation, and fonts.
+- On macOS, do not assume a font family is available just because it worked elsewhere.
+- On macOS, prefer a locally verified CJK font in this order when the PDF workflow allows explicit font selection:
+  - `/System/Library/Fonts/Hiragino Sans GB.ttc`
+  - `/System/Library/Fonts/Supplemental/Songti.ttc`
+  - `/Library/Fonts/Arial Unicode.ttf`
+  - `/System/Library/Fonts/STHeiti Medium.ttc`
+  - `/System/Library/Fonts/STHeiti Light.ttc`
+- Do not hardcode fonts that are missing or known to render poorly on the current macOS host.
+- Do not assume `PingFang` exists on every macOS environment.
+- If the `pdf` skill already has a verified CJK-safe default on the current machine, reuse that default instead of overriding it.
+- Avoid emoji, decorative symbols, and unusual glyphs that often break in PDF rendering.
+- Only include exact price levels, yields, or percentages when they were verified from current sources.
+
+### 6) Render the final PDF
+
+- Convert the completed report into PDF through the `pdf` skill.
+- Ensure the chosen font and renderer support Chinese text and common Markdown symbols.
+- On macOS, verify the selected font path exists before rendering.
+- If the renderer cannot safely output Chinese text, fix the font or rendering path before finishing.
+
+### 7) Perform visual QA before finishing
+
+- Open the rendered PDF locally before completing the task.
+- Inspect at least:
+  - the first page
+  - one section with a table
+  - one section with dense paragraph text
+- Capture temporary screenshots of the rendered PDF pages as a final QA check before considering the report complete.
+- Verify the temporary screenshots for:
+  - correct Chinese glyph rendering
+  - no missing characters or tofu boxes
+  - reasonable line wrapping
+  - table borders and columns staying readable
+  - page margins and spacing looking clean
+  - title, headings, and body hierarchy looking visually balanced
+- If the layout or glyph rendering is wrong or unattractive, fix the font, spacing, or content structure and render again before finishing.
+- Do not treat the task as complete until this screenshot-based visual check passes.
+
+## File Layout Rules
+
+- Store reports inside a month-based folder named `YYYY-MM`.
+- If the user gives a base output directory, create or reuse `YYYY-MM` beneath it.
+- If the user does not give a base output directory, use the current working directory as the base.
+- Keep only the final PDF report as the persistent output. Do not leave Markdown, DOCX, or temporary export files behind after rendering.
+- Remove temporary working files before finishing.
+- The QA screenshots are temporary and must be deleted after the visual check unless the user explicitly asks to keep them.
+
+## Report Naming Rules
+
+- The visible report title must use this exact pattern:
+  - `[YYYY/M/D-YYYY/M/D]-market-research`
+- Build the date range from the exact research window start and end dates.
+- Example:
+  - `[2025/12/6-2025/12/13]-market-research`
+- Because `/` is not safe in macOS filenames, do not use the visible title string directly as the filename.
+- The PDF filename must be the filesystem-safe variant:
+  - `[YYYY-M-D-YYYY-M-D]-market-research.pdf`
+- Example:
+  - `[2025-12-6-2025-12-13]-market-research.pdf`
+
+## Standard Report Requirements
+
+The report must contain these sections in order:
+
+1. Report title and scope
+2. Generated time and research window
+3. Executive summary
+4. Weekly macro recap
+5. Overall market sentiment
+6. Key news and why each item mattered
+7. Instruments to watch next week
+8. Next-week watchpoints or catalyst calendar
+9. Risks and limitations
+
+## Output Rules
+
+- The default deliverable is a PDF.
+- Save the final file at `YYYY-MM/[YYYY-M-D-YYYY-M-D]-market-research.pdf`.
+- The default language is Chinese unless the user explicitly asks for another language.
+- Keep the report evidence-based, concise, and decision-useful.
+- Call out uncertainty, disputed interpretations, and missing data explicitly.
+- Do not present speculative trade recommendations as facts.

package/financial-research/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Financial Research"
+  short_description: "Research the latest completed market week and produce a PDF watchlist"
+  default_prompt: "Use $financial-research to lock the user's local timezone and most recent completed 7-day window ending yesterday, gather authoritative financial and economic sources for that period, identify the key instruments to watch next week, and produce the final report as a PDF in Chinese by default via $pdf."

package/financial-research/assets/weekly_market_report_template.md

@@ -0,0 +1,45 @@
+# {{report_title}}
+
+- Generated at: {{generated_at}}
+- Research window: {{window_start}} to {{window_end}} ({{timezone}})
+- Output file: {{report_filename}}
+- Verified font: {{font_name_or_path}}
+- Scope: {{scope}}
+- Language: {{language}}
+
+## {{executive_summary_heading}}
+
+{{executive_summary}}
+
+## {{macro_recap_heading}}
+
+{{macro_recap}}
+
+## {{market_sentiment_heading}}
+
+- Overall tone: {{overall_tone}}
+- Main drivers: {{main_drivers}}
+- Cross-asset confirmation: {{cross_asset_confirmation}}
+- What changed versus the prior regime: {{regime_shift}}
+
+## {{key_news_heading}}
+
+| Date | Event | Why it mattered this week | Why it matters next week | Main assets |
+| --- | --- | --- | --- | --- |
+| {{date_1}} | {{event_1}} | {{impact_1}} | {{forward_link_1}} | {{assets_1}} |
+
+## {{watchlist_heading}}
+
+| Instrument | Asset class | This week's driver | What to watch next week | Base case | Main risk |
+| --- | --- | --- | --- | --- | --- |
+| {{instrument_1}} | {{asset_class_1}} | {{driver_1}} | {{watchpoint_1}} | {{base_case_1}} | {{risk_1}} |
+
+## {{next_week_watchpoints_heading}}
+
+| Date | Event | Why it matters | Instruments most exposed |
+| --- | --- | --- | --- |
+| {{next_date_1}} | {{next_event_1}} | {{next_impact_1}} | {{next_assets_1}} |
+
+## {{risks_and_limitations_heading}}
+
+{{risks_and_limitations}}