Skip to main content Inicio Creadores johnalbertini14-glitch openclaw-skills options-spread-conviction-engine
options-spread-conviction-engine Multi-regime options spread analysis engine with quantitative rigor. Features regime detection (VIX-based), GARCH volatility forecasting, drawdown-constrained Kelly position sizing, and walk-forward backtesting. Scores vertical spreads (bull put, bear call, bull call, bear put) and multi-leg strategies (iron condors, butterflies, calendar spreads) using Ichimoku, RSI, MACD, Bollinger Bands, and IV term structure analysis.
Ir a la instalación Skills Marketplace Descubre y explora habilidades de IA creadas por la comunidad.
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Mostrar detalles del prompt Un comando directo omite el prompt de revisión. Revisa el origen antes de ejecutarlo.
npx skills add https://github.com/johnalbertini14-glitch/openclaw-skills --skill options-spread-conviction-engineEl comando permanece en una sola línea. Desplázate horizontalmente para revisarlo antes de copiarlo.
¿Prefieres una copia local? Descarga los archivos que SkillsMP tiene disponibles ahora.
Descargar Zip Descargando... Explorador de archivos
34 archivos CODE_REVIEW_REPORT.md 37.7 KB MULTI_LEG_REPORT.md 13.6 KB Ocupaciones relacionadas SOC
Basado en la clasificación ocupacional SOC
name options-spread-conviction-engine description Multi-regime options spread analysis engine with quantitative rigor. Features regime detection (VIX-based), GARCH volatility forecasting, drawdown-constrained Kelly position sizing, and walk-forward backtesting. Scores vertical spreads (bull put, bear call, bull call, bear put) and multi-leg strategies (iron condors, butterflies, calendar spreads) using Ichimoku, RSI, MACD, Bollinger Bands, and IV term structure analysis. version 2.3.0 author Leonardo Da Pinchy metadata {"openclaw":{"emoji":"📊","requires":{"bins":["python3"]},"install":[{"id":"venv-setup","kind":"exec","command":"cd {baseDir} && python3 scripts/setup-venv.sh","label":"Setup isolated Python environment with dependencies"}]}}
Options Spread Conviction Engine
Multi-regime options spread scoring using technical indicators and IV term structure analysis.
Install
brew install jq
npm install yahoo-finance2
sudo ln -s /opt/homebrew/bin/yahoo-finance /usr/local/bin/yf
Overview
This engine analyzes any ticker and scores seven options strategies across two categories:
Vertical Spreads (Directional)
Strategy Type Philosophy Ideal Setup bull_put Credit Mean Reversion Bullish trend + oversold dip bear_call Credit Mean Reversion Bearish trend + overbought rip bull_call Debit Breakout Strong bullish momentum bear_put Debit Breakout Strong bearish momentum
Multi-Leg Strategies (Non-Directional / Theta) Strategy Type Philosophy Ideal Setup iron_condor Credit Premium Selling IV Rank >70, RSI neutral, range-bound butterfly Debit Pinning Play BB squeeze, RSI center, low ADX calendar Debit Theta Harvest Inverted IV term structure (front > back)
Scoring Methodology
Vertical Spreads Weights vary by strategy type (Credit = Mean Reversion, Debit = Breakout):
Credit Spreads (bull_put, bear_call) Indicator Weight Purpose Ichimoku Cloud 25 pts Trend structure & equilibrium RSI 20 pts Entry timing (mean-reversion) MACD 15 pts Momentum confirmation Bollinger Bands 25 pts Volatility regime ADX 15 pts Trend strength validation
Debit Spreads (bull_call, bear_put) Indicator Weight Purpose Ichimoku Cloud 20 pts Trend confirmation RSI 10 pts Directional momentum MACD 30 pts Breakout acceleration Bollinger Bands 25 pts Bandwidth expansion ADX 15 pts Trend strength validation
Multi-Leg Strategies
Iron Condor (Credit / Range-Bound) Component Weight Rationale IV Rank (BBW %) 25 pts Rich premiums to sell RSI Neutrality 20 pts No directional momentum ADX Range-Bound 20 pts Weak trend = range structure Price Position 20 pts Centered in range = safe margins MACD Neutrality 15 pts No acceleration in any direction
IV Rank > 70: Premium-rich environment
RSI 40-60: Neutral momentum
ADX < 25: Weak/no trend
Price near %B center: Max profit zone maximized
SELL put at 1-sigma below price (short put)
BUY put at 2-sigma below (long put — wing)
SELL call at 1-sigma above price (short call)
BUY call at 2-sigma above (long call — wing)
All 4 strikes (put_long, put_short, call_short, call_long)
Max profit zone (width between short strikes)
Wing width
Butterfly (Debit / Volatility Compression) Component Weight Rationale BB Squeeze 30 pts Vol compression = narrow range RSI Neutrality 25 pts Price at equilibrium ADX Weakness 20 pts No directional trend at all Price Centering 15 pts At center of range for max profit MACD Flatness 10 pts No momentum
BBW percentile < 25: Squeeze active
RSI 45-55: Dead-center (tighter than condor)
ADX < 20: Very weak trend
MACD histogram near zero
Price at %B = 0.50
BUY 1 call at strike below center (lower wing)
SELL 2 calls at center strike (body)
BUY 1 call at strike above center (upper wing)
3 strikes (lower_long, middle_short, upper_long)
Max profit price (= middle strike)
Profit zone (approximate breakevens)
Calendar Spread (Debit / Theta Harvesting) Component Weight Rationale IV Term Structure 30 pts Front IV > Back IV = theta edge Price Stability 20 pts Price stays near strike RSI Neutrality 20 pts Not trending away from strike ADX Moderate 15 pts Some structure, not trending hard MACD Neutrality 15 pts No directional acceleration
Front-month IV > Back-month IV by > 5%: Inverted term structure
Low recent volatility: Price stability
RSI neutral: No directional momentum
ADX 18-25: Moderate trend structure (not chaos)
Primary: Live options chain IV from Yahoo Finance
Fallback: Historical volatility proxy (HV 10-day vs 30-day)
ATM strike (rounded to standard interval)
Front expiry: nearest available
Back expiry: 25+ days after front
Single strike (both legs)
Front and back expiry dates
IV differential (%)
Theta advantage description
Conviction Tiers Score Tier Action 80-100 EXECUTE High conviction — Enter the spread 60-79 PREPARE Favorable — Size the trade 40-59 WATCH Interesting — Add to watchlist 0-39 WAIT Poor conditions — Avoid / No setup
Usage
Vertical Spreads
conviction-engine AAPL
conviction-engine SPY --strategy bear_call
conviction-engine QQQ --strategy bull_call --period 2y
Multi-Leg Strategies
conviction-engine SPY --strategy iron_condor
conviction-engine AAPL --strategy butterfly
conviction-engine TSLA --strategy calendar
Multiple Tickers conviction-engine AAPL MSFT GOOGL --strategy bull_put
conviction-engine SPY QQQ IWM --strategy iron_condor
JSON Output (for automation) conviction-engine TSLA --strategy butterfly --json
conviction-engine SPY --strategy calendar --json | jq '.[0].iv_term_structure'
Full Options conviction-engine <ticker> [ticker...]
--strategy {bull_put,bear_call,bull_call,bear_put,iron_condor,butterfly,calendar}
--period {1y,2y,3y,5y}
--interval {1h,1d,1wk}
--json
Example Outputs
Iron Condor ================================================================================
SPY — Iron Condor (Credit)
================================================================================
Price: $681.27 | Score: 31.8/100 → WAIT
[IV Rank +2.5/25]
IV Rank (BBW proxy): 5% (VERY_LOW)
BBW: 3.17 (1Y range: 2.37 - 18.13)
Premiums are THIN — poor risk/reward for credit
Strikes:
BUY 680.0P | SELL 685.0P
SELL 695.0C | BUY 700.0C
Max Profit Zone: $685.0 - $695.0
Wing Width: $5.00
Butterfly ================================================================================
SPY — Long Butterfly (Debit)
================================================================================
Price: $681.27 | Score: 64.5/100 → PREPARE
[BB Squeeze +27.0/30]
Bandwidth: 3.1701 (percentile: 21%)
SQUEEZE ACTIVE — 19 consecutive bars
Strikes:
BUY 1x 685.0C | SELL 2x 690.0C | BUY 1x 695.0C
Max Profit Price: $690.0
Profit Zone: ~$685.0 - $695.0
Calendar Spread ================================================================================
SPY — Calendar Spread (Debit)
================================================================================
Price: $681.27 | Score: 67.2/100 → PREPARE
[IV Term Structure +30.0/30]
Front IV: 27.5% | Back IV: 19.4%
Differential: +41.7%
INVERTED TERM STRUCTURE — calendar opportunity confirmed
Strikes:
Strike: $680.0
SELL 2026-02-13 | BUY 2026-03-13
Theta Advantage: Front IV > Back IV by 41.7%
IV Rank Approximation IV Rank is approximated using Bollinger Bandwidth (BBW) percentile over 252 trading days:
IV Rank ≈ (Current BBW - 52wk Low BBW) / (52wk High BBW - 52wk Low BBW) × 100
This correlation is well-documented: realized volatility (BBW) and implied volatility rank move with ~0.7-0.8 correlation (Sinclair, "Volatility Trading", 2013).
IV Term Structure For calendar spreads, the engine attempts to fetch live ATM implied volatility from Yahoo Finance options chains. If unavailable, it falls back to historical volatility term structure (HV 10-day vs HV 30-day) as a proxy.
Quantitative Modules (v2.3.0) The engine now includes four quantitative modules for rigorous strategy validation and optimization:
1. Regime Detector (regime_detector.py) Market regime classification using VIX percentiles:
CRISIS : VIX > 80th percentile — favors premium selling (iron condors)HIGH_VOL : VIX 60-80th — elevated IV benefits credit spreadsNORMAL : VIX 40-60th — balanced environment, all strategies viableLOW_VOL : VIX 20-40th — cheap options favor debit spreadsEUPHORIA : VIX < 20th — momentum continues, mean reversion brewing
python3 scripts/regime_detector.py
python3 scripts/regime_detector.py --strategy iron_condor --json
from regime_detector import RegimeDetector
detector = RegimeDetector()
regime, confidence = detector.detect_regime()
weights = detector.get_regime_weights(regime)
adjusted_score, reasoning = detector.regime_aware_score(75 , regime, 'bull_put' )
2. Volatility Forecaster (vol_forecaster.py) GARCH-based realized volatility forecasting with VRP analysis:
Fits GARCH(1,1) to historical returns
Forecasts realized volatility over configurable horizon
Calculates volatility risk premium (IV - RV forecast)
Provides conviction adjustments based on VRP
python3 scripts/vol_forecaster.py AAPL
python3 scripts/vol_forecaster.py SPY --iv 0.25 --horizon 5
VRP > 5%: Favorable for selling premium (credit spreads)
VRP < -5%: Favorable for buying premium (debit spreads)
VRP near 0: No volatility edge, focus on directional setup
from vol_forecaster import VolatilityForecaster
forecaster = VolatilityForecaster("AAPL" )
params = forecaster.fit_garch()
forecast = forecaster.forecast_vol(horizon=5 )
vrp, strength, rec = forecaster.vol_risk_premium(iv=0.25 , rv_forecast=forecast.annualized_vol)
adjusted_score, reasoning = forecaster.add_to_conviction(70 , vrp_signal, 'bull_put' )
3. Enhanced Kelly Sizer (enhanced_kelly.py) Drawdown-constrained, correlation-aware position sizing:
Full Kelly criterion calculation
Drawdown constraint: f_dd = f_kelly × (1 - target_dd / max_dd)
Conviction-based Kelly scaling:
90-100: Half Kelly
80-89: Quarter Kelly
60-79: Eighth Kelly
<60: No position
Correlation penalty for portfolio context
python3 scripts/enhanced_kelly.py --loss 80 --win 40 --pop 0.65 --conviction 85
python3 scripts/enhanced_kelly.py --loss 80 --win 40 --pop 0.65 --conviction 85 --correlation 0.3
from enhanced_kelly import EnhancedKellySizer
sizer = EnhancedKellySizer(account_value=390 , max_drawdown=0.20 )
result = sizer.calculate_position(
spread_cost=80 ,
max_loss=80 ,
win_amount=40 ,
conviction=85 ,
pop=0.65 ,
existing_correlation=0.0
)
4. Backtest Validator (backtest_validator.py) Walk-forward validation of conviction scores:
Simulates historical trades across ticker universe
Validates tier separation (EXECUTE vs WAIT performance)
Statistical tests (t-tests, ANOVA)
Tier separation scoring (0-1)
Weight calibration suggestions
python3 scripts/backtest_validator.py --tickers AAPL MSFT SPY --start 2022-01-01 --end 2024-01-01 --strategy bull_put
python3 scripts/backtest_validator.py --tickers SPY --json
Win rate per tier
Expectancy per tier: (win_rate × avg_win) - (loss_rate × avg_loss)
Sharpe ratio per tier
P-values for tier differences
Separation score (0-1, higher = better discrimination)
from backtest_validator import BacktestValidator
validator = BacktestValidator(engine, "2022-01-01" , "2024-01-01" )
results_df = validator.run_walk_forward(["AAPL" , "MSFT" ], hold_days=5 )
report = validator.validate_tiers(results_df)
print (f"Separation score: {report.tier_separation_score:.2 f} " )
print (f"EXECUTE vs WAIT p-value: {report.p_values['execute_vs_wait' ]:.4 f} " )
5. Quantitative Integration (quantitative_integration.py) Unified interface combining all quantitative modules:
python3 scripts/quantitative_integration.py AAPL --regime-aware --vol-aware
python3 scripts/quantitative_integration.py SPY --regime-aware --pop 0.65 --max-loss 80 --win-amount 40
python3 scripts/quantitative_integration.py --backtest SPY QQQ --start 2022-01-01 --end 2024-01-01
from quantitative_integration import QuantConvictionEngine
engine = QuantConvictionEngine(account_value=390 , max_drawdown=0.20 )
result = engine.analyze("AAPL" , "bull_put" , regime_aware=True , vol_aware=True )
print (f"Final score: {result.final_score} " )
print (f"Regime: {result.regime} " )
print (f"VRP: {result.vrp_signal.vrp if result.vrp_signal else 'N/A' } " )
sizing = engine.calculate_position(result, pop=0.65 , max_loss=80 , win_amount=40 )
print (f"Contracts: {sizing['contracts' ]} " )
report = engine.run_backtest(["SPY" , "QQQ" ], "2022-01-01" , "2024-01-01" )
print (f"Recommendation: {report.recommendation} " )
Academic Foundation
Ichimoku Cloud — Trend structure (Hosoda, 1968)RSI — Momentum oscillator (Wilder, 1978)MACD — Trend momentum (Appel, 1979)Bollinger Bands — Volatility envelopes (Bollinger, 2001)IV Rank / Term Structure — Options market microstructure (Sinclair, 2013) Combining orthogonal signals reduces false-positive rate compared to single-indicator strategies (Pring, 2002; Murphy, 1999).
Architecture conviction-engine/
├── scripts/
│ ├── conviction-engine # CLI wrapper (bash)
│ ├── spread_conviction_engine.py # Core engine (vertical spreads)
│ ├── multi_leg_strategies.py # Multi-leg extensions
│ ├── quantitative_integration.py # Unified quantitative interface
│ ├── regime_detector.py # VIX-based regime classification
│ ├── vol_forecaster.py # GARCH volatility forecasting
│ ├── enhanced_kelly.py # Drawdown-constrained Kelly sizing
│ ├── backtest_validator.py # Walk-forward validation
│ ├── quant_scanner.py # Quantitative options scanner
│ ├── market_scanner.py # Technical market scanner
│ ├── calculator.py # Black-Scholes & POP calculator
│ ├── position_sizer.py # Kelly position sizing
│ ├── chain_analyzer.py # IV surface analyzer
│ ├── options_math.py # Core mathematical models
│ └── setup-venv.sh # Environment setup
├── tests/ # Unit tests
│ ├── test_regime_detector.py
│ ├── test_vol_forecaster.py
│ ├── test_enhanced_kelly.py
│ ├── test_backtest_validator.py
│ └── run_tests.py
└── SKILL.md # This documentation
Module Separation
spread_conviction_engine.py : Vertical spreads, shared infrastructure (data fetching, indicator computation)multi_leg_strategies.py : Iron condors, butterflies, calendars (imports from main engine)quantitative_integration.py : Unified interface for regime/vol/Kelly/backtest modulesregime_detector.py : Market regime classification using VIX percentilesvol_forecaster.py : GARCH-based realized volatility forecastingenhanced_kelly.py : Drawdown-constrained, correlation-aware position sizingbacktest_validator.py : Walk-forward validation of conviction scores This separation keeps concerns clean while avoiding duplication.
Limitations & Assumptions
IV Data
Yahoo Finance Limitations : Options chains may be unavailable after market hours or for low-volume tickersFallback : Historical volatility (HV) proxy is less accurate than live IV but provides signalIV Rank : Approximated from BBW; actual IV Rank requires options chain data
Strike Selection
Approximation : Strikes derived from Bollinger Band levels (1-sigma / 2-sigma)Rounding : Rounded to standard option strike intervals based on stock priceNo Live Pricing : Does not fetch live option premiums; strike selection is structural, not value-optimized
Data Quality
Minimum 180 trading days required for full Ichimoku cloud population
Multi-leg strategies require options chains (calendar spreads especially)
After-hours analysis may have reduced data quality
Market Assumptions
Assumes normal options market conditions (not extreme volatility events)
Strike intervals assume US equity options conventions
Not tested on futures, commodities, or non-US markets
Requirements
Python 3.10+ (Python 3.14+ supported via pure-python mode)
Isolated virtual environment (auto-created on first run)
Internet connection (fetches data from Yahoo Finance)
Installation clawhub install options-spread-conviction-engine
The skill automatically creates a virtual environment and installs:
pandas >= 2.0
pandas_ta >= 0.4.0 (pure Python mode on 3.14+)
yfinance >= 1.0
scipy, tqdm
Note: On Python 3.14+, the engine runs in pure Python mode without numba. Performance is slightly reduced but all functionality works correctly.
Market Scanners The engine includes two distinct scanning tools for different trading philosophies:
1. Technical Scanner (market_scanner.py) Automates the search for high-conviction plays across entire stock universes using technical indicators (Ichimoku, RSI, MACD, BB).
Features
Scans S&P 500, Nasdaq 100, or custom ticker lists.
Filters for EXECUTE tier (conviction ≥80).
Runs position sizing to ensure trades fit account guardrails.
Usage
python3 scripts/market_scanner.py --universe sp500
2. Quantitative Scanner (quant_scanner.py) A mathematically-rigorous scanner that ignores technical indicators in favor of market microstructure and probability.
Features
IV Surface Analysis : Analyzes skew and term structure.Monte Carlo POP : 10,000-run simulations for true Probability of Profit.EV Optimization : Finds trades with the highest risk-adjusted mathematical expectancy.Account-Aware : Enforces small-account constraints ($100 max risk).
Usage
python3 scripts/quant_scanner.py SPY --mode pop
python3 scripts/quant_scanner.py AAPL TSLA --mode ev --min-dte 30
Calculator & Position Sizer The integrated toolchain includes:
calculator.py Black-Scholes options pricing with support for:
Single options: calls, puts
Vertical spreads: bull call, bear put
Multi-leg: iron condors, butterflies
Greeks calculation (delta, gamma, theta, vega, rho)
Monte Carlo POP simulation
position_sizer.py Kelly criterion position sizing adapted for small accounts:
Full Kelly and fractional Kelly (default 0.25)
Account guardrails ($390 default, $100 max risk)
Trade screening and ranking
Strike adjustment suggestions
from position_sizer import calculate_position
result = calculate_position(
account_value=390 ,
max_loss_per_spread=80 ,
win_amount=40 ,
pop=0.65 ,
)
Files
scripts/conviction-engine — Main CLI wrapper for conviction enginescripts/spread_conviction_engine.py — Core engine (vertical spreads)scripts/multi_leg_strategies.py — Multi-leg extensions (v2.0.0)scripts/market_scanner.py — Automated market scanner for EXECUTE playsscripts/calculator.py — Black-Scholes pricing, Greeks, Monte Carlo POPscripts/position_sizer.py — Kelly criterion position sizingscripts/setup-venv.sh — Environment setupdata/sp500_tickers.txt — S&P 500 constituentsdata/ndx100_tickers.txt — Nasdaq 100 constituentsassets/ — Documentation and examples
Version History
v2.3.0 (2026-02-13): Quantitative rigor upgrade
Regime Detector: VIX-based market regime classification
Volatility Forecaster: GARCH-based RV forecasting with VRP analysis
Enhanced Kelly Sizer: Drawdown-constrained, correlation-aware position sizing
Backtest Validator: Walk-forward validation with tier separation testing
Quantitative Integration: Unified interface for all quantitative modules
Comprehensive unit test suite for all new modules
v2.2.0 (2026-02-13): Kelly Criterion position sizing with full/half Kelly, edge calculation, and account-aware contract sizingv2.1.0 (2026-02-12): Added market scanner, integrated calculator and position sizerv2.0.0 (2026-02-12): Added multi-leg strategies (iron condor, butterfly, calendar)v1.2.1 (2026-02-09): Volume multiplier, dynamic strike suggestionsv1.1.0 (2026-02-08): Cross-signal weighting, multi-strategy supportv1.0.0 (2026-02-07): Initial bull put spread engine
License MIT — Part of the Financial Toolkit for OpenClaw
