{
  "schemaVersion": "1.0",
  "item": {
    "slug": "options-spread-conviction-engine",
    "name": "Options Spread Conviction Engine",
    "source": "tencent",
    "type": "skill",
    "category": "AI 智能",
    "sourceUrl": "https://clawhub.ai/AdamNaghs/options-spread-conviction-engine",
    "canonicalUrl": "https://clawhub.ai/AdamNaghs/options-spread-conviction-engine",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/options-spread-conviction-engine",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=options-spread-conviction-engine",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "CODE_REVIEW_REPORT.md",
      "MULTI_LEG_REPORT.md",
      "QUANT_SCANNER.md",
      "README.md",
      "SKILL.md",
      "_meta.json"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/options-spread-conviction-engine"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/options-spread-conviction-engine",
    "agentPageUrl": "https://openagent3.xyz/skills/options-spread-conviction-engine/agent",
    "manifestUrl": "https://openagent3.xyz/skills/options-spread-conviction-engine/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/options-spread-conviction-engine/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Options Spread Conviction Engine",
        "body": "Multi-regime options spread scoring using technical indicators and IV term structure analysis."
      },
      {
        "title": "Install",
        "body": "brew install jq\nnpm install yahoo-finance2\nsudo ln -s /opt/homebrew/bin/yahoo-finance /usr/local/bin/yf"
      },
      {
        "title": "Overview",
        "body": "This engine analyzes any ticker and scores seven options strategies across two categories:"
      },
      {
        "title": "Vertical Spreads (Directional)",
        "body": "StrategyTypePhilosophyIdeal Setupbull_putCreditMean ReversionBullish trend + oversold dipbear_callCreditMean ReversionBearish trend + overbought ripbull_callDebitBreakoutStrong bullish momentumbear_putDebitBreakoutStrong bearish momentum"
      },
      {
        "title": "Multi-Leg Strategies (Non-Directional / Theta)",
        "body": "StrategyTypePhilosophyIdeal Setupiron_condorCreditPremium SellingIV Rank >70, RSI neutral, range-boundbutterflyDebitPinning PlayBB squeeze, RSI center, low ADXcalendarDebitTheta HarvestInverted IV term structure (front > back)"
      },
      {
        "title": "Vertical Spreads",
        "body": "Weights vary by strategy type (Credit = Mean Reversion, Debit = Breakout):\n\nCredit Spreads (bull_put, bear_call)\n\nIndicatorWeightPurposeIchimoku Cloud25 ptsTrend structure & equilibriumRSI20 ptsEntry timing (mean-reversion)MACD15 ptsMomentum confirmationBollinger Bands25 ptsVolatility regimeADX15 ptsTrend strength validation\n\nDebit Spreads (bull_call, bear_put)\n\nIndicatorWeightPurposeIchimoku Cloud20 ptsTrend confirmationRSI10 ptsDirectional momentumMACD30 ptsBreakout accelerationBollinger Bands25 ptsBandwidth expansionADX15 ptsTrend strength validation"
      },
      {
        "title": "Multi-Leg Strategies",
        "body": "Iron Condor (Credit / Range-Bound)\n\nComponentWeightRationaleIV Rank (BBW %)25 ptsRich premiums to sellRSI Neutrality20 ptsNo directional momentumADX Range-Bound20 ptsWeak trend = range structurePrice Position20 ptsCentered in range = safe marginsMACD Neutrality15 ptsNo acceleration in any direction\n\nTriggers:\n\nIV Rank > 70: Premium-rich environment\nRSI 40-60: Neutral momentum\nADX < 25: Weak/no trend\nPrice near %B center: Max profit zone maximized\n\nStrike Selection:\n\nSELL put at 1-sigma below price (short put)\nBUY put at 2-sigma below (long put — wing)\nSELL call at 1-sigma above price (short call)\nBUY call at 2-sigma above (long call — wing)\n\nOutput:\n\nAll 4 strikes (put_long, put_short, call_short, call_long)\nMax profit zone (width between short strikes)\nWing width\n\nButterfly (Debit / Volatility Compression)\n\nComponentWeightRationaleBB Squeeze30 ptsVol compression = narrow rangeRSI Neutrality25 ptsPrice at equilibriumADX Weakness20 ptsNo directional trend at allPrice Centering15 ptsAt center of range for max profitMACD Flatness10 ptsNo momentum\n\nTriggers:\n\nBBW percentile < 25: Squeeze active\nRSI 45-55: Dead-center (tighter than condor)\nADX < 20: Very weak trend\nMACD histogram near zero\nPrice at %B = 0.50\n\nStrike Selection:\n\nBUY 1 call at strike below center (lower wing)\nSELL 2 calls at center strike (body)\nBUY 1 call at strike above center (upper wing)\n\nOutput:\n\n3 strikes (lower_long, middle_short, upper_long)\nMax profit price (= middle strike)\nProfit zone (approximate breakevens)\n\nCalendar Spread (Debit / Theta Harvesting)\n\nComponentWeightRationaleIV Term Structure30 ptsFront IV > Back IV = theta edgePrice Stability20 ptsPrice stays near strikeRSI Neutrality20 ptsNot trending away from strikeADX Moderate15 ptsSome structure, not trending hardMACD Neutrality15 ptsNo directional acceleration\n\nTriggers:\n\nFront-month IV > Back-month IV by > 5%: Inverted term structure\nLow recent volatility: Price stability\nRSI neutral: No directional momentum\nADX 18-25: Moderate trend structure (not chaos)\n\nData Sources:\n\nPrimary: Live options chain IV from Yahoo Finance\nFallback: Historical volatility proxy (HV 10-day vs 30-day)\n\nStrike Selection:\n\nATM strike (rounded to standard interval)\nFront expiry: nearest available\nBack expiry: 25+ days after front\n\nOutput:\n\nSingle strike (both legs)\nFront and back expiry dates\nIV differential (%)\nTheta advantage description"
      },
      {
        "title": "Conviction Tiers",
        "body": "ScoreTierAction80-100EXECUTEHigh conviction — Enter the spread60-79PREPAREFavorable — Size the trade40-59WATCHInteresting — Add to watchlist0-39WAITPoor conditions — Avoid / No setup"
      },
      {
        "title": "Vertical Spreads",
        "body": "# 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"
      },
      {
        "title": "Multi-Leg Strategies",
        "body": "# 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"
      },
      {
        "title": "Multiple Tickers",
        "body": "conviction-engine AAPL MSFT GOOGL --strategy bull_put\nconviction-engine SPY QQQ IWM --strategy iron_condor"
      },
      {
        "title": "JSON Output (for automation)",
        "body": "conviction-engine TSLA --strategy butterfly --json\nconviction-engine SPY --strategy calendar --json | jq '.[0].iv_term_structure'"
      },
      {
        "title": "Full Options",
        "body": "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"
      },
      {
        "title": "Iron Condor",
        "body": "================================================================================\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"
      },
      {
        "title": "Butterfly",
        "body": "================================================================================\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"
      },
      {
        "title": "Calendar Spread",
        "body": "================================================================================\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%"
      },
      {
        "title": "IV Rank Approximation",
        "body": "IV Rank is approximated using Bollinger Bandwidth (BBW) percentile over 252 trading days:\n\nIV Rank ≈ (Current BBW - 52wk Low BBW) / (52wk High BBW - 52wk Low BBW) × 100\n\nThis correlation is well-documented: realized volatility (BBW) and implied volatility rank move with ~0.7-0.8 correlation (Sinclair, \"Volatility Trading\", 2013)."
      },
      {
        "title": "IV Term Structure",
        "body": "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."
      },
      {
        "title": "Quantitative Modules (v2.3.0)",
        "body": "The engine now includes four quantitative modules for rigorous strategy validation and optimization:"
      },
      {
        "title": "1. Regime Detector (regime_detector.py)",
        "body": "Market regime classification using VIX percentiles:\n\nCRISIS: VIX > 80th percentile — favors premium selling (iron condors)\nHIGH_VOL: VIX 60-80th — elevated IV benefits credit spreads\nNORMAL: VIX 40-60th — balanced environment, all strategies viable\nLOW_VOL: VIX 20-40th — cheap options favor debit spreads\nEUPHORIA: VIX < 20th — momentum continues, mean reversion brewing\n\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\nIntegration:\n\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')"
      },
      {
        "title": "2. Volatility Forecaster (vol_forecaster.py)",
        "body": "GARCH-based realized volatility forecasting with VRP analysis:\n\nFits GARCH(1,1) to historical returns\nForecasts realized volatility over configurable horizon\nCalculates volatility risk premium (IV - RV forecast)\nProvides conviction adjustments based on VRP\n\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\nInterpretation:\n\nVRP > 5%: Favorable for selling premium (credit spreads)\nVRP < -5%: Favorable for buying premium (debit spreads)\nVRP near 0: No volatility edge, focus on directional setup\n\nIntegration:\n\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')"
      },
      {
        "title": "3. Enhanced Kelly Sizer (enhanced_kelly.py)",
        "body": "Drawdown-constrained, correlation-aware position sizing:\n\nFull Kelly criterion calculation\nDrawdown constraint: f_dd = f_kelly × (1 - target_dd / max_dd)\nConviction-based Kelly scaling:\n\n90-100: Half Kelly\n80-89: Quarter Kelly\n60-79: Eighth Kelly\n<60: No position\n\n\nCorrelation penalty for portfolio context\n\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\nIntegration:\n\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"
      },
      {
        "title": "4. Backtest Validator (backtest_validator.py)",
        "body": "Walk-forward validation of conviction scores:\n\nSimulates historical trades across ticker universe\nValidates tier separation (EXECUTE vs WAIT performance)\nStatistical tests (t-tests, ANOVA)\nTier separation scoring (0-1)\nWeight calibration suggestions\n\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\nOutput Metrics:\n\nWin rate per tier\nExpectancy per tier: (win_rate × avg_win) - (loss_rate × avg_loss)\nSharpe ratio per tier\nP-values for tier differences\nSeparation score (0-1, higher = better discrimination)\n\nIntegration:\n\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}\")"
      },
      {
        "title": "5. Quantitative Integration (quantitative_integration.py)",
        "body": "Unified interface combining all quantitative modules:\n\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\nIntegration:\n\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}\")"
      },
      {
        "title": "Academic Foundation",
        "body": "Ichimoku Cloud — Trend structure (Hosoda, 1968)\nRSI — Momentum oscillator (Wilder, 1978)\nMACD — Trend momentum (Appel, 1979)\nBollinger Bands — Volatility envelopes (Bollinger, 2001)\nIV 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)."
      },
      {
        "title": "Architecture",
        "body": "conviction-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"
      },
      {
        "title": "Module Separation",
        "body": "spread_conviction_engine.py: Vertical spreads, shared infrastructure (data fetching, indicator computation)\nmulti_leg_strategies.py: Iron condors, butterflies, calendars (imports from main engine)\nquantitative_integration.py: Unified interface for regime/vol/Kelly/backtest modules\nregime_detector.py: Market regime classification using VIX percentiles\nvol_forecaster.py: GARCH-based realized volatility forecasting\nenhanced_kelly.py: Drawdown-constrained, correlation-aware position sizing\nbacktest_validator.py: Walk-forward validation of conviction scores\n\nThis separation keeps concerns clean while avoiding duplication."
      },
      {
        "title": "IV Data",
        "body": "Yahoo Finance Limitations: Options chains may be unavailable after market hours or for low-volume tickers\nFallback: Historical volatility (HV) proxy is less accurate than live IV but provides signal\nIV Rank: Approximated from BBW; actual IV Rank requires options chain data"
      },
      {
        "title": "Strike Selection",
        "body": "Approximation: Strikes derived from Bollinger Band levels (1-sigma / 2-sigma)\nRounding: Rounded to standard option strike intervals based on stock price\nNo Live Pricing: Does not fetch live option premiums; strike selection is structural, not value-optimized"
      },
      {
        "title": "Data Quality",
        "body": "Minimum 180 trading days required for full Ichimoku cloud population\nMulti-leg strategies require options chains (calendar spreads especially)\nAfter-hours analysis may have reduced data quality"
      },
      {
        "title": "Market Assumptions",
        "body": "Assumes normal options market conditions (not extreme volatility events)\nStrike intervals assume US equity options conventions\nNot tested on futures, commodities, or non-US markets"
      },
      {
        "title": "Requirements",
        "body": "Python 3.10+ (Python 3.14+ supported via pure-python mode)\nIsolated virtual environment (auto-created on first run)\nInternet connection (fetches data from Yahoo Finance)"
      },
      {
        "title": "Installation",
        "body": "clawhub install options-spread-conviction-engine\n\nThe skill automatically creates a virtual environment and installs:\n\npandas >= 2.0\npandas_ta >= 0.4.0 (pure Python mode on 3.14+)\nyfinance >= 1.0\nscipy, tqdm\n\nNote: On Python 3.14+, the engine runs in pure Python mode without numba. Performance is slightly reduced but all functionality works correctly."
      },
      {
        "title": "Market Scanners",
        "body": "The engine includes two distinct scanning tools for different trading philosophies:"
      },
      {
        "title": "1. Technical Scanner (market_scanner.py)",
        "body": "Automates the search for high-conviction plays across entire stock universes using technical indicators (Ichimoku, RSI, MACD, BB).\n\nFeatures\n\nScans S&P 500, Nasdaq 100, or custom ticker lists.\nFilters for EXECUTE tier (conviction ≥80).\nRuns position sizing to ensure trades fit account guardrails.\n\nUsage\n\n# Scan S&P 500 for high-conviction technical setups\npython3 scripts/market_scanner.py --universe sp500"
      },
      {
        "title": "2. Quantitative Scanner (quant_scanner.py)",
        "body": "A mathematically-rigorous scanner that ignores technical indicators in favor of market microstructure and probability.\n\nFeatures\n\nIV Surface Analysis: Analyzes skew and term structure.\nMonte Carlo POP: 10,000-run simulations for true Probability of Profit.\nEV Optimization: Finds trades with the highest risk-adjusted mathematical expectancy.\nAccount-Aware: Enforces small-account constraints ($100 max risk).\n\nUsage\n\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"
      },
      {
        "title": "Calculator & Position Sizer",
        "body": "The integrated toolchain includes:"
      },
      {
        "title": "calculator.py",
        "body": "Black-Scholes options pricing with support for:\n\nSingle options: calls, puts\nVertical spreads: bull call, bear put\nMulti-leg: iron condors, butterflies\nGreeks calculation (delta, gamma, theta, vega, rho)\nMonte Carlo POP simulation"
      },
      {
        "title": "position_sizer.py",
        "body": "Kelly criterion position sizing adapted for small accounts:\n\nFull Kelly and fractional Kelly (default 0.25)\nAccount guardrails ($390 default, $100 max risk)\nTrade screening and ranking\nStrike adjustment suggestions\n\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"
      },
      {
        "title": "Files",
        "body": "scripts/conviction-engine — Main CLI wrapper for conviction engine\nscripts/spread_conviction_engine.py — Core engine (vertical spreads)\nscripts/multi_leg_strategies.py — Multi-leg extensions (v2.0.0)\nscripts/market_scanner.py — Automated market scanner for EXECUTE plays\nscripts/calculator.py — Black-Scholes pricing, Greeks, Monte Carlo POP\nscripts/position_sizer.py — Kelly criterion position sizing\nscripts/setup-venv.sh — Environment setup\ndata/sp500_tickers.txt — S&P 500 constituents\ndata/ndx100_tickers.txt — Nasdaq 100 constituents\nassets/ — Documentation and examples"
      },
      {
        "title": "Version History",
        "body": "v2.3.0 (2026-02-13): Quantitative rigor upgrade\n\nRegime Detector: VIX-based market regime classification\nVolatility Forecaster: GARCH-based RV forecasting with VRP analysis\nEnhanced Kelly Sizer: Drawdown-constrained, correlation-aware position sizing\nBacktest Validator: Walk-forward validation with tier separation testing\nQuantitative Integration: Unified interface for all quantitative modules\nComprehensive unit test suite for all new modules\n\n\nv2.2.0 (2026-02-13): Kelly Criterion position sizing with full/half Kelly, edge calculation, and account-aware contract sizing\nv2.1.0 (2026-02-12): Added market scanner, integrated calculator and position sizer\nv2.0.0 (2026-02-12): Added multi-leg strategies (iron condor, butterfly, calendar)\nv1.2.1 (2026-02-09): Volume multiplier, dynamic strike suggestions\nv1.1.0 (2026-02-08): Cross-signal weighting, multi-strategy support\nv1.0.0 (2026-02-07): Initial bull put spread engine"
      },
      {
        "title": "License",
        "body": "MIT — Part of the Financial Toolkit for OpenClaw"
      }
    ],
    "body": "Options Spread Conviction Engine\n\nMulti-regime options spread scoring using technical indicators and IV term structure analysis.\n\nInstall\nbrew install jq\nnpm install yahoo-finance2\nsudo ln -s /opt/homebrew/bin/yahoo-finance /usr/local/bin/yf\n\nOverview\n\nThis engine analyzes any ticker and scores seven options strategies across two categories:\n\nVertical Spreads (Directional)\nStrategy\tType\tPhilosophy\tIdeal Setup\nbull_put\tCredit\tMean Reversion\tBullish trend + oversold dip\nbear_call\tCredit\tMean Reversion\tBearish trend + overbought rip\nbull_call\tDebit\tBreakout\tStrong bullish momentum\nbear_put\tDebit\tBreakout\tStrong bearish momentum\nMulti-Leg Strategies (Non-Directional / Theta)\nStrategy\tType\tPhilosophy\tIdeal Setup\niron_condor\tCredit\tPremium Selling\tIV Rank >70, RSI neutral, range-bound\nbutterfly\tDebit\tPinning Play\tBB squeeze, RSI center, low ADX\ncalendar\tDebit\tTheta Harvest\tInverted IV term structure (front > back)\nScoring Methodology\nVertical Spreads\n\nWeights vary by strategy type (Credit = Mean Reversion, Debit = Breakout):\n\nCredit Spreads (bull_put, bear_call)\nIndicator\tWeight\tPurpose\nIchimoku Cloud\t25 pts\tTrend structure & equilibrium\nRSI\t20 pts\tEntry timing (mean-reversion)\nMACD\t15 pts\tMomentum confirmation\nBollinger Bands\t25 pts\tVolatility regime\nADX\t15 pts\tTrend strength validation\nDebit Spreads (bull_call, bear_put)\nIndicator\tWeight\tPurpose\nIchimoku Cloud\t20 pts\tTrend confirmation\nRSI\t10 pts\tDirectional momentum\nMACD\t30 pts\tBreakout acceleration\nBollinger Bands\t25 pts\tBandwidth expansion\nADX\t15 pts\tTrend strength validation\nMulti-Leg Strategies\nIron Condor (Credit / Range-Bound)\nComponent\tWeight\tRationale\nIV Rank (BBW %)\t25 pts\tRich premiums to sell\nRSI Neutrality\t20 pts\tNo directional momentum\nADX Range-Bound\t20 pts\tWeak trend = range structure\nPrice Position\t20 pts\tCentered in range = safe margins\nMACD Neutrality\t15 pts\tNo acceleration in any direction\n\nTriggers:\n\nIV Rank > 70: Premium-rich environment\nRSI 40-60: Neutral momentum\nADX < 25: Weak/no trend\nPrice near %B center: Max profit zone maximized\n\nStrike Selection:\n\nSELL put at 1-sigma below price (short put)\nBUY put at 2-sigma below (long put — wing)\nSELL call at 1-sigma above price (short call)\nBUY call at 2-sigma above (long call — wing)\n\nOutput:\n\nAll 4 strikes (put_long, put_short, call_short, call_long)\nMax profit zone (width between short strikes)\nWing width\nButterfly (Debit / Volatility Compression)\nComponent\tWeight\tRationale\nBB Squeeze\t30 pts\tVol compression = narrow range\nRSI Neutrality\t25 pts\tPrice at equilibrium\nADX Weakness\t20 pts\tNo directional trend at all\nPrice Centering\t15 pts\tAt center of range for max profit\nMACD Flatness\t10 pts\tNo momentum\n\nTriggers:\n\nBBW percentile < 25: Squeeze active\nRSI 45-55: Dead-center (tighter than condor)\nADX < 20: Very weak trend\nMACD histogram near zero\nPrice at %B = 0.50\n\nStrike Selection:\n\nBUY 1 call at strike below center (lower wing)\nSELL 2 calls at center strike (body)\nBUY 1 call at strike above center (upper wing)\n\nOutput:\n\n3 strikes (lower_long, middle_short, upper_long)\nMax profit price (= middle strike)\nProfit zone (approximate breakevens)\nCalendar Spread (Debit / Theta Harvesting)\nComponent\tWeight\tRationale\nIV Term Structure\t30 pts\tFront IV > Back IV = theta edge\nPrice Stability\t20 pts\tPrice stays near strike\nRSI Neutrality\t20 pts\tNot trending away from strike\nADX Moderate\t15 pts\tSome structure, not trending hard\nMACD Neutrality\t15 pts\tNo directional acceleration\n\nTriggers:\n\nFront-month IV > Back-month IV by > 5%: Inverted term structure\nLow recent volatility: Price stability\nRSI neutral: No directional momentum\nADX 18-25: Moderate trend structure (not chaos)\n\nData Sources:\n\nPrimary: Live options chain IV from Yahoo Finance\nFallback: Historical volatility proxy (HV 10-day vs 30-day)\n\nStrike Selection:\n\nATM strike (rounded to standard interval)\nFront expiry: nearest available\nBack expiry: 25+ days after front\n\nOutput:\n\nSingle strike (both legs)\nFront and back expiry dates\nIV differential (%)\nTheta advantage description\nConviction Tiers\nScore\tTier\tAction\n80-100\tEXECUTE\tHigh conviction — Enter the spread\n60-79\tPREPARE\tFavorable — Size the trade\n40-59\tWATCH\tInteresting — Add to watchlist\n0-39\tWAIT\tPoor conditions — Avoid / No setup\nUsage\nVertical Spreads\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\nMulti-Leg Strategies\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\nMultiple Tickers\nconviction-engine AAPL MSFT GOOGL --strategy bull_put\nconviction-engine SPY QQQ IWM --strategy iron_condor\n\nJSON Output (for automation)\nconviction-engine TSLA --strategy butterfly --json\nconviction-engine SPY --strategy calendar --json | jq '.[0].iv_term_structure'\n\nFull Options\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\nExample Outputs\nIron Condor\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\nButterfly\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\nCalendar Spread\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\nIV Rank Approximation\n\nIV Rank is approximated using Bollinger Bandwidth (BBW) percentile over 252 trading days:\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\nIV 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\nQuantitative Modules (v2.3.0)\n\nThe engine now includes four quantitative modules for rigorous strategy validation and optimization:\n\n1. Regime Detector (regime_detector.py)\n\nMarket regime classification using VIX percentiles:\n\nCRISIS: VIX > 80th percentile — favors premium selling (iron condors)\nHIGH_VOL: VIX 60-80th — elevated IV benefits credit spreads\nNORMAL: VIX 40-60th — balanced environment, all strategies viable\nLOW_VOL: VIX 20-40th — cheap options favor debit spreads\nEUPHORIA: VIX < 20th — momentum continues, mean reversion brewing\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\nIntegration:\n\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\n2. Volatility Forecaster (vol_forecaster.py)\n\nGARCH-based realized volatility forecasting with VRP analysis:\n\nFits GARCH(1,1) to historical returns\nForecasts realized volatility over configurable horizon\nCalculates volatility risk premium (IV - RV forecast)\nProvides conviction adjustments based on VRP\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\nInterpretation:\n\nVRP > 5%: Favorable for selling premium (credit spreads)\nVRP < -5%: Favorable for buying premium (debit spreads)\nVRP near 0: No volatility edge, focus on directional setup\n\nIntegration:\n\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\n3. Enhanced Kelly Sizer (enhanced_kelly.py)\n\nDrawdown-constrained, correlation-aware position sizing:\n\nFull Kelly criterion calculation\nDrawdown constraint: f_dd = f_kelly × (1 - target_dd / max_dd)\nConviction-based Kelly scaling:\n90-100: Half Kelly\n80-89: Quarter Kelly\n60-79: Eighth Kelly\n<60: No position\nCorrelation penalty for portfolio context\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\nIntegration:\n\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\n4. Backtest Validator (backtest_validator.py)\n\nWalk-forward validation of conviction scores:\n\nSimulates historical trades across ticker universe\nValidates tier separation (EXECUTE vs WAIT performance)\nStatistical tests (t-tests, ANOVA)\nTier separation scoring (0-1)\nWeight calibration suggestions\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\nOutput Metrics:\n\nWin rate per tier\nExpectancy per tier: (win_rate × avg_win) - (loss_rate × avg_loss)\nSharpe ratio per tier\nP-values for tier differences\nSeparation score (0-1, higher = better discrimination)\n\nIntegration:\n\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\n5. Quantitative Integration (quantitative_integration.py)\n\nUnified interface combining all quantitative modules:\n\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\nIntegration:\n\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\nAcademic Foundation\nIchimoku Cloud — Trend structure (Hosoda, 1968)\nRSI — Momentum oscillator (Wilder, 1978)\nMACD — Trend momentum (Appel, 1979)\nBollinger Bands — Volatility envelopes (Bollinger, 2001)\nIV 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\nArchitecture\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\nModule Separation\nspread_conviction_engine.py: Vertical spreads, shared infrastructure (data fetching, indicator computation)\nmulti_leg_strategies.py: Iron condors, butterflies, calendars (imports from main engine)\nquantitative_integration.py: Unified interface for regime/vol/Kelly/backtest modules\nregime_detector.py: Market regime classification using VIX percentiles\nvol_forecaster.py: GARCH-based realized volatility forecasting\nenhanced_kelly.py: Drawdown-constrained, correlation-aware position sizing\nbacktest_validator.py: Walk-forward validation of conviction scores\n\nThis separation keeps concerns clean while avoiding duplication.\n\nLimitations & Assumptions\nIV Data\nYahoo Finance Limitations: Options chains may be unavailable after market hours or for low-volume tickers\nFallback: Historical volatility (HV) proxy is less accurate than live IV but provides signal\nIV Rank: Approximated from BBW; actual IV Rank requires options chain data\nStrike Selection\nApproximation: Strikes derived from Bollinger Band levels (1-sigma / 2-sigma)\nRounding: Rounded to standard option strike intervals based on stock price\nNo Live Pricing: Does not fetch live option premiums; strike selection is structural, not value-optimized\nData Quality\nMinimum 180 trading days required for full Ichimoku cloud population\nMulti-leg strategies require options chains (calendar spreads especially)\nAfter-hours analysis may have reduced data quality\nMarket Assumptions\nAssumes normal options market conditions (not extreme volatility events)\nStrike intervals assume US equity options conventions\nNot tested on futures, commodities, or non-US markets\nRequirements\nPython 3.10+ (Python 3.14+ supported via pure-python mode)\nIsolated virtual environment (auto-created on first run)\nInternet connection (fetches data from Yahoo Finance)\nInstallation\nclawhub install options-spread-conviction-engine\n\n\nThe skill automatically creates a virtual environment and installs:\n\npandas >= 2.0\npandas_ta >= 0.4.0 (pure Python mode on 3.14+)\nyfinance >= 1.0\nscipy, tqdm\n\nNote: On Python 3.14+, the engine runs in pure Python mode without numba. Performance is slightly reduced but all functionality works correctly.\n\nMarket Scanners\n\nThe engine includes two distinct scanning tools for different trading philosophies:\n\n1. Technical Scanner (market_scanner.py)\n\nAutomates the search for high-conviction plays across entire stock universes using technical indicators (Ichimoku, RSI, MACD, BB).\n\nFeatures\nScans S&P 500, Nasdaq 100, or custom ticker lists.\nFilters for EXECUTE tier (conviction ≥80).\nRuns position sizing to ensure trades fit account guardrails.\nUsage\n# Scan S&P 500 for high-conviction technical setups\npython3 scripts/market_scanner.py --universe sp500\n\n2. Quantitative Scanner (quant_scanner.py)\n\nA mathematically-rigorous scanner that ignores technical indicators in favor of market microstructure and probability.\n\nFeatures\nIV Surface Analysis: Analyzes skew and term structure.\nMonte Carlo POP: 10,000-run simulations for true Probability of Profit.\nEV Optimization: Finds trades with the highest risk-adjusted mathematical expectancy.\nAccount-Aware: Enforces small-account constraints ($100 max risk).\nUsage\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\nCalculator & Position Sizer\n\nThe integrated toolchain includes:\n\ncalculator.py\n\nBlack-Scholes options pricing with support for:\n\nSingle options: calls, puts\nVertical spreads: bull call, bear put\nMulti-leg: iron condors, butterflies\nGreeks calculation (delta, gamma, theta, vega, rho)\nMonte Carlo POP simulation\nposition_sizer.py\n\nKelly criterion position sizing adapted for small accounts:\n\nFull Kelly and fractional Kelly (default 0.25)\nAccount guardrails ($390 default, $100 max risk)\nTrade screening and ranking\nStrike adjustment suggestions\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\nFiles\nscripts/conviction-engine — Main CLI wrapper for conviction engine\nscripts/spread_conviction_engine.py — Core engine (vertical spreads)\nscripts/multi_leg_strategies.py — Multi-leg extensions (v2.0.0)\nscripts/market_scanner.py — Automated market scanner for EXECUTE plays\nscripts/calculator.py — Black-Scholes pricing, Greeks, Monte Carlo POP\nscripts/position_sizer.py — Kelly criterion position sizing\nscripts/setup-venv.sh — Environment setup\ndata/sp500_tickers.txt — S&P 500 constituents\ndata/ndx100_tickers.txt — Nasdaq 100 constituents\nassets/ — Documentation and examples\nVersion History\nv2.3.0 (2026-02-13): Quantitative rigor upgrade\nRegime Detector: VIX-based market regime classification\nVolatility Forecaster: GARCH-based RV forecasting with VRP analysis\nEnhanced Kelly Sizer: Drawdown-constrained, correlation-aware position sizing\nBacktest Validator: Walk-forward validation with tier separation testing\nQuantitative Integration: Unified interface for all quantitative modules\nComprehensive unit test suite for all new modules\nv2.2.0 (2026-02-13): Kelly Criterion position sizing with full/half Kelly, edge calculation, and account-aware contract sizing\nv2.1.0 (2026-02-12): Added market scanner, integrated calculator and position sizer\nv2.0.0 (2026-02-12): Added multi-leg strategies (iron condor, butterfly, calendar)\nv1.2.1 (2026-02-09): Volume multiplier, dynamic strike suggestions\nv1.1.0 (2026-02-08): Cross-signal weighting, multi-strategy support\nv1.0.0 (2026-02-07): Initial bull put spread engine\nLicense\n\nMIT — Part of the Financial Toolkit for OpenClaw"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/AdamNaghs/options-spread-conviction-engine",
    "publisherUrl": "https://clawhub.ai/AdamNaghs/options-spread-conviction-engine",
    "owner": "AdamNaghs",
    "version": "2.2.1",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/options-spread-conviction-engine",
    "downloadUrl": "https://openagent3.xyz/downloads/options-spread-conviction-engine",
    "agentUrl": "https://openagent3.xyz/skills/options-spread-conviction-engine/agent",
    "manifestUrl": "https://openagent3.xyz/skills/options-spread-conviction-engine/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/options-spread-conviction-engine/agent.md"
  }
}