skill-doctor

# Environment Doctor

## Overview

Run environment diagnostics across 14 check categories. Doctor 2.0 identifies
misconfigured providers, stale loaded or cached plugin versions, invalid plugin
assembly, unwritable state, non-terminal run records, orphan process evidence,
broken hooks, and other issues that prevent Claude Octopus from working
correctly.

**Core principle:** Detect problems before they surface in workflows.

---

## When to Use

**Use this skill when:**
- Something isn't working and you're not sure why
- After installing or updating the plugin
- Before a demo or important workflow run
- Checking if providers are properly authenticated
- Verifying scheduler, hooks, or skills are correctly configured

**Do NOT use for:**
- First-time setup (use `/octo:setup` — it guides configuration)
- Project workflow status (use `/octo:status`)
- Debugging application code (use `/octo:debug`)

---

## The Process

### Step 1: Resolve Plugin Root and Run Full Diagnostics

Use this resolver before running Octopus scripts. Do not assume
`~/.claude-octopus/plugin` exists; Windows Git Bash installs may not support the
stable symlink. Run this as a single Bash call.

```bash
OCTO_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
if [[ -z "$OCTO_PLUGIN_ROOT" || ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]]; then
  OCTO_PLUGIN_ROOT="${HOME}/.claude-octopus/plugin"
fi
if [[ ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]] && command -v octopus >/dev/null 2>&1; then
  OCTO_BIN="$(command -v octopus)"
  OCTO_PLUGIN_ROOT="$(cd "$(dirname "$OCTO_BIN")/.." && pwd)"
fi
if [[ ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]]; then
  OCTO_PLUGIN_ROOT="$(
    find "${HOME}/.claude/plugins" -type f -path "*/scripts/orchestrate.sh" -print 2>/dev/null \
      | sed 's#/scripts/orchestrate.sh$##' \
      | { grep -E '(nyldn-plugins|claude-octopus|/octo(/[0-9]|$))' || true; } \
      | sort \
      | tail -1
  )"
fi
if [[ -z "$OCTO_PLUGIN_ROOT" || ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]]; then
  echo "Claude Octopus plugin root not found. Reinstall the octo plugin, then retry doctor diagnostics."
  exit 1
fi
mkdir -p "${HOME}/.claude-octopus"
_octo_stable="${HOME}/.claude-octopus/plugin"
if [[ ! -L "$_octo_stable" ]] || [[ "$(cd "$OCTO_PLUGIN_ROOT" 2>/dev/null && pwd -P)" != "$(cd "$_octo_stable" 2>/dev/null && pwd -P)" ]]; then
  [[ -L "$_octo_stable" || -f "$_octo_stable" ]] && rm -f "$_octo_stable" 2>/dev/null || true
  ln -s "$OCTO_PLUGIN_ROOT" "$_octo_stable" 2>/dev/null || true
fi
unset _octo_stable
export OCTO_PLUGIN_ROOT
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor --verbose
```

This runs all 14 check categories and displays a formatted report.

### Step 2: Filter by Category (Optional)

If the user asks about a specific area, reuse the resolver from Step 1 and
replace its final `doctor --verbose` invocation with one of these lines. These
are replacement lines, not standalone shell calls; `OCTO_PLUGIN_ROOT` must be
resolved in the same Bash call.

```bash
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor providers
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor providers --live
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor companions
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor auth
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor config
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor updates
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor state
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor smoke
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor hooks
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor scheduler
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor skills
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor conflicts
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor agents
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor recurrence
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor cache
```

### Step 3: Check & Install Dependencies

Reuse the Step 1 resolver and replace its final invocation with the dependency
checker to find missing CLIs, statusline config, and recommended plugins:

```bash
bash "$OCTO_PLUGIN_ROOT/scripts/install-deps.sh" check
```

If the check reports missing deps, offer to install them:

```bash
bash "$OCTO_PLUGIN_ROOT/scripts/install-deps.sh" install
```

This auto-installs Codex CLI, jq, and the statusline resolver. Antigravity CLI (`agy`) setup is detected and reported with install guidance. For plugins (claude-mem, document-skills), it prints `/plugin install` commands the user must run manually.

### Step 4: Verbose or JSON Output

As above, run these as the final line of the Step 1 resolver call:

```bash
# Detailed output for troubleshooting
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor --verbose

# Machine-readable output
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor --json

# Combine: specific category + verbose
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor auth --verbose
```

Doctor 2.0 JSON always uses this outer contract:

```json
{
  "schema_version": "10.0",
  "summary": {"passed": 0, "warnings": 0, "failures": 0, "exit_code": 0},
  "results": []
}
```

A check with status `fail` makes both `summary.exit_code` and the process exit
code `1`, while stdout remains valid JSON. Warnings remain structured but do not
make the command fail. Unknown flags, unknown categories, and multiple category
arguments are usage errors with exit code `2`; do not retry them as full scans.

The `providers --live` variant is an explicit, bounded AGY capability check. It
uses one small real request to verify the CLI version, live model catalog and
keyring authentication, configured model, and print-mode dispatch. Do not run
it from startup hooks or routine preflight. If its catalog/auth stage fails,
tell the user to launch plain `agy` and complete the browser sign-in; AGY has no
separate login shell subcommand. On macOS keyring errors, direct them