/setup

name: setup
description: "Guided onboarding wizard for Ouroboros setup"

/ouroboros:setup

Guided onboarding wizard that converts users into power users.

> **Standalone users** (Codex, pip install): Use `ouroboros setup --runtime codex` in your terminal instead. > This skill runs inside a Claude Code session. For other runtime backends, the CLI `ouroboros setup` command handles configuration. > For full install and onboarding instructions, see [Getting Started](docs/getting-started.md).

> **GitHub Copilot CLI users**: Run `ouroboros setup --runtime copilot` (after `pipx install 'ouroboros-ai[mcp]'` or `uv tool install 'ouroboros-ai[mcp]'`). Setup will: > > 1. Live-discover available models from the GitHub Copilot models API (uses `gh auth token`) and let you pick a default. A bundled fallback list is used when offline. > 2. Write `orchestrator.runtime_backend = copilot` and `llm.backend = copilot` plus your chosen default into `~/.ouroboros/config.yaml`. > 3. Register the MCP server in `~/.copilot/mcp-config.json` so the next `copilot` session can call `ooo ...` skills. > > Hyphen Anthropic IDs that the Ouroboros defaults use (for example `claude-opus-4-6`) are auto-mapped at runtime to the dotted form Copilot CLI expects (`claude-opus-4.6`), so existing config files keep working when you switch backends.

Usage

ooo setup
/ouroboros:setup
/ouroboros:setup --uninstall

> **Note**: Claude setup does two things: > 1. **Runtime configuration** — selects the Claude Agent SDK profile on MCP 1.x > 2. **CLAUDE.md integration** (optional) — per-project, adds an Ouroboros command reference block > > It deliberately leaves `~/.claude/mcp.json` untouched because marketplace > plugin wiring owns that file. `[claude]` and its explicit `[claude-sdk]` alias > use MCP 1.x. The plugin launches `[mcp]` in a separate MCP 2 process with the > dependency-free `[claude-cli]` worker.

---

Setup Wizard Flow

When the user invokes this skill, guide them through an enhanced 6-step wizard with progressive disclosure and celebration checkpoints.

---

Step 0: Welcome & Motivation (The Hook)

Start with energy and clear value:

Welcome to Ouroboros Setup!

Let's unlock your full AI development potential.

What you'll get:
- Visual TUI dashboard for real-time progress tracking
- 3-stage evaluation pipeline for quality assurance
- Drift detection to keep projects on track
- Cost optimization (85% savings on average)

Setup takes ~2 minutes. Let's go!

---

Step 0.5: Community Support

Before we begin, check `~/.ouroboros/prefs.json` for `star_asked`. If not `true`, use **AskUserQuestion**:

{
  "questions": [{
    "question": "Ouroboros is free and open-source. A GitHub star helps other developers discover it. Star the repo?",
    "header": "Community",
    "options": [
      {
        "label": "Star on GitHub",
        "description": "Takes 1 second — helps the project grow"
      },
      {
        "label": "Skip for now",
        "description": "Continue with setup"
      }
    ],
    "multiSelect": false
  }]
}

• **Star on GitHub**: Run `gh api -X PUT /user/starred/Q00/ouroboros`, then merge `{"star_asked": true}` into `~/.ouroboros/prefs.json`
• **Skip for now**: Merge `{"star_asked": true}` into `~/.ouroboros/prefs.json`
• **Other**: Merge `{"star_asked": true}` into `~/.ouroboros/prefs.json`

Create `~/.ouroboros/` directory if it doesn't exist. Preserve any existing keys such as `welcomeShown`, `welcomeCompleted`, and `welcomeVersion` when updating `star_asked`:

python3 - <<'PY'
import json, os
path = os.path.expanduser('~/.ouroboros/prefs.json')
os.makedirs(os.path.dirname(path), exist_ok=True)
try:
    with open(path, encoding='utf-8') as f:
        prefs = json.load(f)
    if not isinstance(prefs, dict):
        prefs = {}
except Exception:
    prefs = {}
prefs['star_asked'] = True
with open(path, 'w', encoding='utf-8') as f:
    json.dump(prefs, f, indent=2)
    f.write('\n')
PY

If `star_asked` is already `true`, skip this step silently.

---

Step 1: Environment Detection

Check the user's environment with clear feedback:

python3 --version
which uvx 2>/dev/null && uvx --version 2>/dev/null
which claude 2>/dev/null

**IMPORTANT: If system Python is < 3.12 but uvx is available, also check uv-managed Python:**

uv python list 2>/dev/null | grep "cpython-3.1[2-9]"

If `uv python list` shows Python >= 3.12 available, CLI workflows are available through uv-managed Python even when system Python is older. This does not make the isolated `[claude-sdk]` and MCP 2 profiles import-compatible.

**Report results with personality:**

Environment Detected:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

System Python 3.11         [!] Below 3.12
uv Python 3.12+            [✓] Available (uvx will use this)
uvx package runner         [✓] Available
Runtime backend            [✓] Detected

→ Full Mode Available (via uvx + uv-managed Python >= 3.12)

**Decision Matrix:**

| Environment | Mode | Action | |:------------|:-----|:-------| | Python >= 3.12 + Claude CLI | **Ready** | Configure `[claude]` SDK/MCP 1 and skills | | uvx + Python >= 3.12 | **MCP-capable elsewhere** | Use a supported CLI-backed runtime setup for isolated `ouroboros-ai[mcp]` | | Python < 3.12 only | **Install needed** | Run `uv python install 3.12` then proceed | | No package runner or Ouroboros package | **Install needed** | Install uv first, then proceed |

If deps are missing and the user doesn't want to fix manually, recommend uv. Prefer package-manager paths over the vendor pipe-to-shell when the user's environment supports them (pipx > pip > brew > vendor one-liner):

Or install uv (recommended — handles deps automatically). Any one of:
  pipx install uv
  pip install --user uv
  brew install uv          # macOS / Linuxbrew
  curl -LsSf https://astral.sh/uv/install.sh | sh   # vendor one-liner (last resort)
Then re-run: ooo setup

**IMPOR