gradex 0.1.0__tar.gz

gradex-0.1.0/.evo/traces/12366e76-4c4f-4acf-8b3f-191008979da5.jsonl

@@ -0,0 +1 @@
+{"ts": 1781552055.2846615, "level": "info", "msg": "Experiment 4 started", "data": {}}

gradex-0.1.0/.evo/traces/21a29126-82a1-4d73-afbc-f3e3a09acd7b.jsonl

@@ -0,0 +1,2 @@
+{"ts": 1781552055.2920816, "level": "info", "msg": "Experiment 5 started", "data": {}}
+{"ts": 1781552055.2937756, "level": "info", "msg": "Score: 31.4", "data": {}}

gradex-0.1.0/.evo/traces/2bb4e240-8808-467f-a71a-58df88e0e64d.jsonl

@@ -0,0 +1,2 @@
+{"ts": 1781552055.2601042, "level": "info", "msg": "Experiment 1 started", "data": {}}
+{"ts": 1781552055.2610655, "level": "info", "msg": "Score: 38.1", "data": {}}

gradex-0.1.0/.evo/traces/694b7d35-4b1e-4af2-8ba3-13ca57229cf2.jsonl

@@ -0,0 +1,2 @@
+{"ts": 1781552055.279045, "level": "info", "msg": "Experiment 3 started", "data": {}}
+{"ts": 1781552055.2800758, "level": "info", "msg": "Score: 35.6", "data": {}}

gradex-0.1.0/.evo/traces/b378a2bf-f760-484b-ba45-73fa497ae6bf.jsonl

@@ -0,0 +1 @@
+{"ts": 1781552055.305381, "level": "info", "msg": "Experiment 7 started", "data": {}}

gradex-0.1.0/.evo/traces/c84c3496-5c03-4837-a676-eabe5702edb0.jsonl

@@ -0,0 +1 @@
+{"ts": 1781552055.2998743, "level": "info", "msg": "Experiment 6 started", "data": {}}

gradex-0.1.0/.evo/traces/d6856171-f713-4424-af6b-7eaf749aee83.jsonl

@@ -0,0 +1,2 @@
+{"ts": 1781552055.268299, "level": "info", "msg": "Experiment 2 started", "data": {}}
+{"ts": 1781552055.26949, "level": "info", "msg": "Score: 29.0", "data": {}}

gradex-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,57 @@
+name: CI
+
+on:
+  push:
+    branches: ["main", "master"]
+  pull_request:
+    branches: ["main", "master"]
+
+jobs:
+  # ── Lint & type-check ────────────────────────────────────────────────────
+  lint:
+    name: Lint & type-check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python 3.11
+        run: uv python install 3.11
+
+      - name: Install project + dev dependencies
+        run: uv sync --all-extras
+
+      - name: ruff — lint
+        run: uv run ruff check src/ tests/
+
+      - name: ruff — format check
+        run: uv run ruff format --check src/ tests/
+
+      - name: mypy — type-check
+        run: uv run mypy src/
+
+  # ── Tests (matrix) ───────────────────────────────────────────────────────
+  test:
+    name: pytest / Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install project + dev dependencies
+        run: uv sync --all-extras
+
+      - name: Run tests
+        run: uv run pytest tests/ --tb=short -v

gradex-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    name: Build & publish
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/evo-research-cli
+
+    permissions:
+      id-token: write   # required for trusted publishing (OIDC)
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python 3.11
+        run: uv python install 3.11
+
+      - name: Install project dependencies
+        run: uv sync
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # Uses OIDC trusted publishing — no API token needed.
+        # Configure the "pypi" environment in GitHub repo settings
+        # and add this repo as a trusted publisher on PyPI.

gradex-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: gradex
+Version: 0.1.0
+Summary: Measurable code improvement — autonomous optimization loop
+License: MIT
+Keywords: ai,cli,coding,plugin
+Requires-Python: >=3.11
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: anthropic>=0.25.0
+Requires-Dist: anyio[trio]>=4.0.0
+Requires-Dist: fastapi>=0.111.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: openai>=1.30.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: sqlmodel>=0.0.18
+Requires-Dist: typer>=0.12.0
+Requires-Dist: uvicorn[standard]>=0.29.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Gradex — autonomous code optimization. Measurable improvement, every run.
+
+[![PyPI version](https://img.shields.io/pypi/v/gradex.svg)](https://pypi.org/project/gradex/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Gradex discovers performance targets, captures a baseline, runs autonomous optimization experiments, and ships the best verified patch.
+
+## Install
+
+```bash
+pip install gradex
+```
+
+## 60-Second Quickstart
+
+```bash
+pip install gradex
+gradex install cursor
+gradex discover "make this repo faster"
+gradex optimize
+gradex dashboard
+```
+
+## Providers
+
+| Provider | Best for | Notes |
+|---|---|---|
+| Groq | Free cloud runs | Free tier available, fast iteration |
+| Anthropic | High quality reasoning | Strong patch planning and code edits |
+| OpenAI | General purpose | Broad model options |
+| Ollama | Local/private | Runs fully on your machine |
+
+## CLI Reference
+
+| Command | Description |
+|---|---|
+| `gradex install <host>` | Installs Gradex integration for a coding host |
+| `gradex doctor <host>` | Checks host environment and setup health |
+| `gradex dashboard` | Starts live optimization dashboard |
+| `gradex upgrade` | Checks PyPI for newer Gradex versions |
+| `gradex discover [hint]` | Discovers benchmark target and baseline |
+| `gradex optimize` | Runs autonomous optimization loop |
+| `gradex stats` | Shows run analytics and optional exports |
+| `gradex history` | Lists recent optimization runs |
+
+## How It Works
+
+```text
++-----------+     +-----------+     +----------------------+     +----------------+
+| discover  | --> | baseline  | --> | optimize loop (N)    | --> | best patch out |
++-----------+     +-----------+     +----------------------+     +----------------+
+```
+
+1. `discover` analyzes your repo and creates a measurable benchmark target.
+2. Gradex records a baseline score.
+3. `optimize` runs parallel experiment rounds (patch -> benchmark -> gate checks).
+4. Best validated patch and run analytics are surfaced in dashboard and CLI.
+
+## Dashboard
+
+Dashboard screenshot: [placeholder](https://example.com/gradex-dashboard-screenshot)
+
+## License
+
+MIT

gradex-0.1.0/README.md

@@ -0,0 +1,66 @@
+# Gradex — autonomous code optimization. Measurable improvement, every run.
+
+[![PyPI version](https://img.shields.io/pypi/v/gradex.svg)](https://pypi.org/project/gradex/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Gradex discovers performance targets, captures a baseline, runs autonomous optimization experiments, and ships the best verified patch.
+
+## Install
+
+```bash
+pip install gradex
+```
+
+## 60-Second Quickstart
+
+```bash
+pip install gradex
+gradex install cursor
+gradex discover "make this repo faster"
+gradex optimize
+gradex dashboard
+```
+
+## Providers
+
+| Provider | Best for | Notes |
+|---|---|---|
+| Groq | Free cloud runs | Free tier available, fast iteration |
+| Anthropic | High quality reasoning | Strong patch planning and code edits |
+| OpenAI | General purpose | Broad model options |
+| Ollama | Local/private | Runs fully on your machine |
+
+## CLI Reference
+
+| Command | Description |
+|---|---|
+| `gradex install <host>` | Installs Gradex integration for a coding host |
+| `gradex doctor <host>` | Checks host environment and setup health |
+| `gradex dashboard` | Starts live optimization dashboard |
+| `gradex upgrade` | Checks PyPI for newer Gradex versions |
+| `gradex discover [hint]` | Discovers benchmark target and baseline |
+| `gradex optimize` | Runs autonomous optimization loop |
+| `gradex stats` | Shows run analytics and optional exports |
+| `gradex history` | Lists recent optimization runs |
+
+## How It Works
+
+```text
++-----------+     +-----------+     +----------------------+     +----------------+
+| discover  | --> | baseline  | --> | optimize loop (N)    | --> | best patch out |
++-----------+     +-----------+     +----------------------+     +----------------+
+```
+
+1. `discover` analyzes your repo and creates a measurable benchmark target.
+2. Gradex records a baseline score.
+3. `optimize` runs parallel experiment rounds (patch -> benchmark -> gate checks).
+4. Best validated patch and run analytics are surfaced in dashboard and CLI.
+
+## Dashboard
+
+Dashboard screenshot: [placeholder](https://example.com/gradex-dashboard-screenshot)
+
+## License
+
+MIT

gradex-0.1.0/_seed_demo/traces/16f332f9-6cb5-4988-8b4e-5561f0d0f405.jsonl

@@ -0,0 +1,2 @@
+{"ts": 1781551901.083844, "level": "info", "msg": "Experiment 6 started", "data": {}}
+{"ts": 1781551901.0857167, "level": "info", "msg": "Running benchmark: python bench.py", "data": {}}

gradex-0.1.0/_seed_demo/traces/249fe8c6-39d3-41a5-b97b-a2e4ca1f5aed.jsonl

@@ -0,0 +1,2 @@
+{"ts": 1781551559.5186882, "level": "info", "msg": "Experiment 7 started", "data": {}}
+{"ts": 1781551559.5197375, "level": "info", "msg": "Running benchmark: python bench.py", "data": {}}

gradex-0.1.0/_seed_demo/traces/2a5b0073-0036-4ca8-80e3-2433dc72b5c5.jsonl

@@ -0,0 +1,3 @@
+{"ts": 1781551901.053676, "level": "info", "msg": "Experiment 3 started", "data": {}}
+{"ts": 1781551901.0548875, "level": "info", "msg": "Running benchmark: python bench.py", "data": {}}
+{"ts": 1781551901.0559962, "level": "info", "msg": "Score: 35.6", "data": {}}

gradex-0.1.0/_seed_demo/traces/309ffc37-e9dc-40b3-876c-d508f1190e16.jsonl

@@ -0,0 +1,3 @@
+{"ts": 1781551559.483333, "level": "info", "msg": "Experiment 3 started", "data": {}}
+{"ts": 1781551559.484786, "level": "info", "msg": "Running benchmark: python bench.py", "data": {}}
+{"ts": 1781551559.4855475, "level": "info", "msg": "Score: 35.6", "data": {}}

gradex-0.1.0/_seed_demo/traces/3931b258-6e5f-4e9a-af0e-fd64e0787475.jsonl

@@ -0,0 +1,2 @@
+{"ts": 1781551559.490363, "level": "info", "msg": "Experiment 4 started", "data": {}}
+{"ts": 1781551559.491506, "level": "info", "msg": "Running benchmark: python bench.py", "data": {}}

gradex-0.1.0/_seed_demo/traces/69c4f0c0-572b-451e-a6c6-bba70263eefa.jsonl

@@ -0,0 +1,3 @@
+{"ts": 1781551559.4575434, "level": "info", "msg": "Experiment 1 started", "data": {}}
+{"ts": 1781551559.4589937, "level": "info", "msg": "Running benchmark: python bench.py", "data": {}}
+{"ts": 1781551559.4599133, "level": "info", "msg": "Score: 38.1", "data": {}}

gradex-0.1.0/_seed_demo/traces/77ba77e8-10c5-4128-a239-9123408b3131.jsonl

@@ -0,0 +1,3 @@
+{"ts": 1781551901.0244586, "level": "info", "msg": "Experiment 1 started", "data": {}}
+{"ts": 1781551901.0256388, "level": "info", "msg": "Running benchmark: python bench.py", "data": {}}
+{"ts": 1781551901.0265846, "level": "info", "msg": "Score: 38.1", "data": {}}

gradex-0.1.0/_seed_demo/traces/9aac1f80-efa1-42a8-bad7-f15be2455638.jsonl

@@ -0,0 +1,3 @@
+{"ts": 1781551559.5014331, "level": "info", "msg": "Experiment 5 started", "data": {}}
+{"ts": 1781551559.5026333, "level": "info", "msg": "Running benchmark: python bench.py", "data": {}}
+{"ts": 1781551559.503857, "level": "info", "msg": "Score: 31.4", "data": {}}

gradex-0.1.0/_seed_demo/traces/a3bb20bb-e5ae-4fcf-8846-50e3e6166515.jsonl

@@ -0,0 +1,2 @@
+{"ts": 1781551901.0931492, "level": "info", "msg": "Experiment 7 started", "data": {}}
+{"ts": 1781551901.09441, "level": "info", "msg": "Running benchmark: python bench.py", "data": {}}

gradex-0.1.0/_seed_demo/traces/add76fe1-814d-4bbb-b5a9-ac07d5076c8e.jsonl

@@ -0,0 +1,4 @@
+{"ts": 1781551559.470149, "level": "info", "msg": "Experiment 2 started", "data": {}}
+{"ts": 1781551559.4713607, "level": "info", "msg": "Running benchmark: python bench.py", "data": {}}
+{"ts": 1781551559.472388, "level": "info", "msg": "Score: 29.0", "data": {}}
+{"ts": 1781551559.4734287, "level": "error", "msg": "Gate failed: 2 tests failed", "data": {}}

gradex-0.1.0/_seed_demo/traces/d7ddb230-5e36-42b0-b261-f6dc102aa8db.jsonl

@@ -0,0 +1,2 @@
+{"ts": 1781551559.5113907, "level": "info", "msg": "Experiment 6 started", "data": {}}
+{"ts": 1781551559.5126586, "level": "info", "msg": "Running benchmark: python bench.py", "data": {}}

gradex-0.1.0/_seed_demo/traces/e4dcd895-dfba-4c1a-8b4d-74e7a95ea49e.jsonl

@@ -0,0 +1,2 @@
+{"ts": 1781551901.061851, "level": "info", "msg": "Experiment 4 started", "data": {}}
+{"ts": 1781551901.0633988, "level": "info", "msg": "Running benchmark: python bench.py", "data": {}}

gradex-0.1.0/_seed_demo/traces/e620d384-aef9-4312-b5cb-4dda6a985076.jsonl

@@ -0,0 +1,4 @@
+{"ts": 1781551901.0414634, "level": "info", "msg": "Experiment 2 started", "data": {}}
+{"ts": 1781551901.0427585, "level": "info", "msg": "Running benchmark: python bench.py", "data": {}}
+{"ts": 1781551901.0437982, "level": "info", "msg": "Score: 29.0", "data": {}}
+{"ts": 1781551901.0447173, "level": "error", "msg": "Gate failed: 2 tests failed", "data": {}}

gradex-0.1.0/_seed_demo/traces/e751a1ad-2eae-40d8-b922-d2378551891f.jsonl

@@ -0,0 +1,3 @@
+{"ts": 1781551901.0737042, "level": "info", "msg": "Experiment 5 started", "data": {}}
+{"ts": 1781551901.0750825, "level": "info", "msg": "Running benchmark: python bench.py", "data": {}}
+{"ts": 1781551901.076312, "level": "info", "msg": "Score: 31.4", "data": {}}

gradex-0.1.0/pyproject.toml

@@ -0,0 +1,115 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gradex"
+version = "0.1.0"
+description = "Measurable code improvement — autonomous optimization loop"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+keywords = ["cli", "coding", "plugin", "ai"]
+dependencies = [
+    "typer>=0.12.0",
+    "rich>=13.0.0",
+    "sqlmodel>=0.0.18",
+    "aiosqlite>=0.20.0",
+    "fastapi>=0.111.0",
+    "uvicorn[standard]>=0.29.0",
+    "websockets>=12.0",
+    "jinja2>=3.1.0",
+    "httpx>=0.27.0",
+    "anyio[trio]>=4.0.0",
+    "anthropic>=0.25.0",
+    "openai>=1.30.0",
+]
+
+[project.scripts]
+gradex = "gradex.cli:app"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=5.0.0",
+    "ruff>=0.4.0",
+    "mypy>=1.10.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gradex"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 88
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "C4"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["gradex"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+mypy_path = "src"
+files = ["src/"]
+
+[[tool.mypy.overrides]]
+# SQLModel + SQLAlchemy type stubs have known gaps that produce false positives
+# under strict mode (generic column expressions, dynamic ORM attribute types, etc.).
+module = ["gradex.state", "gradex.repository"]
+warn_return_any = false
+disallow_any_generics = false
+
+[[tool.mypy.overrides]]
+# FastAPI/Starlette route return types and Jinja2 templating are dynamically typed.
+module = ["gradex.dashboard.server", "gradex.dashboard.broadcaster"]
+warn_return_any = false
+disallow_any_generics = false
+
+[[tool.mypy.overrides]]
+module = ["sqlmodel.*", "sqlalchemy.*", "aiosqlite.*", "uvicorn.*", "fastapi.*"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+# tomllib dynamic dict and dataclasses.fields(...) produce Any under strict.
+module = ["gradex.config"]
+warn_return_any = false
+disallow_any_generics = false
+
+[[tool.mypy.overrides]]
+# anthropic/openai SDK attribute chains + httpx resp.json() produce Any.
+module = ["gradex.ai.client", "gradex.ai.discover", "gradex.ai.brief"]
+warn_return_any = false
+disallow_any_generics = false
+
+[[tool.mypy.overrides]]
+module = ["anthropic.*", "openai.*"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+# asyncio.gather return type with return_exceptions=True and SQLModel session
+# usage in subagent/orchestrator produce Any under strict.
+module = ["gradex.subagent", "gradex.orchestrator"]
+warn_return_any = false
+disallow_any_generics = false
+
+[[tool.mypy.overrides]]
+# Host installers use shutil.which (returns str | None), Path.stat(),
+# and json.loads (returns Any) — all produce Any under strict.
+module = ["gradex.hosts.*", "gradex.hosts"]
+warn_return_any = false
+disallow_any_generics = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+
+[dependency-groups]
+dev = [
+    "anyio>=4.13.0",
+    "pytest>=9.1.0",
+]

gradex-0.1.0/seed_dashboard.py

@@ -0,0 +1,52 @@
+import sys
+sys.path.insert(0, "src")
+
+import gradex.state as state_mod
+from pathlib import Path
+
+SEED_DIR = Path("_seed_demo")
+SEED_DIR.mkdir(exist_ok=True)
+state_mod.GRADEX_DIR = SEED_DIR
+state_mod.DB_PATH = SEED_DIR / "state.db"
+
+import gradex.backends.worktree as wt_mod
+wt_mod.GRADEX_DIR = SEED_DIR
+
+from gradex.repository import RunRepository, ExperimentRepository
+from gradex.traces import TraceWriter
+
+run_repo = RunRepository()
+exp_repo = ExperimentRepository()
+
+run = run_repo.create(
+    benchmark_cmd="python bench.py",
+    metric_direction="lower",
+    gate_cmds=["pytest tests/"],
+    baseline_score=41.2,
+)
+
+statuses = [
+    ("passed",   38.1, True),
+    ("rejected", 29.0, False),
+    ("passed",   35.6, True),
+    ("failed",   None, None),
+    ("passed",   31.4, True),
+    ("running",  None, None),
+    ("pending",  None, None),
+]
+
+for i, (status, score, gate_passed) in enumerate(statuses):
+    exp = exp_repo.create(run.id, None, f"gradex/exp-00{i+1}")
+    if score is not None:
+        exp_repo.update_score(exp.id, score, gate_passed, status)
+    tw = TraceWriter(SEED_DIR / "traces" / f"{exp.id}.jsonl")
+    tw.write("info", f"Experiment {i+1} started")
+    tw.write("info", "Running benchmark: python bench.py")
+    if score:
+        tw.write("info", f"Score: {score}")
+    if status == "rejected":
+        tw.write("error", "Gate failed: 2 tests failed")
+
+run_repo.update_baseline_experiment(run.id, exp_repo.list_by_run(run.id)[0].id)
+print(f"Seeded run {run.id[:8]} with {len(statuses)} experiments")
+print("Now run: python -m gradex dashboard")

gradex-0.1.0/skills/claude-code/discover/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: evo-discover
+version: "0.1.0"
+description: >
+  Discover what to optimise in this repo, instrument a benchmark,
+  and record a baseline score.
+---
+
+# evo: discover
+
+You are the **gradex discover agent**. Your job is to explore the
+repository, identify the best optimisation target, instrument a
+benchmark, and record a baseline experiment.
+
+## Prerequisites
+- The `gradex` CLI must be installed (`gradex --version` should succeed).
+- The repo must have at least one committed Python file.
+- You must be running from the repo root.
+
+## Free provider options
+If the user has no API key, suggest Groq (free tier):
+  `gradex discover --provider groq --api-key <key from console.groq.com>`
+For fully local (no account needed):
+  `gradex discover --provider ollama`
+  (requires Ollama running: `ollama serve` + `ollama pull llama3`)
+
+## Steps
+
+### Step 1 — Check environment
+Run: `gradex doctor claude-code`
+If any errors appear, report them and stop.
+
+### Step 2 — Scan the repository
+Use Read and Glob tools to explore the project structure.
+Look for: hot paths, parsers, LLM prompt loops, data pipelines.
+
+### Step 3 — Run discover
+`gradex discover "<one sentence: what to optimise>"`
+
+With free Groq:
+`gradex discover "<goal>" --provider groq --api-key <key>`
+
+This writes `.gradex/benchmark.py` and records a baseline in `.gradex/state.db`.
+
+### Step 4 — Report to user
+Tell the user:
+- What will be optimised and why
+- Baseline score + metric direction
+- Gate command protecting correctness
+- Run ID (first 8 chars)
+- Next: invoke `/gradex:optimize`
+
+## Notes
+- Never modify source files during discover.
+- If `.gradex/benchmark.py` already exists, report and ask to re-run or proceed.

gradex-0.1.0/skills/claude-code/optimize/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: evo-optimize
+version: "0.1.0"
+description: >
+  Run the evo optimization loop — spawn parallel experiments,
+  score each patch, keep only improvements that pass gates.
+---
+
+# evo: optimize
+
+You are the **gradex optimize agent**.
+
+## Parameters
+| Parameter | Default | Description                              |
+|-----------|---------|------------------------------------------|
+| subagents | 3       | Parallel experiments per round           |
+| budget    | 5       | Max experiments per subagent             |
+| stall     | 3       | Rounds without improvement before stop   |
+| provider  | groq    | anthropic / openai / groq / ollama       |
+
+## Free provider options
+Groq (recommended free):
+  `gradex optimize --provider groq --api-key <key>`
+Ollama (local, no account):
+  `gradex optimize --provider ollama`
+
+## Steps
+
+### Step 1 — Confirm run exists
+A run must exist from `gradex discover`. If not, tell user to run discover first.
+
+### Step 2 — Start optimization
+Default: `gradex optimize`
+With params: `gradex optimize --subagents 3 --budget 10 --stall 3 --provider groq --api-key <key>`
+
+### Step 3 — Monitor
+Tell user to open in separate terminal:
+`gradex dashboard`  →  http://127.0.0.1:8080
+
+### Step 4 — Report results
+When complete:
+- Rounds / experiments / passed count
+- Baseline vs best score + improvement %
+- Stop reason (stall / budget)
+- If improved: winning experiment ID
+  "Review changes in `.gradex/worktrees/<id>/` before merging"
+
+## Safety
+- Main branch is NEVER modified.
+- Experiment promoted ONLY IF score improved AND all gates passed.
+- Ctrl+C safely stops the loop and cleans worktrees.