Supervisor Agent

Status: Verified against code Last Updated: 2026-02-04

Role in Plain English

The Supervisor Agent is the final decision maker. It takes all the verdicts from Technical, Macro, and Wild Card agents and produces the complete trade plan:

"Given everything we know, what's the trade and how do we execute it?"

What It Does

1. Synthesizes Agent Verdicts

The Supervisor receives:

• Technical Verdict: Direction, confidence, entry type, S/R levels
• Macro Verdict: Market regime, cross-asset alignment, economic assessment
• Wild Card Verdict: Risks identified, contingencies, timing considerations
• VWAP Context: Today's VWAP extracted from snapshot (for intraday bias)

VWAP in Supervisor Prompt: The Supervisor extracts VWAP from the snapshot and includes it in its synthesis:

• Price above VWAP = favor longs
• Price below VWAP = favor shorts
• Used as dynamic support/resistance for entry zone decisions

2. Resolves Conflicts

When agents disagree:

Scenario	Resolution
Technical says LONG, Macro says LONG	Strong agreement → High confidence trade
Technical says LONG, Macro says SHORT	Technical wins (has actual price data)
Technical says LONG, Macro says NEUTRAL	Trade the Technical direction
Both say NEUTRAL <40%	No Trade

3. Makes Trade/No-Trade Decision

TRADE when:

• Both agents agree (any direction)
• ONE agent is directional with >50% confidence
• BOTH agents have ANY directional opinion

NO TRADE only when:

• BOTH agents say "neutral" with <40% confidence EACH
• Market is completely closed
• Critical system error

4. SHORT Trade Safety Checks (CRITICAL)

When the Technical Agent recommends a SHORT trade, the Supervisor applies extra validation:

Check	Action
Macro is risk_on (bullish)	REDUCE overall confidence by 15%, add warning
Macro is neutral	Add note "extra caution advised"
Macro is risk_off (bearish)	Full confidence, conditions aligned
Pattern not yet broken	Flag as "anticipatory signal - wait for breakdown"
Entry type mismatch	Flag if Technical used wrong vocabulary for shorts
Confidence cap	NEVER issue SHORT with >80% confidence unless Macro confirms bearish

This does NOT apply to LONG trades — Technical Agent has full authority for longs.

5. Calculates Position Details

For the trade plan, Supervisor determines:

Element	How It's Determined
Entry Zone	From Technical Agent's support levels
Position Size	Account size × Risk % ÷ Stop distance
Stop Loss	Based on trade style + support levels
Profit Targets	Based on trade style + resistance levels
Time Stop	Based on trade style (minutes to weeks)

6. Selects Options Contracts (If OPTIONS)

For OPTIONS trades, the Supervisor uses a multi-phase filtering process to ensure quality contracts:

Primary Filtering

• Targets contracts with balanced delta (not too aggressive, not too conservative)
• Prioritizes the "sweet spot" for directional exposure vs. risk

Expanded Filtering

• If the primary filter finds no contracts, criteria are relaxed while still avoiding extremes
• Ensures you can still trade even in thin markets

Fallback Handling

• If no contracts meet delta criteria, the system may accept contracts with valid pricing
• Adds appropriate caution notes when greeks data is incomplete

No Suitable Contracts

• If ALL phases fail, returns NO TRADE rather than forcing a poor contract choice

Mike's Top 5 Criteria (Selection Priority)

Priority	Criteria	What to Look For
1	Price	Must fit within your risk budget
2	Volume	Higher is better (easier entry/exit)
3	Theta	Lower absolute value (less daily decay)
4	Delta	Balanced directional exposure
5	Open Interest	Sufficient liquidity for your size

DTE by Trade Style

Style	DTE Required	Note
SCALP	0DTE when available (otherwise nearest expiration)	Index ETFs (SPY/QQQ/IWM) can have daily expirations. Individual stocks typically only have true 0DTE on Fridays — otherwise use the nearest expiration and label it clearly (not true 0DTE).
DAY	3-7 DTE	Matches 1-5 day holding period
SWING	8-30 DTE	2-3 week positions
INVESTMENT	30-60 DTE	Longer term holds

7. Post-LLM Contract Validation

After the LLM selects a contract, the Supervisor validates the response to prevent hallucination:

Validation Check	Requirement
Symbol format	Must start with "O:"
Expiration format	Must be YYYY-MM-DD
Bid/Ask	Both must exist and be positive
Strike	Must exist and be positive
Cross-reference	Symbol must be in the original contract list

If validation fails, the trade is REJECTED with reason "Contract validation failed."

8. Anti-Chase Prompt Awareness (Added 2026-02-03)

The Supervisor Agent is now anti-chase aware at the LLM level, not just via the post-LLM guard. This reduces blocked trades by helping the LLM proactively avoid chase entries.

What's Injected:

1. System Prompt: Explicit anti-chase rules matching the deterministic guard (10% ATR threshold, 2+ opposite-color bars for pullback, BLOCK conditions for LONG/SHORT)

2. Dynamic Context: Live market data injected into each request:

   • Current Price, HOD, LOD
   • Distance to HOD/LOD
   • 30-day ATR (when available)
   • Calculated chase zones
   • Warning about pullback structure

How It Works:

• LLM sees the anti-chase rules and current market context
• LLM is instructed to prefer entries at support (longs) or resistance (shorts)
• If current price is in chase zone with no pullback → LLM should recommend waiting or NO TRADE
• This is layer 1 of a 3-layer defense (prompt → guard → review agent)

Files: supervisor_agent.py, chop_supervisor.py (prompt sections)

9. ATR-Based Target Warnings (Soft Sanity Check)

After the LLM produces profit targets, the Supervisor runs a sanity check comparing TP1 distance against the stock's volatility (ATR). This is a warning only — it does NOT override targets.

Trade Style	Threshold	Meaning
SCALP	0.5x ATR	Warn if TP1 is more than half a typical day's range away
DAY	1.0x ATR	Warn if TP1 exceeds one day's typical range
SWING	2.0x ATR	Warn if TP1 exceeds two days' range
INVESTMENT	5.0x ATR	Warn if TP1 exceeds a week's range

What happens when threshold is exceeded:

• Trade plan passes through unchanged
• target_warning field is added: "TP1 is 1.8x ATR from entry (threshold: 1.0x) — verify achievable in DAY timeframe"
• Useful for review but doesn't block the trade

Why this exists: Prevents the AI from setting targets that are technically at resistance but unrealistic for the trade style (e.g., targeting weekly highs on a DAY trade).

Trade Plan Output Structure

The Supervisor produces a complete trade plan covering:

Synthesis

• How strongly each agent supports the trade
• Whether agents agree or conflict (and how it was resolved)
• Overall risk assessment from Wild Card analysis

Entry

• Clear direction (LONG or SHORT)
• Entry trigger and strategy (e.g., buy at support, short the rejection)
• Ideal entry zone with confidence estimate
• Explicit waiting instructions (what price action to wait for)

Position

• Recommended size (full, half, or quarter position)
• Quantity in appropriate units (shares, contracts, or coins)
• Total cost and maximum risk in dollars

Exit

• Stop loss placement with rationale
• Profit targets (typically scaled exit at two levels)
• Time stop appropriate to trade style

Options Details (If Applicable)

• Recommended contract with full symbol
• Contract type, strike, and expiration
• Key greeks (delta, theta, etc.)
• Current bid/ask quotes
• Liquidity metrics (volume, open interest)
• Rationale based on selection criteria

Stop/Target Framework by Trade Style

Style	Stop Placement	Targets	Time Stop
SCALP	Tight, near-term structure	Small, quick profits (scaled exit)	15-30 min
DAY	Based on intraday support	Moderate moves (scaled exit)	Market close
SWING	Anchored to daily structure	Larger swings (scaled exit)	3-5 days
INVESTMENT	Wide, based on ATR and major levels	Trend-based	None

Important: These are frameworks, not fixed presets. The Supervisor places stops using actual support/resistance structure and adjusts based on the Technical Agent's volatility regime. If market structure requires a wider stop than typical for that style, the plan flags this and may suggest a different style or no trade.

10. OPTIONS Stop Loss: Stock Level is King (Added 2026-02-04)

For OPTIONS trades, the Supervisor enforces "Stock Level is King" — stops are anchored to meaningful stock support/resistance levels, not arbitrary premium percentages.

How It Works:

1. LLM sets stock-level stop first (stock_price_range)

   • Based on actual technical levels (support, resistance, key levels)
   • Example: "Stop below $681.00 (below Weekend Low/minor support)"

2. System computes premium stop automatically

   Premium Change = Stock Change × Delta
   Premium Stop = Entry Premium - Premium Change

3. SWING trades get theta buffer

   • 2 days of theta decay added to premium stop
   • Prevents time decay from triggering stop prematurely

4. Overlap prevention

   • Stop zone must not overlap entry zone
   • Minimum gap: 0.25 × ATR (volatility-adjusted)
   • Auto-shifts stop if overlap detected (flags stop_auto_shifted)

5. Rationale synchronization

   • Stop rationale always references the stock level
   • Example: "Stop below $681.00" (not "stop at $1.76 premium")

Output Structure:

"stop_loss": {
  "stock_price_range": [680.00, 681.00],  // Source of truth
  "price_range": [1.76, 2.22],            // Computed from stock stop
  "rationale": "Stop below $681.00...",   // References stock level
  "total_loss": "~$310"
}

UI/Voice Display:

• Primary: "SPY @ $680.00 - $681.00" (stock level)
• Secondary: "Premium: $1.76 - $2.22" (for reference)

Why This Matters:

• Prevents discrepancy between LLM rationale ("support at $681") and numeric stop (arbitrary premium %)
• Ensures stops are placed at meaningful technical levels
• Premium stop is mathematically derived, not guessed

CRITICAL: CRYPTO Time Stops

Crypto trades 24/7 — no market close. Use hour-based time stops:

• DAY: "Close within 8-12 hours"
• NOT: "Close by 4:00 PM ET"

Crypto time-stop rule:

• Crypto trades are 24/7 (no market close)
• Never use “Close by EOD” / “4:00 PM ET” language for crypto
• Use hour-based time stops instead (e.g., “Close within 8 hours”)

Probability Ranges

The Supervisor is instructed to provide RANGES, not single values:

• Entry zone: low/mid/high with confidence
• Targets: ranges with probability of reaching
• Confidence: explanation of what % means

Example: "75% confidence means Technical and Macro align with moderate conviction. There's a 25% chance the trade fails due to unexpected news or failed support."

Implementation details are intentionally omitted from public documentation.