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 --> ```bash 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**: ```json { "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`: ```bash 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: ```bash 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: ```bash uv python list 2>/dev/null | grep "cpython-3.1[2-9]" ``` The resolver already rejects system Python below 3.12 and provisions a compatible uv-managed Python when needed. This does not make the isolated `[claude-sdk]` and MCP 2 profiles import-compatible. **Report results with personality:** ``` Environment Detected: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Skill Python 3.12+ [✓] Resolver-selected uv Python 3.12+ [✓] Available 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 ``` **IMPORTANT**: Never install `[mcp,claude]`, `[mcp,claude-sdk]`, or `[all,mcp]` together and never write a direct `ouroboros` or `python -m ouroboros` MCP fallback. MCP 2 launchers must use an isolated `uvx --isolated --python '>=3.12' --from 'ouroboros-ai[mcp]' ...` or `pipx run --spec 'ouroboros-ai[mcp]' ...` process. Only `[mcp,claude-cli]` is supported because the CLI worker is out of process. Do not write an Ouroboros entry to `~/.claude/mcp.json`; the plugin owns that registration. **If prerequisites are missing, show:** ``` Ouroboros requires uvx (recommended) or the ouroboros package installed. Quick install (< 1 minute) — install uv via any 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: uv python install 3.12 Then re-run: ooo setup ``` **Celebration Checkpoint 1:** ``` Great news! You're ready for the full Ouroboros experience. ``` --- ### Step 2: MCP Profile Boundary **Show progress:** ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Verifying Runtime Boundary... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ The default Claude SDK profile stays on MCP 1.x. The plugin-owned MCP server runs MCP 2 separately and selects the `[claude-cli]` worker. This setup enables: Visual TUI Dashboard [Watch execution in real-time] 3-Stage Evaluation [Mechanical → Semantic → Consensus] Drift Detection [Alert when projects go off-track] Session Replay [Debug any execution from events] ``` **Do not create, update, or remove `~/.claude/mcp.json`.** Existing entries may be user-managed or belong to another compatible runtime. Explain that advanced MCP workflows require a host-managed isolated `[mcp]` launcher. The Claude marketplace plugin or another supported host setup owns that registration. **Celebration Checkpoint 2:** ``` Runtime boundary verified! You can now: - Use Claude-native ooo interview, seed, evaluate, and unstuck workflows - Use the Claude SDK on MCP 1.x with isolated MCP 2 tools - Keep the Claude SDK and MCP 2 dependency graphs conflict-free ``` --- ### Step 3: CLAUDE.md Integration (Optional) Ask with clear value proposition: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ CLAUDE.md Integration ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Add Ouroboros quick-reference to your CLAUDE.md? This gives you instant command reminders without leaving your project context. What gets added (~40 lines): - Philosophy and pipeline overview - Command routing table with lazy-loaded agents - Agent catalog summary A backup will be created: CLAUDE.md.bak [Integrate / Skip / Preview first] ``` **If "Preview first", show:** ````markdown <!-- ooo:START --> <!-- ooo:VERSION:0.54.4 --> # Ouroboros — Specification-First AI Development > Before telling AI what to build, define what should be built. > As Socrates asked 2,500 years ago — "What do you truly know?" > Ouroboros turns that question into an evolutionary AI workflow engine. Most AI coding fails at the input, not the output. Ouroboros fixes this by **exposing hidden assumptions before any code is written**. 1. **Socratic Clarity** — Question until ambiguity ≤ 0.2 2. **Ontological Precision** — Solve the root problem, not symptoms 3. **Evolutionary Loops** — Each evaluation cycle feeds back into better specs ``` Interview → Seed → Execute → Evaluate ↑ ↓ └─── Evolutionary Loop ─────┘ ``` ## ooo Commands Each command loads its agent/MCP on-demand. Details in each skill file. | Command | Loads | |---------|-------| | `ooo` | — | | `ooo interview` | `ouroboros:socratic-interviewer` | | `ooo seed` | `ouroboros:seed-architect` | | `ooo run` | MCP required | | `ooo evolve` | MCP: `evolve_step` | | `ooo evaluate` | `ouroboros:evaluator` | | `ooo unstuck` | `ouroboros:{persona}` | | `ooo status` | MCP: `session_status` | | `ooo setup` | — | | `ooo help` | — | ## Agents Loaded on-demand — not preloaded. **Core**: socratic-interviewer, ontologist, seed-architect, evaluator, wonder, reflect, advocate, contrarian, judge **Support**: hacker, simplifier, researcher, architect <!-- ooo:END --> ```` **If Integrate:** 1. Backup existing CLAUDE.md to CLAUDE.md.bak 2. Append the block above 3. Confirm successful integration **Celebration Checkpoint 3:** ``` CLAUDE.md updated! You now have instant Ouroboros reference available in every project. ``` --- ### Step 4: Quick Verification Run verification with visual feedback: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Verifying Setup... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` Check skills are loadable: ```bash ls skills/ | wc -l # Should show 12+ skills ``` Check agents are available: ```bash ls src/ouroboros/agents/*.md | wc -l # Should show 20+ bundled agents ``` Confirm the saved Ouroboros config selects the default Claude Agent SDK runtime on MCP 1.x while `~/.claude/mcp.json` was not mutated by this setup. The dependency-free Claude CLI worker remains a distinct, explicit `[claude-cli]` selection for the isolated MCP 2 process. --- ### Step 5: Success Summary Display with celebration: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Ouroboros Setup Complete! ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Mode: Claude Agent SDK (MCP 1.x) Skills Registered: 15 workflow skills Agents Available: 9 specialized agents MCP Server: Host-owned (config not mutated) CLAUDE.md: ✓ Integrated ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ You're Ready to Go! ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Start your first project: ooo interview "your project idea" Learn what's possible: ooo help Try the interactive tutorial: ooo tutorial Join the community: Star us on GitHub! github.com/Q00/ouroboros ``` --- ### Step 5.1: Model Choice (Claude Code) Before continuing to repository setup, give Claude Code users the same optional control over models without making it a requirement. Ask in the user's language; for Korean, use: ```json { "questions": [{