--- name: q00/welcome source: https://app.decimal.ai/s/q00-welcome@4/SKILL.md source_sha256: decddff09592 --- # /ouroboros:welcome Interactive onboarding for new Ouroboros users. ## Usage ``` /ouroboros:welcome # First-time or update onboarding /ouroboros:welcome --skip # Skip welcome, mark as shown /ouroboros:welcome --force # Force re-run welcome even if shown ``` ## Instructions When this skill is invoked, follow this flow: ### 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. ```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 } ``` --- ### Pre-Check: Already Completed? First, check `~/.ouroboros/prefs.json` for `welcomeCompleted`. For upgrades from older releases, also treat legacy `welcomeShown: true` as completed so the welcome prompt does not reappear forever: ```bash PREFFILE="$HOME/.ouroboros/prefs.json" if [ -f "$PREFFILE" ]; then WELCOME_COMPLETED=$(ouroboros_python - <<'PY' import json, os path = os.path.expanduser('~/.ouroboros/prefs.json') try: prefs = json.load(open(path, encoding='utf-8')) except Exception: prefs = {} if not isinstance(prefs, dict): prefs = {} print(prefs.get('welcomeCompleted') or ('legacy-welcomeShown' if prefs.get('welcomeShown') else '')) PY ) WELCOME_VERSION=$(ouroboros_python - <<'PY' import json, os path = os.path.expanduser('~/.ouroboros/prefs.json') try: prefs = json.load(open(path, encoding='utf-8')) except Exception: prefs = {} if not isinstance(prefs, dict): prefs = {} print(prefs.get('welcomeVersion') or '') PY ) if [ -n "$WELCOME_COMPLETED" ] && [ "$WELCOME_COMPLETED" != "null" ]; then ALREADY_COMPLETED="true" fi fi ``` Before honoring that completion marker, determine whether setup is ready. A previously completed welcome must never hide the setup gate from a user who chose **나중에** or whose setup was later removed: ```bash if ouroboros_python - "$HOME/.ouroboros/config.yaml" <<'PY' from __future__ import annotations import sys from pathlib import Path try: import yaml except ModuleNotFoundError: yaml = None config_path = Path(sys.argv[1]) def yaml_mapping(source: str) -> dict[str, dict[str, str]]: """Read the top-level mapping scalars this readiness gate owns.""" if yaml is not None: loaded = yaml.safe_load(source) or {} return loaded if isinstance(loaded, dict) else {} parsed: dict[str, dict[str, str]] = {} section: str | None = None def scalar_value(raw: str) -> str: return raw.strip().split(" #", 1)[0].strip().rstrip(",}").strip().strip("'\"") def flow_mapping(raw: str) -> dict[str, str]: value = raw.strip().split(" #", 1)[0].strip() if not (value.startswith("{") and value.endswith("}")): return {} fields: dict[str, str] = {} for part in value[1:-1].split(","): key, separator, field_value = part.partition(":") if separator: fields[key.strip().strip("'\"")] = scalar_value(field_value) return fields for raw_line in source.splitlines(): if not raw_line.strip() or raw_line.lstrip().startswith("#"): continue indent = len(raw_line) - len(raw_line.lstrip()) key, separator, raw_value = raw_line.strip().partition(":") if not separator: continue if indent == 0: section = key.strip("'\"") parsed[section] = flow_mapping(raw_value) elif section is not None: parsed.setdefault(section, {})[key.strip("'\"")] = scalar_value(raw_value) return parsed try: config = yaml_mapping(config_path.read_text(encoding="utf-8")) except (OSError, ValueError): raise SystemExit(1) orchestrator = config.get("orchestrator") if isinstance(config, dict) else None llm = config.get("llm") if isinstance(config, dict) else None # Existing YAML form: runtime_backend: claude. Parsing avoids assuming its order. # The marketplace plugin owns its MCP capability. Host-owned # ~/.claude/mcp.json is intentionally not part of SDK setup readiness. ready = ( isinstance(orchestrator, dict) and orchestrator.get("runtime_backend") in {"claude", "claude_mcp"} and isinstance(llm, dict) and llm.get("backend") == "claude" ) raise SystemExit(0 if ready else 1) PY then SETUP_READY="true" fi ``` **If `ALREADY_COMPLETED` is true, `SETUP_READY` is true, AND no `--force` flag:** Use **AskUserQuestion**: ```json { "questions": [{ "question": "Ouroboros welcome was already completed on $WELCOME_COMPLETED. What would you like to do?", "header": "Welcome", "options": [ { "label": "Skip", "description": "Continue to work (recommended)" }, { "label": "Re-run welcome", "description": "Go through the interactive onboarding again" } ], "multiSelect": false }] } ``` - **Skip**: Mark as complete and exit - **Re-run welcome**: Continue to Step 1 below If the welcome was completed but `SETUP_READY` is not true, bypass this completion prompt and continue to the Setup Gate below. **If `--skip` flag present:** - Merge `welcomeShown: true`, `welcomeCompleted: `, and `welcomeVersion` into `~/.ouroboros/prefs.json` without deleting existing keys: ```bash ouroboros_python - <<'PY' import json, os from datetime import UTC, datetime 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.update({ 'welcomeShown': True, 'welcomeCompleted': datetime.now(UTC).isoformat(), 'welcomeVersion': '0.36.0', }) with open(path, 'w', encoding='utf-8') as f: json.dump(prefs, f, indent=2) f.write('\n') PY ``` - Show brief message: ``` Ouroboros welcome skipped. Run /ouroboros:welcome --force to re-run onboarding. ``` - Exit --- ### Setup Gate: First Use Before showing the welcome banner, check whether Ouroboros has been prepared on this machine: ```bash if ouroboros_python - "$HOME/.ouroboros/config.yaml" <<'PY' from __future__ import annotations import sys from pathlib import Path try: import yaml except ModuleNotFoundError: yaml = None config_path = Path(sys.argv[1]) def yaml_mapping(source: str) -> dict[str, dict[str, str]]: """Read only the top-level mapping scalars owned by this readiness gate.""" if yaml is not None: loaded = yaml.safe_load(source) or {} return loaded if isinstance(loaded, dict) else {} parsed: dict[str, dict[str, str]] = {} section: str | None = None def scalar_value(raw: str) -> str: return raw.strip().split(" #", 1)[0].strip().rstrip(",}").strip().strip("'\"") def flow_mapping(raw: str) -> dict[str, str]: value = raw.strip().split(" #", 1)[0].strip() if not (value.startswith("{") and value.endswith("}")): return {} fields: dict[str, str] = {} for part in value[1:-1].split(","): key, separator, field_value = part.partition(":") if separator: fields[key.strip().strip("'\"")] = scalar_value(field_value) return fields for raw_line in source.splitlines(): if not raw_line.strip() or raw_line.lstrip().startswith("#"): continue indent = len(raw_line) - len(raw_line.lstrip()) key, separator, raw_value = raw_line.strip().partition(":") if not separator: continue if indent == 0: section = key.strip("'\"") parsed[section] = flow_mapping(raw_value) elif section is not None: parsed.setdefault(section, {})[key.strip("'\"")] = scalar_value(raw_value) return parsed try: config = yaml_mapping(config_path.read_text(encoding="utf-8")) except (OSError, ValueError): raise SystemExit(1) orchestrator = config.get("orchestrator") if isinstance(config, dict) else None llm = config.get("llm") if isinstance(config, dict) else None # Existing YAML form: runtime_backend: claude. Parsing avoids assuming its order. # The marketplace plugin owns its MCP capability. Host-owned # ~/.claude/mcp.json is intentionally not part of SDK setup readiness. ready = ( isinstance(orchestrator, dict) and orchestrator.get("runtime_backend") in {"claude", "claude_mcp"} and isinstance(llm, dict) and llm.get("backend") == "claude" ) raise SystemExit(0 if ready else 1) PY then echo "SETUP_READY" else echo "SETUP_REQUIRED" fi ``` If setup is required, ask one concise question in the user's language. For a Korean conversation, use: ```json { "questions": [{ "question": "Ouroboros를 처음 사용하시네요. 시작하기 전에 실행 환경을 설정할까요?", "header": "Ouroboros 시작하기", "options": [ { "label": "설정하고 시작하기 (권장)", "description": "한 번만 설정하면 바로 사용할 수 있어요" }, { "label": "나중에", "description": "지금은 기본 안내만 보고 나중에 설정할게요" } ], "multiSelect": false }] } ``` - **설정하고 시작하기**: Follow `../setup/SKILL.md`. Do not ask the user to copy a command when the current host can run it. - **나중에**: Continue with the welcome flow, but do not claim that MCP-only execution features are ready. After successful setup, `../setup/SKILL.md` presents the model choice. Do not repeat it here; continue to Step 1 after the setup skill returns. Do not show this gate again once the Claude runtime and LLM backend are ready. The normal settings UI remains available later through `ooo config`, so a model choice made now is never permanent. --- ### Step 1: Welcome Banner Display: ``` Welcome to Ouroboros! The serpent that eats itself -- better every loop. Most AI coding fails at the input, not the output. Ouroboros fixes this by exposing hidden assumptions BEFORE any code is written. Interview -> Seed -> Execute -> Evaluate ^ | +---- Evolutionary Loop -----+ ``` --- ### Step 2: Persona Detection **AskUserQuestion**: ```json { "questions": [{ "question": "What brings you to Ouroboros?", "header": "Welcome", "options": [ { "label": "New project idea", "description": "I have a vague idea and want to crystallize it into a clear spec" }, { "label": "Tired of rewriting prompts", "description": "AI keeps building the wrong thing because my requirements are unclear" }, { "label": "Just exploring", "description": "Heard about Ouroboros and want to see what it does" } ], "multiSelect": false }] } ``` Give brief personalized response (1-2 sentences) based on choice. --- ### Step 3: Advanced Runtime Check Ordinary Claude setup uses the default `[claude]` Agent SDK profile on MCP 1.x. It intentionally leaves host-owned `~/.claude/mcp.json` untouched; do not inspect or mutate that file as an onboarding health check. The dependency-free worker is the explicit `[claude-cli]` profile used by an isolated MCP 2 process. If the active runtime does not expose Ouroboros MCP tools, **AskUserQuestion**: ```json { "questions": [{ "question": "Advanced MCP workflows require a host-managed MCP 2 launcher. What would you like to do?", "header": "Runtime", "options": [ { "label": "Continue native (Recommended)", "description": "Use Claude-native interview, seed, evaluate, and unstuck workflows" }, { "label": "Show MCP setup", "description": "See supported Codex, OpenCode, Kiro, Copilot, or Hermes setup commands" } ], "multiSelect": false }] } ``` - **Continue native**: Continue to Step 4 - **Show MCP setup**: Explain that the Claude marketplace plugin or another supported host setup owns the isolated `[mcp]` launcher. Never combine `[claude-sdk]` with `[mcp]`. Then continue to Step 4. --- ### Step 4: Quick Reference ``` Available Commands: +---------------------------------------------------+ | Command | What It Does | |-----------------|----------------------------------| | ooo interview | Socratic Q&A -- expose hidden | | | assumptions in your requirements | | ooo seed | Crystallize answers into spec | | ooo run | Execute with visual TUI | | ooo evaluate | 3-stage verification | | ooo unstuck | Lateral thinking when stuck | | ooo config | Settings GUI: agents & models | | ooo help | Full command reference | +---------------------------------------------------+ ``` --- ### Step 4: First Action **AskUserQuestion**: ```json { "questions": [{ "question": "What would you like to do first?", "header": "Get started", "options": [ { "label": "Start a project", "description": "Run a Socratic interview on your idea right now" }, { "label": "Try the tutorial", "description": "Interactive hands-on learning with a sample project" }, { "label": "Read the docs", "description": "Full command reference and architecture overview" } ], "multiSelect": false }] } ``` Based on choice: - **Start a project**: Ask "What do you want to build?" → execute `../interview/SKILL.md` - **Try the tutorial**: Execute `../tutorial/SKILL.md` - **Read the docs**: Execute `../help/SKILL.md` --- ### Step 5: GitHub Star (Last Step) Check `gh` availability first: ```bash gh auth status &>/dev/null && echo "GH_OK" || echo "GH_MISSING" ``` **If `GH_OK` AND `star_asked` not true:** **AskUserQuestion**: ```json { "questions": [{ "question": "If you're enjoying Ouroboros, would you like to star it on GitHub?", "header": "Community", "options": [ { "label": "Star on GitHub", "description": "Takes 1 second -- helps the project grow" }, { "label": "Maybe later", "description": "Skip for now" } ], "multiSelect": false }] } ``` - **Star on GitHub**: `gh api -X PUT /user/starred/Q00/ouroboros` - Both choices: merge the welcome completion fields into `~/.ouroboros/prefs.json` without deleting existing keys. Set `star_asked: true` after either star prompt choice so the star prompt is not repeated: ```bash ouroboros_python - <<'PY' import json, os from datetime import UTC, datetime 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.update({ 'star_asked': True, 'welcomeShown': True, 'welcomeCompleted': datetime.now(UTC).isoformat(), 'welcomeVersion': '0.36.0', }) with open(path, 'w', encoding='utf-8') as f: json.dump(prefs, f, indent=2) f.write('\n') PY ``` **If `GH_MISSING` or `star_asked` is true:** Merge the welcome completion fields into `~/.ouroboros/prefs.json` without deleting existing keys: ```bash ouroboros_python - <<'PY' import json, os from datetime import UTC, datetime 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.update({ 'welcomeShown': True, 'welcomeCompleted': datetime.now(UTC).isoformat(), 'welcomeVersion': '0.36.0', }) with open(path, 'w', encoding='utf-8') as f: json.dump(prefs, f, indent=2) f.write('\n') PY ``` --- ### Completion Message ``` Ouroboros Setup Complete! MAGIC KEYWORDS (optional shortcuts): Just include these naturally in your request: | Keyword | Effect | Example | |---------|--------|---------| | interview | Socratic Q&A | "interview me about my app idea" | | seed | Crystallize spec | "seed the requirements" | | evaluate | 3-stage check | "evaluate this implementation" | | stuck | Lateral thinking | "I'm stuck on the auth flow" | REAL-TIME MONITORING (TUI): When running ooo run or ooo evolve, open a separate terminal: uvx --python '>=3.12' --from 'ouroboros-ai[tui]' ouroboros tui monitor Press 1-4 to switch screens (Dashboard, Execution, Logs, Debug). READY TO BUILD: - ooo interview "your project idea" - ooo tutorial # Interactive learning - ooo help # Full reference ``` --- ## Prefs File Structure `~/.ouroboros/prefs.json`: ```json { "welcomeShown": true, "welcomeCompleted": "2025-02-23T15:30:00+09:00", "welcomeVersion": "0.36.0", "star_asked": true } ``` ## RFC #1392 State Breadcrumb Footer Your final response MUST end with exactly one breadcrumb footer line: ``` ◆ → next: ``` Derive `` from live session state via `ouroboros_session_status` when that MCP projection is available; otherwise derive it from this skill's actual outcome. Never use a linear `Step N of M` footer because Ouroboros is an evolutionary loop. When the next action is genuinely a choice, list 2-3 honest options in the `next:` clause. The breadcrumb line must be the last line of the response.