Setup Prospector

---
name: setup-prospector
description: >
  Set up claude-prospector's plugin-owned Python venv. Invoked via /setup-prospector
  or natural-language triggers: "set up claude-prospector", "install prospector
  dependencies", "prospector isn't working", "fix prospector", "repair prospector".
  Do not trigger on "dashboard", "usage analysis", or "skill adoption" — those
  are distinct skills.
triggers:
  - /setup-prospector
  - set up claude-prospector
  - install prospector dependencies
  - prospector isn't working
  - fix prospector
  - repair prospector
---

# Setup claude-prospector

This skill materialises the plugin-owned Python venv that the plugin's hooks
need to run `claude-prospector` as a subprocess. Run it once after first install
and after any plugin version update.

## Step 1: Resolve `${CLAUDE_PLUGIN_DATA}`

Read the `CLAUDE_PLUGIN_DATA` environment variable, but **do not trust it
blindly**. When this skill is driven from a main session, `CLAUDE_PLUGIN_DATA`
may be set to a *different* plugin's data dir (observed in the wild as
`.../data/codex-openai-codex`). Before using it, confirm its basename begins
with `claude-prospector-` — i.e. it is *this* plugin's data dir. The marketplace
suffix may legitimately differ (`-glitchwerks` for the public install, or
another suffix for a local/forked marketplace), so match the `claude-prospector-`
prefix, **not** a hardcoded marketplace. If `CLAUDE_PLUGIN_DATA` is unset, empty,
or its basename belongs to a *different* plugin, ignore it and compute the
default instead (using the canonical `glitchwerks` marketplace slug):

```
~/.claude/plugins/data/claude-prospector-glitchwerks/
```

The slug is `<plugin>-<marketplace>` — `claude-prospector` published from the
`glitchwerks` marketplace — with every character outside `[a-zA-Z0-9_-]`
replaced by a hyphen.

Create the directory if it does not exist.

## Step 2: Discover Python

Find a Python ≥ 3.10 interpreter using this probe chain (stop at first success):

1. `flag.interpreter` from the prior `setup-state.json` (if a flag exists from a
   previous run, try that interpreter first).
2. `$CLAUDE_PROSPECTOR_BOOTSTRAP_PYTHON` environment variable (absolute path).
3. `py -3` (Windows only).
4. `python3`
5. `python`

Probe each candidate with:
```
<candidate> -c "import sys; sys.exit(0 if sys.version_info >= (3, 10) else 1)"
```

If all candidates fail, ask the user:
> "No Python ≥ 3.10 interpreter found. Please provide an absolute path to
> a Python 3.10+ executable, or set CLAUDE_PROSPECTOR_BOOTSTRAP_PYTHON."

## Step 3: Wipe the existing venv

If `${CLAUDE_PLUGIN_DATA}/venv/` exists, remove it entirely:
```
shutil.rmtree(<plugin_data>/venv)
```
This is always-wipe-first (spec D4). A partial venv from a failed previous run
is handled correctly by this unconditional removal.

## Step 4: Create the venv

```
<python_cmd> -m venv <plugin_data>/venv
```

Where `<python_cmd>` is the interpreter found in Step 2. If this fails, surface
the stderr to the user and do NOT proceed to Step 5.

## Step 5: Install claude-prospector (PyPI first)

First, ensure pip is available in the new venv:
```
<venv_python> -m ensurepip --upgrade
```

Then install the exact plugin version from the configured package index:
```
<venv_python> -m pip install claude-prospector==<version>
```

Where `<version>` is the current plugin version (read from `pyproject.toml`
`[project].version`, falling back to `.claude-plugin/plugin.json` `version`).

If `$CLAUDE_PROSPECTOR_PIP_SPEC` is set, use its value as the entire package
spec instead of `claude-prospector==<version>` (test/dev override only). The
override is authoritative: if that install fails, surface stderr verbatim,
wipe the partial venv, and do NOT offer another install source or proceed to
Step 6.

If the default exact-version install succeeds, proceed to Step 6. If it fails,
preserve and surface stderr verbatim, but do not wipe the venv yet. Ask the
user:

> "The preferred package-index install for claude-prospector v`<version>`
> failed. May I download the matching `v<version>` tag from the public
> `glitchwerks/claude-prospector` GitHub repository, resolve it to an immutable
> commit SHA, and build it into the plugin venv?"

This prompt is mandatory. Prior permission to run setup, a request not to
interrupt, or general network access is not approval for the GitHub fallback.

If the user declines, wipe the partial venv and do NOT proceed to Step 6. Only
after explicit approval, resolve the version-matching tag:

```
git ls-remote https://github.com/glitchwerks/claude-prospector.git \
  "refs/tags/v<version>" "refs/tags/v<version>^{}"
```

If a peeled `refs/tags/v<version>^{}` line is present, require exactly one such
line and use its 40-character hexadecimal commit SHA; ignore the direct tag-
object SHA. Otherwise, require exactly one direct `refs/tags/v<version>` line
and use its 40-character hexadecimal SHA as the lightweight tag's commit. A
missing, duplicate, or malformed applicable result is a failure. Never install
from the tag name, `main`, or another moving ref.

Install from the immutable commit SHA so pip clones the public repository and
builds the package into the new venv:

```
<venv_python> -m pip install \
  "git+https://github.com/glitchwerks/claude-prospector.git@<commit_sha>"
```

If Git is unavailable, tag resolution fails, or the source install fails,
surface the actionable error (including stderr), wipe the partial venv, and do
NOT proceed to Step 6. This fallback still requires the configured package
index or local cache to supply any missing build and runtime dependencies.

## Step 6: Verify import

```
<venv_python> -c "import claude_prospector"
```

If this fails, wipe the venv and report the import error. Suggest
`pip cache purge` and retry if the error looks like a wheel issue.

## Step 7: Write the setup-state flag

Write `${CLAUDE_PLUGIN_DATA}/setup-state.json` with this shape:

```json
{
  "version": "<current_version>",
  "venv_path": "<absolute_path_to_venv_dir>",
  "interpreter": "<probe_string_from_step_2>",
  "installed_at": "<UTC_ISO_8601_timestamp>"
}
```

The `venv_path` is the absolute path to the venv root (e.g.
`C:/Users/alice/.claude/plugins/data/claude-prospector-glitchwerks/venv`).
The `interpreter` is the raw command string from Step 2 (e.g. `py -3` or
`python3`), not an absolute path, so re-setup can reuse it.

## Step 8: Tell the user

Report success:
> "Setup complete. Open a new Claude Code session to activate claude-prospector.
> The dashboard, skill-tracking, and usage-analysis features will work normally
> after the next session starts."