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:

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:

1. Single-Ticker Deep Dive
2. Multi-Ticker/Universe Screening
3. Macro/News-Led Investigation
4. Portfolio Refresh

Standard Routes

Single-Ticker Deep Dive

Use when the user asks to analyze, value, or decide on one ticker.

Pipeline:

1. vnstock-free-expert
2. Optional macro/news monitors
3. earnings-quality-reviewer
4. equity-valuation-framework
5. portfolio-analytics if holdings exist
6. portfolio-risk-manager
7. trade-decision-policy
8. institutional-governance if a D1 draft is justified

Multi-Ticker Screening

Use when the user asks for best stocks, VN30/sector screening, or shortlist selection.

Pipeline:

1. vnstock-free-expert
2. strategy-backtester
3. earnings-quality-reviewer on finalists
4. equity-valuation-framework
5. trade-decision-policy
6. institutional-governance

Macro/News-Led Investigation

Use when the user asks how macro or news affects Vietnam stocks.

Pipeline:

1. nso-macro-monitor
2. us-macro-news-monitor
3. vn-market-news-monitor
4. stock-picker-orchestrator
5. vnstock-free-expert
6. earnings-quality-reviewer and equity-valuation-framework for decision-critical names

Portfolio Refresh

Use when the user asks for rebalance, watchlist refresh, risk review, or portfolio action drafts.

Pipeline:

1. Read D1 portfolio state.
2. Refresh market/fundamental evidence.
3. Run macro/news monitors.
4. Run portfolio-analytics.
5. Run valuation on key holdings/watchlist names.
6. Run portfolio-risk-manager.
7. Run trade-decision-policy.
8. 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:

1. Evidence is gathered.
2. trade-decision-policy creates recommendation labels and draft target weights.
3. institutional-governance runs compliance checks.
4. Drafts with any FAIL compliance check are blocked.
5. Drafts with no FAIL checks may become pending approval.
6. Explicit user approval is required for D1 target-state promotion.
7. The new target state supersedes the previous approved target state.
8. Unchanged target positions are preserved.
9. 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:

1. What Was Fetched
2. Pipeline Chosen
3. Assumptions
4. Results
5. Confidence and Gaps
6. Risk Flags
7. Next-Step Options
8. Decision 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.