Setup

---
name: setup
description: Install or verify the ade-bench harness, the Python project that actually runs the benchmark tasks this plugin generates. Use when ade-bench isn't yet on the user's machine, when a generated task fails because the harness is missing, or when the user explicitly asks to set up ade-bench. Also invoked automatically by plan-tasks and create-task when they detect ade-bench is missing.
argument-hint: "[--path <install-path>]"
---

# ADE-Bench Setup

The plugin generates task definitions. ade-bench (a separate Python project) is what actually executes them inside Docker against the user's data. This skill makes ade-bench available so generated tasks can be run.

Default install location: `~/.ade-bench`. The skill `git clone`s ade-bench there, runs `uv sync` to install Python deps, and `uv tool install .` to put the `ade` CLI on PATH.

---

## Step 1: Parse Arguments

- `--path <install-path>`: Where to install ade-bench. Default: `~/.ade-bench`.

Resolve `~` to the user's home directory. Use the resolved absolute path in every step below.

---

## Step 2: Check Prerequisites

Run these in parallel and collect the results:

1. **git**: `command -v git`
2. **uv**: `command -v uv`
3. **docker**: `command -v docker`

If any of the three is missing, stop and tell the user what's missing and how to install it:

- **git**: Use the system package manager (`brew install git`, `apt install git`, etc.).
- **uv**: `curl -LsSf https://astral.sh/uv/install.sh | sh` (then restart the shell or `source ~/.zshrc`).
- **docker**: Recommend Docker Desktop, Colima, or OrbStack. Don't try to install or start Docker. The user must do this.

If `docker` is installed but not running, that's fine for setup — flag it but proceed. Docker only needs to be running when tasks actually execute.

---

## Step 3: Detect Existing Installation

Two checks, in order:

1. **Already installed via this skill?**
   ```bash
   test -f <install-path>/pyproject.toml && grep -q 'name = "ade-bench"' <install-path>/pyproject.toml
   ```
2. **Already on PATH from somewhere else?**
   ```bash
   command -v ade
   ```

If either succeeds:
- Run `ade --help` to confirm the CLI works.
- Tell the user where ade-bench was found and that no install is needed.
- Skip to Step 7 (DuckDB database download — still verify it's been done) and continue from there.

If `<install-path>` exists but is **not** a valid ade-bench checkout (different repo, partial clone, leftover files), stop and ask the user whether to remove and reinstall or pick a different path. Do not silently overwrite.

If nothing is installed, proceed to Step 4.

---

## Step 4: Clone the Repository

```bash
git clone https://github.com/dbt-labs/ade-bench.git <install-path>
```

If the clone fails, report the error verbatim and stop. The most common reasons are no network, GitHub auth issues, or `<install-path>` already existing as a non-empty directory.

---

## Step 5: Install Python Dependencies

```bash
cd <install-path> && uv sync
```

This builds a local virtualenv at `<install-path>/.venv` and installs all Python deps. Expect this to take 30 seconds to a couple of minutes depending on network speed.

---

## Step 6: Install the `ade` CLI Globally

```bash
cd <install-path> && uv tool install .
```

`uv tool install` puts the `ade` entry point on the user's PATH (under `~/.local/bin` by default). After this, `ade run …` works from any directory.

Verify:
```bash
command -v ade && ade --help
```

If `ade` is not found after `uv tool install`, the user's `~/.local/bin` is probably not on PATH. Tell them:
> "`ade` was installed but isn't on PATH. Add `~/.local/bin` to your PATH — for zsh, run: `echo 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.zshrc && source ~/.zshrc`"

Don't modify the user's shell config yourself.

---

## Step 7: Download Bundled DuckDB Databases

ade-bench ships several bundled dbt projects (`airbnb`, `f1`, `quickbooks`, …) along with reference DuckDB files used as the source database for those projects. The `.duckdb` files live in a GitHub release (`dbt-labs/ade-bench:databases`), not in the repo itself — `<install-path>/shared/databases/duckdb/` is empty after `git clone`. Without these files, any task targeting a bundled project fails at `setup_duckdb` with "DuckDB database '<name>' not found at <path>".

The release currently totals ~225 MB. Skip this step only if the user has explicitly said they'll exclusively use their own dbt projects with their own DuckDB files (the generators write `db_dir` into `task.yaml` for those — bundled databases aren't consulted).

### 7.1 Check if already populated

Compare the number of `.duckdb` files locally present against the expected count from the GitHub release. Skip the download only when they match exactly — a partial state (e.g., 10 of 11 files) should fall through to Step 7.2 so `gh release download` can fetch the missing file(s).

```bash
present=$(ls <install-path>/shared/databases/duckdb/*.duckdb 2>/dev/null | wc -l | tr -d ' ')

if [ "$present" -gt 0 ]; then
  expected=$(gh release view databases --repo dbt-labs/ade-bench \
    --json assets \
    --jq '[.assets[] | select(.name | endswith(".duckdb"))] | length' 2>/dev/null)

  if [ -n "$expected" ] && [ "$present" -eq "$expected" ]; then
    # All files present — skip the rest of Step 7 and report "databases already present"
    :
  fi
fi
```

Notes:
- Costs one extra `gh release view` API call only when *some* files are already present, so the first-run path is unaffected.
- If `gh` isn't installed or isn't authenticated, the `expected` lookup returns empty and the check falls through to Step 7.2 (which has its own gh-missing branch with manual-download instructions). Consistent.
- This makes the check survive future ade-bench bundled-project additions without touching the skill — the threshold is whatever the release says it is.

Stash the `expected` value if you got one — Step 7.4 uses it for the user-facing report.

### 7.2 Check `gh` availability and auth

```bash
command -v gh && gh auth status
```

- **`gh` missing** → tell the user to either install it (`brew install gh`) or download the release assets manually from `https://github.com/dbt-labs/ade-bench/releases/tag/databases` into `<install-path>/shared/databases/duckdb/`. Skip the download and continue to Step 8.
- **`gh` present but not authenticated** → tell the user to run `gh auth login` and re-invoke `/ade-bench:setup`. Skip the download and continue to Step 8.

### 7.3 Download

```bash
gh release download databases \
  --repo dbt-labs/ade-bench \
  --pattern "*.duckdb" \
  --dir <install-path>/shared/databases/duckdb
```

If the command fails partway through (network, auth expiry), report the error verbatim and continue. The user can rerun the same command later — `gh release download` skips files that already exist.

Do **not** block the rest of setup on a download failure. Snowflake-only users don't need these, and a partial download can be completed manually later.

### 7.4 Verify

```bash
present=$(ls <install-path>/shared/databases/duckdb/*.duckdb 2>/dev/null | wc -l | tr -d ' ')
size=$(du -sh <install-path>/shared/databases/duckdb 2>/dev/null | cut -f1)
```

Use the `expected` value from Step 7.1 if you have it. Report the count as `<present>/<expected>` so a partial state is visually obvious — e.g.:

- All present: `DuckDB DBs: 11/11 files (224 MB)`
- Partial: `DuckDB DBs: 10/11 files (210 MB) — re-run /ade-bench:setup to fetch the missing file`
- Expected-count unknown (gh missing/unauthed): `DuckDB DBs: 11 files (224 MB)` — fall back to just the count.

---

## Step 8: Verify Docker

```bash
docker ps
```

If it fails:
- "Cannot connect to the Docker daemon" → Docker isn't running. Tell the user to start it.
- "command not found" → Already handled in Step 2.

If Docker isn't running, that's fine for now — flag it but don't block. The user only needs it when running tasks.

---

## Step 9: Initialize Snowflake `.env` (Conditional)

Only if the user has indicated they'll be running Snowflake-targeted tasks (or if the calling skill detected a Snowflake project). Skip for DuckDB-only users.

```bash
test -f <install-path>/.env || cp <install-path>/.env.example <install-path>/.env
```

Tell the user:
> "I copied `.env.example` to `.env` at `<install-path>/.env`. Open it and fill in your Snowflake credentials before running Snowflake tasks. Required vars: `SNOWFLAKE_ACCOUNT`, `SNOWFLAKE_USER`, `SNOWFLAKE_PASSWORD`, `SNOWFLAKE_ROLE`, `SNOWFLAKE_WAREHOUSE`."

**Do not prompt for credentials. Do not write credential values to any file.** The user fills in `.env` themselves.

---

## Step 10: Report Results

Summarize for the user:

```
ade-bench setup complete.
  Install path:    <install-path>
  CLI on PATH:     ade (verified with `ade --help`)
  DuckDB DBs:      <present>/<expected> files (<size>) | <present> files (<size>) if expected unknown | not downloaded — install `gh` and rerun, or download manually
  Docker:          <running | installed but not running | not installed>
  Snowflake env:   <.env created at <path>, fill in credentials | not initialized — DuckDB-only>

Next: run `/ade-bench:plan-tasks <project-path>` or `/ade-bench:create-task <project-path>` to generate your first benchmark tasks.
```

---

## Important Guidelines

- **Don't install dependencies the user already has.** Step 3 short-circuits if a working ade-bench is already on the system.
- **Don't write credentials anywhere.** The Snowflake setup ends at copying `.env.example` to `.env`. The user fills it in.
- **Don't start Docker.** If Docker isn't running, tell the user. Don't run `open -a Docker` or anything similar — it's surprising and sometimes wrong.
- **Don't modify the user's shell config.** If PATH adjustment is needed, tell the user the command to run; don't run it.
- **Default install location is `~/.ade-bench`.** Honor `--path` if provided, but don't invent alternative defaults.