oh-my-opencode 4.19.3 → 5.0.0-beta.1

package/packages/omo-codex/plugin/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/omo-codex/plugin/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/omo-codex/plugin/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/omo-codex/plugin/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/omo-codex/plugin/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/omo-codex/plugin/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/omo-codex/plugin/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/omo-codex/plugin/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/omo-codex/plugin/skills/start-work/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: start-work
-description: "Execute a Prometheus work plan in Codex with Boulder state, evidence ledger updates, worktree discipline, parallel subagents, and Stop-hook continuation. Use after planning when the user says start work, execute plan, continue plan, resume plan, or asks to run a .omo/plans plan."
+description: "Execute a Prometheus work plan with Boulder state, evidence ledger updates, worktree discipline, parallel subagents, and Stop-hook continuation. Use after planning when the user says start work, execute plan, continue plan, resume plan, or asks to run a .omo/plans plan."
 ---
 
 ## Codex Harness Tool Compatibility
@@ -29,8 +29,8 @@ For work likely to exceed one wait cycle, require the child to send `WORKING: <t
 
 **YOU DO NOT WRITE CODE. YOU DO NOT EDIT PRODUCT FILES. YOU DO NOT RUN QA YOURSELF. EVERY unit of implementation, test, QA, and review work MUST be delegated to a spawned subagent. NO EXCEPTIONS.** Your hands touch only plan selection, `.omo/` state (Boulder, ledger, plan checkboxes), decomposition, dispatch, verdicts, and evidence records. About to edit a product file or run an implementation command yourself? **STOP. SPAWN A WORKER INSTEAD.** Orchestrate at **MAXIMUM PARALLELISM**: every independent unit runs concurrently; only named dependencies serialize.
 
-### Delegation by difficulty (Codex tier workers)
-When tier worker agents are installed (Codex), size each implementation lane by difficulty and pass the matching `agent_type` where the spawn schema exposes it: LOW (one-file fix, boilerplate, config/copy) -> `lazycodex-worker-low`; MEDIUM (standard feature, few files, known patterns) -> `lazycodex-worker-medium`; HIGH (new module, cross-module refactor, concurrency/security/migration) -> `lazycodex-worker-high`. Explorer/librarian research lanes keep their own roles. Difficulty (model power) is orthogonal to the LIGHT/HEAVY rigor tier in step 4 — judge each on its own facts. On spawn surfaces without `agent_type` (deployed v2), state the tier inside `message`.
+### Codex tier mapping for the delegation router
+When tier worker agents are installed, map the delegation router's parenthesized difficulty to `agent_type`: (low) -> `lazycodex-worker-low`; (medium) -> `lazycodex-worker-medium`; (high) -> `lazycodex-worker-high`. Explorer/librarian research lanes keep their own roles. On spawn surfaces without `agent_type`, state the tier inside `message`. Difficulty (model power) is orthogonal to the LIGHT/HEAVY rigor tier in step 4 — judge each on its own facts.
 
 ## Codex Subagent Reliability
 
@@ -40,7 +40,7 @@ Plan and reviewer agents may run for a long time: spawn them in the background a
 
 # start-work
 
-Execute a Prometheus work plan until every top-level checkbox is complete. This skill pairs with the Codex `Stop` / `SubagentStop` continuation hook (`components/start-work-continuation`), which re-injects the next turn while `.omo/boulder.json` says this `codex:<session_id>` still has unchecked plan work.
+Execute a Prometheus work plan until every top-level checkbox is complete. This skill pairs with the harness's start-work continuation hook, which re-injects the next turn while `.omo/boulder.json` says this `codex:<session_id>` still has unchecked plan work.
 
 ## Usage
 
@@ -104,14 +104,58 @@ Write `.omo/boulder.json` before implementation starts. Prefix session ids with
 
 For PR/branch work, a task-owned worktree is mandatory before implementation starts: pass `--worktree`, or use `--make-pr`/`--ship`, which auto-create one. Verify the path with `git worktree list --porcelain` or create it with `git worktree add <path> <branch-or-HEAD>`, then store the absolute path as `worktree_path`. All edits, commands, tests, and evidence capture must run inside that worktree.
 
+## Parallel delivery lanes (teams and worktrees)
+
+Solo orchestration with parallel background workers is the default topology. Decide once, when the wave's lanes are known, and record the verdict in the ledger:
+
+- **Independent lanes -> parallel workers.** Separate files, no shared contract: one parallel spawn burst; no team.
+- **Overlapping lanes -> a team.** The lanes touch the same module or contract AND running them concurrently actually finishes sooner: stand up a team (where the harness has one) so one lane's discoveries relay through you mid-flight.
+- **PR-mode independent lanes -> a worktree per lane.** Under `--make-pr`/`--ship`, when a wave holds independent checkboxes, give each lane its own branch and task-owned worktree, delivered as its own PR.
+
+Landing rules, regardless of topology:
+
+- **Merge per verified unit.** A lane lands the moment its own gates pass — it never waits for the slowest sibling. Integrate landed work back into the base the remaining lanes branch from.
+- **Only the orchestrator merges.** Workers and team members never merge and never push the base branch.
+- **Conflicts are the orchestrator's job.** Decide the landing order and tell the later lane what changed; a worker never resolves a sibling's conflict blind.
+
 ## Phase 3: Execute the next checkbox
 
 1. Read the full selected plan.
 2. Find the first unchecked column-0 checkbox in `## TODOs` or `## Final Verification Wave`.
 3. Ignore nested checkboxes under acceptance criteria, evidence, and definition-of-done sections.
 4. Classify the checkbox tier and record it in its ledger entry. Default is LIGHT — a narrow change inside existing layers. Take HEAVY only on a fact you can point to: a new module / abstraction / domain model; auth, security, or session; an external integration; a DB schema or migration; concurrency or transaction boundaries; a cross-domain refactor; or the plan or user signals care. When unsure, take HEAVY; upgrade and redo skipped gates the moment a HEAVY fact surfaces; never downgrade.
-5. Decompose that checkbox into atomic sub-tasks. Collect every other unchecked checkbox in the same plan wave whose dependencies are met — their lanes execute concurrently.
-6. **DELEGATE EVERYTHING. YOU NEVER IMPLEMENT.** Dispatch ALL independent sub-tasks across those checkboxes in one parallel `multi_agent_v1.spawn_agent` burst; serialize only named dependencies. Verification and checkbox marking stay per-checkbox.
+5. Decompose that checkbox into atomic sub-tasks sized for ONE worker in ONE run — a sub-task that would need mid-flight steering is two sub-tasks. Collect every other unchecked checkbox in the same plan wave whose dependencies are met — their lanes execute concurrently. A wave that could split further but holds fewer than 3 independent sub-tasks is under-split.
+6. **DELEGATE EVERYTHING. YOU NEVER IMPLEMENT.** Route every sub-task through the delegation router below, then dispatch ALL independent sub-tasks across those checkboxes in one parallel worker-spawn burst (a single batched spawn call where the harness supports it); serialize only named dependencies. Verification and checkbox marking stay per-checkbox.
+7. Give every dispatched sub-task its completion condition and watch for it per the section below. A dispatch whose completion nobody watches is an unfinished dispatch.
+
+### Monitor every dispatched subagent to its completion condition
+
+A spawned worker is not fire-and-forget. For EACH subagent in the burst, name the observable state that ends its lane — the file written, the PR opened, the checkbox's gates green — and put a watcher on THAT state, never on a clock.
+
+- **Arm one watcher per lane, at spawn time.** The worker's own completion arrives on its own as an injected notification; arm an explicit `monitor` on top of it only when the lane's completion condition lives OUTSIDE the child's final message — CI turning green, a log line, a build artifact appearing, a branch landing. Watch the state itself (`monitor` with a command that exits or emits on that condition), and keep the burst's watchers distinct so one lane firing never reads as another's.
+- **NEVER poll and NEVER sleep.** No `sleep`, no timed retry loop, no re-reading the same status hoping it changed. Between waves, do independent root work or end the turn; an idle session is always woken. A single `task_output({ mode: "tail" })` peek is allowed only when a midpoint decision genuinely depends on it.
+- **Tear the watcher down the instant it resolves.** The moment a monitor fires, or you discover it was armed on the WRONG condition (it watches a path the lane never touches, a pattern that can never match, a lane you already cancelled), stop it with `kill_bash` and say so in the ledger. A stale watcher re-fires on unrelated output and corrupts the next wave's verdict.
+- **Then advance.** Fired watcher plus verified evidence means that lane's gates run and its checkbox closes; a mis-set watcher means re-arm it on the right condition or drop it, and continue. Never let a dead watcher hold the run open, and never treat watcher silence as a pass.
+
+### Delegation router — recommended task executor category
+
+When the plan annotates a todo with `Recommended task executor category:`, follow that annotation; deviate only for a reason recorded in the ledger entry. Otherwise route by shape, in the omo category vocabulary (category-capable harnesses pass it directly on the worker-spawn tool, e.g. `task(category="quick", ...)`; others map the parenthesized difficulty):
+
+| Category | Route here |
+| --- | --- |
+| `quick` (low) | mechanical, single-file, boilerplate, config/copy — the default for every splittable piece |
+| `unspecified-low` (low) | small tasks that fit no other category |
+| `unspecified-high` (medium) | standard features across a few files with known patterns |
+| `visual-engineering` (medium) | frontend, UI/UX, styling, animation |
+| `writing` (low) | documentation and prose |
+| `git` (low) | git operations |
+| `deep` (high) | hairy debugging, research-heavy or subtle cross-module work |
+| `ultrabrain` (high) | ONE genuinely hard, logic-heavy problem — hand it the goal, not step-by-step instructions |
+
+Sizing is a two-branch decision made per checkbox, before dispatch:
+
+- **Splittable work splits.** When the checkbox decomposes into independent pieces, dispatch them as a swarm of `quick`/`unspecified-low` workers in ONE parallel burst — many small cheap workers in parallel beat one large delegation.
+- **Cohesive hard work stays whole.** When splitting would sever shared reasoning (one algorithm, one migration, one subtle bug), send the WHOLE problem to `deep` or `ultrabrain` as ONE delegation. Never force-split work whose parts share one insight.
 
 Each sub-task message must include:
 
@@ -122,11 +166,12 @@ Each sub-task message must include:
 5. One Manual-QA channel, named with the exact tool and exact invocation (the literal `curl`, `send-keys`, `browser:control-in-app-browser` action, `page.click`, payload, selectors, and the binary observable that decides PASS/FAIL), not "verify it works". A LIGHT checkbox needs one real-surface proof of its deliverable, and auxiliary surfaces (CLI stdout, DB state diff, parsed config dump) are first-class when the surface is CLI- or data-shaped:
    - HTTP call: `curl -i` against the live endpoint.
    - Terminal / TUI: drive a real pty; `tmux send-keys` is fine for a boot/behavior smoke, but color/layout/CJK evidence goes through the xterm.js web terminal below, NEVER `tmux capture-pane`.
-   - Browser use: in Codex, use `browser:control-in-app-browser` first when available and the scenario does not need an authenticated or persistent user browser profile; otherwise drive the real page with Chrome, or agent-browser (https://github.com/vercel-labs/agent-browser) when Chrome is unavailable.
+   - Browser use: prefer the harness's in-app browser control when available and the scenario does not need an authenticated or persistent user browser profile; otherwise drive the real page with Chrome, or agent-browser (https://github.com/vercel-labs/agent-browser) when Chrome is unavailable.
    - Computer use: OS-level GUI automation against the running desktop app when the surface is not a page.
    - TUI visual evidence: when a TUI claim needs visual QA or PR proof, run `node script/qa/web-terminal-visual-qa.mjs --command "<cmd>" --input "{Enter}" --evidence-dir <dir>` (real pty rendered through xterm.js in Chrome) and attach `terminal.png` plus `metadata.json`.
 6. The adversarial classes that apply to this sub-task (from the 9 ultraqa classes) and how each is probed.
 7. Required artifact path and cleanup receipt.
+8. Tool-use expectations: batch independent tool calls in parallel; when the harness exposes a code-execution surface (eval), use it for multi-call steps instead of one-by-one calls.
 
 The 9 ultraqa classes are trigger-mapped: new input parsing → malformed input; untrusted external text → prompt injection; resumable or long-running flows → cancel/resume; generated or cached artifacts → stale state; uncommitted user files in scope → dirty worktree; long external commands → hung or long commands; new or timing-sensitive tests → flaky tests; log-based success claims → misleading success output; mid-operation interrupts → repeated interruptions. A class applies when its trigger fact holds. Probe each applicable class; record the rest as not-applicable with a one-line reason.
 
@@ -167,7 +212,7 @@ A worker done claim is never final: each implementation sub-task returns a `Done
 
 Rules:
 - `confirmed` is the only pass verdict. `false-positive`, `needs-fix`, and `needs-human-review` all block checkbox completion.
-- The verifier must be independent from the executor: use `lazycodex-gate-reviewer`, a scoped `worker` reviewer, or root only when root did not implement or materially rewrite that task.
+- The verifier must be independent from the executor: use the harness's gate reviewer (see the harness compatibility section) or a fresh reviewer worker on a strong model, or root only when root did not implement or materially rewrite that task.
 - A worker done claim must be independently verified before it becomes checkbox completion.
 - On any non-confirmed verdict, append the feedback to the ledger, reset the checkbox work to in-progress, and re-dispatch the executor with the exact failure.
 - The verifier must probe the applicable adversarial keys, including `stale_state`, `dirty_worktree`, and `misleading_success_output`, before allowing `FullyDone`.
@@ -206,5 +251,5 @@ When all top-level checkboxes in `## TODOs` and `## Final Verification Wave` are
 - No completion claim while an applicable ultraqa adversarial class was never probed. Each applicable class needs a captured observable result; each skipped class needs a one-line not-applicable reason in the ledger.
 - No `ORCHESTRATION COMPLETE`, final response, PR creation, PR handoff, or merge before the Global Review and Debugging Gate passes with recorded evidence.
 - No PR/branch implementation or review in the main worktree; create or use a task-owned git worktree first.
-- No unprefixed session ids in Boulder state. Codex sessions are always `codex:<session_id>`.
+- No unprefixed session ids in Boulder state. Sessions are always recorded as `codex:<session_id>`.
 - No stale-memory execution. The plan and ledger are the durable source of truth.