{"id":"94156fb7-c620-484f-8387-183743004f65","entityType":"agent","slug":"clawhub-skills-adamnaghs-options-spread-conviction-engine","name":"options-spread-conviction-engine","canonicalUrl":"https://www.xpersona.co/agent/clawhub-skills-adamnaghs-options-spread-conviction-engine","canonicalPath":"/agent/clawhub-skills-adamnaghs-options-spread-conviction-engine","generatedAt":"2026-10-09T13:28:35.388Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"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. --- 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","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. Last updated 4/15/2026.","installCommand":"clawhub skill install skills:adamnaghs:options-spread-conviction-engine","sourceUrl":"https://github.com/openclaw/skills/tree/main/skills/adamnaghs/options-spread-conviction-engine","homepage":null,"primaryLinks":[{"label":"View on ClawHub","url":"https://github.com/openclaw/skills/tree/main/skills/adamnaghs/options-spread-conviction-engine","kind":"source"}],"safetyScore":84,"overallRank":62,"popularityScore":50,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Multi-regime options spread analysis engine with quantitative rigor. Features regime detection (VIX-based), GARCH volatility forecasting, drawdown-constrained K"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[{"label":"s","status":"self-declared"},{"label":"for","status":"self-declared"}],"verifiedCount":0,"selfDeclaredCount":3,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"},{"key":"s","type":"capability","support":"supported","confidenceSource":"profile","notes":"Declared in agent profile metadata"},{"key":"for","type":"capability","support":"supported","confidenceSource":"profile","notes":"Declared in agent profile metadata"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile capability:s|supported|profile capability:for|supported|profile"}},"adoption":{"evidence":{"source":"no-adoption-signals","verified":false,"confidence":"low","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":"No source adoption metrics were available."},"stars":null,"forks":null,"downloads":null,"packageName":null,"latestVersion":null,"tractionLabel":null},"release":{"evidence":{"source":"agent-index","verified":false,"confidence":"medium","updatedAt":"2026-02-25T05:55:48.181Z","emptyReason":null},"lastUpdatedAt":"2026-04-15T00:45:39.800Z","lastCrawledAt":"2026-02-25T05:55:48.181Z","lastIndexedAt":null,"nextCrawlAt":"2026-02-26T05:55:48.181Z","lastVerifiedAt":null,"highlights":[]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install skills:adamnaghs:options-spread-conviction-engine","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-skills-adamnaghs-options-spread-conviction-engine/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-skills-adamnaghs-options-spread-conviction-engine/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-skills-adamnaghs-options-spread-conviction-engine/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-skills-adamnaghs-options-spread-conviction-engine/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-skills-adamnaghs-options-spread-conviction-engine/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-skills-adamnaghs-options-spread-conviction-engine/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T13:28:35.387Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-skills-adamnaghs-options-spread-conviction-engine/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-skills-adamnaghs-options-spread-conviction-engine/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-skills-adamnaghs-options-spread-conviction-engine/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-skills-adamnaghs-options-spread-conviction-engine/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"readme":"---\nname: options-spread-conviction-engine\ndescription: 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.\nversion: 2.3.0\nauthor: Leonardo Da Pinchy\nmetadata:\n  openclaw:\n    emoji: 📊\n    requires:\n      bins: [\"python3\"]\n    install:\n      - id: venv-setup\n        kind: exec\n        command: \"cd {baseDir} && python3 scripts/setup-venv.sh\"\n        label: \"Setup isolated Python environment with dependencies\"\n---\n\n# Options Spread Conviction Engine\n\n**Multi-regime options spread scoring using technical indicators and IV term structure analysis.**\n\n## Install\n\n```bash\nbrew install jq\nnpm install yahoo-finance2\nsudo ln -s /opt/homebrew/bin/yahoo-finance /usr/local/bin/yf\n```\n\n## Overview\n\nThis engine analyzes any ticker and scores **seven** options strategies across two categories:\n\n### Vertical Spreads (Directional)\n| Strategy | Type | Philosophy | Ideal Setup |\n|----------|------|------------|-------------|\n| **bull_put** | Credit | Mean Reversion | Bullish trend + oversold dip |\n| **bear_call** | Credit | Mean Reversion | Bearish trend + overbought rip |\n| **bull_call** | Debit | Breakout | Strong bullish momentum |\n| **bear_put** | Debit | Breakout | Strong bearish momentum |\n\n### Multi-Leg Strategies (Non-Directional / Theta)\n| Strategy | Type | Philosophy | Ideal Setup |\n|----------|------|------------|-------------|\n| **iron_condor** | Credit | Premium Selling | IV Rank >70, RSI neutral, range-bound |\n| **butterfly** | Debit | Pinning Play | BB squeeze, RSI center, low ADX |\n| **calendar** | Debit | Theta Harvest | Inverted IV term structure (front > back) |\n\n## Scoring Methodology\n\n### Vertical Spreads\n\nWeights vary by strategy type (Credit = Mean Reversion, Debit = Breakout):\n\n#### Credit Spreads (bull_put, bear_call)\n| Indicator | Weight | Purpose |\n|-----------|--------|---------|\n| Ichimoku Cloud | 25 pts | Trend structure & equilibrium |\n| RSI | 20 pts | Entry timing (mean-reversion) |\n| MACD | 15 pts | Momentum confirmation |\n| Bollinger Bands | 25 pts | Volatility regime |\n| ADX | 15 pts | Trend strength validation |\n\n#### Debit Spreads (bull_call, bear_put)\n| Indicator | Weight | Purpose |\n|-----------|--------|---------|\n| Ichimoku Cloud | 20 pts | Trend confirmation |\n| RSI | 10 pts | Directional momentum |\n| MACD | 30 pts | Breakout acceleration |\n| Bollinger Bands | 25 pts | Bandwidth expansion |\n| ADX | 15 pts | Trend strength validation |\n\n### Multi-Leg Strategies\n\n#### Iron Condor (Credit / Range-Bound)\n| Component | Weight | Rationale |\n|-----------|--------|-----------|\n| IV Rank (BBW %) | 25 pts | Rich premiums to sell |\n| RSI Neutrality | 20 pts | No directional momentum |\n| ADX Range-Bound | 20 pts | Weak trend = range structure |\n| Price Position | 20 pts | Centered in range = safe margins |\n| MACD Neutrality | 15 pts | No acceleration in any direction |\n\n**Triggers:**\n- IV Rank > 70: Premium-rich environment\n- RSI 40-60: Neutral momentum\n- ADX < 25: Weak/no trend\n- Price near %B center: Max profit zone maximized\n\n**Strike Selection:**\n- SELL put at 1-sigma below price (short put)\n- BUY put at 2-sigma below (long put — wing)\n- SELL call at 1-sigma above price (short call)\n- BUY call at 2-sigma above (long call — wing)\n\n**Output:**\n- All 4 strikes (put_long, put_short, call_short, call_long)\n- Max profit zone (width between short strikes)\n- Wing width\n\n#### Butterfly (Debit / Volatility Compression)\n| Component | Weight | Rationale |\n|-----------|--------|-----------|\n| BB Squeeze | 30 pts | Vol compression = narrow range |\n| RSI Neutrality | 25 pts | Price at equilibrium |\n| ADX Weakness | 20 pts | No directional trend at all |\n| Price Centering | 15 pts | At center of range for max profit |\n| MACD Flatness | 10 pts | No momentum |\n\n**Triggers:**\n- BBW percentile < 25: Squeeze active\n- RSI 45-55: Dead-center (tighter than condor)\n- ADX < 20: Very weak trend\n- MACD histogram near zero\n- Price at %B = 0.50\n\n**Strike Selection:**\n- BUY 1 call at strike below center (lower wing)\n- SELL 2 calls at center strike (body)\n- BUY 1 call at strike above center (upper wing)\n\n**Output:**\n- 3 strikes (lower_long, middle_short, upper_long)\n- Max profit price (= middle strike)\n- Profit zone (approximate breakevens)\n\n#### Calendar Spread (Debit / Theta Harvesting)\n| Component | Weight | Rationale |\n|-----------|--------|-----------|\n| IV Term Structure | 30 pts | Front IV > Back IV = theta edge |\n| Price Stability | 20 pts | Price stays near strike |\n| RSI Neutrality | 20 pts | Not trending away from strike |\n| ADX Moderate | 15 pts | Some structure, not trending hard |\n| MACD Neutrality | 15 pts | No directional acceleration |\n\n**Triggers:**\n- Front-month IV > Back-month IV by > 5%: Inverted term structure\n- Low recent volatility: Price stability\n- RSI neutral: No directional momentum\n- ADX 18-25: Moderate trend structure (not chaos)\n\n**Data Sources:**\n- Primary: Live options chain IV from Yahoo Finance\n- Fallback: Historical volatility proxy (HV 10-day vs 30-day)\n\n**Strike Selection:**\n- ATM strike (rounded to standard interval)\n- Front expiry: nearest available\n- Back expiry: 25+ days after front\n\n**Output:**\n- Single strike (both legs)\n- Front and back expiry dates\n- IV differential (%)\n- Theta advantage description\n\n## Conviction Tiers\n\n| Score | Tier | Action |\n|-------|------|--------|\n| 80-100 | EXECUTE | High conviction — Enter the spread |\n| 60-79 | PREPARE | Favorable — Size the trade |\n| 40-59 | WATCH | Interesting — Add to watchlist |\n| 0-39 | WAIT | Poor conditions — Avoid / No setup |\n\n## Usage\n\n### Vertical Spreads\n\n```bash\n# Basic analysis (auto-detects best strategy)\nconviction-engine AAPL\n\n# Specific strategy\nconviction-engine SPY --strategy bear_call\nconviction-engine QQQ --strategy bull_call --period 2y\n```\n\n### Multi-Leg Strategies\n\n```bash\n# Iron Condor — high IV, range-bound\nconviction-engine SPY --strategy iron_condor\n\n# Butterfly — volatility compression, pinning play\nconviction-engine AAPL --strategy butterfly\n\n# Calendar — inverted IV term structure, theta harvest\nconviction-engine TSLA --strategy calendar\n```\n\n### Multiple Tickers\n\n```bash\nconviction-engine AAPL MSFT GOOGL --strategy bull_put\nconviction-engine SPY QQQ IWM --strategy iron_condor\n```\n\n### JSON Output (for automation)\n\n```bash\nconviction-engine TSLA --strategy butterfly --json\nconviction-engine SPY --strategy calendar --json | jq '.[0].iv_term_structure'\n```\n\n### Full Options\n\n```bash\nconviction-engine <ticker> [ticker...]\n  --strategy {bull_put,bear_call,bull_call,bear_put,iron_condor,butterfly,calendar}\n  --period {1y,2y,3y,5y}\n  --interval {1h,1d,1wk}\n  --json\n```\n\n## Example Outputs\n\n### Iron Condor\n\n```\n================================================================================\nSPY — Iron Condor (Credit)\n================================================================================\nPrice: $681.27 | Score: 31.8/100 → WAIT\n\n[IV Rank +2.5/25]\n  IV Rank (BBW proxy): 5% (VERY_LOW)\n  BBW: 3.17 (1Y range: 2.37 - 18.13)\n  Premiums are THIN — poor risk/reward for credit\n\nStrikes:\n  BUY  680.0P | SELL 685.0P\n  SELL 695.0C | BUY  700.0C\n  Max Profit Zone: $685.0 - $695.0\n  Wing Width: $5.00\n```\n\n### Butterfly\n\n```\n================================================================================\nSPY — Long Butterfly (Debit)\n================================================================================\nPrice: $681.27 | Score: 64.5/100 → PREPARE\n\n[BB Squeeze +27.0/30]\n  Bandwidth: 3.1701 (percentile: 21%)\n  SQUEEZE ACTIVE — 19 consecutive bars\n\nStrikes:\n  BUY 1x 685.0C | SELL 2x 690.0C | BUY 1x 695.0C\n  Max Profit Price: $690.0\n  Profit Zone: ~$685.0 - $695.0\n```\n\n### Calendar Spread\n\n```\n================================================================================\nSPY — Calendar Spread (Debit)\n================================================================================\nPrice: $681.27 | Score: 67.2/100 → PREPARE\n\n[IV Term Structure +30.0/30]\n  Front IV: 27.5% | Back IV: 19.4%\n  Differential: +41.7%\n  INVERTED TERM STRUCTURE — calendar opportunity confirmed\n\nStrikes:\n  Strike: $680.0\n  SELL 2026-02-13 | BUY 2026-03-13\n  Theta Advantage: Front IV > Back IV by 41.7%\n```\n\n## IV Rank Approximation\n\nIV Rank is approximated using **Bollinger Bandwidth (BBW) percentile** over 252 trading days:\n\n```\nIV Rank ≈ (Current BBW - 52wk Low BBW) / (52wk High BBW - 52wk Low BBW) × 100\n```\n\nThis correlation is well-documented: realized volatility (BBW) and implied volatility rank move with ~0.7-0.8 correlation (Sinclair, \"Volatility Trading\", 2013).\n\n## IV Term Structure\n\nFor 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.\n\n## Quantitative Modules (v2.3.0)\n\nThe engine now includes four quantitative modules for rigorous strategy validation and optimization:\n\n### 1. Regime Detector (`regime_detector.py`)\n\nMarket regime classification using VIX percentiles:\n- **CRISIS**: VIX > 80th percentile — favors premium selling (iron condors)\n- **HIGH_VOL**: VIX 60-80th — elevated IV benefits credit spreads\n- **NORMAL**: VIX 40-60th — balanced environment, all strategies viable\n- **LOW_VOL**: VIX 20-40th — cheap options favor debit spreads\n- **EUPHORIA**: VIX < 20th — momentum continues, mean reversion brewing\n\n```bash\n# Detect current regime\npython3 scripts/regime_detector.py\n\n# Get regime-adjusted weights for specific strategy\npython3 scripts/regime_detector.py --strategy iron_condor --json\n```\n\n**Integration:**\n```python\nfrom regime_detector import RegimeDetector\n\ndetector = RegimeDetector()\nregime, confidence = detector.detect_regime()\nweights = detector.get_regime_weights(regime)\nadjusted_score, reasoning = detector.regime_aware_score(75, regime, 'bull_put')\n```\n\n### 2. Volatility Forecaster (`vol_forecaster.py`)\n\nGARCH-based realized volatility forecasting with VRP analysis:\n- Fits GARCH(1,1) to historical returns\n- Forecasts realized volatility over configurable horizon\n- Calculates volatility risk premium (IV - RV forecast)\n- Provides conviction adjustments based on VRP\n\n```bash\n# Analyze AAPL volatility\npython3 scripts/vol_forecaster.py AAPL\n\n# Compare IV = 25% vs forecast RV\npython3 scripts/vol_forecaster.py SPY --iv 0.25 --horizon 5\n```\n\n**Interpretation:**\n- VRP > 5%: Favorable for selling premium (credit spreads)\n- VRP < -5%: Favorable for buying premium (debit spreads)\n- VRP near 0: No volatility edge, focus on directional setup\n\n**Integration:**\n```python\nfrom vol_forecaster import VolatilityForecaster\n\nforecaster = VolatilityForecaster(\"AAPL\")\nparams = forecaster.fit_garch()  # Returns omega, alpha, beta\nforecast = forecaster.forecast_vol(horizon=5)\nvrp, strength, rec = forecaster.vol_risk_premium(iv=0.25, rv_forecast=forecast.annualized_vol)\nadjusted_score, reasoning = forecaster.add_to_conviction(70, vrp_signal, 'bull_put')\n```\n\n### 3. Enhanced Kelly Sizer (`enhanced_kelly.py`)\n\nDrawdown-constrained, correlation-aware position sizing:\n- Full Kelly criterion calculation\n- Drawdown constraint: f_dd = f_kelly × (1 - target_dd / max_dd)\n- Conviction-based Kelly scaling:\n  - 90-100: Half Kelly\n  - 80-89: Quarter Kelly\n  - 60-79: Eighth Kelly\n  - <60: No position\n- Correlation penalty for portfolio context\n\n```bash\n# Calculate position with $390 account\npython3 scripts/enhanced_kelly.py --loss 80 --win 40 --pop 0.65 --conviction 85\n\n# Include correlation with existing position\npython3 scripts/enhanced_kelly.py --loss 80 --win 40 --pop 0.65 --conviction 85 --correlation 0.3\n```\n\n**Integration:**\n```python\nfrom enhanced_kelly import EnhancedKellySizer\n\nsizer = EnhancedKellySizer(account_value=390, max_drawdown=0.20)\nresult = sizer.calculate_position(\n    spread_cost=80,\n    max_loss=80,\n    win_amount=40,\n    conviction=85,\n    pop=0.65,\n    existing_correlation=0.0\n)\n# Returns: contracts, total_risk, kelly_fraction, recommendation\n```\n\n### 4. Backtest Validator (`backtest_validator.py`)\n\nWalk-forward validation of conviction scores:\n- Simulates historical trades across ticker universe\n- Validates tier separation (EXECUTE vs WAIT performance)\n- Statistical tests (t-tests, ANOVA)\n- Tier separation scoring (0-1)\n- Weight calibration suggestions\n\n```bash\n# Backtest bull_put on AAPL, MSFT, SPY (2022-2024)\npython3 scripts/backtest_validator.py --tickers AAPL MSFT SPY --start 2022-01-01 --end 2024-01-01 --strategy bull_put\n\n# JSON output for analysis\npython3 scripts/backtest_validator.py --tickers SPY --json\n```\n\n**Output Metrics:**\n- Win rate per tier\n- Expectancy per tier: (win_rate × avg_win) - (loss_rate × avg_loss)\n- Sharpe ratio per tier\n- P-values for tier differences\n- Separation score (0-1, higher = better discrimination)\n\n**Integration:**\n```python\nfrom backtest_validator import BacktestValidator\n\nvalidator = BacktestValidator(engine, \"2022-01-01\", \"2024-01-01\")\nresults_df = validator.run_walk_forward([\"AAPL\", \"MSFT\"], hold_days=5)\nreport = validator.validate_tiers(results_df)\nprint(f\"Separation score: {report.tier_separation_score:.2f}\")\nprint(f\"EXECUTE vs WAIT p-value: {report.p_values['execute_vs_wait']:.4f}\")\n```\n\n### 5. Quantitative Integration (`quantitative_integration.py`)\n\nUnified interface combining all quantitative modules:\n\n```bash\n# Full quantitative analysis with regime and VRP\npython3 scripts/quantitative_integration.py AAPL --regime-aware --vol-aware\n\n# With Kelly sizing\npython3 scripts/quantitative_integration.py SPY --regime-aware --pop 0.65 --max-loss 80 --win-amount 40\n\n# Run backtest validation\npython3 scripts/quantitative_integration.py --backtest SPY QQQ --start 2022-01-01 --end 2024-01-01\n```\n\n**Integration:**\n```python\nfrom quantitative_integration import QuantConvictionEngine\n\nengine = QuantConvictionEngine(account_value=390, max_drawdown=0.20)\n\n# Analyze with regime and VRP adjustments\nresult = engine.analyze(\"AAPL\", \"bull_put\", regime_aware=True, vol_aware=True)\nprint(f\"Final score: {result.final_score}\")\nprint(f\"Regime: {result.regime}\")\nprint(f\"VRP: {result.vrp_signal.vrp if result.vrp_signal else 'N/A'}\")\n\n# Calculate position size\nsizing = engine.calculate_position(result, pop=0.65, max_loss=80, win_amount=40)\nprint(f\"Contracts: {sizing['contracts']}\")\n\n# Run backtest validation\nreport = engine.run_backtest([\"SPY\", \"QQQ\"], \"2022-01-01\", \"2024-01-01\")\nprint(f\"Recommendation: {report.recommendation}\")\n```\n\n## Academic Foundation\n\n- **Ichimoku Cloud** — Trend structure (Hosoda, 1968)\n- **RSI** — Momentum oscillator (Wilder, 1978)\n- **MACD** — Trend momentum (Appel, 1979)\n- **Bollinger Bands** — Volatility envelopes (Bollinger, 2001)\n- **IV Rank / Term Structure** — Options market microstructure (Sinclair, 2013)\n\nCombining orthogonal signals reduces false-positive rate compared to single-indicator strategies (Pring, 2002; Murphy, 1999).\n\n## Architecture\n\n```\nconviction-engine/\n├── scripts/\n│   ├── conviction-engine              # CLI wrapper (bash)\n│   ├── spread_conviction_engine.py    # Core engine (vertical spreads)\n│   ├── multi_leg_strategies.py        # Multi-leg extensions\n│   ├── quantitative_integration.py    # Unified quantitative interface\n│   ├── regime_detector.py             # VIX-based regime classification\n│   ├── vol_forecaster.py              # GARCH volatility forecasting\n│   ├── enhanced_kelly.py              # Drawdown-constrained Kelly sizing\n│   ├── backtest_validator.py          # Walk-forward validation\n│   ├── quant_scanner.py               # Quantitative options scanner\n│   ├── market_scanner.py              # Technical market scanner\n│   ├── calculator.py                  # Black-Scholes & POP calculator\n│   ├── position_sizer.py              # Kelly position sizing\n│   ├── chain_analyzer.py              # IV surface analyzer\n│   ├── options_math.py                # Core mathematical models\n│   └── setup-venv.sh                  # Environment setup\n├── tests/                             # Unit tests\n│   ├── test_regime_detector.py\n│   ├── test_vol_forecaster.py\n│   ├── test_enhanced_kelly.py\n│   ├── test_backtest_validator.py\n│   └── run_tests.py\n└── SKILL.md                           # This documentation\n```\n\n### Module Separation\n\n- **spread_conviction_engine.py**: Vertical spreads, shared infrastructure (data fetching, indicator computation)\n- **multi_leg_strategies.py**: Iron condors, butterflies, calendars (imports from main engine)\n- **quantitative_integration.py**: Unified interface for regime/vol/Kelly/backtest modules\n- **regime_detector.py**: Market regime classification using VIX percentiles\n- **vol_forecaster.py**: GARCH-based realized volatility forecasting\n- **enhanced_kelly.py**: Drawdown-constrained, correlation-aware position sizing\n- **backtest_validator.py**: Walk-forward validation of conviction scores\n\nThis separation keeps concerns clean while avoiding duplication.\n\n## Limitations & Assumptions\n\n### IV Data\n- **Yahoo Finance Limitations**: Options chains may be unavailable after market hours or for low-volume tickers\n- **Fallback**: Historical volatility (HV) proxy is less accurate than live IV but provides signal\n- **IV Rank**: Approximated from BBW; actual IV Rank requires options chain data\n\n### Strike Selection\n- **Approximation**: Strikes derived from Bollinger Band levels (1-sigma / 2-sigma)\n- **Rounding**: Rounded to standard option strike intervals based on stock price\n- **No Live Pricing**: Does not fetch live option premiums; strike selection is structural, not value-optimized\n\n### Data Quality\n- Minimum 180 trading days required for full Ichimoku cloud population\n- Multi-leg strategies require options chains (calendar spreads especially)\n- After-hours analysis may have reduced data quality\n\n### Market Assumptions\n- Assumes normal options market conditions (not extreme volatility events)\n- Strike intervals assume US equity options conventions\n- Not tested on futures, commodities, or non-US markets\n\n## Requirements\n\n- Python 3.10+ (Python 3.14+ supported via pure-python mode)\n- Isolated virtual environment (auto-created on first run)\n- Internet connection (fetches data from Yahoo Finance)\n\n## Installation\n\n```bash\nclawhub install options-spread-conviction-engine\n```\n\nThe skill automatically creates a virtual environment and installs:\n- pandas >= 2.0\n- pandas_ta >= 0.4.0 (pure Python mode on 3.14+)\n- yfinance >= 1.0\n- scipy, tqdm\n\n**Note:** On Python 3.14+, the engine runs in pure Python mode without numba. Performance is slightly reduced but all functionality works correctly.\n\n## Market Scanners\n\nThe engine includes two distinct scanning tools for different trading philosophies:\n\n### 1. Technical Scanner (market_scanner.py)\nAutomates the search for high-conviction plays across entire stock universes using technical indicators (Ichimoku, RSI, MACD, BB).\n\n#### Features\n- Scans S&P 500, Nasdaq 100, or custom ticker lists.\n- Filters for EXECUTE tier (conviction ≥80).\n- Runs position sizing to ensure trades fit account guardrails.\n\n#### Usage\n```bash\n# Scan S&P 500 for high-conviction technical setups\npython3 scripts/market_scanner.py --universe sp500\n```\n\n### 2. Quantitative Scanner (quant_scanner.py)\nA mathematically-rigorous scanner that ignores technical indicators in favor of market microstructure and probability.\n\n#### Features\n- **IV Surface Analysis**: Analyzes skew and term structure.\n- **Monte Carlo POP**: 10,000-run simulations for true Probability of Profit.\n- **EV Optimization**: Finds trades with the highest risk-adjusted mathematical expectancy.\n- **Account-Aware**: Enforces small-account constraints ($100 max risk).\n\n#### Usage\n```bash\n# Maximize POP (Probability of Profit) for SPY\npython3 scripts/quant_scanner.py SPY --mode pop\n\n# High-expectancy (EV) plays with specific DTE\npython3 scripts/quant_scanner.py AAPL TSLA --mode ev --min-dte 30\n```\n\n## Calculator & Position Sizer\n\nThe integrated toolchain includes:\n\n### calculator.py\nBlack-Scholes options pricing with support for:\n- Single options: calls, puts\n- Vertical spreads: bull call, bear put\n- Multi-leg: iron condors, butterflies\n- Greeks calculation (delta, gamma, theta, vega, rho)\n- Monte Carlo POP simulation\n\n### position_sizer.py\nKelly criterion position sizing adapted for small accounts:\n- Full Kelly and fractional Kelly (default 0.25)\n- Account guardrails ($390 default, $100 max risk)\n- Trade screening and ranking\n- Strike adjustment suggestions\n\n```python\nfrom position_sizer import calculate_position\n\nresult = calculate_position(\n    account_value=390,\n    max_loss_per_spread=80,\n    win_amount=40,\n    pop=0.65,\n)\n# Returns: contracts, total_risk, recommendation, reason\n```\n\n## Files\n\n- `scripts/conviction-engine` — Main CLI wrapper for conviction engine\n- `scripts/spread_conviction_engine.py` — Core engine (vertical spreads)\n- `scripts/multi_leg_strategies.py` — Multi-leg extensions (v2.0.0)\n- `scripts/market_scanner.py` — Automated market scanner for EXECUTE plays\n- `scripts/calculator.py` — Black-Scholes pricing, Greeks, Monte Carlo POP\n- `scripts/position_sizer.py` — Kelly criterion position sizing\n- `scripts/setup-venv.sh` — Environment setup\n- `data/sp500_tickers.txt` — S&P 500 constituents\n- `data/ndx100_tickers.txt` — Nasdaq 100 constituents\n- `assets/` — Documentation and examples\n\n## Version History\n\n- **v2.3.0** (2026-02-13): Quantitative rigor upgrade\n  - Regime Detector: VIX-based market regime classification\n  - Volatility Forecaster: GARCH-based RV forecasting with VRP analysis\n  - Enhanced Kelly Sizer: Drawdown-constrained, correlation-aware position sizing\n  - Backtest Validator: Walk-forward validation with tier separation testing\n  - Quantitative Integration: Unified interface for all quantitative modules\n  - Comprehensive unit test suite for all new modules\n- **v2.2.0** (2026-02-13): Kelly Criterion position sizing with full/half Kelly, edge calculation, and account-aware contract sizing\n- **v2.1.0** (2026-02-12): Added market scanner, integrated calculator and position sizer\n- **v2.0.0** (2026-02-12): Added multi-leg strategies (iron condor, butterfly, calendar)\n- **v1.2.1** (2026-02-09): Volume multiplier, dynamic strike suggestions\n- **v1.1.0** (2026-02-08): Cross-signal weighting, multi-strategy support\n- **v1.0.0** (2026-02-07): Initial bull put spread engine\n\n## License\n\nMIT — Part of the Financial Toolkit for OpenClaw\n","readmeExcerpt":"--- 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","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"brew install jq\nnpm install yahoo-finance2\nsudo ln -s /opt/homebrew/bin/yahoo-finance /usr/local/bin/yf"},{"language":"bash","snippet":"# Basic analysis (auto-detects best strategy)\nconviction-engine AAPL\n\n# Specific strategy\nconviction-engine SPY --strategy bear_call\nconviction-engine QQQ --strategy bull_call --period 2y"},{"language":"bash","snippet":"# Iron Condor — high IV, range-bound\nconviction-engine SPY --strategy iron_condor\n\n# Butterfly — volatility compression, pinning play\nconviction-engine AAPL --strategy butterfly\n\n# Calendar — inverted IV term structure, theta harvest\nconviction-engine TSLA --strategy calendar"},{"language":"bash","snippet":"conviction-engine AAPL MSFT GOOGL --strategy bull_put\nconviction-engine SPY QQQ IWM --strategy iron_condor"},{"language":"bash","snippet":"conviction-engine TSLA --strategy butterfly --json\nconviction-engine SPY --strategy calendar --json | jq '.[0].iv_term_structure'"},{"language":"bash","snippet":"conviction-engine <ticker> [ticker...]\n  --strategy {bull_put,bear_call,bull_call,bear_put,iron_condor,butterfly,calendar}\n  --period {1y,2y,3y,5y}\n  --interval {1h,1d,1wk}\n  --json"}],"parameters":{},"dependencies":[],"permissions":[],"extractedFiles":[],"languages":["typescript"],"docsSourceLabel":"CLAWHUB","editorialOverview":"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. --- 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","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":431,"uniquenessScore":60,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T13:28:35.388Z","emptyReason":null},"items":[{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-10T18:48:31.762Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}