/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.

Python Runtime (Required)

Before running any shell snippet below, define this resolver in the same shell. It accepts only Python 3.12 or newer, prefers `python3` and then `python`, and uses uv as the final fallback. Call `ouroboros_python` directly and quote every argument passed to it; the function preserves arguments and heredoc/stdin input. Only the probe and child interpreter discard inherited CPython path-selection overrides; the caller shell keeps its environment unchanged.

<!-- ouroboros-python-resolver:start -->

ouroboros_python() {
  if command -v python3 >/dev/null 2>&1 &&
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command python3 -c 'import sys; raise SystemExit(sys.version_info < (3, 12))') >/dev/null 2>&1
  then
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command python3 "$@")
    return
  fi
  if command -v python >/dev/null 2>&1 &&
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command python -c 'import sys; raise SystemExit(sys.version_info < (3, 12))') >/dev/null 2>&1
  then
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command python "$@")
    return
  fi
  if command -v uv >/dev/null 2>&1; then
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command uv run --no-project --quiet --python '>=3.12' python "$@")
    return
  fi
  printf '%s\n' 'Ouroboros skills require Python >= 3.12 or uv on PATH.' >&2
  return 127
}

<!-- ouroboros-python-resolver:end -->

---

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`:

ouroboros_python - <<'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:

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

For diagnostics, list uv-managed Python installations when uv is available:

uv python l