specweave 0.4.0 → 0.6.0

package/plugins/specweave-ml/skills/time-series-forecaster/SKILL.md

@@ -0,0 +1,569 @@
+---
+name: time-series-forecaster
+description: |
+  Time series forecasting with ARIMA, Prophet, LSTM, and statistical methods. Activates for "time series", "forecasting", "predict future", "trend analysis", "seasonality", "ARIMA", "Prophet", "sales forecast", "demand prediction", "stock prediction". Handles trend decomposition, seasonality detection, multivariate forecasting, and confidence intervals with SpecWeave increment integration.
+---
+
+# Time Series Forecaster
+
+## Overview
+
+Specialized forecasting pipelines for time-dependent data. Handles trend analysis, seasonality detection, and future predictions using statistical methods, machine learning, and deep learning approaches—all integrated with SpecWeave's increment workflow.
+
+## Why Time Series is Different
+
+**Standard ML assumptions violated**:
+- ❌ Data is NOT independent (temporal correlation)
+- ❌ Data is NOT identically distributed (trends, seasonality)
+- ❌ Random train/test split is WRONG (breaks temporal order)
+
+**Time series requirements**:
+- ✅ Temporal order preserved
+- ✅ No data leakage from future
+- ✅ Stationarity checks
+- ✅ Autocorrelation analysis
+- ✅ Seasonality decomposition
+
+## Forecasting Methods
+
+### 1. Statistical Methods (Baseline)
+
+**ARIMA (AutoRegressive Integrated Moving Average)**:
+```python
+from specweave import TimeSeriesForecaster
+
+forecaster = TimeSeriesForecaster(
+    method="arima",
+    increment="0042"
+)
+
+# Automatic order selection (p, d, q)
+forecaster.fit(train_data)
+
+# Forecast next 30 periods
+forecast = forecaster.predict(horizon=30)
+
+# Generates:
+# - Trend analysis
+# - Seasonality decomposition
+# - Autocorrelation plots (ACF, PACF)
+# - Residual diagnostics
+# - Forecast with confidence intervals
+```
+
+**Seasonal Decomposition**:
+```python
+# Decompose into trend + seasonal + residual
+decomposition = forecaster.decompose(
+    data=sales_data,
+    model='multiplicative',  # Or 'additive'
+    period=12  # Monthly seasonality
+)
+
+# Creates:
+# - Trend component plot
+# - Seasonal component plot
+# - Residual component plot
+# - Strength of trend/seasonality metrics
+```
+
+### 2. Prophet (Facebook)
+
+**Best for**: Business time series (sales, website traffic, user growth)
+
+```python
+from specweave import ProphetForecaster
+
+forecaster = ProphetForecaster(increment="0042")
+
+# Prophet handles:
+# - Multiple seasonality (daily, weekly, yearly)
+# - Holidays and events
+# - Missing data
+# - Outliers
+
+forecaster.fit(
+    data=sales_data,
+    holidays=us_holidays,  # Built-in holiday effects
+    seasonality_mode='multiplicative'
+)
+
+forecast = forecaster.predict(horizon=90)
+
+# Generates:
+# - Trend + seasonality + holiday components
+# - Change point detection
+# - Uncertainty intervals
+# - Cross-validation results
+```
+
+**Prophet with Custom Regressors**:
+```python
+# Add external variables (marketing spend, weather, etc.)
+forecaster.add_regressor("marketing_spend")
+forecaster.add_regressor("temperature")
+
+# Prophet incorporates external factors into forecast
+```
+
+### 3. Deep Learning (LSTM/GRU)
+
+**Best for**: Complex patterns, multivariate forecasting, non-linear relationships
+
+```python
+from specweave import LSTMForecaster
+
+forecaster = LSTMForecaster(
+    lookback_window=30,  # Use 30 past observations
+    horizon=7,  # Predict 7 steps ahead
+    increment="0042"
+)
+
+# Automatically handles:
+# - Sequence creation
+# - Train/val/test split (temporal)
+# - Scaling
+# - Early stopping
+
+forecaster.fit(
+    data=sensor_data,
+    epochs=100,
+    batch_size=32
+)
+
+forecast = forecaster.predict(horizon=7)
+
+# Generates:
+# - Training history plots
+# - Validation metrics
+# - Attention weights (if using attention)
+# - Forecast uncertainty estimation
+```
+
+### 4. Multivariate Forecasting
+
+**VAR (Vector AutoRegression)** - Multiple related time series:
+```python
+from specweave import VARForecaster
+
+# Forecast multiple related series simultaneously
+forecaster = VARForecaster(increment="0042")
+
+# Example: Forecast sales across multiple stores
+# Each store's sales affects others
+forecaster.fit(data={
+    'store_1_sales': store1_data,
+    'store_2_sales': store2_data,
+    'store_3_sales': store3_data
+})
+
+forecast = forecaster.predict(horizon=30)
+# Returns forecasts for all 3 stores
+```
+
+## Time Series Best Practices
+
+### 1. Temporal Train/Test Split
+
+```python
+# ❌ WRONG: Random split (data leakage!)
+X_train, X_test = train_test_split(data, test_size=0.2)
+
+# ✅ CORRECT: Temporal split
+split_date = "2024-01-01"
+train = data[data.index < split_date]
+test = data[data.index >= split_date]
+
+# Or use last N periods as test
+train = data[:-30]  # All but last 30 observations
+test = data[-30:]   # Last 30 observations
+```
+
+### 2. Stationarity Testing
+
+```python
+from specweave import TimeSeriesAnalyzer
+
+analyzer = TimeSeriesAnalyzer(increment="0042")
+
+# Check stationarity (required for ARIMA)
+stationarity = analyzer.check_stationarity(data)
+
+if not stationarity['is_stationary']:
+    # Make stationary via differencing
+    data_diff = analyzer.difference(data, order=1)
+    
+    # Or detrend
+    data_detrended = analyzer.detrend(data)
+```
+
+**Stationarity Report**:
+```markdown
+# Stationarity Analysis
+
+## ADF Test (Augmented Dickey-Fuller)
+- Test Statistic: -2.15
+- P-value: 0.23
+- Critical Value (5%): -2.89
+- Result: ❌ NON-STATIONARY (p > 0.05)
+
+## Recommendation
+Apply differencing (order=1) to remove trend.
+
+After differencing:
+- ADF Test Statistic: -5.42
+- P-value: 0.0001
+- Result: ✅ STATIONARY
+```
+
+### 3. Seasonality Detection
+
+```python
+# Automatic seasonality detection
+seasonality = analyzer.detect_seasonality(data)
+
+# Results:
+# - Daily: False
+# - Weekly: True (period=7)
+# - Monthly: True (period=30)
+# - Yearly: False
+```
+
+### 4. Cross-Validation for Time Series
+
+```python
+# Time series cross-validation (expanding window)
+cv_results = forecaster.cross_validate(
+    data=data,
+    horizon=30,  # Forecast 30 steps ahead
+    n_splits=5,  # 5 expanding windows
+    metric='mape'
+)
+
+# Visualizes:
+# - MAPE across different time periods
+# - Forecast vs actual for each fold
+# - Model stability over time
+```
+
+### 5. Handling Missing Data
+
+```python
+# Time series-specific imputation
+forecaster.handle_missing(
+    method='interpolate',  # Or 'forward_fill', 'backward_fill'
+    limit=3  # Max consecutive missing values to fill
+)
+
+# For seasonal data
+forecaster.handle_missing(
+    method='seasonal_interpolate',
+    period=12  # Use seasonal pattern to impute
+)
+```
+
+## Common Time Series Patterns
+
+### Pattern 1: Sales Forecasting
+
+```python
+from specweave import SalesForecastPipeline
+
+pipeline = SalesForecastPipeline(increment="0042")
+
+# Handles:
+# - Weekly/monthly seasonality
+# - Holiday effects
+# - Marketing campaign impact
+# - Trend changes
+
+pipeline.fit(
+    sales_data=daily_sales,
+    holidays=us_holidays,
+    regressors={
+        'marketing_spend': marketing_data,
+        'competitor_price': competitor_data
+    }
+)
+
+forecast = pipeline.predict(horizon=90)  # 90 days ahead
+
+# Generates:
+# - Point forecast
+# - Prediction intervals (80%, 95%)
+# - Component analysis (trend, seasonality, regressors)
+# - Anomaly flags for past data
+```
+
+### Pattern 2: Demand Forecasting
+
+```python
+from specweave import DemandForecastPipeline
+
+# Inventory optimization, supply chain planning
+pipeline = DemandForecastPipeline(
+    aggregation='daily',  # Or 'weekly', 'monthly'
+    increment="0042"
+)
+
+# Multi-product forecasting
+forecasts = pipeline.fit_predict(
+    products=['product_A', 'product_B', 'product_C'],
+    horizon=30
+)
+
+# Generates:
+# - Demand forecast per product
+# - Confidence intervals
+# - Stockout risk analysis
+# - Reorder point recommendations
+```
+
+### Pattern 3: Stock Price Prediction
+
+```python
+from specweave import FinancialForecastPipeline
+
+# Stock prices, crypto, forex
+pipeline = FinancialForecastPipeline(increment="0042")
+
+# Handles:
+# - Volatility clustering
+# - Non-linear patterns
+# - Technical indicators
+
+pipeline.fit(
+    price_data=stock_prices,
+    features=['volume', 'volatility', 'RSI', 'MACD']
+)
+
+forecast = pipeline.predict(horizon=7)
+
+# Generates:
+# - Price forecast with confidence bands
+# - Volatility forecast (GARCH)
+# - Trading signals (optional)
+# - Risk metrics
+```
+
+### Pattern 4: Sensor Data / IoT
+
+```python
+from specweave import SensorForecastPipeline
+
+# Temperature, humidity, machine metrics
+pipeline = SensorForecastPipeline(
+    method='lstm',  # Deep learning for complex patterns
+    increment="0042"
+)
+
+# Multivariate: Multiple sensor readings
+pipeline.fit(
+    sensors={
+        'temperature': temp_data,
+        'humidity': humidity_data,
+        'pressure': pressure_data
+    }
+)
+
+forecast = pipeline.predict(horizon=24)  # 24 hours ahead
+
+# Generates:
+# - Multi-sensor forecasts
+# - Anomaly detection (unexpected values)
+# - Maintenance alerts
+```
+
+## Evaluation Metrics
+
+**Time series-specific metrics**:
+
+```python
+from specweave import TimeSeriesEvaluator
+
+evaluator = TimeSeriesEvaluator(increment="0042")
+
+metrics = evaluator.evaluate(
+    y_true=test_data,
+    y_pred=forecast
+)
+
+# Metrics:
+# - MAPE (Mean Absolute Percentage Error) - business-friendly
+# - RMSE (Root Mean Squared Error) - penalizes large errors
+# - MAE (Mean Absolute Error) - robust to outliers
+# - MASE (Mean Absolute Scaled Error) - scale-independent
+# - Directional Accuracy - did we predict up/down correctly?
+```
+
+**Evaluation Report**:
+```markdown
+# Time Series Forecast Evaluation
+
+## Point Metrics
+- MAPE: 8.2% (target: <10%) ✅
+- RMSE: 124.5
+- MAE: 98.3
+- MASE: 0.85 (< 1 = better than naive forecast) ✅
+
+## Directional Accuracy
+- Correct direction: 73% (up/down predictions)
+
+## Forecast Bias
+- Mean Error: -5.2 (slight under-forecasting)
+- Bias: -2.1%
+
+## Confidence Intervals
+- 80% interval coverage: 79.2% ✅
+- 95% interval coverage: 94.1% ✅
+
+## Recommendation
+✅ DEPLOY: Model meets accuracy targets and is well-calibrated.
+```
+
+## Integration with SpecWeave
+
+### Increment Structure
+
+```
+.specweave/increments/0042-sales-forecast/
+├── spec.md (forecasting requirements, accuracy targets)
+├── plan.md (forecasting strategy, method selection)
+├── tasks.md
+├── data/
+│   ├── train_data.csv
+│   ├── test_data.csv
+│   └── schema.yaml
+├── experiments/
+│   ├── arima-baseline/
+│   ├── prophet-holidays/
+│   └── lstm-multivariate/
+├── models/
+│   ├── prophet_model.pkl
+│   └── lstm_model.h5
+├── forecasts/
+│   ├── forecast_2024-01.csv
+│   ├── forecast_2024-02.csv
+│   └── forecast_with_intervals.csv
+└── analysis/
+    ├── stationarity_test.md
+    ├── seasonality_decomposition.png
+    └── forecast_evaluation.md
+```
+
+### Living Docs Integration
+
+```bash
+/specweave:sync-docs update
+```
+
+Updates:
+```markdown
+<!-- .specweave/docs/internal/architecture/time-series-forecasting.md -->
+
+## Sales Forecasting Model (Increment 0042)
+
+### Method Selected: Prophet
+- Reason: Handles multiple seasonality + holidays well
+- Alternatives tried: ARIMA (MAPE 12%), LSTM (MAPE 10%)
+- Prophet: MAPE 8.2% ✅ BEST
+
+### Seasonality Detected
+- Weekly: Strong (7-day cycle)
+- Monthly: Moderate (30-day cycle)
+- Yearly: Weak
+
+### Holiday Effects
+- Black Friday: +180% sales (strongest)
+- Christmas: +120% sales
+- Thanksgiving: +80% sales
+
+### Forecast Horizon
+- 90 days ahead
+- Confidence intervals: 80%, 95%
+- Update frequency: Weekly retraining
+
+### Model Performance
+- MAPE: 8.2% (target: <10%)
+- Directional accuracy: 73%
+- Deployed: 2024-01-15
+```
+
+## Commands
+
+```bash
+# Create time series forecast
+/ml:forecast --horizon 30 --method prophet
+
+# Evaluate forecast
+/ml:evaluate-forecast 0042
+
+# Decompose time series
+/ml:decompose-timeseries 0042
+```
+
+## Advanced Features
+
+### 1. Ensemble Forecasting
+
+```python
+# Combine multiple methods for robustness
+ensemble = EnsembleForecast(increment="0042")
+
+ensemble.add_forecaster("arima", weight=0.3)
+ensemble.add_forecaster("prophet", weight=0.5)
+ensemble.add_forecaster("lstm", weight=0.2)
+
+# Weighted average of all forecasts
+forecast = ensemble.predict(horizon=30)
+
+# Ensemble typically 10-20% more accurate than single model
+```
+
+### 2. Forecast Reconciliation
+
+```python
+# For hierarchical time series (e.g., total sales = store1 + store2 + store3)
+reconciler = ForecastReconciler(increment="0042")
+
+# Ensures forecasts sum correctly
+reconciled = reconciler.reconcile(
+    forecasts={
+        'total': total_forecast,
+        'store1': store1_forecast,
+        'store2': store2_forecast,
+        'store3': store3_forecast
+    },
+    method='bottom_up'  # Or 'top_down', 'middle_out'
+)
+```
+
+### 3. Forecast Monitoring
+
+```python
+# Track forecast accuracy over time
+monitor = ForecastMonitor(increment="0042")
+
+# Compare forecasts vs actuals
+monitor.track_performance(
+    forecasts=past_forecasts,
+    actuals=actual_values
+)
+
+# Alerts when accuracy degrades
+if monitor.accuracy_degraded():
+    print("⚠️ Forecast accuracy dropped 15% - retrain model!")
+```
+
+## Summary
+
+Time series forecasting requires specialized techniques:
+- ✅ Temporal validation (no random split)
+- ✅ Stationarity testing
+- ✅ Seasonality detection
+- ✅ Trend decomposition
+- ✅ Cross-validation (expanding window)
+- ✅ Confidence intervals
+- ✅ Forecast monitoring
+
+This skill handles all time series complexity within SpecWeave's increment workflow, ensuring forecasts are reproducible, documented, and production-ready.

package/plugins/specweave-payments/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "specweave-payments",
+  "description": "Payment processing integration for Stripe, PayPal, and billing automation. Includes checkout flows, subscription lifecycle management, PCI DSS compliance guidance, and recurring billing. Focus on production-ready payment systems.",
+  "version": "1.0.0",
+  "author": {
+    "name": "SpecWeave Team"
+  }
+}

package/plugins/specweave-testing/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "specweave-testing",
+  "description": "End-to-end browser testing with Playwright. Validates user flows, captures screenshots, checks accessibility, and visual regression. Test execution infrastructure for SpecWeave increments.",
+  "version": "1.0.0",
+  "author": {
+    "name": "SpecWeave Team"
+  }
+}

package/plugins/specweave-tooling/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "specweave-tooling",
+  "description": "SpecWeave skill development and orchestration tools. Create new skills with proper structure, test cases, and activation triggers. Includes skill router for intelligent skill activation based on context. Meta-tooling for extending SpecWeave.",
+  "version": "1.0.0",
+  "author": {
+    "name": "SpecWeave Team"
+  }
+}

package/plugins/specweave-ui/.claude-plugin/plugin.json

@@ -0,0 +1,106 @@
+{
+  "name": "specweave-ui",
+  "description": "Complete UI/UX development toolkit - Playwright E2E testing, Figma design integration, React/Vue/Angular development, design systems, Storybook component testing. Auto-activates for frontend projects.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Anton Abyzov",
+    "email": "anton@spec-weave.com",
+    "url": "https://spec-weave.com"
+  },
+  "license": "MIT",
+  "homepage": "https://spec-weave.com/plugins/ui",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anton-abyzov/specweave.git",
+    "directory": "src/plugins/specweave-ui"
+  },
+  "keywords": [
+    "ui",
+    "ux",
+    "playwright",
+    "figma",
+    "react",
+    "nextjs",
+    "design-system",
+    "e2e-testing",
+    "storybook",
+    "frontend"
+  ],
+  "specweave": {
+    "core_version": ">=0.4.0",
+    "plugin_type": "domain",
+    "category": "ui-ux"
+  },
+  "provides": {
+    "skills": [
+      "e2e-playwright",
+      "figma-designer",
+      "figma-implementer",
+      "figma-mcp-connector",
+      "design-system-architect",
+      "frontend",
+      "nextjs"
+    ],
+    "agents": [
+      "ui-ux-specialist"
+    ],
+    "commands": [
+      "ui.test",
+      "ui.design",
+      "ui.implement"
+    ]
+  },
+  "auto_detect": {
+    "packages": [
+      "@playwright/test",
+      "playwright",
+      "figma",
+      "@figma/rest-api-types",
+      "react",
+      "react-dom",
+      "next",
+      "vue",
+      "@angular/core",
+      "@storybook/react",
+      "@storybook/vue",
+      "@storybook/angular"
+    ],
+    "files": [
+      "playwright.config.ts",
+      "playwright.config.js",
+      "figma.config.json",
+      ".storybook/",
+      "next.config.js",
+      "next.config.ts"
+    ],
+    "triggers": [
+      "playwright",
+      "e2e",
+      "end-to-end",
+      "figma",
+      "design",
+      "ui",
+      "ux",
+      "frontend",
+      "react",
+      "next",
+      "vue",
+      "angular",
+      "storybook",
+      "design system",
+      "component library"
+    ]
+  },
+  "dependencies": {
+    "mcp_servers": {
+      "browserbase": {
+        "optional": true,
+        "description": "Cloud browser automation for Playwright tests",
+        "env_vars": [
+          "BROWSERBASE_API_KEY",
+          "BROWSERBASE_PROJECT_ID"
+        ]
+      }
+    }
+  }
+}

package/plugins/specweave-ui/.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "browserbase": {
+      "command": "npx",
+      "args": ["-y", "@browserbasehq/mcp-server-browserbase"],
+      "env": {
+        "BROWSERBASE_API_KEY": "${BROWSERBASE_API_KEY}",
+        "BROWSERBASE_PROJECT_ID": "${BROWSERBASE_PROJECT_ID}"
+      },
+      "description": "Cloud browser automation for running Playwright tests in scalable infrastructure",
+      "optional": true
+    }
+  }
+}