oh-my-opencode 4.19.3 → 4.19.4

package/packages/shared-skills/skills/data-scientist/references/integration-patterns.md

@@ -0,0 +1,153 @@
+# Integration Patterns: DuckDB ↔ Polars
+
+## Zero-Copy Conversions (FASTEST)
+
+### DuckDB → Polars (Recommended)
+
+```python
+import duckdb
+import polars as pl
+
+# Direct conversion with .pl() - zero-copy via Arrow
+df_polars = duckdb.sql("""
+    SELECT * FROM 'data.parquet'
+    WHERE amount > 100
+""").pl()  # Returns Polars DataFrame directly
+
+# Lazy version for large datasets
+lazy_df = duckdb.sql("SELECT * FROM 'data.parquet'").pl(lazy=True)
+result = lazy_df.filter(pl.col('status') == 'active').collect()
+```
+
+### Polars → DuckDB (Direct Reference)
+
+```python
+import duckdb
+import polars as pl
+
+# DuckDB can query Polars DataFrames directly by name
+df = pl.read_parquet('data.parquet')
+
+result = duckdb.sql("""
+    SELECT category, SUM(amount) as total
+    FROM df
+    GROUP BY category
+    ORDER BY total DESC
+""").pl()  # Query df directly, return as Polars
+```
+
+### Via Arrow (When Needed)
+
+```python
+# Polars → Arrow → DuckDB
+df_polars = pl.read_csv('data.csv')
+duckdb.register('my_table', df_polars.to_arrow())
+
+# DuckDB → Arrow → Polars
+arrow_table = duckdb.sql("SELECT * FROM data").arrow()
+df_polars = pl.from_arrow(arrow_table)
+```
+
+## WRONG vs RIGHT Patterns
+
+### ❌ NEVER - Using Pandas
+
+```python
+# FORBIDDEN - decisively slower than Polars/DuckDB on every operation!
+import pandas as pd
+df = pd.read_csv('data.csv')
+result = df.groupby('category')['amount'].sum()
+```
+
+### ✅ CORRECT - DuckDB for simple aggregation query
+
+```python
+import duckdb
+# Direct file query - no memory loading!
+result = duckdb.sql("""
+    SELECT category, SUM(amount) as total
+    FROM 'data.csv'
+    GROUP BY category
+""").pl()  # Fast, memory-efficient
+```
+
+### ❌ NEVER - Loading file before DuckDB query
+
+```python
+# WRONG - Unnecessary memory usage
+import polars as pl
+import duckdb
+df = pl.read_csv('data.csv')  # Loads entire file
+result = duckdb.sql("SELECT * FROM df WHERE amount > 100").pl()
+```
+
+### ✅ CORRECT - Let DuckDB query directly
+
+```python
+import duckdb
+# DuckDB queries file directly - much faster!
+result = duckdb.sql("""
+    SELECT * FROM 'data.csv'
+    WHERE amount > 100
+""").pl()
+```
+
+### ❌ NEVER - Eager evaluation in Polars
+
+```python
+# WRONG - Loads everything immediately
+import polars as pl
+df = pl.read_csv('large_data.csv')  # Eager load
+filtered = df.filter(pl.col('value') > 100)
+```
+
+### ✅ CORRECT - Lazy evaluation
+
+```python
+import polars as pl
+# Lazy - builds query plan, optimizes, executes once
+df = pl.scan_csv('large_data.csv')  # Lazy
+result = (
+    df
+    .filter(pl.col('value') > 100)
+    .groupby('category')
+    .agg(pl.sum('value'))
+    .collect()  # Execute optimized plan
+)
+```
+
+### ❌ NEVER - Unnecessary Conversions
+
+```python
+# WASTEFUL (DuckDB → Pandas → Polars)
+import duckdb, pandas as pd, polars as pl
+df_pd = duckdb.sql("SELECT * FROM 'data.csv'").df()  # requires pandas - the skill never ships it
+df_pl = pl.from_pandas(df_pd)
+```
+
+### ✅ CORRECT - Direct conversion
+
+```python
+# DIRECT (DuckDB → Polars via Arrow)
+import duckdb
+df_pl = duckdb.sql("SELECT * FROM 'data.csv'").pl()
+```
+
+### ❌ NEVER - Wrong tool for heavy filtering
+
+```python
+# SLOW (DuckDB not optimal for filtering)
+import duckdb
+result = duckdb.sql("""
+    SELECT * FROM 'huge.csv'
+    WHERE complex_filter = true
+""").pl()
+```
+
+### ✅ CORRECT - Use Polars for filtering
+
+```python
+# FAST (Polars 128x faster for filtering)
+import polars as pl
+result = pl.scan_csv('huge.csv').filter(pl.col('complex_filter')).collect()
+```

package/packages/shared-skills/skills/data-scientist/references/performance-benchmarks.md

@@ -0,0 +1,37 @@
+# Performance Benchmarks
+
+Routing heuristics distilled from public 2024-2025 results in the [db-benchmark suite](https://github.com/h2oai/db-benchmark) (rendered at [h2oai.github.io/db-benchmark](https://h2oai.github.io/db-benchmark/)) and from the vendors' own documentation ([duckdb.org](https://duckdb.org/), [pola.rs](https://pola.rs/)).
+
+**Read these as routing guidance, not guarantees.** Multipliers vary with dataset size, cardinality, data types, and hardware. When the choice materially matters, measure on the actual data.
+
+## Operation Performance Comparison
+
+| Operation Type      | Winner      | Indicative advantage | When to Use                                    |
+|---------------------|-------------|----------------------|------------------------------------------------|
+| **Filtering**       | **Polars**  | often the fastest by a wide margin (SIMD, predicate pushdown) | Single-table filters |
+| **Sorting**         | **Polars**  | typically the fastest | ORDER BY operations, ranking                   |
+| **Joins**           | **DuckDB**  | typically faster; richer join types | Multi-table joins, especially complex joins    |
+| **Aggregations**    | **DuckDB**  | typically faster on large datasets | GROUP BY, complex aggregations                 |
+| **Window Funcs**    | **Polars**  | typically faster | RANK, LAG/LEAD, running totals                 |
+| **Transformations** | **Polars**  | typically faster | Pivot, melt, string operations                 |
+| **Direct Query**    | **DuckDB**  | avoids loading to memory entirely | Ad-hoc exploration without loading to memory   |
+| **Streaming**       | **Polars**  | handles datasets larger than RAM | Datasets larger than RAM                       |
+
+Both tools are decisively faster than pandas on 1M+ row workloads, which is why pandas is banned outright in this skill.
+
+## Operation Detection Keywords
+
+Automatically detect operation types from user requests:
+
+- **Filter**: "where", "filter", "condition", "select rows", "find"
+- **Sort**: "sort", "order", "top", "bottom", "rank"
+- **Join**: "join", "merge", "combine tables"
+- **Aggregate**: "group", "sum", "avg", "count", "mean", "total", "aggregate"
+- **Transform**: "pivot", "melt", "reshape", "string operations", "clean", "transform"
+- **Window**: "running", "cumulative", "lag", "lead", "rank", "partition"
+
+## Benchmarking Notes
+
+- Public suites exercise typical analytical workloads (1M-100M rows).
+- Performance advantages are approximate and vary by dataset characteristics.
+- Real-world performance depends on data types, cardinality, and hardware.

package/packages/shared-skills/skills/data-scientist/references/uv-setup.md

@@ -0,0 +1,78 @@
+# uv Setup — Per-Platform
+
+This skill runs every data operation through `uv run --with ...`. If `uv --version` fails, set uv up with the automated scripts or the manual commands below, then verify.
+
+## Automated (recommended)
+
+| Platform | Command |
+|---|---|
+| macOS / Linux / WSL / Git Bash | `bash scripts/setup-uv.sh` |
+| Windows (PowerShell) | `powershell -ExecutionPolicy Bypass -File scripts/setup-uv.ps1` |
+
+Both scripts: detect OS + architecture → install uv to the latest release when missing → upgrade it when present (`uv self update`) → make it resolvable for the current shell → verify with `uv --version`. They are idempotent — safe to re-run any time.
+
+## Manual install per platform
+
+### macOS
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh        # official installer → ~/.local/bin/uv
+# or, with Homebrew:
+brew install uv
+```
+
+### Linux (x86_64 / aarch64)
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh        # official installer → ~/.local/bin/uv
+```
+
+The installer detects glibc vs musl and downloads the right static binary. On minimal containers, ensure `curl` (or `wget`) exists; `wget -qO- https://astral.sh/uv/install.sh | sh` is the fallback.
+
+### Windows (native)
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+# or, with winget:
+winget install --id=astral-sh.uv -e
+```
+
+### Windows Subsystem for Linux / Git Bash
+
+Use the Linux/macOS installer inside the Unix shell, not the PowerShell installer:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### CI
+
+```yaml
+# GitHub Actions
+- uses: astral-sh/setup-uv@v5
+# or plain shell anywhere:
+- run: curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+## PATH notes
+
+- The official installers put the binary in `~/.local/bin` (Unix) or `%USERPROFILE%\.local\bin` (Windows). New shells get it automatically on most setups; an already-open shell needs `export PATH="$HOME/.local/bin:$PATH"` (Unix) or `$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"` (PowerShell) once.
+- Homebrew and winget install into their own prefixes that are already on PATH.
+
+## Upgrade to latest
+
+```bash
+uv self update
+```
+
+`uv self update` only works for official-installer binaries; Homebrew/winget installs upgrade through their package manager (`brew upgrade uv` / `winget upgrade astral-sh.uv`). The setup scripts handle this automatically.
+
+## Verify
+
+```bash
+uv --version
+```
+
+## Offline / air-gapped
+
+Download the matching archive from the uv GitHub releases page, extract it, and put the `uv` binary anywhere on PATH. `uv run --with <pkg>` still needs network for first-time package resolution unless a mirror is configured via `UV_INDEX_URL`.

package/packages/shared-skills/skills/data-scientist/scripts/quick-query.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#     "duckdb",
+#     "polars",
+#     "numpy",
+#     "pyarrow",
+#     "typer",
+#     "rich",
+# ]
+# ///
+
+"""Quick data query runner. SQL arg -> DuckDB; --filter (Polars SQL) -> Polars; --describe -> schema + stats."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich import print as rprint
+from rich.table import Table
+
+
+def _run_duckdb(file_path: Path, sql: str) -> None:
+    import duckdb
+
+    table_ref = f"'{file_path}'"
+    stem = file_path.stem
+    query = sql
+    for alias in ("data", "df", stem):
+        query = query.replace(f"FROM {alias} ", f"FROM {table_ref} ")
+        query = query.replace(f"FROM {alias}\n", f"FROM {table_ref}\n")
+        query = query.replace(f"from {alias} ", f"from {table_ref} ")
+        query = query.replace(f"from {alias}\n", f"from {table_ref}\n")
+        if query.endswith(f"FROM {alias}") or query.endswith(f"from {alias}"):
+            query = query[: -len(alias)] + table_ref
+
+    result = duckdb.sql(query)
+    df = result.pl()
+    _print_polars(df)
+
+
+def _run_polars_filter(file_path: Path, expr: str) -> None:
+    import polars as pl
+
+    df = _read_file(file_path)
+    filtered = df.filter(pl.sql_expr(expr))
+    _print_polars(filtered)
+
+
+def _run_describe(file_path: Path) -> None:
+    df = _read_file(file_path)
+
+    rprint(f"\n[bold]Schema:[/bold] {file_path.name} ({len(df)} rows × {len(df.columns)} cols)")
+    for name, dtype in zip(df.columns, df.dtypes):
+        rprint(f"  {name}: [cyan]{dtype}[/cyan]")
+
+    rprint("\n[bold]Statistics:[/bold]")
+    _print_polars(df.describe())
+
+
+def _read_file(file_path: Path):  # noqa: ANN202
+    import polars as pl
+
+    suffix = file_path.suffix.lower()
+    if suffix == ".csv":
+        return pl.read_csv(file_path)
+    if suffix == ".parquet":
+        return pl.read_parquet(file_path)
+    if suffix == ".json":
+        return pl.read_json(file_path)
+    if suffix in (".jsonl", ".ndjson"):
+        return pl.read_ndjson(file_path)
+    rprint(f"[red]Unsupported format:[/red] {suffix} (Excel: export to CSV or Parquet first)")
+    raise SystemExit(1)
+
+
+def _print_polars(df) -> None:  # noqa: ANN001
+    table = Table(show_lines=False)
+    for col_name in df.columns:
+        table.add_column(col_name)
+    for row in df.iter_rows():
+        table.add_row(*(str(v) for v in row))
+    rprint(table)
+    rprint(f"[dim]{df.shape[0]} rows × {df.shape[1]} cols[/dim]")
+
+
+def main(
+    file: Path = typer.Argument(help="Data file (csv, parquet, json, ndjson)"),
+    sql: str = typer.Argument(None, help="SQL query (uses DuckDB). Use 'data' as table name."),
+    filter_expr: str = typer.Option(None, "--filter", "-f", help="Polars SQL filter, e.g. 'amount > 100'"),
+    describe: bool = typer.Option(False, "--describe", "-d", help="Print schema + stats"),
+) -> None:
+    """Query data files with DuckDB (SQL) or Polars (SQL filter expressions)."""
+    if not file.exists():
+        rprint(f"[red]File not found:[/red] {file}")
+        raise SystemExit(1)
+
+    if describe:
+        _run_describe(file)
+    elif filter_expr:
+        _run_polars_filter(file, filter_expr)
+    elif sql:
+        _run_duckdb(file, sql)
+    else:
+        _run_describe(file)
+
+
+if __name__ == "__main__":
+    typer.run(main)

package/packages/shared-skills/skills/data-scientist/scripts/setup-uv.ps1

@@ -0,0 +1,53 @@
+[CmdletBinding()]
+param()
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+function Write-Step([string]$Message) { Write-Host "[setup-uv] $Message" }
+
+Write-Step "detected os=$([System.Runtime.InteropServices.RuntimeInformation]::OSDescription) arch=$([System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture)"
+
+$uv = Get-Command uv -ErrorAction SilentlyContinue
+if ($null -ne $uv) {
+    $current = (& uv --version) | Select-Object -First 1
+    Write-Step "uv already installed ($current) - upgrading"
+    & uv self update 2>$null
+    if ($LASTEXITCODE -ne 0) {
+        Write-Step "uv self update unavailable (package-manager install) - trying winget"
+        if (Get-Command winget -ErrorAction SilentlyContinue) {
+            & winget upgrade --id=astral-sh.uv -e --accept-source-agreements --accept-package-agreements 2>$null
+            if ($LASTEXITCODE -ne 0) { & winget install --id=astral-sh.uv -e --accept-source-agreements --accept-package-agreements }
+        } else {
+            Write-Step "no winget; keeping current uv (already functional)"
+        }
+    }
+} else {
+    Write-Step "uv not found - installing latest via the official installer"
+    $installed = $false
+    try {
+        powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+        $installed = $true
+    } catch {
+        Write-Step "official installer failed ($($_.Exception.Message)) - trying winget"
+        if (Get-Command winget -ErrorAction SilentlyContinue) {
+            & winget install --id=astral-sh.uv -e --accept-source-agreements --accept-package-agreements
+            $installed = ($LASTEXITCODE -eq 0)
+        }
+    }
+    if (-not $installed -and $null -eq (Get-Command uv -ErrorAction SilentlyContinue)) {
+        Write-Step "FAIL: could not install uv - install it manually per references/uv-setup.md"
+        exit 1
+    }
+}
+
+if ($null -eq (Get-Command uv -ErrorAction SilentlyContinue)) {
+    $localBin = Join-Path $env:USERPROFILE '.local\bin'
+    if (Test-Path (Join-Path $localBin 'uv.exe')) { $env:Path = "$localBin;$env:Path" }
+}
+
+if ($null -eq (Get-Command uv -ErrorAction SilentlyContinue)) {
+    Write-Step "FAIL: uv still not on PATH after install - add %USERPROFILE%\.local\bin to PATH and retry"
+    exit 1
+}
+
+Write-Step "OK: $((& uv --version) | Select-Object -First 1)"

package/packages/shared-skills/skills/data-scientist/scripts/setup-uv.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+log() { printf '[setup-uv] %s\n' "$*"; }
+
+os="$(uname -s 2>/dev/null || echo unknown)"
+arch="$(uname -m 2>/dev/null || echo unknown)"
+log "detected os=${os} arch=${arch}"
+
+case "$os" in
+  Darwin|Linux) ;;
+  MINGW*|MSYS*|CYGWIN*)
+    log "Git Bash / MSYS environment detected - installing the Windows build is not supported here."
+    log "Use the Linux installer inside WSL, or run scripts/setup-uv.ps1 in PowerShell instead."
+    exit 1
+    ;;
+  *)
+    log "unsupported OS: ${os} - see references/uv-setup.md for manual steps."
+    exit 1
+    ;;
+esac
+
+if command -v uv >/dev/null 2>&1; then
+  current="$(uv --version 2>/dev/null | head -n1)"
+  log "uv already installed (${current}) - upgrading"
+  if uv self update >/dev/null 2>&1; then
+    log "uv self update succeeded"
+  else
+    log "uv self update unavailable (package-manager install) - trying Homebrew"
+    if command -v brew >/dev/null 2>&1; then
+      brew upgrade uv >/dev/null 2>&1 || brew install uv
+    else
+      log "no Homebrew; keeping current uv (already functional)"
+    fi
+  fi
+else
+  log "uv not found - installing latest via the official installer"
+  if command -v curl >/dev/null 2>&1; then
+    curl -LsSf https://astral.sh/uv/install.sh | sh
+  elif command -v wget >/dev/null 2>&1; then
+    wget -qO- https://astral.sh/uv/install.sh | sh
+  elif command -v brew >/dev/null 2>&1; then
+    log "no curl/wget - installing via Homebrew"
+    brew install uv
+  else
+    log "neither curl, wget, nor brew available - install one of them and re-run."
+    exit 1
+  fi
+fi
+
+if ! command -v uv >/dev/null 2>&1; then
+  export PATH="$HOME/.local/bin:$PATH"
+fi
+
+if ! command -v uv >/dev/null 2>&1; then
+  log "FAIL: uv still not on PATH after install - add \$HOME/.local/bin to PATH and retry."
+  exit 1
+fi
+
+log "OK: $(uv --version)"

package/packages/shared-skills/skills/debugging/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debugging
-description: "MUST USE for any real runtime debugging across ANY language or binary — crashes, silent failures, wrong responses, stuck processes, memory leaks, async misbehavior, unexplained timing, reverse engineering. Runs a hypothesis-driven loop: form ≥3 hypotheses, investigate in parallel, after 2 failed rounds spawn Oracles from orthogonal angles, confirm root cause, lock with a failing test, fix minimally, QA by actually USING the system, scrub artifacts. The actual HOW lives in `references/` — READ THEM. Triggers: 'debug this', 'why is X not working', 'hanging', 'attach a debugger', 'reverse engineer', 'pwndbg', 'gdb', 'lldb', 'node inspect', 'tsx debug', 'pdb', 'dlv', 'delve', 'rust-gdb', 'set a breakpoint', 'context window exploded', 'why is the response empty', 'why is this happening', 'trace this bug', 'reproduce and fix', 'silent failure', 'HTTP 200 but empty', 'why did it stop', 'inspect the binary', 'playwright', 'flaky test', 'fails intermittently', 'passes in isolation', 'only fails in CI'."
+description: "MUST USE for any real runtime debugging across ANY language or binary — crashes, silent failures, wrong responses, stuck processes, memory leaks, async misbehavior, unexplained timing, reverse engineering. Runs a hypothesis-driven loop: form ≥3 hypotheses, investigate in parallel, after 2 failed rounds spawn Oracles from orthogonal angles, confirm root cause, lock with a failing test, fix minimally, QA by actually USING the system, scrub artifacts. The actual HOW lives in `references/` — READ THEM. Triggers: 'debug this', 'why is X not working', 'hanging', 'attach a debugger', 'reverse engineer', 'pwndbg', 'gdb', 'lldb', 'node inspect', 'pdb', 'dlv', 'delve', 'rust-gdb', 'set a breakpoint', 'context window exploded', 'why is the response empty', 'why is this happening', 'trace this bug', 'reproduce and fix', 'silent failure', 'HTTP 200 but empty', 'why did it stop', 'inspect the binary', 'playwright', 'flaky test', 'fails intermittently', 'passes in isolation', 'only fails in CI'."
 ---
 
 # Debugging

package/packages/shared-skills/skills/programming/SKILL.md

@@ -238,8 +238,7 @@ Logging is part of the code you ship, and it has iron rules of its own: levels c
 ## DEPENDENCY UPGRADES — CROSS-CUTTING RULES
 
 - **`0.x` minor = major.** Semver promises nothing below 1.0: treat `0.N → 0.N+1` as a breaking upgrade — read the changelog, build, and run the full suite before trusting it. A required field appearing in a public options type is a routine `0.x` "minor".
-- **Version literals live outside the manifest.** Before committing a bump, grep the repo for the old version string: Dockerfiles pinning a global CLI, CI workflows, docs, and contract tests all carry copies. A bump that updates only the package manifest ships a split-brain deploy.
-- **Pin-parity contract tests are a pattern, not a nuisance.** A small test asserting the lockfile-resolved version equals the deploy artifact's pin (Dockerfile, image tag) turns silent drift into a red test. If the project has one, update it deliberately; if the bump reveals unguarded drift, add the test with the bump.
+- **Version literals live outside the manifest.** Before committing a bump, grep the repo for the old version string: Dockerfiles pinning a global CLI, CI workflows, and docs all carry copies. A bump that updates only the package manifest ships a split-brain deploy.
 - **Never hand-merge a lockfile.** On conflict, take either side whole and regenerate with the package manager — the resolver owns that file, not you.
 
 ---

package/packages/shared-skills/skills/ulw-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ulw-plan
-description: "MUST USE for planning before coding when design uncertainty remains after discovery: ambiguous scope, competing decompositions, unclear boundaries, uncertain dependency ordering, architecture decisions, a vague 'just make it good / figure out what to build' brief, or any request to plan, interview, or break work down. Explore-first planning consultant (Prometheus) that grounds in the codebase, asks only the forks exploration cannot resolve - or researches them to best practice when the intent is fuzzy - waits for explicit approval, then writes ONE decision-complete work plan a worker executes with zero further interview. Triggers: ulw-plan, plan this, make a plan, plan before coding, interview me, break this down, start planning, plan mode, just make it good, figure out what to build."
+description: "ACTIVATES ONLY on an explicit user request for the ulw-plan workflow: the user themselves saying ulw-plan, ulw plan, /skill:ulw-plan, or asking in their own words for a work plan before coding. NEVER self-activates: a bare ulw/ultrawork run, an agent-side routing decision, or reading this file is not a request, and the plan-gated reviewers (metis/momus) stay locked without a user request plus a written .omo/plans plan file. Explore-first planning consultant (Prometheus) that grounds in the codebase, asks only the forks exploration cannot resolve - or researches them to best practice when the intent is fuzzy - waits for explicit approval, then writes ONE decision-complete work plan a worker executes with zero further interview. Triggers: ulw-plan, ulw plan, plan this, make a plan, plan before coding, interview me, break this down, start planning, plan mode."
 metadata:
   short-description: Explore-first planning consultant that waits for your okay before planning
 ---