AGENTS.md — AI-MarketTracker (Codex CLI Rules & Context)
Purpose. This document gives Codex CLI and human contributors a single source of truth for how to build and evolve AI-MarketTracker without code drift. It defines non-negotiables, coding standards, data contracts, the Zero-DTE options strategy, and acceptance checks the agent must pass before making changes.
0) Project Charter (Do Not Drift)
- Goal: A hedge-fund-grade trading assistant powered by open-source LLMs, MCP servers, and RAG over finance knowledge.
- Sources of truth:
- Polygon.io for stocks, options, indices (SPX), greeks, IV, snapshots (via Polygon MCP + REST fallback). oai_citation:0‡GitHub
- Congressional activity (CapitolTrades) for issuer↔ticker signals.
- Macro calendar (Fed/FOMC, CPI/PCE) to detect high-vol events.
- Memory & RAG: MongoDB Atlas Vector Search embedded alongside OLTP data. oai_citation:1‡MongoDB
- LLM serving: vLLM (OpenAI-compatible server) or TGI behind an internal router. oai_citation:2‡VLLM Documentation
- Agent runtime: Codex CLI operating in repo root with this file as authoritative context. oai_citation:3‡OpenAI Developers
1) Non-Negotiables
- Do not alter existing trade evaluation logic, GPT prompt format, or MongoDB field structures without explicit approval.
- All new API contracts must use TypeScript types or Zod schemas and be backward-compatible.
- Security: no secrets in code; use env vars and local secret managers.
- Reproducibility: every code change must come with docs updates (README, this file, or
/docs).
2) Tech & Environment
- Frontend: React + Vite + TypeScript
- Backend: Node.js + Express + TypeScript
- Data: MongoDB (OLTP) + Atlas Vector Search for embeddings oai_citation:4‡MongoDB
- LLM: vLLM OpenAI-compatible endpoint (or TGI) oai_citation:5‡VLLM Documentation
- Agent: Codex CLI (local) oai_citation:6‡OpenAI Developers
- MCP: Prefer Polygon MCP server with our thin adapter for normalization/caching; REST fallback for gaps. oai_citation:7‡GitHub
3) Directory Contracts
Keep this shape. Additions are allowed; moving/removing top-level folders requires approval.
AI-MarketTracker/ ├─ client/ # React + Vite + TS (SSE/WebSocket for streams) │ ├─ src/ │ │ ├─ pages/ (Dashboard, Ideas, History, Settings) │ │ ├─ features/ (trade, auth) │ │ ├─ services/ (axios client, SSE, typed APIs) │ │ ├─ components/ (ui, charts, layout) │ │ ├─ contexts/ (AuthContext, ThemeContext) │ │ ├─ types/ (DTOs) │ │ └─ utils/ (formatters, guards) │ └─ .env.example ├─ server/ # Node/Express + TS │ ├─ src/ │ │ ├─ routes/ (trades, features, health, sse) │ │ ├─ controllers/ (preserve evaluation logic) │ │ ├─ services/ │ │ │ ├─ orchestrator/ │ │ │ ├─ risk-engine/ │ │ │ ├─ evaluator/ (ex-ante, ex-post) │ │ │ ├─ rag/ (retriever, indexer, corpus) │ │ │ ├─ llm-router/ (prompts, model selection) │ │ │ ├─ mcp-clients/ (polygon, congress, news, fed) │ │ │ ├─ feature-store/ (RSI, MACD, VWAP) │ │ │ └─ cache/ (Redis) │ │ ├─ models/ (Mongo schemas) │ │ ├─ workers/ (feature-ingest, outcome-cron, rag-indexer, finetune) │ │ ├─ config/ (env, mongo, redis, otel) │ │ └─ types/ (shared DTOs) │ └─ .env.example ├─ docs/ # Keep lightweight until endpoints stabilize │ └─ (optional future) ARCHITECTURE.md └─ AGENTS.md # THIS FILE (rules & context for Codex)
4) Strategy Playbook — Zero-DTE Options Selling (SPX)
The assistant must follow these steps and explain rationale in outputs.
Core principle: sell zero-DTE OTM options with ~20→12 delta targeting high probability of expiring worthless (≈70–80%). (This is a heuristic, not a guarantee; always enforce risk caps.)
Step A — Macro/Event Check
- Query today’s macro calendar for Fed speeches, FOMC, CPI/PCE or other market-moving events.
- If no major events, proceed; if major events, expect higher IV & widen buffers (farther OTM, smaller size), or skip.
Why: Event-driven volatility elevates tail risk.
Step B — Market Context (“Information Radar”)
- Market-cap leaders: MSFT, AAPL, NVDA, GOOGL, AMZN, META, TSLA → gauge market beta.
- Risk-on ETFs: XLK, XLF, XLY, XLI, XLB, SMH, ARKK → breadth/risk appetite.
- Defensive ETFs: XLV, XLP, XLU, XLRE, XLC → leadership implies caution.
- Internals: A/D line, RSI, momentum gauges → confirm bias (bullish / bearish / neutral).
Step C — SPX Range Framing (Trade Window ~ last 2 hours)
- Time window guideline: 1:30–2:00 PM ET to close.
- On 15-min SPX: mark day high/low, compute midpoint, identify support/resistance; include Quantum VPOC if available.
- Strike selection: choose OTM options with delta 20→12.
- Bullish/neutral: sell put credit spread (short put + long lower put).
- Bearish: sell call credit spread (short call + long higher call).
- Premium targeting: if late-day premium is light, adjust contract count (respect risk caps).
Step D — Monitor to Expiry
- Keep a news feed open; track tick speed and 1m/5m/15m charts.
- Watch RSI/TRIX, A/D line, and delta drift on your strikes.
- Risk rule: if price approaches strikes or breaks key levels, reduce risk or exit.
- If safe into close, let expire to collect credit (avoid extra day trades).
Mapping to Data Inputs (must be wired by the agent):
- SPX index data: via Indices API (
I:SPX) for levels & aggregates. oai_citation:8‡Polygon - SPX options chain: via Options API; confirm options ticker format (YYMMDD + C/P + strike). oai_citation:9‡Polygon
- Greeks/IV & snapshots: via Polygon options endpoints/MCP tools. oai_citation:10‡Polygon
- Macro schedule: Fed/FOMC/CPI/PCE via our macro MCP (data sources vary; document when locked).
- ETF/Leaders quotes: via Polygon equities endpoints or snapshots.
5) Data Contracts & Schemas
5.1 Recommendation Output (JSON)
The LLM must emit this exact shape (stringified JSON), validated in the backend:
{
"ticker": "SPX",
"strategy": "zero_dte_credit_spread",
"bias": "bullish | bearish | neutral",
"window": { "startET": "13:30", "endET": "16:00" },
"spread": {
"type": "put_credit | call_credit",
"short_leg": { "option": "O:SPX<YYMMDD><C|P><strike*1000>", "delta": 0.18 },
"long_leg": { "option": "O:SPX<YYMMDD><C|P><strike*1000>", "delta": 0.10 },
"width": 5
},
"sizing": { "contracts": 2, "per_contract_credit": 0.65, "est_max_loss": 435.00 },
"risk": { "stop_rule": "breach_midpoint_or_SR", "event_risk": "none|elevated" },
"context": {
"leaders": { "green": ["MSFT","NVDA"], "red": ["AAPL"] },
"risk_on_etfs": { "green_count": 5, "tickers": ["XLK","SMH","XLF"] },
"defensive_etfs": { "leading": false },
"internals": { "ad_line": "positive", "rsi_15m": 54 }
},
"notes": "Late-day theta favorable; choose 20→12 delta OTM; widen if IV high."
}
Options symbol format reference (underlying + YYMMDD + C/P + strike×1000). 
5.2 Retrieval Query (RAG)
- Use MongoDB Atlas Vector Search; hybrid filter by { ticker: "SPX" | "SPY", doc_type, date_range }. 
- Top-k 8–20; apply recency bias.
⸻
6) MCP Usage Policy
- Default to the Polygon MCP server for tool calls. It exposes Polygon APIs as MCP tools and is actively maintained/experimental. 
- If a needed endpoint isn’t exposed, call Polygon REST directly through our adapter.
- Normalize all responses to our DTOs before passing to RAG/LLM.
⸻
7) LLM Serving Rules
- Prefer vLLM OpenAI-compatible server (drop-in for Chat API). Configure model, max tokens, temperature, and enable continuous batching for throughput. 
- Use two paths:
- Fast path: short prompt for quotes/what-ifs.
- Deep path: full RAG context + strategy rubric above.
- Always produce valid JSON per §5.1; no extra prose in the JSON block.
⸻
8) Risk & Compliance Guardrails
- Capital check: ensure credit spread cost/risk ≤ user capital slice.
- Event risk: widen OTM or reduce size on macro days (from Step A).
- Liquidity: minimum open interest & spread width sanity checks.
- Stop/Exit rules: codify breach of midpoint or key S/R.
⸻
9) Logging, Testing, Git
- Logs: Pino JSON w/ ISO timestamp + requestId; log input params, chosen strikes, deltas, credits, risk flags.
- Tests:
- Unit: DTO validators, deltas-in-range, JSON schema.
- Integration: MCP adapter happy/edge paths; RAG retrieval filters.
- Commits: Conventional Commits (feat:, fix:, docs:).
- PRs: include screenshots or sample JSON outputs.
⸻
10) Codex CLI — Task Templates
Run Codex in repo root. If Codex proposes changes that violate §1 non-negotiables, reject and re-plan. 
Task: Wire Polygon MCP + REST fallback
/task Create server/src/services/mcp-clients/polygon with client.ts calling Polygon MCP tools, restFallback.ts for missing endpoints, and adapter.ts that normalizes to our DTOs. Add unit tests for both paths.
Task: Implement SPX chain fetch + delta filter
/task Add orchestrator step to fetch SPX options chain, compute deltas, select OTM 20→12, and return candidate spreads with credits. Include min OI and max spread width checks.
Task: RAG retriever
/task Implement server/src/services/rag/retriever.ts using Atlas Vector Search with filters {ticker, doc_type, date_range}, topK=12, recency bias. Add tests using fixtures.
Task: LLM deep path
/task Add llm-router deep path that builds system+context prompt and enforces JSON schema from §5.1. Use vLLM OpenAI-compatible endpoint.
⸻
11) MVP Checklist (Agent must update status in PRs)
- Polygon MCP adapter + REST fallback wired (SPX, options, greeks) 
- SPX range framing + delta 20→12 spread selector
- Macro event gate (Fed/FOMC/CPI/PCE)
- Risk engine: affordability + size + guardrails
- RAG retriever (Atlas Vector Search) + embeddings job 
- vLLM deep path with strict JSON output 
- Evaluator (ex-post) to label outcomes and feed fine-tune sets
- Frontend: Ideas page (SSE), History, Dashboard (leaders/ETFs/internals)
⸻
12) Quick Reference (Docs & Formats)
- Polygon MCP (official GitHub) — capabilities & tool list. 
- Polygon indices & tickers (I:SPX) — SPX levels & aggregates. 
- Polygon options contracts — contract overview; symbol format guide. 
- Atlas Vector Search — overview and $vectorSearch aggregation. 
- vLLM OpenAI-Compatible Server — serving models behind Chat API. 
- Codex CLI (local agent) — usage, AGENTS.md integration. 
- Mermaid in GitHub (optional future docs) — render diagrams in Markdown. 
⸻
Appendix: Sample Queries
- All indices tickers (includes SPX):
GET /v3/reference/tickers?market=indices&active=true&limit=1000&apiKey=... (Polygon) 
- Options contract detail (by symbol):
GET /v3/reference/options/contracts/{options_ticker} (Polygon) 
Keep this file updated as endpoints mature. End of AGENTS.md.