Vietnam Stock Institutional Plugin
Overview
vietnam-stock-institutional is a coordinated skill plugin for Vietnam listed-equity research, valuation, portfolio risk, recommendation labels, and approval-gated institutional governance.
The plugin is designed for HOSE, HNX, and UPCoM equities. It can support professional decision workflows and D1-backed target portfolio governance. It does not support broker execution in the current phase.
Included Skills
The plugin bundles 12 skills:
| Skill | Role |
|---|---|
stock-picker-orchestrator | Top-level router for stock analysis requests. |
vnstock-free-expert | Free-tier-safe Vietnam market and fundamental data workflow using vnstock. |
nso-macro-monitor | Official Vietnam NSO macro release monitoring. |
vn-market-news-monitor | Domestic Vietnam financial media narrative monitoring. |
us-macro-news-monitor | US macro/news spillover mapping to Vietnam sectors. |
strategy-backtester | Historical ranking and selection strategy validation. |
earnings-quality-reviewer | Earnings quality, cash conversion, accrual, and red-flag review. |
equity-valuation-framework | Multiples, DCF, scenario valuation, and thesis standard. |
portfolio-analytics | Portfolio volatility, beta, drawdown, correlation, and concentration analytics. |
portfolio-risk-manager | IPS mini, sizing policy, triggers, invalidation, and rebalance discipline. |
trade-decision-policy | Converts evidence into BUY, ADD, HOLD, TRIM, or EXIT labels and target-weight drafts. |
institutional-governance | Cloudflare D1 approvals, compliance checks, audit events, and approved target portfolio state. |
Core Operating Boundary
Allowed:
- Analyze Vietnam stocks.
- Screen and rank listed Vietnam equities.
- Run valuation and portfolio risk workflows.
- Produce structured labels:
BUY,ADD,HOLD,TRIM,EXIT. - Create approval-gated target portfolio drafts.
- Promote approved drafts to D1 approved target portfolio state after explicit user approval.
Not allowed:
- Place broker orders.
- Call broker APIs.
- Create executable order tickets.
- Produce market/limit/time-in-force/routing instructions.
- Treat an approved target portfolio state as an executable order.
Recommended Entry Point
Start with stock-picker-orchestrator for most user requests.
It classifies the task into one of four routes:
Single-Ticker Deep DiveMulti-Ticker/Universe ScreeningMacro/News-Led InvestigationPortfolio Refresh
Standard Routes
Single-Ticker Deep Dive
Use when the user asks to analyze, value, or decide on one ticker.
Pipeline:
vnstock-free-expert- Optional macro/news monitors
earnings-quality-reviewerequity-valuation-frameworkportfolio-analyticsif holdings existportfolio-risk-managertrade-decision-policyinstitutional-governanceif a D1 draft is justified
Multi-Ticker Screening
Use when the user asks for best stocks, VN30/sector screening, or shortlist selection.
Pipeline:
vnstock-free-expertstrategy-backtesterearnings-quality-revieweron finalistsequity-valuation-frameworktrade-decision-policyinstitutional-governance
Macro/News-Led Investigation
Use when the user asks how macro or news affects Vietnam stocks.
Pipeline:
nso-macro-monitorus-macro-news-monitorvn-market-news-monitorstock-picker-orchestratorvnstock-free-expertearnings-quality-reviewerandequity-valuation-frameworkfor decision-critical names
Portfolio Refresh
Use when the user asks for rebalance, watchlist refresh, risk review, or portfolio action drafts.
Pipeline:
- Read D1 portfolio state.
- Refresh market/fundamental evidence.
- Run macro/news monitors.
- Run
portfolio-analytics. - Run valuation on key holdings/watchlist names.
- Run
portfolio-risk-manager. - Run
trade-decision-policy. - Run
institutional-governance.
D1 Governance Model
Cloudflare D1 is the source of truth for:
- Portfolio policy.
- Holdings snapshots.
- Latest approved target state.
- Pending drafts.
- Approvals.
- Compliance records.
- Audit events.
State lifecycle:
- Evidence is gathered.
trade-decision-policycreates recommendation labels and draft target weights.institutional-governanceruns compliance checks.- Drafts with any
FAILcompliance check are blocked. - Drafts with no
FAILchecks may become pending approval. - Explicit user approval is required for D1 target-state promotion.
- The new target state supersedes the previous approved target state.
- Unchanged target positions are preserved.
- Audit events are written for state transitions.
Approval question:
Do you approve the pending target portfolio draft changes listed above for D1 promotion to the approved target state? This approval does not authorize broker execution.
Harness Agent Guide
For a complete paste-ready guide for another agent, see:
docs/harness-agent-stock-skill-guide.md
For Hermes scheduled review prompt, see:
docs/institutional-vn-daily-cron-prompt.md
Required Output Sections
For orchestrated investment work, return:
What Was FetchedPipeline ChosenAssumptionsResultsConfidence and GapsRisk FlagsNext-Step OptionsDecision and Governance
Decision and Governance must include:
- Recommendation label.
- Draft target weight and maximum weight.
- Compliance status.
- Approval requirement.
- D1 write intent.
- Broker execution status:
Disabled.
Validation
From the original workspace, the source skill system was validated with:
python3 tools/validate_stock_skills.py
./tools/smoke_stock_skill_scripts.sh
cd platform/cloudflare && npm ci && npm run typecheck && npm test
Expected baseline:
- 12 skills pass static validation.
- CLI and fixture smoke checks pass.
- D1 governance markers pass.
- Broker execution remains disabled.
- Cloudflare governance tests pass.
Notes
This plugin bundles the skills and operating docs. The Cloudflare Worker/D1 implementation files remain in the source workspace under skills/platform/cloudflare; they are not included as executable plugin runtime code in this package.